From a08bdbeee62e07836ba24f7046dc6356f481afc7 Mon Sep 17 00:00:00 2001 From: Fred Rolland Date: Wed, 11 Sep 2024 11:03:23 +0300 Subject: [PATCH] doc: add missing comments in API Signed-off-by: Fred Rolland --- api/v1alpha1/hostdevicenetwork_types.go | 4 +- api/v1alpha1/ipoibnetwork_types.go | 4 +- api/v1alpha1/macvlannetwork_types.go | 4 +- api/v1alpha1/nicclusterpolicy_types.go | 50 +++++++++++++------ .../mellanox.com_hostdevicenetworks.yaml | 9 ++-- .../crd/bases/mellanox.com_ipoibnetworks.yaml | 4 +- .../bases/mellanox.com_macvlannetworks.yaml | 4 +- .../mellanox.com_nicclusterpolicies.yaml | 46 +++++++---------- .../crds/mellanox.com_hostdevicenetworks.yaml | 9 ++-- .../crds/mellanox.com_ipoibnetworks.yaml | 4 +- .../crds/mellanox.com_macvlannetworks.yaml | 4 +- .../crds/mellanox.com_nicclusterpolicies.yaml | 46 +++++++---------- 12 files changed, 98 insertions(+), 90 deletions(-) diff --git a/api/v1alpha1/hostdevicenetwork_types.go b/api/v1alpha1/hostdevicenetwork_types.go index 47c4ab301..970780ead 100644 --- a/api/v1alpha1/hostdevicenetwork_types.go +++ b/api/v1alpha1/hostdevicenetwork_types.go @@ -60,7 +60,9 @@ type HostDeviceNetwork struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec HostDeviceNetworkSpec `json:"spec,omitempty"` + // Defines the desired state of HostDeviceNetwork + Spec HostDeviceNetworkSpec `json:"spec,omitempty"` + // Defines the observed state of HostDeviceNetwork Status HostDeviceNetworkStatus `json:"status,omitempty"` } diff --git a/api/v1alpha1/ipoibnetwork_types.go b/api/v1alpha1/ipoibnetwork_types.go index c892e71f0..25454f5c2 100644 --- a/api/v1alpha1/ipoibnetwork_types.go +++ b/api/v1alpha1/ipoibnetwork_types.go @@ -58,7 +58,9 @@ type IPoIBNetwork struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec IPoIBNetworkSpec `json:"spec,omitempty"` + // Defines the desired state of IPoIBNetwork + Spec IPoIBNetworkSpec `json:"spec,omitempty"` + // Defines the observed state of IPoIBNetwork Status IPoIBNetworkStatus `json:"status,omitempty"` } diff --git a/api/v1alpha1/macvlannetwork_types.go b/api/v1alpha1/macvlannetwork_types.go index 8a9759f29..ba2b0f74b 100644 --- a/api/v1alpha1/macvlannetwork_types.go +++ b/api/v1alpha1/macvlannetwork_types.go @@ -64,7 +64,9 @@ type MacvlanNetwork struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec MacvlanNetworkSpec `json:"spec,omitempty"` + // Defines the desired state of MacvlanNetworkSpec + Spec MacvlanNetworkSpec `json:"spec,omitempty"` + // Defines the observed state of MacvlanNetwork Status MacvlanNetworkStatus `json:"status,omitempty"` } diff --git a/api/v1alpha1/nicclusterpolicy_types.go b/api/v1alpha1/nicclusterpolicy_types.go index ffc7149bc..81985cb0e 100644 --- a/api/v1alpha1/nicclusterpolicy_types.go +++ b/api/v1alpha1/nicclusterpolicy_types.go @@ -72,6 +72,7 @@ func (is *ImageSpec) GetContainerResources() []ResourceRequirements { // ImageSpecWithConfig Contains ImageSpec and optional configuration type ImageSpecWithConfig struct { + // Image information for the component ImageSpec `json:""` // Configuration for the component as a string Config *string `json:"config,omitempty"` @@ -136,16 +137,18 @@ type DriverUpgradePolicySpec struct { // +optional // +kubebuilder:default:=1 // +kubebuilder:validation:Minimum:=0 - MaxParallelUpgrades int `json:"maxParallelUpgrades,omitempty"` - WaitForCompletion *WaitForCompletionSpec `json:"waitForCompletion,omitempty"` - DrainSpec *DrainSpec `json:"drain,omitempty"` + MaxParallelUpgrades int `json:"maxParallelUpgrades,omitempty"` + // The configuration for waiting on pods completions + WaitForCompletion *WaitForCompletionSpec `json:"waitForCompletion,omitempty"` + // The configuration for node drain during automatic upgrade + DrainSpec *DrainSpec `json:"drain,omitempty"` // SafeLoad turn on safe driver loading (cordon and drain the node before loading the driver) // +optional // +kubebuilder:default:=false SafeLoad bool `json:"safeLoad,omitempty"` } -// WaitForCompletionSpec describes the configuration for waiting on job completions +// WaitForCompletionSpec describes the configuration for waiting on pods completions type WaitForCompletionSpec struct { // PodSelector specifies a label selector for the pods to wait for completion // For more details on label selectors, see: @@ -191,6 +194,7 @@ type DrainSpec struct { // 1. Image information for device plugin // 2. Device plugin configuration type DevicePluginSpec struct { + // Image information for the device plugin and optional configuration ImageSpecWithConfig `json:""` // Enables use of container device interface (CDI) UseCdi bool `json:"useCdi,omitempty"` @@ -201,6 +205,7 @@ type DevicePluginSpec struct { // 2. Multus CNI config if config is missing or empty then multus config will be automatically generated from the CNI // configuration file of the master plugin (the first file in lexicographical order in cni-conf-dir) type MultusSpec struct { + // Image information for Multus and optional configuration ImageSpecWithConfig `json:""` } @@ -255,11 +260,13 @@ type IBKubernetesSpec struct { type NVIPAMSpec struct { // Enable deployment of the validation webhook EnableWebhook bool `json:"enableWebhook,omitempty"` - ImageSpec `json:""` + // Image information for nv-ipam + ImageSpec `json:""` } // NICFeatureDiscoverySpec describes configuration options for nic-feature-discovery type NICFeatureDiscoverySpec struct { + // Image information for nic-feature-discovery ImageSpec `json:""` } @@ -273,6 +280,7 @@ type DOCATelemetryServiceConfig struct { // DOCATelemetryServiceSpec is the configuration for DOCA Telemetry Service. type DOCATelemetryServiceSpec struct { + // Image information for DOCA Telemetry Service ImageSpec `json:""` // +optional // Config contains custom config for the DOCATelemetryService. @@ -288,20 +296,30 @@ type NicClusterPolicySpec struct { // Additional nodeAffinity rules to inject to the DaemonSets objects that are managed by the operator NodeAffinity *v1.NodeAffinity `json:"nodeAffinity,omitempty"` // Additional tolerations to inject to the DaemonSets objects that are managed by the operator - Tolerations []v1.Toleration `json:"tolerations,omitempty"` - OFEDDriver *OFEDDriverSpec `json:"ofedDriver,omitempty"` - RdmaSharedDevicePlugin *DevicePluginSpec `json:"rdmaSharedDevicePlugin,omitempty"` - SriovDevicePlugin *DevicePluginSpec `json:"sriovDevicePlugin,omitempty"` - IBKubernetes *IBKubernetesSpec `json:"ibKubernetes,omitempty"` - SecondaryNetwork *SecondaryNetworkSpec `json:"secondaryNetwork,omitempty"` - NvIpam *NVIPAMSpec `json:"nvIpam,omitempty"` - NicFeatureDiscovery *NICFeatureDiscoverySpec `json:"nicFeatureDiscovery,omitempty"` - DOCATelemetryService *DOCATelemetryServiceSpec `json:"docaTelemetryService,omitempty"` + Tolerations []v1.Toleration `json:"tolerations,omitempty"` + // Configuration options for OFED driver + OFEDDriver *OFEDDriverSpec `json:"ofedDriver,omitempty"` + // Configuration options for RDMA shared device plugin + RdmaSharedDevicePlugin *DevicePluginSpec `json:"rdmaSharedDevicePlugin,omitempty"` + // Configuration options for SRIOV device plugin + SriovDevicePlugin *DevicePluginSpec `json:"sriovDevicePlugin,omitempty"` + // Configuration options for ib-kubernetes + IBKubernetes *IBKubernetesSpec `json:"ibKubernetes,omitempty"` + // Configuration options for secondary network + SecondaryNetwork *SecondaryNetworkSpec `json:"secondaryNetwork,omitempty"` + // Configuration options nv-ipam + NvIpam *NVIPAMSpec `json:"nvIpam,omitempty"` + // Configuration options nic-feature-discovery + NicFeatureDiscovery *NICFeatureDiscoverySpec `json:"nicFeatureDiscovery,omitempty"` + // Configuration options DOCA Telemetry Service + DOCATelemetryService *DOCATelemetryServiceSpec `json:"docaTelemetryService,omitempty"` } // AppliedState defines a finer-grained view of the observed state of NicClusterPolicy type AppliedState struct { + // Name of the deployed component this state refers to Name string `json:"name"` + // The state of the deployed component. ("ready", "notReady", "ignore", "error") // +kubebuilder:validation:Enum={"ready", "notReady", "ignore", "error"} State State `json:"state"` // Message is a human readable message indicating details about why @@ -335,7 +353,9 @@ type NicClusterPolicy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec NicClusterPolicySpec `json:"spec,omitempty"` + // Defines the desired state of NicClusterPolicy + Spec NicClusterPolicySpec `json:"spec,omitempty"` + // Defines the observed state of NicClusterPolicy Status NicClusterPolicyStatus `json:"status,omitempty"` } diff --git a/config/crd/bases/mellanox.com_hostdevicenetworks.yaml b/config/crd/bases/mellanox.com_hostdevicenetworks.yaml index e9cae8a53..52217cfb6 100644 --- a/config/crd/bases/mellanox.com_hostdevicenetworks.yaml +++ b/config/crd/bases/mellanox.com_hostdevicenetworks.yaml @@ -44,7 +44,7 @@ spec: metadata: type: object spec: - description: HostDeviceNetworkSpec defines the desired state of HostDeviceNetwork + description: Defines the desired state of HostDeviceNetwork properties: ipam: description: IPAM configuration to be used for this network @@ -57,7 +57,7 @@ spec: type: string type: object status: - description: HostDeviceNetworkStatus defines the observed state of HostDeviceNetwork + description: Defines the observed state of HostDeviceNetwork properties: appliedStates: description: AppliedStates provide a finer view of the observed state @@ -71,9 +71,12 @@ spec: the state is in this condition type: string name: + description: Name of the deployed component this state refers + to type: string state: - description: State represents reconcile state of the system. + description: The state of the deployed component. ("ready", + "notReady", "ignore", "error") enum: - ready - notReady diff --git a/config/crd/bases/mellanox.com_ipoibnetworks.yaml b/config/crd/bases/mellanox.com_ipoibnetworks.yaml index e651f1a61..7e2c49870 100644 --- a/config/crd/bases/mellanox.com_ipoibnetworks.yaml +++ b/config/crd/bases/mellanox.com_ipoibnetworks.yaml @@ -44,7 +44,7 @@ spec: metadata: type: object spec: - description: IPoIBNetworkSpec defines the desired state of IPoIBNetwork + description: Defines the desired state of IPoIBNetwork properties: ipam: description: IPAM configuration to be used for this network. @@ -58,7 +58,7 @@ spec: type: string type: object status: - description: IPoIBNetworkStatus defines the observed state of IPoIBNetwork + description: Defines the observed state of IPoIBNetwork properties: ipoibNetworkAttachmentDef: description: Network attachment definition generated from IPoIBNetworkSpec diff --git a/config/crd/bases/mellanox.com_macvlannetworks.yaml b/config/crd/bases/mellanox.com_macvlannetworks.yaml index b6b2b2a3a..f7a1628b6 100644 --- a/config/crd/bases/mellanox.com_macvlannetworks.yaml +++ b/config/crd/bases/mellanox.com_macvlannetworks.yaml @@ -44,7 +44,7 @@ spec: metadata: type: object spec: - description: MacvlanNetworkSpec defines the desired state of MacvlanNetwork + description: Defines the desired state of MacvlanNetworkSpec properties: ipam: description: IPAM configuration to be used for this network. @@ -72,7 +72,7 @@ spec: type: string type: object status: - description: MacvlanNetworkStatus defines the observed state of MacvlanNetwork + description: Defines the observed state of MacvlanNetwork properties: macvlanNetworkAttachmentDef: description: Network attachment definition generated from MacvlanNetworkSpec diff --git a/config/crd/bases/mellanox.com_nicclusterpolicies.yaml b/config/crd/bases/mellanox.com_nicclusterpolicies.yaml index 1464eb639..f99d2e351 100644 --- a/config/crd/bases/mellanox.com_nicclusterpolicies.yaml +++ b/config/crd/bases/mellanox.com_nicclusterpolicies.yaml @@ -44,11 +44,10 @@ spec: metadata: type: object spec: - description: NicClusterPolicySpec defines the desired state of NicClusterPolicy + description: Defines the desired state of NicClusterPolicy properties: docaTelemetryService: - description: DOCATelemetryServiceSpec is the configuration for DOCA - Telemetry Service. + description: Configuration options DOCA Telemetry Service properties: config: description: |- @@ -126,8 +125,7 @@ spec: - version type: object ibKubernetes: - description: IBKubernetesSpec describes configuration options for - ib-kubernetes + description: Configuration options for ib-kubernetes properties: containerResources: description: ResourceRequirements describes the compute resource @@ -208,8 +206,7 @@ spec: - version type: object nicFeatureDiscovery: - description: NICFeatureDiscoverySpec describes configuration options - for nic-feature-discovery + description: Configuration options nic-feature-discovery properties: containerResources: description: ResourceRequirements describes the compute resource @@ -465,10 +462,7 @@ spec: x-kubernetes-map-type: atomic type: object nvIpam: - description: |- - NVIPAMSpec describes configuration options for nv-ipam - 1. Image information for nv-ipam - 2. Configuration for nv-ipam + description: Configuration options nv-ipam properties: containerResources: description: ResourceRequirements describes the compute resource @@ -538,8 +532,7 @@ spec: - version type: object ofedDriver: - description: OFEDDriverSpec describes configuration options for OFED - driver + description: Configuration options for OFED driver properties: certConfig: description: 'Optional: Custom TLS certificates configuration @@ -794,8 +787,8 @@ spec: if set to false all other options are ignored type: boolean drain: - description: DrainSpec describes configuration for node drain - during automatic upgrade + description: The configuration for node drain during automatic + upgrade properties: deleteEmptyDir: default: false @@ -839,8 +832,7 @@ spec: and drain the node before loading the driver) type: boolean waitForCompletion: - description: WaitForCompletionSpec describes the configuration - for waiting on job completions + description: The configuration for waiting on pods completions properties: podSelector: description: |- @@ -867,10 +859,7 @@ spec: - version type: object rdmaSharedDevicePlugin: - description: |- - DevicePluginSpec describes configuration options for device plugin - 1. Image information for device plugin - 2. Device plugin configuration + description: Configuration options for RDMA shared device plugin properties: config: description: Configuration for the component as a string @@ -943,8 +932,7 @@ spec: - version type: object secondaryNetwork: - description: SecondaryNetworkSpec describes configuration options - for secondary network + description: Configuration options for secondary network properties: cniPlugins: description: Image information for CNI plugins @@ -1219,10 +1207,7 @@ spec: type: object type: object sriovDevicePlugin: - description: |- - DevicePluginSpec describes configuration options for device plugin - 1. Image information for device plugin - 2. Device plugin configuration + description: Configuration options for SRIOV device plugin properties: config: description: Configuration for the component as a string @@ -1336,7 +1321,7 @@ spec: type: array type: object status: - description: NicClusterPolicyStatus defines the observed state of NicClusterPolicy + description: Defines the observed state of NicClusterPolicy properties: appliedStates: description: AppliedStates provide a finer view of the observed state @@ -1350,9 +1335,12 @@ spec: the state is in this condition type: string name: + description: Name of the deployed component this state refers + to type: string state: - description: State represents reconcile state of the system. + description: The state of the deployed component. ("ready", + "notReady", "ignore", "error") enum: - ready - notReady diff --git a/deployment/network-operator/crds/mellanox.com_hostdevicenetworks.yaml b/deployment/network-operator/crds/mellanox.com_hostdevicenetworks.yaml index e9cae8a53..52217cfb6 100644 --- a/deployment/network-operator/crds/mellanox.com_hostdevicenetworks.yaml +++ b/deployment/network-operator/crds/mellanox.com_hostdevicenetworks.yaml @@ -44,7 +44,7 @@ spec: metadata: type: object spec: - description: HostDeviceNetworkSpec defines the desired state of HostDeviceNetwork + description: Defines the desired state of HostDeviceNetwork properties: ipam: description: IPAM configuration to be used for this network @@ -57,7 +57,7 @@ spec: type: string type: object status: - description: HostDeviceNetworkStatus defines the observed state of HostDeviceNetwork + description: Defines the observed state of HostDeviceNetwork properties: appliedStates: description: AppliedStates provide a finer view of the observed state @@ -71,9 +71,12 @@ spec: the state is in this condition type: string name: + description: Name of the deployed component this state refers + to type: string state: - description: State represents reconcile state of the system. + description: The state of the deployed component. ("ready", + "notReady", "ignore", "error") enum: - ready - notReady diff --git a/deployment/network-operator/crds/mellanox.com_ipoibnetworks.yaml b/deployment/network-operator/crds/mellanox.com_ipoibnetworks.yaml index e651f1a61..7e2c49870 100644 --- a/deployment/network-operator/crds/mellanox.com_ipoibnetworks.yaml +++ b/deployment/network-operator/crds/mellanox.com_ipoibnetworks.yaml @@ -44,7 +44,7 @@ spec: metadata: type: object spec: - description: IPoIBNetworkSpec defines the desired state of IPoIBNetwork + description: Defines the desired state of IPoIBNetwork properties: ipam: description: IPAM configuration to be used for this network. @@ -58,7 +58,7 @@ spec: type: string type: object status: - description: IPoIBNetworkStatus defines the observed state of IPoIBNetwork + description: Defines the observed state of IPoIBNetwork properties: ipoibNetworkAttachmentDef: description: Network attachment definition generated from IPoIBNetworkSpec diff --git a/deployment/network-operator/crds/mellanox.com_macvlannetworks.yaml b/deployment/network-operator/crds/mellanox.com_macvlannetworks.yaml index b6b2b2a3a..f7a1628b6 100644 --- a/deployment/network-operator/crds/mellanox.com_macvlannetworks.yaml +++ b/deployment/network-operator/crds/mellanox.com_macvlannetworks.yaml @@ -44,7 +44,7 @@ spec: metadata: type: object spec: - description: MacvlanNetworkSpec defines the desired state of MacvlanNetwork + description: Defines the desired state of MacvlanNetworkSpec properties: ipam: description: IPAM configuration to be used for this network. @@ -72,7 +72,7 @@ spec: type: string type: object status: - description: MacvlanNetworkStatus defines the observed state of MacvlanNetwork + description: Defines the observed state of MacvlanNetwork properties: macvlanNetworkAttachmentDef: description: Network attachment definition generated from MacvlanNetworkSpec diff --git a/deployment/network-operator/crds/mellanox.com_nicclusterpolicies.yaml b/deployment/network-operator/crds/mellanox.com_nicclusterpolicies.yaml index 1464eb639..f99d2e351 100644 --- a/deployment/network-operator/crds/mellanox.com_nicclusterpolicies.yaml +++ b/deployment/network-operator/crds/mellanox.com_nicclusterpolicies.yaml @@ -44,11 +44,10 @@ spec: metadata: type: object spec: - description: NicClusterPolicySpec defines the desired state of NicClusterPolicy + description: Defines the desired state of NicClusterPolicy properties: docaTelemetryService: - description: DOCATelemetryServiceSpec is the configuration for DOCA - Telemetry Service. + description: Configuration options DOCA Telemetry Service properties: config: description: |- @@ -126,8 +125,7 @@ spec: - version type: object ibKubernetes: - description: IBKubernetesSpec describes configuration options for - ib-kubernetes + description: Configuration options for ib-kubernetes properties: containerResources: description: ResourceRequirements describes the compute resource @@ -208,8 +206,7 @@ spec: - version type: object nicFeatureDiscovery: - description: NICFeatureDiscoverySpec describes configuration options - for nic-feature-discovery + description: Configuration options nic-feature-discovery properties: containerResources: description: ResourceRequirements describes the compute resource @@ -465,10 +462,7 @@ spec: x-kubernetes-map-type: atomic type: object nvIpam: - description: |- - NVIPAMSpec describes configuration options for nv-ipam - 1. Image information for nv-ipam - 2. Configuration for nv-ipam + description: Configuration options nv-ipam properties: containerResources: description: ResourceRequirements describes the compute resource @@ -538,8 +532,7 @@ spec: - version type: object ofedDriver: - description: OFEDDriverSpec describes configuration options for OFED - driver + description: Configuration options for OFED driver properties: certConfig: description: 'Optional: Custom TLS certificates configuration @@ -794,8 +787,8 @@ spec: if set to false all other options are ignored type: boolean drain: - description: DrainSpec describes configuration for node drain - during automatic upgrade + description: The configuration for node drain during automatic + upgrade properties: deleteEmptyDir: default: false @@ -839,8 +832,7 @@ spec: and drain the node before loading the driver) type: boolean waitForCompletion: - description: WaitForCompletionSpec describes the configuration - for waiting on job completions + description: The configuration for waiting on pods completions properties: podSelector: description: |- @@ -867,10 +859,7 @@ spec: - version type: object rdmaSharedDevicePlugin: - description: |- - DevicePluginSpec describes configuration options for device plugin - 1. Image information for device plugin - 2. Device plugin configuration + description: Configuration options for RDMA shared device plugin properties: config: description: Configuration for the component as a string @@ -943,8 +932,7 @@ spec: - version type: object secondaryNetwork: - description: SecondaryNetworkSpec describes configuration options - for secondary network + description: Configuration options for secondary network properties: cniPlugins: description: Image information for CNI plugins @@ -1219,10 +1207,7 @@ spec: type: object type: object sriovDevicePlugin: - description: |- - DevicePluginSpec describes configuration options for device plugin - 1. Image information for device plugin - 2. Device plugin configuration + description: Configuration options for SRIOV device plugin properties: config: description: Configuration for the component as a string @@ -1336,7 +1321,7 @@ spec: type: array type: object status: - description: NicClusterPolicyStatus defines the observed state of NicClusterPolicy + description: Defines the observed state of NicClusterPolicy properties: appliedStates: description: AppliedStates provide a finer view of the observed state @@ -1350,9 +1335,12 @@ spec: the state is in this condition type: string name: + description: Name of the deployed component this state refers + to type: string state: - description: State represents reconcile state of the system. + description: The state of the deployed component. ("ready", + "notReady", "ignore", "error") enum: - ready - notReady