CRD Design and Go API Types

Table of Contents

1. Introduction

2. CRD Anatomy

3. Designing the AppStack API

4. Writing the Go Types

5. kubebuilder Validation Markers

6. Status Design with Conditions

7. Generating CRD YAML

8. Writing a Sample Manifest

9. Common Mistakes

---

Introduction

CRD design is where most operator complexity starts. Getting the API types right matters more than getting the reconcile logic right — type changes are hard to migrate, and a poorly modelled spec leads to a controller full of edge cases.

This article covers:

• What a CRD actually is in Go

• Designing the AppStack spec and status

• Using kubebuilder markers for validation and generation

• How make manifests turns Go structs into OpenAPI-validated CRD YAML

---

CRD Anatomy

A CRD is a Kubernetes API extension. When you apply a CRD to a cluster, the API server starts accepting resources of that type. A CRD defines:

• API group/version/kind: apps.htunn.io/v1alpha1/AppStack

• Spec schema: the fields users define (desired state)

• Status schema: the fields the controller writes (observed state)

• Validation: field types, required/optional, enum values, numeric ranges

• Subresources: whether status and scale are separate subresources

In Go, a CRD is represented by three structs:

// AppStack is the Schema for the appstacks API
type AppStack struct {
    metav1.TypeMeta   `json:",inline"`        // apiVersion, kind
    metav1.ObjectMeta `json:"metadata,omitempty"`  // name, namespace, labels, etc.

    Spec   AppStackSpec   `json:"spec,omitempty"`
    Status AppStackStatus `json:"status,omitempty"`
}

// AppStackSpec defines the desired state
type AppStackSpec struct { ... }

// AppStackStatus defines the observed state
type AppStackStatus struct { ... }

The metav1.TypeMeta and metav1.ObjectMeta are embedded from k8s.io/apimachinery/pkg/apis/meta/v1. You don't define them — they're inherited.

---

Designing the AppStack API

The AppStack resource manages three Kubernetes resources for a given application:

• Deployment — runs the container

• Service — exposes it on a port within the cluster

• HorizontalPodAutoscaler — scales replicas based on CPU (optional)

What does the user need to declare? Only what's variable across applications:

Field	What it controls
spec.image	Container image (repository + tag)
spec.port	Port the container listens on
spec.replicas	Desired replica count (overridden by HPA if autoscaling enabled)
spec.env	Environment variables
spec.autoscaling.enabled	Whether to create an HPA
spec.autoscaling.minReplicas	HPA minimum
spec.autoscaling.maxReplicas	HPA maximum
spec.autoscaling.cpuTargetPercent	HPA CPU utilization target

Everything else — label selectors, pod templates, readiness probes — the operator sets with sensible defaults.

---

Writing the Go Types

Open api/v1alpha1/appstack_types.go. The scaffold already has stub structs. Replace them with the full type definition:

package v1alpha1

import (
    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// AppStackSpec defines the desired state of AppStack
type AppStackSpec struct {
    // Image is the container image to deploy.
    // +kubebuilder:validation:MinLength=1
    Image string `json:"image"`

    // Port is the port the container listens on.
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=65535
    Port int32 `json:"port"`

    // Replicas is the desired number of pod replicas.
    // Ignored when autoscaling is enabled.
    // +optional
    // +kubebuilder:default=1
    // +kubebuilder:validation:Minimum=0
    Replicas *int32 `json:"replicas,omitempty"`

    // Env is a list of environment variables to set in the container.
    // +optional
    Env []corev1.EnvVar `json:"env,omitempty"`

    // Autoscaling configures HorizontalPodAutoscaler for this AppStack.
    // +optional
    Autoscaling *AutoscalingSpec `json:"autoscaling,omitempty"`
}

// AutoscalingSpec configures the HPA for the AppStack.
type AutoscalingSpec struct {
    // Enabled controls whether an HPA is created.
    // +kubebuilder:default=false
    Enabled bool `json:"enabled"`

    // MinReplicas is the lower limit for the number of replicas.
    // +optional
    // +kubebuilder:default=1
    // +kubebuilder:validation:Minimum=1
    MinReplicas *int32 `json:"minReplicas,omitempty"`

    // MaxReplicas is the upper limit for the number of replicas.
    // +kubebuilder:validation:Minimum=1
    MaxReplicas int32 `json:"maxReplicas"`

    // CPUTargetPercent is the target CPU utilization percentage (0-100).
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=100
    // +kubebuilder:default=70
    CPUTargetPercent int32 `json:"cpuTargetPercent"`
}

// AppStackStatus defines the observed state of AppStack
type AppStackStatus struct {
    // Conditions represent the current state of the AppStack.
    // +optional
    // +listType=map
    // +listMapKey=type
    Conditions []metav1.Condition `json:"conditions,omitempty"`

    // ReadyReplicas is the number of ready replicas in the managed Deployment.
    // +optional
    ReadyReplicas int32 `json:"readyReplicas,omitempty"`

    // Phase is a summary of the current AppStack state.
    // +optional
    Phase AppStackPhase `json:"phase,omitempty"`

    // ObservedGeneration is the .metadata.generation that was last processed.
    // Used to detect spec changes that haven't been reconciled yet.
    // +optional
    ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

// AppStackPhase is the high-level lifecycle phase of an AppStack.
// +kubebuilder:validation:Enum=Pending;Running;Degraded;Error
type AppStackPhase string

const (
    AppStackPhasePending  AppStackPhase = "Pending"
    AppStackPhaseRunning  AppStackPhase = "Running"
    AppStackPhaseDegraded AppStackPhase = "Degraded"
    AppStackPhaseError    AppStackPhase = "Error"
)

// Condition type constants — used as the Type field in metav1.Condition
const (
    ConditionTypeAvailable   = "Available"
    ConditionTypeProgressing = "Progressing"
    ConditionTypeDegraded    = "Degraded"
)

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`
// +kubebuilder:printcolumn:name="Image",type=string,JSONPath=`.spec.image`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

// AppStack is the Schema for the appstacks API
type AppStack struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   AppStackSpec   `json:"spec,omitempty"`
    Status AppStackStatus `json:"status,omitempty"`
}

// +kubebuilder:object:root=true

// AppStackList contains a list of AppStack
type AppStackList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty"`
    Items           []AppStack `json:"items"`
}

func init() {
    SchemeBuilder.Register(&AppStack{}, &AppStackList{})
}

---

kubebuilder Validation Markers

kubebuilder reads Go struct comments that start with // +kubebuilder: and generates corresponding OpenAPI v3 schema in the CRD YAML. This means validation runs at the API server level — invalid resources are rejected before your controller ever sees them.

Common Validation Markers

// +kubebuilder:validation:MinLength=1       // string: minimum length
// +kubebuilder:validation:MaxLength=63      // string: maximum length
// +kubebuilder:validation:Pattern=`^[a-z]` // string: regex pattern
// +kubebuilder:validation:Minimum=1         // numeric: minimum value
// +kubebuilder:validation:Maximum=65535     // numeric: maximum value
// +kubebuilder:validation:Enum=A;B;C        // string: allowed values
// +kubebuilder:default=1                    // field default value
// +optional                                 // field is not required

Object-Level Markers

Applied to the top-level struct:

// +kubebuilder:object:root=true        // marks this as a CRD root type
// +kubebuilder:subresource:status      // enables status as a separate subresource
// +kubebuilder:printcolumn:...         // adds columns to `kubectl get` output

The subresource:status marker is important. It means:

• .spec updates go through r.Update()

• .status updates go through r.Status().Update()

• These are separate API calls, and separate RBAC permissions

This prevents users from accidentally overwriting status when updating spec.

Print Columns

The printcolumn markers control what kubectl get appstack shows:

// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`
// +kubebuilder:printcolumn:name="Image",type=string,JSONPath=`.spec.image`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

Result:

NAME         PHASE     READY   IMAGE                              AGE
api-service  Running   3       ghcr.io/htunn/api-service:v1.2.0  2d

---

Status Design with Conditions

metav1.Condition is the standard Kubernetes API type for expressing resource status. Using it correctly makes your operator consistent with built-in controllers and visible to standard tooling.

type Condition struct {
    Type               string             // e.g. "Available", "Progressing"
    Status             ConditionStatus    // True, False, or Unknown
    ObservedGeneration int64              // generation this condition was observed at
    LastTransitionTime Time               // when Status last changed
    Reason             string             // machine-readable, CamelCase reason code
    Message            string             // human-readable explanation
}

For AppStack, three conditions cover the lifecycle:

Condition	True means	False means
Available	≥1 replica is ready	Deployment exists but has 0 ready replicas
Progressing	Reconcile is actively working	Reconcile is stable, no changes in progress
Degraded	An error occurred	No errors

A healthy AppStack looks like:

Available   True    DeploymentReady     3/3 replicas ready
Progressing False   ReconcileComplete   No changes pending
Degraded    False   -                   -

A deploying AppStack:

Available   False   DeploymentPending   0/3 replicas ready
Progressing True    DeploymentUpdating  Updating to image v1.3.0
Degraded    False   -                   -

A failed AppStack:

Available   False   DeploymentFailed    Image pull failed
Progressing False   ReconcileError      -
Degraded    True    ImagePullBackOff    Container ghcr.io/htunn/api:v9.9 failed to pull

Reason Codes

Reason must be CamelCase with no spaces. These are constants:

const (
    ReasonDeploymentReady    = "DeploymentReady"
    ReasonDeploymentPending  = "DeploymentPending"
    ReasonDeploymentFailed   = "DeploymentFailed"
    ReasonDeploymentUpdating = "DeploymentUpdating"
    ReasonReconcileComplete  = "ReconcileComplete"
    ReasonReconcileError     = "ReconcileError"
    ReasonImagePullBackOff   = "ImagePullBackOff"
)

---

Generating CRD YAML

After writing the Go types:

make generate   # generates zz_generated.deepcopy.go
make manifests  # generates config/crd/bases/apps.htunn.io_appstacks.yaml

The generated CRD YAML looks like:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: appstacks.apps.htunn.io
spec:
  group: apps.htunn.io
  names:
    kind: AppStack
    listKind: AppStackList
    plural: appstacks
    singular: appstack
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        properties:
          spec:
            properties:
              image:
                minLength: 1
                type: string
              port:
                format: int32
                maximum: 65535
                minimum: 1
                type: integer
              replicas:
                default: 1
                format: int32
                minimum: 0
                type: integer
              autoscaling:
                properties:
                  enabled:
                    default: false
                    type: boolean
                  maxReplicas:
                    format: int32
                    minimum: 1
                    type: integer
                  # ... and so on
    subresources:
      status: {}
    additionalPrinterColumns:
    - jsonPath: .status.phase
      name: Phase
      type: string
    - jsonPath: .status.readyReplicas
      name: Ready
      type: integer

Check the generated file at config/crd/bases/apps.htunn.io_appstacks.yaml to verify your markers produced the intended schema.

Install the updated CRD:

make install

# Verify the schema
kubectl get crd appstacks.apps.htunn.io -o jsonpath='{.spec.versions[0].schema}' | python3 -m json.tool | head -60

---

Writing a Sample Manifest

kubebuilder generates config/samples/apps_v1alpha1_appstack.yaml. Update it with a realistic sample:

apiVersion: apps.htunn.io/v1alpha1
kind: AppStack
metadata:
  name: api-service
  namespace: default
  labels:
    app.kubernetes.io/name: api-service
    app.kubernetes.io/managed-by: appstack-operator
spec:
  image: ghcr.io/htunn/api-service:v1.2.0
  port: 8080
  replicas: 2
  env:
    - name: LOG_LEVEL
      value: info
    - name: METRICS_ENABLED
      value: "true"
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 8
    cpuTargetPercent: 60

Apply it:

kubectl apply -f config/samples/apps_v1alpha1_appstack.yaml
kubectl get appstack -n default

At this point, the spec is accepted by the API server (validation passes), but no resources are created yet — that's the controller's job, covered in the next article.

---

Common Mistakes

Forgetting +kubebuilder:subresource:status Without this, calling r.Status().Update() fails with a "not found" error on the status subresource. Always add this marker to your root type.

Using error in status fields Status structs must be JSON-serializable and deepcopy-able. Use string for error messages, not error. The metav1.Condition.Message field is the right place for error descriptions.

Making required fields optional in the spec If image is truly required to do anything, mark it required (no // +optional). Accepting a resource with an empty image and failing in the controller is harder to debug than a validation rejection at apply time.

Not using pointer types for optional numeric fields Replicas *int32 vs Replicas int32 — the pointer form allows nil (field omitted). Non-pointer int32 defaults to 0 when not provided, which is a valid but often undesired value. Use pointer types for optional numeric fields.

Editing zz_generated.deepcopy.go This file is regenerated on every make generate. Never edit it manually.

---

Next: The Controller and Reconcile Loop →