Functions CRD

[lkingland]

Functions CRD Status Design

Architecture Context

The Functions CRD follows a GitOps model where Git is the source of truth. The CRD spec is intentionally minimal - Kubernetes developers expecting to "drive" everything from the CRD should understand that the Function's state lives in its repository, not the CRD.

Division of responsibilities:

• CI/CD → Builds and deploys when function source changes
• Operator → Rebuilds when middleware updates (same commit, new runtime layers), reconciles state, reports status

Middleware versions are embedded in the func binary. When the operator triggers a rebuild via func deploy --remote (Tekton Pipeline), it updates the runtime without requiring Function authors to change anything. Full dependency inversion.

---

Spec (Minimal by Design)

apiVersion: functions.knative.dev/v1alpha1
kind: Function
metadata:
  name: my-function.example.com # FQDN is a Function's primary key, and can be derived by the Operator
spec:
  repository: https://github.com/user/my-function.git # Required
  autoUpdate: true  # Optional - omit to inherit from operator default

---

Status (Rich by Design)

status:
  # Top-level state
  phase: Ready  # Pending | Rebuilding | Deploying | Ready | Failed | Degraded
  observedGeneration: 1

  # Git state (derived from func.yaml cluster mapping)
  git:
    clusterIdentity: "https://api.cluster-b.example.com:6443"
    resolvedBranch: develop
    observedCommit: "a1b2c3d"
    lastChecked: "2026-01-29T22:30:00Z"

  # Current deployment
  deployment:
    image: "quay.io/user/my-function@sha256:..."
    imageBuilt: "2026-01-29T20:00:00Z"
    deployer: knative  # or "kubernetes"
    namespace: default
    runtime: go

  # Middleware tracking (operator's responsibility)
  middleware:
    current: "1.4.2"
    available: "1.4.3"  # Omit if current is latest
    autoUpdate:
      effective: true   # Resolved value being applied
      source: operator  # "operator" (inherited) | "function" (explicit override)
    pendingRebuild: true
    lastRebuild: "2026-01-28T10:00:00Z"

  # Autoscaled instances (Knative/KEDA)
  instances:
    ready: 3
    desired: 3
    pending: 0

  # Underlying Kubernetes resources
  services:
    - name: my-function
      kind: Service.serving.knative.dev/v1
      ready: true
      url: https://my-function.default.example.com
      latestRevision: my-function-00003
      createdAt: "2026-01-25T12:00:00Z"

  # Standard Kubernetes conditions
  conditions:
    - type: Ready
      status: "True"
      reason: ServiceHealthy
      lastTransitionTime: "2026-01-29T22:28:00Z"
    - type: RepositoryAccessible
      status: "True"
    - type: MiddlewareCurrent
      status: "False"
      reason: UpdatePending
      message: "1.4.3 available, rebuild queued"
    - type: ServiceReady
      status: "True"

  # Rolling event log (max 50 entries, FIFO)
  history:
    - time: "2026-01-29T22:28:00Z"
      type: Deployed
      message: "CI/CD deployed commit a1b2c3d"
    - time: "2026-01-28T10:00:00Z"
      type: Rebuilt
      message: "Middleware update 1.4.1 → 1.4.2"
    - time: "2026-01-25T12:00:00Z"
      type: Created
      message: "Initial deployment from commit 9f8e7d6"

---

Status Fields Reference

phase - High-level state: Pending, Rebuilding, Deploying, Ready, Failed, Degraded

git

• clusterIdentity - API server address used to resolve branch mapping
• resolvedBranch - Branch this cluster deploys from (derived from func.yaml)
• observedCommit - Git SHA currently deployed
• lastChecked - Last time operator checked the repo

deployment

• image - Full image reference with digest
• imageBuilt - When the image was built
• deployer - knative or kubernetes
• namespace - Deployment namespace
• runtime - Language runtime (go, node, python, etc.)

middleware

• current - Middleware version in deployed image
• available - Newer version available (omit if current)
• autoUpdate.effective - Resolved boolean being applied
• autoUpdate.source - operator (inherited) or function (overridden)
• pendingRebuild - True if rebuild queued
• lastRebuild - Timestamp of last operator-triggered rebuild

instances - ready, desired, pending counts for autoscaling (Knative/KEDA)

services - Array of underlying K8s resources with status

conditions - Standard K8s condition array

history - Rolling log, max 50 entries, FIFO eviction

---

Condition Types

• Ready - Overall health; true when function is serving traffic
• RepositoryAccessible - Can operator reach and read the git repo
• MiddlewareCurrent - Is deployed middleware the latest available
• ServiceReady - Is the underlying Knative Service / K8s Deployment healthy

---

Design Rationale

Why minimal spec? The Git repository is the source of truth. Everything about the Function (config, environment, scaling, subscriptions) lives in func.yaml in the repo. The CRD points to it; it doesn't duplicate it.

Why rich status? Kubernetes developers expect visibility. A single-field spec might feel "empty" - the status compensates by showing everything that's happening: what's deployed, from which commit, on which branch, with which middleware, how many instances, what resources were created. They can inspect the CRD and understand the full picture without digging through multiple resources.

Why autoUpdate inheritance? Fleet-level control with per-function override. Ops teams set the operator default; individual functions can opt out for stability-sensitive deployments.

---

Reconciliation Triggers

The operator updates status in response to two trigger mechanisms:

1. Annotation-based trigger (primary)

When func deploy completes, it touches the Function CRD via annotation:

metadata:
  name: my-function.example.com
  annotations:
    functions.knative.dev/last-deployed: "2026-01-29T22:30:00Z"
    functions.knative.dev/deployed-commit: "a1b2c3d"

This immediately triggers reconciliation. The operator:

1. Sees annotation changed
2. Inspects actual cluster state (Knative Service, pods, etc.)
3. Updates status to reflect reality

2. Periodic resync (backup)

A background resync runs on a configurable interval (default: 5 minutes) to catch edge cases where:

• Deploy completed but CRD annotation wasn't updated (network blip, crash)
• Owned resources changed externally
• Middleware updates became available

Reconciliation flow

┌─────────────────────────────────────────────────────────┐
│                    Trigger Sources                       │
├─────────────────────────────────────────────────────────┤
│  func deploy          Periodic resync      Owned resource│
│  (annotation)         (5 min default)      status change │
└─────────┬─────────────────┬─────────────────────┬───────┘
          │                 │                     │
          └─────────────────┼─────────────────────┘
                            ▼
                    ┌───────────────┐
                    │  Reconcile()  │
                    └───────┬───────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
    Check Git repo    Inspect Knative    Check middleware
    (branch, commit)  Service status     version
          │                 │                 │
          └─────────────────┼─────────────────┘
                            ▼
                    ┌───────────────┐
                    │ Update status │
                    └───────────────┘

Operator configuration

• resyncInterval (default: 5m) - Periodic reconciliation interval
• defaultAutoUpdate (default: true) - Fleet-wide default for middleware auto-updates