This quickstart guide walks you through installing the Pod Mutator Controller and creating your first pod mutation. By the end, you'll have a working mutation that automatically adds a label to pods in a target namespace.

The quickstart covers:

• Part 1: Install the pod mutator
• Part 2: Create a pod mutation
• Part 3: Configure target filters
• Part 4: Verify the mutation

This guide assumes you have a basic familiarity with Kubernetes concepts, such as namespaces, pods, and labels, and that you can run kubectl commands against your cluster.

Before you start

Before starting this quickstart, ensure you have:

• A Kubernetes cluster connected to Cast AI
• kubectl configured to access your cluster
• The following Cast AI components at minimum versions:
  • castai-agent: 0.123.0 or higher
  • castai-cluster-controller: 0.85.0 or higher

You can verify your component versions with:

helm list -n castai-agent --filter 'castai-agent|cluster-controller'

Example output:

robertas@Robertass-MacBook-Pro ~ % helm list -n castai-agent --filter 'castai-agent|cluster-controller'
NAME              	NAMESPACE   	REVISION	UPDATED                                	STATUS  	CHART                           	APP VERSION
castai-agent      	castai-agent	1       	2025-12-17 10:33:15.856274144 +0000 UTC	deployed	castai-agent-0.129.0            	v0.108.0   
cluster-controller	castai-agent	1       	2025-12-17 10:36:27.258252445 +0000 UTC	deployed	castai-cluster-controller-0.86.0	v0.60.0    

Part 1: Install the pod mutator

The pod mutator is the controller that applies mutations to pods at creation time. You can install it via the Cast AI console or Helm.

Option A: Install via console

1. In the Cast AI console, select your cluster from the cluster list.

2. Navigate to Autoscaler → Pod mutations in the sidebar.
   If the pod mutator is not installed, you'll see an installation prompt with a script. Copy it.

   

3. Open your cloud shell or terminal and run the script to install the pod mutator in your cluster.

Option B: Install via Helm

1. Add the Cast AI Helm repository:

   Shell

   helm repo add castai-helm https://castai.github.io/helm-charts
   helm repo update

2. Install the pod mutator:

   Shell

   helm upgrade -i --create-namespace -n castai-agent pod-mutator \
   castai-helm/castai-pod-mutator \
   	--set castai.apiUrl="https://api.cast.ai" \
     --set castai.apiKey="${CASTAI_API_KEY}" \
     --set castai.clusterID="${CLUSTER_ID}"

   Replace ${CASTAI_API_KEY} and ${CLUSTER_ID} with your actual values. You can find these in the Cast AI console under User → API keys and in your cluster's settings.

Verify installation

Confirm the pod mutator is running:

kubectl get pods -n castai-agent -l app.kubernetes.io/name=castai-pod-mutator

Expected output:

NAME                                  READY   STATUS    RESTARTS      AGE
castai-pod-mutator-767d48f477-4tdrw   1/1     Running   0             172m
castai-pod-mutator-767d48f477-d7s45   1/1     Running   1 (97s ago)   172m

Part 2: Create a pod mutation

With the pod mutator installed, you can create your first mutation. This example creates a mutation that adds a label to pods.

1. In the Cast AI console, navigate to Autoscaler → Pod mutations.

2. Click Add mutation.

3. Enter a name for your mutation in the Mutation name field:

   demo-label-mutation

   📘

   Note

   Mutation names cannot be changed after creation. Always choose a descriptive name that reflects what the mutation does.

4. Under Default configuration, click the Configuration dropdown and select Labels.

5. In the Labels configuration that appears, add a label:

   • Key: mutated-by
   • Value: castai

6. Click Go to target workloads to proceed to filter configuration.

Part 3: Configure target filters

Filters determine which pods receive the mutation. For this quickstart, we'll target pods in a specific namespace.

1. Under Filter target workloads, click the Filter type dropdown and select the Include namespace filter.

2. Select a namespace where you want to test the mutation. If you don't have a test namespace, you can create one:

   Shell

   kubectl create namespace pod-mutation-demo

   Then select pod-mutation-demo in the console.

3. Click Go to review to review the mutation configuration.

   

4. (Optional) Review the Configuration summary of your mutation configuration:

   

5. (Optional) Review the Affected/Unaffected workloads. This shows existing workloads match your filter criteria, split into:

• Affected: Workloads that will receive the mutation
• Unaffected: Workloads that will not receive it

For the purpose of this quickstart, we've deployed a simple workload with 4 replicas, called mutation-demo:

6. Click Create and confirm enablement to proceed.

The mutation is now active. Any new pods created in the target namespace will automatically receive the mutated-by: castai label.

Part 4: Verify the mutation

Test that the mutation is working by creating a pod in the target namespace.

1. Create a test pod:

   Shell

   kubectl run test-pod --image=nginx -n pod-mutation-demo

2. Wait for the pod to be created, then check its labels:

   Shell

   kubectl get pod test-pod -n pod-mutation-demo -o jsonpath='{.metadata.labels}' | jq

   Expected output (formatted):

   JSON

   {
     "mutated-by": "castai",
     "run": "test-pod"
   }

   The mutated-by: castai label confirms the mutation was applied.

3. You can also verify by describing the pod:

   Shell

   kubectl describe pod test-pod -n pod-mutation-demo | grep -A5 "Labels:"

4. Clean up the test resources:

   Shell

   kubectl delete namespace pod-mutation-demo

5. (Optional) Delete the test mutation in the Cast AI console by navigating to Autoscaler → Pod mutations, clicking on demo-label-mutation, and selecting Delete mutation:

   

Troubleshooting

If the mutation isn't applied to your test pod, check the following:

Pod mutator not running:

kubectl get pods -n castai-agent -l app.kubernetes.io/name=castai-pod-mutator

If no pods are listed or the status isn't Running, review the installation steps.

Check pod mutator logs:

kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-pod-mutator --tail=50

Look for errors related to your mutation or webhook configuration.

Mutation not synced to cluster:

Mutations created in the console are synced to your cluster as custom resources. Verify the mutation exists:

kubectl get podmutations.podmutations.cast.ai

Namespace filter mismatch:

Ensure the namespace you're creating pods in matches the filter configured in the mutation.

Next steps

Now that you've created your first mutation, explore more advanced use cases:

• Pod mutations reference — Complete reference for all configuration options and CRD specification