Install

This is the path to your own cluster and your own database. To see the operator run against a cluster and database it builds for itself, with no digests to choose, read Try it locally instead.

What you need

• A Kubernetes cluster in the supported window, and cluster-admin on it. The window is Kubernetes support.
• Operation Pods must be able to reach the manager’s result Service over HTTPS. The default installation uses durable results and needs no kubelet log-size change. See Result delivery.
• Helm 4 or newer. Helm 3 is not supported and is not tested: it reaches end of life before this operator’s first release.
• kubectl, and jq for the commands on the pages that follow.
• The chart, at a version you chose deliberately. The next section is how.
• Three image digests and one Ptah version, covered below.
• A database the operator can reach, and an OCI registry it can read. Both are needed by First schema rather than by the install.

Choose a version, once

Every command on these pages comes from one version: the chart, the examples beside it, and the images it names. Mixing them is the common way a first install fails, so choose once and stay there.

A published release is the reproducible choice. Each one ships the chart as a .tgz with checksums, signatures and build provenance, and Releases and provenance carries the verification.

VERSION=<release tag>
gh release download "$VERSION" --repo stokaro/ptah-operator \
  --pattern 'ptah-operator-*.tgz' --pattern release-manifest.txt --pattern SHA256SUMS
# Verify the assets before installing them, then use the .tgz below in place of
# ./charts/ptah-operator.

To run master instead, name the commit rather than the branch, and keep the examples from the same commit:

git clone https://github.com/stokaro/ptah-operator
cd ptah-operator
git checkout <commit>

There is no third option: the chart is not published to a Helm repository, and ./charts/ptah-operator without a selected commit is whatever the working tree happens to hold.

The manager, runner, and Ptah executor images must be selected explicitly. All three are required to use immutable SHA-256 references. The executor version is explicit too: it must identify the verified build in the selected executor digest and is never inferred from an image tag or supplied by a chart default.

A release names every one of them in its release-manifest.txt. The digest in image is <operator-image-digest>, and the same image is the runner. The executor is the Ptah release image the operator was tested with, unchanged: the digest in executor is <executor-image-digest>, and executor-ptah-version is the <ptah-version> to pass with it. The chart does not read the manifest, and it would take any other verified executor just as well; the values below are where the choice is made. Authenticate the manifest and verify each image’s signature first, as Releases and provenance shows.

helm upgrade --install ptah-operator ./charts/ptah-operator \
  --namespace ptah-system \
  --create-namespace \
  --set-string image.digest=sha256:<operator-image-digest> \
  --set-string execution.runnerImage=ghcr.io/stokaro/ptah-operator@sha256:<operator-image-digest> \
  --set-string execution.executorImage=ghcr.io/stokaro/ptah@sha256:<executor-image-digest> \
  --set-string execution.ptahVersion=<ptah-version>

Install into a namespace of its own, and treat it as part of the cluster’s control plane for as long as the release exists. Whoever can create or modify a workload in a namespace can run it as any ServiceAccount there, including the operator’s, so every principal with that right in the release namespace is a Ptah administrator. Keep application workloads out of it, and grant namespace-admin or workload-creation access there only to people you trust to administer Ptah. A separate coordination.namespace is held the same way. Security model states the contract, and Operations lists what else an installation has to satisfy.

The chart refuses to install into default, into a kube-* namespace, or into one that already runs workloads that are not this release’s. Its notes warn about RoleBindings there that would make somebody else a Ptah administrator. Both read the cluster, so neither runs under helm template or a GitOps tool that renders with it; What the chart checks says what else they cannot see.

The supplied version is recorded in plans, approvals, Jobs, and applied status alongside the executor digest. Verify both values against the Ptah release before installation; changing the digest requires verifying and supplying its version again. Which Ptah builds have been run against this operator is Ptah compatibility.

The chart supports the Kubernetes window documented in Kubernetes support. It intentionally does not bind the optional approver ClusterRole to any identity.

Confirm it installed

Helm reports success when its hooks completed, which is not the same as the manager serving. Two readings settle it:

kubectl -n ptah-system wait --for=condition=Available deployment --all --timeout=5m
kubectl get crd -o json | jq -r '
  .items[] | select(.spec.group == "operator.ptah.run") |
  "\(.metadata.name)\t\([.status.conditions[]? | select(.type == "Established") | .status] | first // "unknown")"'

Ten CRDs, each Established=True, and the manager and certificate-rotator Deployments available. Until the webhook certificate has been issued and accepted the admission webhooks reject writes, so a PtahSchema created in the first seconds can be refused; the wait above is what settles it.

Every value the chart takes is in configuration.

The client

The chart installs the operator. Reading what it planned or applied is a separate install on your own machine: kubectl ptah, a plugin published with each release. Its read commands only read; kubectl ptah approve creates the approval of a plan you reviewed, as you, and suspend, resume, refresh and set-source patch a schema or a migration, as you. Read a plan carries the download, the checksum check and the RBAC each command needs.