A custom resource definition (CRD) extends the Kubernetes API with a new resource type. It defines the type’s name, API group, scope, and schema, including permitted fields and values. A namespaced resource belongs to a namespace; a cluster-scoped resource belongs to the whole cluster. Installing a CRD makes the type available through the Kubernetes API, but does not by itself define how to manage instances. An operator typically supplies that behavior through a controller. section 5.4.1 section 5.4
Keep the definition separate from the object you create: one CRD can have many custom resources (CRs). For example, CloudNativePG installs a CRD for PostgreSQL Cluster resources; an individual Cluster object requests a particular PostgreSQL cluster. Here, “PostgreSQL cluster” does not mean the Kubernetes cluster. section 5.4.3 section 5.4.1
To install and inspect an operator’s resource types:
- Apply the operator manifest, for example with `kubectl apply --server-side -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.26/releases/cnpg-1.26.1.yaml`. This installation also creates its CRDs. Helm installs an operator’s CRDs by default unless given `--skip-crds`. section 5.4.2
- Run `kubectl get crds` to confirm the definitions exist, then `kubectl api-resources --api-group=postgresql.cnpg.io` to find their API resources. Use `kubectl explain clusters.postgresql.cnpg.io` to inspect the Cluster type and its fields without reading the full generated CRD schema. section 5.4.2 section 5.4.1
- Check that the operator controller is running with `kubectl get deployment -n cnpg-system cnpg-controller-manager` before expecting it to act on a new Cluster object. section 5.4.3
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: my-postgres-cluster
namespace: default
spec:
instances: 1
storage:
size: 1Gi
This YAML is a custom resource, not its CRD. It selects the installed `postgresql.cnpg.io/v1` Cluster type and requests one PostgreSQL instance with 1Gi of storage in the default namespace. section 5.4.3
Apply that CR with `kubectl apply -f postgres-cluster.yaml`. Verify the result with `kubectl get cluster my-postgres-cluster`, `kubectl describe cluster my-postgres-cluster`, and `kubectl get pods`; the example shows a healthy Cluster and a running pod. CRDs also underpin the Gateway API, whose GatewayClass, Gateway, and HTTPRoute objects may already be available when configuring routes. section 5.4.3 section 6.7
