Platform API & Self-Service Labs

# db-crd.yaml — Lab 1. A platform API with a schema, printer columns and /status.
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.platform.acme.io      # MUST be <plural>.<group>
spec:
  group: platform.acme.io
  scope: Namespaced
  names:
    kind: Database
    plural: databases
    singular: database
    shortNames: [db]
    categories: [platform]
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: [engine, team]
              properties:
                engine:   { type: string, enum: [postgres, mysql] }
                version:  { type: string, default: "16" }
                size:     { type: string, enum: [small, medium, large], default: small }
                replicas: { type: integer, minimum: 1, maximum: 5, default: 1 }
                team:     { type: string, pattern: "^[a-z][a-z0-9-]{2,20}$" }
                highAvailability: { type: boolean, default: false }
            status:
              type: object
              properties:
                phase:              { type: string }
                endpoint:           { type: string }
                observedGeneration: { type: integer }
                conditions:
                  type: array
                  x-kubernetes-list-type: map
                  x-kubernetes-list-map-keys: [type]
                  items:
                    type: object
                    required: [type, status, lastTransitionTime, reason, message]
                    properties:
                      type:               { type: string }
                      status:             { type: string, enum: ["True", "False", "Unknown"] }
                      reason:             { type: string }
                      message:            { type: string }
                      observedGeneration: { type: integer }
                      lastTransitionTime: { type: string, format: date-time }
      subresources:
        status: {}
      additionalPrinterColumns:
        - { name: Engine, type: string, jsonPath: .spec.engine }
        - { name: Size,   type: string, jsonPath: .spec.size }
        - { name: Team,   type: string, jsonPath: .spec.team }
        - { name: Phase,  type: string, jsonPath: .status.phase }
        - { name: Age,    type: date,   jsonPath: .metadata.creationTimestamp }

# orders-db.yaml — Lab 2. Note what is NOT here: version, size, replicas, highAvailability.
apiVersion: platform.acme.io/v1alpha1
kind: Database
metadata:
  name: orders-db
  namespace: checkout
spec:
  engine: postgres
  team: checkout

# bad-db.yaml — Lab 3. Four deliberate crimes. Apply them ONE at a time.
apiVersion: platform.acme.io/v1alpha1
kind: Database
metadata: { name: bad-db, namespace: checkout }
spec:
  engine: banana            # 1. not in the enum   -> rejected
  team: Payments!           # 2. fails the pattern -> rejected
  replicas: 9               # 3. above maximum: 5  -> rejected
  nickname: hunter2         # 4. undeclared field  -> SILENTLY PRUNED, not rejected

# Lab 4 — add to db-crd.yaml, then re-apply the CRD.
# (A) cross-field + object-level rules: put these on the spec object itself.
            spec:
              type: object
              x-kubernetes-validations:
                - rule: "!has(self.highAvailability) || !self.highAvailability || self.replicas >= 3"
                  message: "highAvailability requires replicas >= 3"
                - rule: "self.size != 'small' || !self.highAvailability"
                  message: "small databases cannot be highly available — pick medium or large"
              required: [engine, team]
              properties:
                # (B) a transition rule: oldSelf makes the field immutable after creation.
                engine:
                  type: string
                  enum: [postgres, mysql]
                  x-kubernetes-validations:
                    - rule: "self == oldSelf"
                      message: "engine is immutable — create a new Database instead"

# Lab 5 — scaffold the operator. The generated CRD REPLACES your hand-written one,
# so clear the old registration first to avoid a confusing merge.
kubectl delete crd databases.platform.acme.io

mkdir -p ~/labs/db-operator && cd ~/labs/db-operator
kubebuilder init --domain acme.io --repo acme.io/db-operator
kubebuilder create api --group platform --version v1alpha1 --kind Database --resource --controller
# --resource and --controller answer the two prompts up front; omit them and it asks y/n instead.
# --domain acme.io + --group platform = the API group platform.acme.io from Lab 1.

# edit api/v1alpha1/database_types.go and internal/controller/database_controller.go,
# then regenerate + install + run the controller OUTSIDE the cluster:
make manifests generate
make install                 # applies config/crd/bases/*.yaml
make run                     # leave this running in its own terminal

// api/v1alpha1/database_types.go — markers generate the schema you hand-wrote in Lab 1.
type DatabaseSpec struct {
	// +kubebuilder:validation:Enum=postgres;mysql
	// this marker is how your Lab 4 CEL survives regeneration — without it the
	// generated CRD ships with no x-kubernetes-validations at all.
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="engine is immutable; create a new Database instead"
	Engine string `json:"engine"`
	// +kubebuilder:validation:Pattern=`^[a-z][a-z0-9-]{2,20}$`
	Team string `json:"team"`
	// +kubebuilder:default=small
	// +kubebuilder:validation:Enum=small;medium;large
	Size string `json:"size,omitempty"`
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=5
	Replicas int32 `json:"replicas,omitempty"`
}

type DatabaseStatus struct {
	Phase              string             `json:"phase,omitempty"`
	ObservedGeneration int64              `json:"observedGeneration,omitempty"`
	Conditions         []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:shortName=db,categories=platform
// +kubebuilder:printcolumn:name="Engine",type=string,JSONPath=`.spec.engine`
// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
type Database struct { /* ... generated ... */ }

// internal/controller/database_controller.go — Labs 6, 7 and 8 all live in this one func.
const dbFinalizer = "platform.acme.io/finalizer"

func (r *DatabaseReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	var db platformv1alpha1.Database
	if err := r.Get(ctx, req.NamespacedName, &db); err != nil {
		return ctrl.Result{}, client.IgnoreNotFound(err)   // gone; children GC'd via ownerRefs
	}

	// --- Lab 7: deletion path. Runs only once deletionTimestamp is set. ---
	if !db.DeletionTimestamp.IsZero() {
		if controllerutil.ContainsFinalizer(&db, dbFinalizer) {
			// pretend-expensive cleanup: final backup, deprovision the external thing
			log.FromContext(ctx).Info("running cleanup before delete", "db", db.Name)
			controllerutil.RemoveFinalizer(&db, dbFinalizer)
			if err := r.Update(ctx, &db); err != nil {
				return ctrl.Result{}, err
			}
		}
		return ctrl.Result{}, nil                          // object disappears now
	}
	if controllerutil.AddFinalizer(&db, dbFinalizer) {
		if err := r.Update(ctx, &db); err != nil {
			return ctrl.Result{}, err
		}
	}

	// --- Lab 5 + 6: build the child and stamp ownership on it. ---
	dep := &appsv1.Deployment{ObjectMeta: metav1.ObjectMeta{
		Name: db.Name + "-" + db.Spec.Engine, Namespace: db.Namespace}}
	if _, err := controllerutil.CreateOrUpdate(ctx, r.Client, dep, func() error {
		dep.Spec = desiredPodSpec(&db)                     // your helper
		return controllerutil.SetControllerReference(&db, dep, r.Scheme)   // ownerRef
	}); err != nil {
		return ctrl.Result{}, err
	}

	// --- Lab 8: report back. status is the contract with your users. ---
	meta.SetStatusCondition(&db.Status.Conditions, metav1.Condition{
		Type:               "Ready",
		Status:             metav1.ConditionTrue,
		Reason:             "Provisioned",
		Message:            "database workload is running",
		ObservedGeneration: db.Generation,
	})
	db.Status.Phase = "Ready"
	db.Status.ObservedGeneration = db.Generation           // "I have seen this spec"
	return ctrl.Result{}, r.Status().Update(ctx, &db)
}

# Lab 9 — Crossplane + a provider that needs no cloud account.
helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
helm install crossplane crossplane-stable/crossplane \
  --namespace crossplane-system --create-namespace --wait

kubectl get pods -n crossplane-system

# provider-kubernetes provisions objects INSIDE this cluster — perfect for a lab.
cat <<'EOF' | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-kubernetes
spec:
  package: xpkg.upbound.io/crossplane-contrib/provider-kubernetes:v0.14.0
EOF

kubectl get providers -w        # wait for INSTALLED=True HEALTHY=True, then Ctrl-C

# which Object version did THIS build install? Use whatever this prints in Lab 10.
kubectl api-resources --api-group=kubernetes.crossplane.io

# the provider's ServiceAccount needs rights to create what it composes (lab-grade RBAC)
SA=$(kubectl -n crossplane-system get sa -o name | grep provider-kubernetes | sed 's|.*/||')
echo "provider SA: ${SA:-NONE — the provider is not healthy yet, wait and re-run}"
kubectl create clusterrolebinding provider-kubernetes-admin \
  --clusterrole=cluster-admin --serviceaccount="crossplane-system:${SA}"

cat <<'EOF' | kubectl apply -f -
apiVersion: kubernetes.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: InjectedIdentity
EOF

# Lab 10 — xrd.yaml: the API and the recipe. The order form is a SECOND file,
# because the claim's CRD does not exist until the XRD below is Established.
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xappdatabases.platform.acme.io
spec:
  group: platform.acme.io
  names:      { kind: XAppDatabase, plural: xappdatabases }
  claimNames: { kind: AppDatabase,  plural: appdatabases }     # the namespaced front door
  versions:
    - name: v1alpha1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: [parameters]
              properties:
                parameters:
                  type: object
                  required: [size]
                  properties:
                    size: { type: string, enum: [small, large] }
---
# the composition pipeline needs a function; older Crossplane used mode: Resources instead
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-patch-and-transform
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.7.0
---
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: appdatabase.kubernetes
spec:
  compositeTypeRef:
    apiVersion: platform.acme.io/v1alpha1
    kind: XAppDatabase
  mode: Pipeline
  pipeline:
    - step: render
      functionRef: { name: function-patch-and-transform }
      input:
        apiVersion: pt.fn.crossplane.io/v1beta1
        kind: Resources
        resources:
          - name: config
            base:
              apiVersion: kubernetes.crossplane.io/v1alpha2   # match Lab 9's api-resources output
              kind: Object
              spec:
                providerConfigRef: { name: default }
                forProvider:
                  manifest:
                    apiVersion: v1
                    kind: ConfigMap
                    metadata:
                      namespace: checkout
                      name: placeholder          # patched below
                    data:
                      size: placeholder
            patches:
              - type: FromCompositeFieldPath
                fromFieldPath: metadata.name
                toFieldPath: spec.forProvider.manifest.metadata.name
              - type: FromCompositeFieldPath
                fromFieldPath: spec.parameters.size
                toFieldPath: spec.forProvider.manifest.data.size

# ---------------------------------------------------------------------------
# claim.yaml — a SEPARATE file. Apply it only after xrd.yaml is Established.
# ---------------------------------------------------------------------------
# apiVersion: platform.acme.io/v1alpha1
# kind: AppDatabase                                # Dot writes ONLY this
# metadata:
#   name: orders
#   namespace: checkout
# spec:
#   parameters:
#     size: small

# Lab 11 — break it, then walk the chain from the top down.
# Aim the composed ConfigMap at a namespace that does not exist. (Do NOT try to break it
# by deleting the ProviderConfig: it carries an in-use finalizer, so the delete just hangs
# and nothing actually fails — a good lesson in its own right.)
kubectl patch composition appdatabase.kubernetes --type=json \
  -p '[{"op":"replace","path":"/spec/pipeline/0/input/resources/0/base/spec/forProvider/manifest/metadata/namespace","value":"nowhere"}]'

# nudge the claim so the composite re-renders with the poisoned base
kubectl patch appdatabase orders -n checkout --type=merge \
  -p '{"spec":{"parameters":{"size":"large"}}}'

# 1. the claim: is it Synced? Ready? What do its events say?
kubectl describe appdatabase orders -n checkout

# 2. hop to the composite it points at
kubectl get appdatabase orders -n checkout -o jsonpath='{.spec.resourceRef.kind}/{.spec.resourceRef.name}'
kubectl describe xappdatabase <name-from-above>

# 3. hop to every managed resource the composite owns
kubectl get managed
kubectl describe object <name>

# 4. and when the object itself looks fine, ask the controller
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes --tail=60
kubectl get events -n checkout --sort-by=.lastTimestamp | tail -20

# 5. repair — put the namespace back and touch NOTHING else
kubectl patch composition appdatabase.kubernetes --type=json \
  -p '[{"op":"replace","path":"/spec/pipeline/0/input/resources/0/base/spec/forProvider/manifest/metadata/namespace","value":"checkout"}]'
kubectl get appdatabase orders -n checkout -w    # READY flips True on its own, then Ctrl-C

# Capstone — template.yaml. Put it in a folder with skeleton/manifest.yaml alongside.
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: database-request
  title: Request a Database
  description: Generates a platform.acme.io Database manifest — no YAML required
spec:
  owner: platform-team
  type: resource
  parameters:
    - title: Your database
      required: [name, team, engine]
      properties:
        name:   { type: string, title: Name }
        team:   { type: string, title: Owning team }
        engine: { type: string, title: Engine, enum: [postgres, mysql] }
        size:   { type: string, title: Size, enum: [small, medium, large], default: small }
  steps:
    - id: render
      name: Render the manifest
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name:   ${{ parameters.name }}
          team:   ${{ parameters.team }}
          engine: ${{ parameters.engine }}
          size:   ${{ parameters.size }}
  output:
    text:
      - title: Your Database manifest — copy this into manifest.yaml
        content: |
          apiVersion: platform.acme.io/v1alpha1
          kind: Database
          metadata:
            name: ${{ parameters.name }}
            namespace: checkout
          spec:
            engine: ${{ parameters.engine }}
            team: ${{ parameters.team }}
            size: ${{ parameters.size }}
      - title: Next step
        content: Commit that manifest — GitOps will apply it.

# skeleton/manifest.yaml — same content, rendered into the task workspace by fetch:template.
# (A real template would add a publish:* step to open a PR with this file; the output
#  block above is the lab-sized substitute so you get something to paste.)
# apiVersion: platform.acme.io/v1alpha1
# kind: Database
# metadata:
#   name: ${{ values.name }}
#   namespace: checkout
# spec:
#   engine: ${{ values.engine }}
#   team: ${{ values.team }}
#   size: ${{ values.size }}