Kubernetes Extension Manifest Management

Kubernetes Extension Manifest Management is the practice of packaging, ordering, and deploying the full set of manifests that constitute an extension, CRDs, RBAC, webhook configurations, and the controller Deployment itself, as a coherent, reproducible unit, addressing the specific ordering and templating challenges that arise when an extension's own components depend on each other being installed in a particular sequence.

The Kubebuilder config Layout

Kustomize-Based Manifest Organization

config/
  crd/
    bases/
      databases.example.com_postgresclusters.yaml
  rbac/
    role.yaml
    role_binding.yaml
    service_account.yaml
  webhook/
    manifests.yaml
  manager/
    manager.yaml
  default/
    kustomization.yaml

The standard scaffold produced by Kubebuilder and the Operator SDK organizes each manifest category into its own directory, combined via Kustomize overlays under config/default, letting an extension's RBAC, CRDs, and Deployment each be generated, patched, and versioned independently while still producing a single coherent installable bundle.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../crd
  - ../rbac
  - ../manager
  - ../webhook

Ordering Dependencies Between Manifest Categories

CRDs Must Precede Custom Resources

kubectl apply -f config/crd/
kubectl apply -f config/samples/

A CustomResourceDefinition must exist before any instance of that custom resource type can be created; applying both in a single kubectl apply -f . over a directory generally works because the API server processes CRDs quickly, but a CI pipeline or GitOps controller enforcing strict per-manifest health checks before proceeding may need explicit sequencing (a wait step, or separate apply phases) to avoid a race where a custom resource is submitted before its CRD is fully established.

Webhooks Must Precede Enforcement of Their Rules

webhooks:
  - failurePolicy: Ignore

During initial installation, a webhook configuration referencing a Service whose backing Deployment has not yet become ready would, with failurePolicy: Fail, block every matching request cluster-wide until the webhook pod starts; many extension installers deliberately apply webhook configurations with Ignore during initial rollout, or delay applying them until the Deployment's readiness is confirmed, tightening to Fail only once the webhook is verified reachable.

Packaging Formats

Helm Charts

# templates/crds/postgrescluster-crd.yaml
{{- if .Values.installCRDs }}
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
...
{{- end }}

Helm's own convention places CRDs in a dedicated crds/ directory (installed once, never templated or upgraded by subsequent helm upgrade calls) specifically because Helm does not manage CRD lifecycle the same way it manages other templated resources, a frequent source of confusion when a chart upgrade is expected to also update CRD schemas and silently does not.

helm upgrade --install postgres-operator ./chart --set installCRDs=true

Plain Aggregated Manifests

kubectl apply -f https://example.com/postgres-operator/v1.4.0/install.yaml

A single concatenated YAML file containing every manifest in dependency order is the simplest packaging format, trading the flexibility of templating for a single, unambiguous, version-pinned artifact that is straightforward to review in full before applying.

GitOps and Drift Management

Ensuring Reconciliation Order in GitOps Tools

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"
spec:
  source:
    path: config/crd

GitOps tools such as Argo CD support explicit sync-wave annotations, letting CRDs be applied in an earlier wave than the resources and RBAC that depend on them, formalizing the ordering requirement as declarative configuration rather than relying on incidental processing order within a single apply operation.

Detecting Manifest Drift

kubectl diff -f config/crd/bases/postgresclusters-crd.yaml

Because a running cluster's CRD schema, RBAC, and webhook configuration can be modified out-of-band (a manual kubectl edit, an emergency hotfix), comparing the Git-tracked manifest set against live cluster state before any planned change is standard practice, and is precisely the drift-detection responsibility a GitOps reconciliation loop automates on an ongoing basis.

Relationship to CRD Management and Operator Management

Extension manifest management is the packaging and deployment discipline underlying every other extension-related practice already covered, providing the ordering guarantees that CRD management's schema evolution and Operator management's installation and upgrade processes depend on: a correctly designed manifest bundle is what turns the individually correct pieces, a valid CRD schema, appropriately scoped RBAC, a working webhook, into a single artifact that installs and upgrades reliably as a whole.