Skip to main content

Deploy to Kubernetes

This guide shows you how to containerize an app and run it on Kubernetes, connected to Catalyst Cloud. It works the same for an AI agent, a workflow app and an app that uses the Dapr APIs.

Your code runs in a Kubernetes pod. There is no sidecar to install. The pod connects to Catalyst Cloud with the three environment variables from Connect to Catalyst, which you store as a Kubernetes Secret.

App pod connected to Catalyst CloudKubernetesCatalyst CloudSecretcatalyst-credentialsApp podApp IDDapr APIsworkflows, state,pub/sub
App pod connected to Catalyst CloudThe pod reads its Catalyst credentials from a Kubernetes Secret and connects to Catalyst Cloud through its App ID.

Prerequisites​

1. Create a Catalyst project and app​

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

diagrid project create my-project
diagrid app create my-app --project my-project
tip

Use descriptive names that match your application. You can reuse a project you already created in a previous tutorial. Create a new app 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'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 API token:

diagrid app get my-app --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. Pick your language:

FROM python:3.12-slim

WORKDIR /app

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

COPY . .

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

Replace agent.py with your app's entry point.

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

diagrid[langgraph]
fastapi
uvicorn
tip

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

For a workflow or Dapr API app, list dapr and dapr-ext-workflow (workflows) plus your web framework instead.

4. Build and push the image​

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

docker build -t your-registry/my-app:latest .
docker push your-registry/my-app: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 app get.

6. Create a Kubernetes Deployment​

Create deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: your-registry/my-app: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 app needs other secrets, such as an LLM API key, add them to the Secret and reference them the same way:

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

7. Let Catalyst reach your app (if it receives calls)​

Skip this step if your app only calls Catalyst, for example a workflow worker or an agent that you start through the Catalyst APIs. Leave the app connection unset; see When to leave the app connection unset. If people or other services call your app directly, still give it a Kubernetes Service.

If Catalyst calls your app, for pub/sub deliveries, service invocation, input bindings or health checks, the app needs an endpoint Catalyst can reach:

  1. Expose the pod's port with a Kubernetes Service and an ingress or load balancer that has a public address.

  2. Point the app at that address, and set an application token so your app can check that the call comes from Catalyst:

    diagrid app update my-app --project my-project \
      --endpoint https://my-app.example.com \
      --endpoint-token "<a-secret-you-choose>"

  3. In your app, reject requests whose dapr-api-token header doesn't match that token. See Secure the application connection for why this is not the same value as DAPR_API_TOKEN, and to allowlist the project's egress address.

8. 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 app connected to Catalyst:

kubectl logs -f deployment/my-app

You should see the app start. A workflow app logs that its workflow worker connected to Catalyst. To check an app that receives calls, publish a test message or invoke it with diagrid call.

Summary​

In this guide, you:

  • Created a Catalyst project and app for Kubernetes use
  • Retrieved the HTTP endpoint, gRPC endpoint, and API token
  • Containerized your app
  • Stored Catalyst credentials as a Kubernetes Secret
  • Deployed the app with the three environment variables your code reads from

Next steps​

Last updated on