update API

Author: leon-ape

apis/apps/v1/types.go

@@ -257,21 +257,27 @@ type ComponentNetwork struct {
 	// +optional
 	DNSConfig *corev1.PodDNSConfig `json:"dnsConfig,omitempty"`
 
-	// Specifies the host ports of the pod.
-	// It's valid if and only if the `hostNetwork` is enabled.
+	// HostPorts specifies the mapping of container ports to host ports.
+	// The behavior varies based on the HostNetwork setting:
 	//
-	// If any host ports are specified, the default host-port manager provided by KB will be ignored.
-	// Therefore, it is the user's responsibility to specify all container ports that need to be bound to host ports.
-	// Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.
+	// 1. When HostNetwork is enabled:
+	//    Allows customization of host ports.
+	//    - Mandatory: All container ports defined in `cmpd.spec.hostNetwork` MUST be mapped to a host port here.
+	//    - Sidecar (kbagent): The "http" and "streaming" ports for kbagent also require host binding.
+	//      They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+	//      (Note: Automatic allocation is supported ONLY for kbagent ports).
 	//
-	// !!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: 'http', 'streaming'.
+	// 2. When HostNetwork is disabled:
+	//    Allows optional mapping from container ports to host ports.
+	//    - Mappings are restricted to ports defined in `cmpd.spec.runtime.containers.ports`.
+	//    - Any specified container ports not present in the runtime definition will be ignored.
 	//
 	// +optional
 	HostPorts []HostPort `json:"hostPorts,omitempty"`
 }
 
 type HostPort struct {
-	// The name of the host port.
+	// The name of the container port.
 	//
 	// +kubebuilder:validation:Required
 	Name string `json:"name"`

config/crd/bases/apps.kubeblocks.io_clusters.yaml

@@ -2776,20 +2776,26 @@ spec:
                           type: boolean
                         hostPorts:
                           description: |-
-                            Specifies the host ports of the pod.
-                            It's valid if and only if the `hostNetwork` is enabled.
+                            HostPorts specifies the mapping of container ports to host ports.
+                            The behavior varies based on the HostNetwork setting:
 
 
-                            If any host ports are specified, the default host-port manager provided by KB will be ignored.
-                            Therefore, it is the user's responsibility to specify all container ports that need to be bound to host ports.
-                            Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.
+                            1. When HostNetwork is enabled:
+                               Allows customization of host ports.
+                               - Mandatory: All container ports defined in `cmpd.spec.hostNetwork` MUST be mapped to a host port here.
+                               - Sidecar (kbagent): The "http" and "streaming" ports for kbagent also require host binding.
+                                 They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+                                 (Note: Automatic allocation is supported ONLY for kbagent ports).
 
 
-                            !!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: 'http', 'streaming'.
+                            2. When HostNetwork is disabled:
+                               Allows optional mapping from container ports to host ports.
+                               - Mappings are restricted to ports defined in `cmpd.spec.runtime.containers.ports`.
+                               - Any specified container ports not present in the runtime definition will be ignored.
                           items:
                             properties:
                               name:
-                                description: The name of the host port.
+                                description: The name of the container port.
                                 type: string
                               port:
                                 description: The port number of the host port.
@@ -14054,20 +14060,26 @@ spec:
                               type: boolean
                             hostPorts:
                               description: |-
-                                Specifies the host ports of the pod.
-                                It's valid if and only if the `hostNetwork` is enabled.
+                                HostPorts specifies the mapping of container ports to host ports.
+                                The behavior varies based on the HostNetwork setting:
 
 
-                                If any host ports are specified, the default host-port manager provided by KB will be ignored.
-                                Therefore, it is the user's responsibility to specify all container ports that need to be bound to host ports.
-                                Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.
+                                1. When HostNetwork is enabled:
+                                   Allows customization of host ports.
+                                   - Mandatory: All container ports defined in `cmpd.spec.hostNetwork` MUST be mapped to a host port here.
+                                   - Sidecar (kbagent): The "http" and "streaming" ports for kbagent also require host binding.
+                                     They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+                                     (Note: Automatic allocation is supported ONLY for kbagent ports).
 
 
-                                !!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: 'http', 'streaming'.
+                                2. When HostNetwork is disabled:
+                                   Allows optional mapping from container ports to host ports.
+                                   - Mappings are restricted to ports defined in `cmpd.spec.runtime.containers.ports`.
+                                   - Any specified container ports not present in the runtime definition will be ignored.
                               items:
                                 properties:
                                   name:
-                                    description: The name of the host port.
+                                    description: The name of the container port.
                                     type: string
                                   port:
                                     description: The port number of the host port.

config/crd/bases/apps.kubeblocks.io_components.yaml

@@ -2555,20 +2555,26 @@ spec:
                     type: boolean
                   hostPorts:
                     description: |-
-                      Specifies the host ports of the pod.
-                      It's valid if and only if the `hostNetwork` is enabled.
+                      HostPorts specifies the mapping of container ports to host ports.
+                      The behavior varies based on the HostNetwork setting:
 
 
-                      If any host ports are specified, the default host-port manager provided by KB will be ignored.
-                      Therefore, it is the user's responsibility to specify all container ports that need to be bound to host ports.
-                      Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.
+                      1. When HostNetwork is enabled:
+                         Allows customization of host ports.
+                         - Mandatory: All container ports defined in `cmpd.spec.hostNetwork` MUST be mapped to a host port here.
+                         - Sidecar (kbagent): The "http" and "streaming" ports for kbagent also require host binding.
+                           They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+                           (Note: Automatic allocation is supported ONLY for kbagent ports).
 
 
-                      !!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: 'http', 'streaming'.
+                      2. When HostNetwork is disabled:
+                         Allows optional mapping from container ports to host ports.
+                         - Mappings are restricted to ports defined in `cmpd.spec.runtime.containers.ports`.
+                         - Any specified container ports not present in the runtime definition will be ignored.
                     items:
                       properties:
                         name:
-                          description: The name of the host port.
+                          description: The name of the container port.
                           type: string
                         port:
                           description: The port number of the host port.

deploy/helm/crds/apps.kubeblocks.io_clusters.yaml

@@ -2776,20 +2776,26 @@ spec:
                           type: boolean
                         hostPorts:
                           description: |-
-                            Specifies the host ports of the pod.
-                            It's valid if and only if the `hostNetwork` is enabled.
+                            HostPorts specifies the mapping of container ports to host ports.
+                            The behavior varies based on the HostNetwork setting:
 
 
-                            If any host ports are specified, the default host-port manager provided by KB will be ignored.
-                            Therefore, it is the user's responsibility to specify all container ports that need to be bound to host ports.
-                            Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.
+                            1. When HostNetwork is enabled:
+                               Allows customization of host ports.
+                               - Mandatory: All container ports defined in `cmpd.spec.hostNetwork` MUST be mapped to a host port here.
+                               - Sidecar (kbagent): The "http" and "streaming" ports for kbagent also require host binding.
+                                 They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+                                 (Note: Automatic allocation is supported ONLY for kbagent ports).
 
 
-                            !!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: 'http', 'streaming'.
+                            2. When HostNetwork is disabled:
+                               Allows optional mapping from container ports to host ports.
+                               - Mappings are restricted to ports defined in `cmpd.spec.runtime.containers.ports`.
+                               - Any specified container ports not present in the runtime definition will be ignored.
                           items:
                             properties:
                               name:
-                                description: The name of the host port.
+                                description: The name of the container port.
                                 type: string
                               port:
                                 description: The port number of the host port.
@@ -14054,20 +14060,26 @@ spec:
                               type: boolean
                             hostPorts:
                               description: |-
-                                Specifies the host ports of the pod.
-                                It's valid if and only if the `hostNetwork` is enabled.
+                                HostPorts specifies the mapping of container ports to host ports.
+                                The behavior varies based on the HostNetwork setting:
 
 
-                                If any host ports are specified, the default host-port manager provided by KB will be ignored.
-                                Therefore, it is the user's responsibility to specify all container ports that need to be bound to host ports.
-                                Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.
+                                1. When HostNetwork is enabled:
+                                   Allows customization of host ports.
+                                   - Mandatory: All container ports defined in `cmpd.spec.hostNetwork` MUST be mapped to a host port here.
+                                   - Sidecar (kbagent): The "http" and "streaming" ports for kbagent also require host binding.
+                                     They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+                                     (Note: Automatic allocation is supported ONLY for kbagent ports).
 
 
-                                !!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: 'http', 'streaming'.
+                                2. When HostNetwork is disabled:
+                                   Allows optional mapping from container ports to host ports.
+                                   - Mappings are restricted to ports defined in `cmpd.spec.runtime.containers.ports`.
+                                   - Any specified container ports not present in the runtime definition will be ignored.
                               items:
                                 properties:
                                   name:
-                                    description: The name of the host port.
+                                    description: The name of the container port.
                                     type: string
                                   port:
                                     description: The port number of the host port.

deploy/helm/crds/apps.kubeblocks.io_components.yaml

@@ -2555,20 +2555,26 @@ spec:
                     type: boolean
                   hostPorts:
                     description: |-
-                      Specifies the host ports of the pod.
-                      It's valid if and only if the `hostNetwork` is enabled.
+                      HostPorts specifies the mapping of container ports to host ports.
+                      The behavior varies based on the HostNetwork setting:
 
 
-                      If any host ports are specified, the default host-port manager provided by KB will be ignored.
-                      Therefore, it is the user's responsibility to specify all container ports that need to be bound to host ports.
-                      Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.
+                      1. When HostNetwork is enabled:
+                         Allows customization of host ports.
+                         - Mandatory: All container ports defined in `cmpd.spec.hostNetwork` MUST be mapped to a host port here.
+                         - Sidecar (kbagent): The "http" and "streaming" ports for kbagent also require host binding.
+                           They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+                           (Note: Automatic allocation is supported ONLY for kbagent ports).
 
 
-                      !!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: 'http', 'streaming'.
+                      2. When HostNetwork is disabled:
+                         Allows optional mapping from container ports to host ports.
+                         - Mappings are restricted to ports defined in `cmpd.spec.runtime.containers.ports`.
+                         - Any specified container ports not present in the runtime definition will be ignored.
                     items:
                       properties:
                         name:
-                          description: The name of the host port.
+                          description: The name of the container port.
                           type: string
                         port:
                           description: The port number of the host port.

docs/developer_docs/api-reference/cluster.md

@@ -6167,12 +6167,24 @@ Kubernetes core/v1.PodDNSConfig
 </td>
 <td>
 <em>(Optional)</em>
-<p>Specifies the host ports of the pod.
-It&rsquo;s valid if and only if the <code>hostNetwork</code> is enabled.</p>
-<p>If any host ports are specified, the default host-port manager provided by KB will be ignored.
-Therefore, it is the user&rsquo;s responsibility to specify all container ports that need to be bound to host ports.
-Check @cmpd.spec.hostNetwork to obtain all container ports that need to be bound.</p>
-<p>!!!!! When you specify the host ports, you must specify two additional ports for the kbagent sidecar of KB: &lsquo;http&rsquo;, &lsquo;streaming&rsquo;.</p>
+<p>HostPorts specifies the mapping of container ports to host ports.
+The behavior varies based on the HostNetwork setting:</p>
+<ol>
+<li><p>When HostNetwork is enabled:
+Allows customization of host ports.</p>
+<ul>
+<li>Mandatory: All container ports defined in <code>cmpd.spec.hostNetwork</code> MUST be mapped to a host port here.</li>
+<li>Sidecar (kbagent): The &ldquo;http&rdquo; and &ldquo;streaming&rdquo; ports for kbagent also require host binding.
+They can be explicitly defined here, or automatically allocated by enabling the host-port manager.
+(Note: Automatic allocation is supported ONLY for kbagent ports).</li>
+</ul></li>
+<li><p>When HostNetwork is disabled:
+Allows optional mapping from container ports to host ports.</p>
+<ul>
+<li>Mappings are restricted to ports defined in <code>cmpd.spec.runtime.containers.ports</code>.</li>
+<li>Any specified container ports not present in the runtime definition will be ignored.</li>
+</ul></li>
+</ol>
 </td>
 </tr>
 </tbody>
@@ -8472,7 +8484,7 @@ string
 </em>
 </td>
 <td>
-<p>The name of the host port.</p>
+<p>The name of the container port.</p>
 </td>
 </tr>
 <tr>