User guide

Before you start

Ask your platform administrator to install crate-operator and confirm that your namespace can run its database pods and provision persistent storage. You need kubectl access to create Crate resources and inspect the resulting workloads in that namespace. Port forwarding also requires permission to access pod port forwarding.

The operator's database pod template uses a privileged init container. Your namespace's security policy must permit it. See the administrator guide for installation requirements.

Request a cluster

Save the following as my-crate.yaml. Use an existing application namespace in place of test-crate if your administrator manages namespaces for you.

apiVersion: v1
kind: Namespace
metadata:
  name: test-crate
---
apiVersion: k8s.tlspu.com/v1
kind: Crate
metadata:
  name: simple
  namespace: test-crate
spec:
  clusterSize: "3"
  dataSize: "1Gi"
  image: "crate:latest"

kubectl apply -f my-crate.yaml
kubectl get crates.k8s.tlspu.com -n test-crate
kubectl get statefulset,pods,services,pvc -n test-crate
kubectl rollout status statefulset/simple -n test-crate --timeout=300s

crate:latest is the CRD default. For a persistent environment, replace it with an explicit CrateDB image tag tested and approved by your administrator before creating the request. The controller passes image directly to the container specification.

The request creates the following resources in test-crate:

The StatefulSet has no readiness or liveness probes. A completed rollout confirms Kubernetes workload readiness, but does not verify database cluster health. Check the database logs and the expected node membership before using it.

Request configuration

All supported spec fields are strings. Quote numeric values such as "3".

There is no separate version field. Unsupported fields are not part of the CRD schema and must not be used to configure the operator.

Use a positive integer string for clusterSize and a valid Kubernetes storage quantity for dataSize. The CRD does not validate these formats. The generated database arguments always include gateway.recover_after_nodes=2, so a one-node request is not a supported example in this guide; use the three-node default.

Storage uses ReadWriteOnce claims without an explicit storageClassName. The administrator must provide compatible storage. The claim size is per pod: a three-node cluster requesting 1Gi asks for three 1Gi volumes. This does not describe usable database capacity, which also depends on database replication and overhead.

Connect to the database

The client Service exposes:

An application in the same namespace can use host simple. In another namespace, use simple.test-crate.svc.cluster.local with the required port. The controller's discovery configuration assumes the cluster DNS suffix cluster.local.

For local access, keep this command running:

kubectl port-forward -n test-crate service/simple 4200:4200 5432:5432

Open http://127.0.0.1:4200 for the web interface, or configure a PostgreSQL wire protocol client to use host 127.0.0.1 and port 5432. Your administrator should provide the required database credentials and connection policy. The operator does not create users, passwords, TLS certificates, Ingress resources, or NetworkPolicies. The Service is internal to Kubernetes by default.

Inspect a request or report a failure

kubectl get crates.k8s.tlspu.com simple -n test-crate -o yaml
kubectl describe statefulset simple -n test-crate
kubectl get pods -n test-crate -l app=simple
kubectl describe pod simple-0 -n test-crate
kubectl logs simple-0 -n test-crate -c simple
kubectl logs simple-0 -n test-crate -c init-sysctl
kubectl get pvc -n test-crate
kubectl get events -n test-crate --sort-by=.metadata.creationTimestamp

An absent StatefulSet or Service usually requires administrator investigation. Pending pods may be waiting for storage or scheduling; image pull failures and init container failures appear in pod details and events. Include the request name, namespace, relevant events, and pod logs in your report.

spec.created: "True" is not a success or readiness signal. The controller sets it after processing an add event even if resource creation raised an error.

Changes and removal

Editing clusterSize, image, or dataSize on an existing request does not change its StatefulSet or claims. Ask your administrator to plan scaling, upgrades, storage expansion, or recovery. Resetting created does not trigger reconciliation.

To remove a cluster request and its database workload, first arrange any required backup with your administrator, then run:

kubectl delete crates.k8s.tlspu.com simple -n test-crate
kubectl get statefulset,services,pvc -n test-crate

The controller must be running and observe the deletion to remove the StatefulSet and both Services. It does not delete persistent volume claims, set owner references, or use a finalizer. Ask your administrator to verify workload cleanup and decide whether retained claims should be kept or explicitly deleted. Avoid deleting the namespace as a shortcut: that also removes its claims and other applications' resources.