Kubernetes¶
The Kubernetes operator lets Kubernetes see and drive the Structures that already exist in
Contractor. It adds a Structure custom resource (contractor.t3kton.com/v1), one per
Contractor Structure, so kubectl, GitOps tools and anything else that speaks the Kubernetes
API can build, destroy and reconfigure them, and watch job progress.
It does not create Structures or Foundations in Contractor. Those are planned in Contractor (UI, CLI or API) as usual, the operator adopts the ones you point it at. The operator is the bridge between a Kubernetes cluster and Contractor, Contractor still does all the work of provisioning.
Source: https://github.com/T3kton/kubernetes
How it Works¶
The operator runs in a cluster and connects to Contractor over its normal API as a regular
Contractor user. For each Structure resource it compares the resource with the Structure
in Contractor and reconciles the two. Which side wins is set by the global
sync mode.
The Structure Resource¶
apiVersion: contractor.t3kton.com/v1
kind: Structure
metadata:
name: structure-sample
spec:
id: 3 # ID of the Structure in Contractor, required, can not be changed
state: built # planned | built, defaults to the current state in Contractor
blueprint: test-structure-base # defaults to the current blueprint in Contractor
configValues: # defaults to the current values in Contractor
myval: stuff
thisint: 123
consumerRef: {} # optional free form reference to whatever uses this Structure, not used by the operator
A mutating webhook fills in the defaults when the resource is created, so spec: {id: 3} adopts
the Structure exactly as it is in Contractor right now.
status shows what Contractor reports: state, blueprint, hostname, configValues,
the foundation and its blueprint, and the running job (script, state, message, progress
and time remaining). kubectl get structures shows the highlights. The operator also emits
Kubernetes events when jobs are created and finish, and when the spec is synced in follow mode.
Conditions¶
status.conditions has a Ready condition. kubectl wait --for=condition=Ready structure/NAME
waits until the Structure matches the spec (or Contractor, in follow mode) and no job is running.
Reason |
Ready |
Meaning |
|---|---|---|
Reconciled |
True |
In sync. |
JobRunning |
False |
A job is running in Contractor. |
ApplyingChanges |
False |
A change was just made, waiting to see it take effect. |
ContractorError |
False |
Contractor could not be reached or returned an error, it is retried with backoff. The message has the details. |
InvalidSpec |
False |
The spec can not be acted on, for example it asks for a state that can not be reached from the current one. |
SyncFailed |
False |
Follow mode only, the spec could not be updated to match Contractor. |
Sync Modes¶
The mode is a single global setting for the operator (--sync-mode or the SYNC_MODE
environment variable). There is no per-Structure setting, to stop managing a Structure, delete
its Structure resource. Deleting the resource never destroys or changes anything in
Contractor.
enforce (default)¶
The Kubernetes resource is the source of truth and Contractor is changed to match it.
configValuesare written to Contractor.
state: builtstarts acreatejob,state: plannedstarts adestroyjob.Changing the
blueprintupdates it in Contractor, which only allows that while the Structure is planned. The validation webhook enforces the same rule. To change the blueprint of a built Structure: setstate: planned, wait for the destroy job to finish, change theblueprint, then setstate: built.While a job is running the operator only watches, progress is shown in
status.job.
Changes made directly in Contractor, for example from the UI, are reverted to match the
resource. Idle Structures are re-checked every --resync-interval (default 5 minutes), so
drift is noticed even when nothing happens in Kubernetes.
follow¶
Contractor is the source of truth. The operator never changes anything in Contractor and never
starts a job. Once no job is running it updates the resource’s spec to match Contractor
(state, then blueprint and configValues), and edits made to the spec are overwritten
at the next resync. Use this when the Structures are managed elsewhere and Kubernetes only needs
to know about them.
Deploying¶
Prerequisites¶
A Kubernetes cluster, v1.32 or newer, and
kubectlaccess (cluster-admin for the install)cert-manager installed in the cluster, the operator’s webhooks use it for their TLS certificate
A running Contractor the cluster can reach over HTTP(S)
A Contractor user for the operator. It needs to read Structures, Foundations, BluePrints and Jobs and, in
enforcemode, update Structures and run their create and destroy jobs.To build the image and manifests: Go 1.26+ and docker (see the repository)
Install¶
From a checkout of https://github.com/T3kton/kubernetes:
make docker-build docker-push IMG=<some-registry>/t3kton-operator:tag
make install # the CRDs
make deploy IMG=<some-registry>/t3kton-operator:tag # the operator, creates the t3kton-contractor namespace
Alternatively, make build-installer IMG=<some-registry>/t3kton-operator:tag writes a single
dist/install.yaml with everything in it, which can be applied with kubectl apply -f.
Then give the operator its Contractor credentials in a Secret named contractor-credentials in the
t3kton-contractor namespace:
kubectl -n t3kton-contractor create secret generic contractor-credentials \
--from-literal=host=http://contractor.example.com \
--from-literal=username=k8s \
--from-literal=password=CHANGEME
The pod will show CreateContainerConfigError until the Secret exists, and starts on its own once
it does. A template is in config/samples/contractor-credentials-secret.yaml. Do not commit a
filled in copy, use something like sealed-secrets or external-secrets if this is managed from git.
Configuration¶
The flags override the environment variables. The deployment reads the first four from the Secret.
Flag |
Environment |
Default |
Description |
|---|---|---|---|
–contractor-host |
CONTRACTOR_HOST |
Contractor’s URL |
|
–contractor-username |
CONTRACTOR_USERNAME |
k8s |
|
–contractor-password |
CONTRACTOR_PASSWORD |
k8s |
|
–contractor-proxy |
CONTRACTOR_PROXY |
Proxy to reach Contractor through |
|
–sync-mode |
SYNC_MODE |
enforce |
|
–resync-interval |
5m |
How often idle Structures are
re-checked, |
To change the sync mode or resync interval, set them in config/manager/manager.yaml (there
are commented examples) before make deploy.
The operator does not connect to Contractor at startup, so it starts even if Contractor is down.
Until Contractor is back the Structures show Ready=False with reason ContractorError,
and the webhooks refuse to create or change Structures because they can not check them.
Adopting a Structure¶
Find the ID of the Structure in Contractor (the UI, or contractorcli), then:
kubectl apply -f - <<EOF
apiVersion: contractor.t3kton.com/v1
kind: Structure
metadata:
name: web01
spec:
id: 3
EOF
kubectl get structures -o wide
kubectl wait --for=condition=Ready structure/web01 --timeout=30m
Building it is then a change to the resource:
kubectl patch structure web01 --type merge -p '{"spec": {"state": "built"}}'
and kubectl get structure web01 -o jsonpath='{.status.job}' shows the job’s progress.
Safety checks¶
The validation webhook refuses a Structure that does not exist in Contractor, changes to spec.id,
blueprint changes on a built Structure, and deleting a resource whose Structure is (or is targeted to be)
built or has a job. Set state: planned and let the destroy finish first.
Uninstall¶
kubectl delete structures --all # Contractor is not changed
make undeploy # the operator
make uninstall # the CRDs
Trying it Out¶
The e2e tests in the repository (make test-e2e) are also a working example. They deploy the
operator into a kind cluster and work real Structures through it against the demo stack from the
In Docker page’s docker repository (docker-compose up -d), which includes the Test
plugin that only simulates builds, so nothing real is touched.