Skip to main content

Deploy AI Agents to Kubernetes

This guide shows you how to containerize a Python AI agent and deploy it to Kubernetes, connected to the Catalyst Cloud workflow engine and authorization service.

Your agent code runs in a Kubernetes pod. There is no sidecar to install — the pod connects directly to Catalyst Cloud using three environment variables that you store as a Kubernetes Secret.

Prerequisites​

1. Create a Catalyst Project and App ID​

If you don't already have a project and App ID from a previous tutorial:

diagrid project create my-project
diagrid appid create my-agent --project my-project
tip

Use descriptive names that match your application. You can reuse a project you already created in a previous tutorial — just create a new App ID for the Kubernetes deployment.

2. Retrieve Catalyst Credentials​

You need three values to connect your pod to Catalyst: the project's HTTP endpoint, the project's gRPC endpoint, and the App ID's API token.

Get the project endpoints:

diagrid project get my-project -o json

Look for status.endpoints.http.url and status.endpoints.grpc.url in the output:

{
  "status": {
    "endpoints": {
      "http": { "url": "https://http-prj123456.cloud.r1.diagrid.io:443" },
      "grpc": { "url": "https://grpc-prj123456.cloud.r1.diagrid.io:443" }
    }
  }
}

Get the App ID API token:

diagrid appid get my-agent --project my-project -o yaml

Look for status.apiToken in the output:

status:
  apiToken: diagrid://v1/...

Save all three values — you'll store them as a Kubernetes Secret in a later step.

3. Write a Dockerfile​

Create a Dockerfile in your project directory. The install command differs per framework:

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "agent.py"]

Create a requirements.txt with your framework's dependencies:

diagrid[langgraph]
fastapi
uvicorn
tip

If your agent does not use the diagrid SDK (e.g. a plain access policy service invocation app), just list your direct dependencies: fastapi, uvicorn, httpx, etc.

4. Build and Push the Image​

Replace your-registry and my-agent with your registry path and image name.

docker build -t your-registry/my-agent:latest .
docker push your-registry/my-agent:latest

5. Store Credentials as a Kubernetes Secret​

Create a Kubernetes Secret with the three Catalyst credentials you retrieved in step 2:

kubectl create secret generic catalyst-credentials \
  --from-literal=http-endpoint="https://http-prj123456.cloud.r1.diagrid.io:443" \
  --from-literal=grpc-endpoint="https://grpc-prj123456.cloud.r1.diagrid.io:443" \
  --from-literal=api-token="diagrid://v1/..."
tip

Replace the placeholder values with the real ones from diagrid project get and diagrid appid get.

6. Create a Kubernetes Deployment​

Create deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      labels:
        app: my-agent
    spec:
      containers:
        - name: my-agent
          image: your-registry/my-agent:latest
          ports:
            - containerPort: 8001
          env:
            - name: DAPR_HTTP_ENDPOINT
              valueFrom:
                secretKeyRef:
                  name: catalyst-credentials
                  key: http-endpoint
            - name: DAPR_GRPC_ENDPOINT
              valueFrom:
                secretKeyRef:
                  name: catalyst-credentials
                  key: grpc-endpoint
            - name: DAPR_API_TOKEN
              valueFrom:
                secretKeyRef:
                  name: catalyst-credentials
                  key: api-token

If your agent needs an LLM API key, add it to the secret and reference it the same way:

            - name: OPENAI_API_KEY
              valueFrom:
                secretKeyRef:
                  name: catalyst-credentials
                  key: openai-api-key

7. Apply and Verify​

Deploy to your cluster:

kubectl apply -f deployment.yaml

Check that the pod is running:

kubectl get pods

Stream the logs to verify the agent connected to Catalyst:

kubectl logs -f deployment/my-agent

You should see the agent start up and, if it uses durable workflows, a message indicating the Dapr workflow runner has connected to Catalyst. If using service invocation, you can kubectl exec into the pod or expose it via a Service to send test requests.

Summary​

In this guide, you:

  • Created a Catalyst project and App ID for Kubernetes use
  • Retrieved the HTTP endpoint, gRPC endpoint, and API token
  • Containerized your Python agent with a framework-appropriate requirements.txt
  • Stored Catalyst credentials as a Kubernetes Secret
  • Deployed the agent with the three environment variables your code reads from

Next Steps​