fix: add fields documentation in CRDs

deploy/cloud/operator/Makefile

@@ -58,7 +58,8 @@ ensure-yq:
 
 .PHONY: manifests
 manifests: controller-gen ensure-yq ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
-	$(CONTROLLER_GEN) rbac:roleName=manager-role crd:maxDescLen=0 webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+	# Use a large maxDescLen to ensure all field comments are included as OpenAPI descriptions
+	$(CONTROLLER_GEN) rbac:roleName=manager-role crd:maxDescLen=100000 webhook paths="./..." output:crd:artifacts:config=config/crd/bases
 	echo "Removing name from mainContainer required fields"
 	for file in config/crd/bases/*.yaml; do \
 		yq eval '(.. | select(has("mainContainer")) | .mainContainer.required) |= (. - ["name"])' -i --indent 2 $$file || exit 1; \
@@ -96,6 +97,7 @@ manifests: controller-gen ensure-yq ## Generate WebhookConfiguration, ClusterRol
 			yq eval '.metadata.annotations."helm.sh/resource-policy" = "keep"' -i "$$file"; \
 		fi; \
 	done
+	cp config/crd/bases/*.yaml ../helm/crds/templates/
 
 .PHONY: generate
 generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.

deploy/cloud/operator/api/v1alpha1/dynamocomponentdeployment_types.go

@@ -38,6 +38,8 @@ const (
 
 // DynamoComponentDeploymentSpec defines the desired state of DynamoComponentDeployment
 type DynamoComponentDeploymentSpec struct {
+	// DynamoComponent selects the Dynamo component from the archive to deploy.
+	// Typically corresponds to a component defined in the packaged Dynamo artifacts.
 	DynamoComponent string `json:"dynamoComponent,omitempty"`
 	// contains the tag of the DynamoComponent: for example, "my_package:MyService"
 	DynamoTag string `json:"dynamoTag,omitempty"`
@@ -46,6 +48,8 @@ type DynamoComponentDeploymentSpec struct {
 	// +kubebuilder:validation:Enum=sglang;vllm;trtllm
 	BackendFramework string `json:"backendFramework,omitempty"`
 
+	// DynamoComponentDeploymentSharedSpec embeds common deployment and runtime
+	// settings that apply to the component (resources, scaling, ingress, etc.).
 	DynamoComponentDeploymentSharedSpec `json:",inline"`
 }
 
@@ -57,61 +61,79 @@ type DynamoComponentDeploymentSharedSpec struct {
 	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
+	// Annotations to add to generated Kubernetes resources for this component
+	// (such as Pod, Service, and Ingress when applicable).
 	Annotations map[string]string `json:"annotations,omitempty"`
-	Labels      map[string]string `json:"labels,omitempty"`
+	// Labels to add to generated Kubernetes resources for this component.
+	Labels map[string]string `json:"labels,omitempty"`
 
-	// contains the name of the service
+	// contains the name of the component
 	ServiceName string `json:"serviceName,omitempty"`
 
+	// ComponentType indicates the role of this component (for example, "main").
 	ComponentType string `json:"componentType,omitempty"`
 
 	// dynamo namespace of the service (allows to override the dynamo namespace of the service defined in annotations inside the dynamo archive)
 	DynamoNamespace *string `json:"dynamoNamespace,omitempty"`
 
-	Resources        *dynamoCommon.Resources    `json:"resources,omitempty"`
-	Autoscaling      *Autoscaling               `json:"autoscaling,omitempty"`
-	Envs             []corev1.EnvVar            `json:"envs,omitempty"`
-	EnvFromSecret    *string                    `json:"envFromSecret,omitempty"`
-	PVC              *PVC                       `json:"pvc,omitempty"`
-	RunMode          *RunMode                   `json:"runMode,omitempty"`
-	ExternalServices map[string]ExternalService `json:"externalServices,omitempty"`
-
+	// Resources requested and limits for this component, including CPU, memory,
+	// GPUs/devices, and any runtime-specific resources.
+	Resources *dynamoCommon.Resources `json:"resources,omitempty"`
+	// Autoscaling config for this component (replica range, target utilization, etc.).
+	Autoscaling *Autoscaling `json:"autoscaling,omitempty"`
+	// Envs defines additional environment variables to inject into the component containers.
+	Envs []corev1.EnvVar `json:"envs,omitempty"`
+	// EnvFromSecret references a Secret whose key/value pairs will be exposed as
+	// environment variables in the component containers.
+	EnvFromSecret *string `json:"envFromSecret,omitempty"`
+	// PVC config describing volumes to be mounted by the component.
+	PVC *PVC `json:"pvc,omitempty"`
+
+	// Ingress config to expose the component outside the cluster (or through a service mesh).
 	Ingress *IngressSpec `json:"ingress,omitempty"`
 
 	// +optional
+	// ExtraPodMetadata adds labels/annotations to the created Pods.
 	ExtraPodMetadata *dynamoCommon.ExtraPodMetadata `json:"extraPodMetadata,omitempty"`
 	// +optional
+	// ExtraPodSpec merges additional fields into the generated PodSpec for advanced
+	// customization (tolerations, node selectors, affinity, etc.).
 	ExtraPodSpec *dynamoCommon.ExtraPodSpec `json:"extraPodSpec,omitempty"`
 
-	LivenessProbe  *corev1.Probe `json:"livenessProbe,omitempty"`
+	// LivenessProbe to detect and restart unhealthy containers.
+	LivenessProbe *corev1.Probe `json:"livenessProbe,omitempty"`
+	// ReadinessProbe to signal when the container is ready to receive traffic.
 	ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"`
-	Replicas       *int32        `json:"replicas,omitempty"`
-}
-
-type RunMode struct {
-	Standalone *bool `json:"standalone,omitempty"`
-}
-
-type ExternalService struct {
-	DeploymentSelectorKey   string `json:"deploymentSelectorKey,omitempty"`
-	DeploymentSelectorValue string `json:"deploymentSelectorValue,omitempty"`
+	// Replicas is the desired number of Pods for this component when autoscaling is not used.
+	Replicas *int32 `json:"replicas,omitempty"`
 }
 
 type IngressTLSSpec struct {
+	// SecretName is the name of a Kubernetes Secret containing the TLS certificate and key.
 	SecretName string `json:"secretName,omitempty"`
 }
 
 type IngressSpec struct {
-	Enabled                    bool              `json:"enabled,omitempty"`
-	Host                       string            `json:"host,omitempty"`
-	UseVirtualService          bool              `json:"useVirtualService,omitempty"`
-	VirtualServiceGateway      *string           `json:"virtualServiceGateway,omitempty"`
-	HostPrefix                 *string           `json:"hostPrefix,omitempty"`
-	Annotations                map[string]string `json:"annotations,omitempty"`
-	Labels                     map[string]string `json:"labels,omitempty"`
-	TLS                        *IngressTLSSpec   `json:"tls,omitempty"`
-	HostSuffix                 *string           `json:"hostSuffix,omitempty"`
-	IngressControllerClassName *string           `json:"ingressControllerClassName,omitempty"`
+	// Enabled exposes the component through an ingress or virtual service when true.
+	Enabled bool `json:"enabled,omitempty"`
+	// Host is the base host name to route external traffic to this component.
+	Host string `json:"host,omitempty"`
+	// UseVirtualService indicates whether to configure a service-mesh VirtualService instead of a standard Ingress.
+	UseVirtualService bool `json:"useVirtualService,omitempty"`
+	// VirtualServiceGateway optionally specifies the gateway name to attach the VirtualService to.
+	VirtualServiceGateway *string `json:"virtualServiceGateway,omitempty"`
+	// HostPrefix is an optional prefix added before the host.
+	HostPrefix *string `json:"hostPrefix,omitempty"`
+	// Annotations to set on the generated Ingress/VirtualService resources.
+	Annotations map[string]string `json:"annotations,omitempty"`
+	// Labels to set on the generated Ingress/VirtualService resources.
+	Labels map[string]string `json:"labels,omitempty"`
+	// TLS holds the TLS configuration used by the Ingress/VirtualService.
+	TLS *IngressTLSSpec `json:"tls,omitempty"`
+	// HostSuffix is an optional suffix appended after the host.
+	HostSuffix *string `json:"hostSuffix,omitempty"`
+	// IngressControllerClassName selects the ingress controller class (e.g., "nginx").
+	IngressControllerClassName *string `json:"ingressControllerClassName,omitempty"`
 }
 
 func (i *IngressSpec) IsVirtualServiceEnabled() bool {
@@ -125,8 +147,12 @@ func (i *IngressSpec) IsVirtualServiceEnabled() bool {
 type DynamoComponentDeploymentStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
+	// Conditions captures the latest observed state of the component (including
+	// availability and readiness) using standard Kubernetes condition types.
 	Conditions []metav1.Condition `json:"conditions"`
 
+	// PodSelector contains the labels that can be used to select Pods belonging to
+	// this component deployment.
 	PodSelector map[string]string `json:"podSelector,omitempty"`
 }
 
@@ -143,7 +169,9 @@ type DynamoComponentDeployment struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   DynamoComponentDeploymentSpec   `json:"spec,omitempty"`
+	// Spec defines the desired state for this Dynamo component deployment.
+	Spec DynamoComponentDeploymentSpec `json:"spec,omitempty"`
+	// Status reflects the current observed state of the component deployment.
 	Status DynamoComponentDeploymentStatus `json:"status,omitempty"`
 }
 

deploy/cloud/operator/api/v1alpha1/dynamographdeployment_types.go

@@ -29,25 +29,30 @@ import (
 
 // DynamoGraphDeploymentSpec defines the desired state of DynamoGraphDeployment.
 type DynamoGraphDeploymentSpec struct {
-	// required
+	// DynamoGraph selects the graph (workflow/topology) to deploy. This must match
+	// a graph name packaged with the Dynamo archive.
 	DynamoGraph string `json:"dynamoGraph,omitempty"`
-	// optional
-	// key is the name of the service defined in DynamoComponent
-	// value is the DynamoComponentDeployment override for that service
-	// if not set, the DynamoComponentDeployment will be used as is
+	// Services allows per-service overrides of the component deployment settings.
+	// - key: name of the service defined by the DynamoComponent
+	// - value: overrides for that service
+	// If not set for a service, the default DynamoComponentDeployment values are used.
 	// +kubebuilder:validation:Optional
 	Services map[string]*DynamoComponentDeploymentOverridesSpec `json:"services,omitempty"`
-	// Environment variables to be set in the deployment
+	// Envs are environment variables applied to all services in the graph unless
+	// overridden by service-specific configuration.
 	// +kubebuilder:validation:Optional
 	Envs []corev1.EnvVar `json:"envs,omitempty"`
-	// BackendFramework specifies the backend framework (e.g., "sglang", "vllm", "trtllm")
+	// BackendFramework specifies the backend framework (e.g., "sglang", "vllm", "trtllm").
 	// +kubebuilder:validation:Enum=sglang;vllm;trtllm
 	BackendFramework string `json:"backendFramework,omitempty"`
 }
 
 // DynamoGraphDeploymentStatus defines the observed state of DynamoGraphDeployment.
 type DynamoGraphDeploymentStatus struct {
-	State      string             `json:"state,omitempty"`
+	// State is a high-level textual status of the graph deployment lifecycle.
+	State string `json:"state,omitempty"`
+	// Conditions contains the latest observed conditions of the graph deployment.
+	// The slice is merged by type on patch updates.
 	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`
 }
 
@@ -59,7 +64,9 @@ type DynamoGraphDeployment struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   DynamoGraphDeploymentSpec   `json:"spec,omitempty"`
+	// Spec defines the desired state for this graph deployment.
+	Spec DynamoGraphDeploymentSpec `json:"spec,omitempty"`
+	// Status reflects the current observed state of this graph deployment.
 	Status DynamoGraphDeploymentStatus `json:"status,omitempty"`
 }