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.

  • configValues are written to Contractor.

  • state: built starts a create job, state: planned starts a destroy job.

  • Changing the blueprint updates 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: set state: planned, wait for the destroy job to finish, change the blueprint, then set state: 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 kubectl access (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 enforce mode, 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

http://contractor

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

enforce or follow

–resync-interval

5m

How often idle Structures are re-checked, 0 turns it off

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.