Cluster Lifecycle Guide
This guide covers how to provision, initialize, and decommission Kubernetes clusters using the Codiac CLI. It describes the three supported paths for standing up a cluster, and the day-2 operations that keep clusters healthy over time.
Background: What Is an Infrx Enterprise?
Codiac manages two distinct classes of software assets:
| Class | Purpose | Enterprise |
|---|---|---|
| SDLC assets | Application workloads that make up a company's service architecture | Your product enterprise (e.g., acme) |
| Infrx assets | Cluster-level components that support or enhance the cluster itself | k8sinfrx (the built-in infrastructure enterprise) |
The k8sinfrx enterprise is a Codiac built-in that every tenant has. It is the home for
cluster infrastructure assets — things like an ingress controller, a cert manager, a cluster
autoscaler, and the Codiac in-cluster agent.
Note:
k8sinfrxis a fixed, well-known name in the current release. Future releases will let you designate any enterprise as an infrx enterprise, but for now this single built-in enterprise covers all cluster-level asset management.
Infrx assets work exactly the same way as SDLC assets — they have versions, snapshots
(called cluster stacks), config, and the same cod asset and cod snapshot feature
set. The only differences are:
- The infrx lexicon uses install / uninstall instead of deploy / undeploy, and cluster stack instead of snapshot, to reduce confusion between the two layers.
- You target a cluster directly when installing infrx assets — Codiac handles the underlying deployment routing.
- Infrx assets can optionally declare a namespace config to control which Kubernetes namespace they are installed into. If no namespace is specified, the asset goes into the default infrx asset namespace.
The Codiac In-Cluster Agent
The Codiac in-cluster agent runs inside your cluster and enables Codiac to manage workloads
and configurations there. It can be installed using the Codiac CLI (using the
cod cluster agent install command) or installed with Helm as a standalone Helm chart
(using helm install). It is distinct from the other infrx assets — it is the prerequisite
for all cluster installs and must be installed before running any cod cluster install or
cod cluster stack install operation.
See the Codiac Agent Reference for CLI usage, Helm equivalents, and the full settings schema.
Three Paths to a Running Cluster
Path A — Bootstrap (recommended for most users)
The fastest way to stand up a fully working cluster. One command handles provisioning, agent install, and default stack install end to end.
cod cluster bootstrap
What it does, in order:
- Provisions the raw cluster (cloud infra only — no agent, no components)
- Installs the Codiac in-cluster agent
- Installs the default cluster stack (the latest snapshot in
k8sinfrxtaggeddefault)
Path B — Manual Sequence (current recommended path)
For users who want visibility and control at each step, or who need to insert custom work between steps (e.g., update DNS, set up firewall rules, run custom helm charts).
# Step 1: Provision the cluster (raw infrastructure only)
cod cluster provision
# Step 2: Install the Codiac in-cluster agent
cod cluster agent install <cluster-name>
# Step 3: Install the default cluster stack
cod cluster stack install
Step 1 details — cod cluster provision
Provisions a bare Kubernetes cluster in your cloud subscription with no Codiac-managed components installed on it. You will be prompted for cloud provider, subscription, region, node spec, and other parameters interactively.
# Interactive — recommended for first-time use
cod cluster provision
# Azure, fully scripted
cod cluster provision my-cluster \
--provider azure \
--providerSubscription <subscription-id> \
--resourceGroup my-rg \
--location eastus \
--nodeSpec Standard_D4s_v3 \
--nodeQty 3 \
--silent
cod cluster createis the legacy equivalent ofcod cluster provisionand will be removed in a future release. Useprovisionfor all new work.
After provisioning, Codiac records the cluster and you can verify it with:
cod cluster list
Step 2 details — cod cluster agent install
Installs the Codiac in-cluster agent on the cluster. This is required before any cluster installs can run.
cod cluster agent install my-cluster
See the Codiac Agent Reference for configuration options and Helm equivalents.
Step 3 details — cod cluster stack install
Installs a cluster stack (a versioned set of infrx assets) onto the cluster. The default stack contains the ingress controller, cert manager, and other components that Codiac has preconfigured as a starting point.
# Interactive — select stack version and target cluster
cod cluster stack install
# Scripted — specify version and target cluster explicitly
cod cluster stack install -v <version> -c <cluster-name> --silent
Path C — Capture an Existing Cluster
If you already have a running cluster and want to bring it under Codiac management:
# Step 1: Create a Codiac record for the existing cluster
cod cluster capture
# Step 2: Install the Codiac agent
cod cluster agent install <cluster-name>
# Step 3 (optional): Install a cluster stack
cod cluster stack install
cod cluster capture does not touch the cluster infrastructure — it only creates the
Codiac record that points to it. You will need cloud provider credentials available
(cod csp login) before running this command.
Step 3 is optional in the capture path. Your cluster may already have all the components
it needs from your own provisioning process — a cluster stack is there when you want it,
not required. If you do want to layer on Codiac-managed infrx assets (or supplement your
existing setup with additional components), run cod cluster stack install to install a
stack of your choosing.
# Azure
cod cluster capture -n my-cluster -p azure \
-s <subscription-id> -l eastus -g my-resource-group
# AWS
cod cluster capture -n my-cluster -p aws \
-s <account-id> -l us-east-1
Day-2 Operations
Checking Cluster Status
# List all clusters in your tenant
cod cluster list
# View the setup journal for a specific cluster (per-component status)
cod cluster journal <cluster-name>
Connecting Locally
Downloads the kubeconfig for a cluster and sets it as your default kubectl context:
cod cluster connect <cluster-name>
Updating the Cluster Stack
To update infrx components on a running cluster, tag a new cluster stack version and install it:
# Install a specific cluster stack version
cod cluster stack install -v <new-version> -c <cluster-name>
# Or interactively select from available stacks
cod cluster stack install
Installing or Updating a Single Infrx Asset
To deploy a single infrx asset (rather than an entire stack) to a cluster:
cod cluster install
This is the infrx equivalent of cod asset deploy. It targets a cluster instead of a
cabinet.
Scaling Node Groups
cod cluster scaling update \
-c <cluster-name> \
-n <node-group-name> \
--min 2 --max 10 --desired 4
Reconfiguring the Agent
# Overlay a single setting
cod cluster agent configure <cluster-name>
# Replace the entire configuration from a YAML file
cat my-agent-settings.yaml | cod cluster agent configure <cluster-name> --mode replace
See the Codiac Agent Reference for the full settings schema.
Starting and Stopping a Local Cluster
For locally hosted clusters (MicroK8s):
cod cluster start [cluster-name]
cod cluster stop [cluster-name]
Decommissioning a Cluster
Remove the agent and components first
# Uninstall individual infrx assets, or install an empty stack
cod cluster uninstall
# Uninstall the agent
cod cluster agent uninstall <cluster-name>
Destroy the cluster infrastructure
cod cluster destroy -n <cluster-name> --provider azure
cod cluster destroy tears down the physical cloud resources but keeps the Codiac record
intact. This is intentional and useful: because Codiac stores the full configuration state
of every cluster, cabinet, and installed asset, a destroyed cluster can be exactly
reprovisioned at any time with cod cluster provision (re-using the existing record). This
destroy-and-reprovision loop is a common workflow for troubleshooting or rebuilding clusters.
The entire history, configuration, and stack definition remains available and ready to be
re-animated on the new infrastructure.
Permanently remove the Codiac record
Only run this when you are certain the cluster will never be reprovisioned. Forgetting the cluster removes the record and all associated configuration from Codiac and cannot be undone.
cod cluster forget -n <cluster-name>
What happens to cabinets: Any cabinets assigned to this cluster are orphaned by
default — their cluster assignment is cleared so they can be re-attached elsewhere, but
their definitions are preserved. If you want to delete the cabinet records entirely, add
--forget-cabinets:
cod cluster forget -n <cluster-name> --forget-cabinets
When running interactively, cluster forget will show you the list of affected cabinets
and confirm the action before proceeding.
Command Summary
| Goal | Command |
|---|---|
| Provision + agent install + default stack (all-in-one) | cod cluster bootstrap |
| Provision a new cluster | cod cluster provision |
| Register an existing cluster | cod cluster capture |
| List clusters | cod cluster list |
| View cluster setup journal | cod cluster journal <cluster> |
| Connect kubectl locally | cod cluster connect <cluster> |
| Install the agent | cod cluster agent install <cluster> |
| Reconfigure the agent | cod cluster agent configure <cluster> |
| Uninstall the agent | cod cluster agent uninstall <cluster> |
| Install a cluster stack | cod cluster stack install |
| Install a single infrx asset | cod cluster install |
| Scale node group | cod cluster scaling update |
| Start local cluster | cod cluster start |
| Stop local cluster | cod cluster stop |
| Remove Codiac record only | cod cluster forget |
| Destroy cloud infrastructure | cod cluster destroy |
| Restore a cluster from its stored definition | cod cluster restore |
Related Docs
- Cluster Workflows Guide — define-first, restore, cabinet attach, and rebuild patterns
- Infrx Assets & Cluster Stacks
- Codiac Agent Reference