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: k8sinfrx is 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:

1. Provisions the raw cluster (cloud infra only — no agent, no components)
2. Installs the Codiac in-cluster agent
3. Installs the default cluster stack (the latest snapshot in k8sinfrx tagged default)

---

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 create is the legacy equivalent of cod cluster provision and will be removed in a future release. Use provision for 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>

---

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

---

Related Docs

• Cluster Workflows Guide — define-first, restore, cabinet attach, and rebuild patterns
• Infrx Assets & Cluster Stacks
• Codiac Agent Reference