Deploy the service

This guide is for the person deploying and maintaining the service, not a one-command installer. You need a Kubernetes cluster, deployment permissions and the external dependencies below. To try the UI, start with the local quickstart.

The YAML files are examples. Their images, domains and credential settings must be replaced for your deployment.

Start with two processes

configra management is for people: the workspace, login, edits and logs. configra api is for applications reading configuration and files. They run separately but use the same MySQL database and Master Key, which decrypts stored content.

Release binaries do not install these dependencies. OIDC connects Configra to your login provider; register an application there with the callback URL and role mapping. Do not reuse the demo’s fixed accounts or passwords.

Bootstrap Secrets

deploy/kubernetes/base contains a Management Deployment and an independently scalable API Deployment. Provision these Secrets through your own credential-distribution process:

These Secrets belong in the Configra service namespace, not in the application’s configra-credentials Secret.

Generate the Master Key once for the initial deployment. Reuse the original for restarts and recovery. Its base64 text is separate from Kubernetes’ Secret data encoding. With kubectl create secret --from-file, the file contains base64 text and kubectl encodes the API layer. Do not repeatedly decode it or generate a new key when a Pod restarts.

Configra does not use its own provider to load bootstrap data. The service needs those values before it can start; it cannot fetch them from itself afterwards.

Configure an overlay

A registry stores your container images. A Kustomize overlay is a directory of deployment customizations. Build the tagged source, push to your registry, and replace the image, hostname, OIDC, NATS and namespace settings.

The following only builds and renders an example. Replace registry.example.com; kubectl kustomize prints YAML without deploying. Review that output before applying your own overlay with kubectl apply -k:

docker build -t registry.example.com/configra:1.0.1 .
kubectl kustomize deploy/kubernetes/base
# Configure and inspect your overlay before running kubectl apply -k against it.

Example registry references are placeholders, not published images. The listeners use 8443 for Management and 9443 for API; their Kubernetes Services expose 443.

Ingress and TLS

Management can use a regular HTTPS Ingress. The machine API requires TCP / TLS passthrough so the original client certificate reaches Configra. TLS must reach Configra so it can verify the client certificate. Terminating the connection at the ingress and forwarding a certificate Header is not equivalent.

Use an API hostname covered by its server certificate. Managed client CAs do not change the API’s HTTPS certificate. An external client CA may be retained with tls.client_ca_file alongside managed CAs.

Startup and upgrade order

Start Management first and check /health/ready. Verify OIDC Admin access, then create environments, Tokens and client credentials before deploying API consumers.

For schema v1-to-v2 upgrades, upgrade Management first. It uses the Crypto Sentinel, an encrypted verification record in the database, to check the Master Key before updating the schema under a database lock. Upgrade API afterwards. A wrong Master Key is not a reason to initialize a restored database as a new installation.

Management’s versioned embedded assets need a coordinated rollout; the base keeps a controlled replacement strategy. Database HA, NetworkPolicy, backup retention, ingress limits and recovery drills remain deployment-specific work.

Allow endpoint removal before stopping

maxUnavailable: 0 alone does not prevent connection errors during replacement: Service endpoint updates and process shutdown happen independently. Add this under the configra container in both Deployments:

lifecycle:
  preStop:
    sleep:
      seconds: 5

Kubelet performs the wait; the image needs no shell. PodLifecycleSleepAction is enabled by default from Kubernetes 1.30 and stable from 1.34. Check support on older clusters. See Kubernetes lifecycle hooks.

The service keeps accepting requests during the wait, then receives its stop signal and allows up to 15 seconds for requests to finish. Keep terminationGracePeriodSeconds at least 30 seconds. If your ingress takes longer to remove endpoints, adjust both durations and test them. Management’s Recreate upgrade still has downtime.

The v1.0.1 base manifests include this hook. When upgrading from rc.2, check that your overlay preserves it and test rolling updates through your actual ingress.