Capstone: Deploy Your Module 6 Agent to Kubernetes

Your FastAPI agent from Module 6 is containerized and pushed to a registry. Now deploy it to a production-like environment using Kubernetes.

This capstone differs from earlier lessons: you start with a specification, not a command. Write out what you're deploying and why. Then have AI generate the manifests that implement your specification. Finally, deploy your agent, configure it with secrets and environment variables, and validate that Kubernetes is managing it correctly (scaling, self-healing, logging).

By the end, your agent will run on a Kubernetes cluster, surviving Pod crashes and responding to scaling demands—all orchestrated by Kubernetes' declarative model.

---

The Specification-First Approach

Before you write a single line of YAML, specify what you're building.

A specification answers these questions:

• What are we deploying? (What's the container? Where is it?)
• Why are we deploying it this way? (What constraints drive our choices?)
• How many copies should run? (What's the replicas count based on?)
• What configuration does it need? (Environment variables, secrets, resource limits?)
• How do we validate it's working? (Health checks, access tests, what success looks like?)

Here's a template to guide your thinking:

This specification becomes the contract between you and Kubernetes. AI will read it and generate manifests that fulfill the contract.

---

Writing Your Specification

Before proceeding to AI, write your specification in a text editor or document.

Key Details for Your Module 6 Agent

Container image: This is the image you pushed in Module 6. Remember the format:

Example: ghcr.io/yourusername/module6-agent:latest

Port: Your FastAPI agent listens on port 8000 by default (unless you configured differently in Module 6).

Environment variables: Your agent needs:

• OPENAI_API_KEY: Your OpenAI API key (should be in a Secret for security)
• Any other config from Module 6? (Database URLs, model names, API endpoints?)

Readiness and liveness probes: FastAPI's health check endpoint is typically /health or you can use the root endpoint / and check for HTTP 200.

Replicas: For learning purposes, 2-3 replicas is appropriate (shows redundancy). For production load, you'd scale higher.

Resources: A FastAPI agent with OpenAI calls is lightweight:

• Request: CPU 100m (100 millicores), Memory 256Mi
• Limit: CPU 500m, Memory 512Mi

Service exposure: For Docker Desktop development, NodePort is practical (access via localhost). For cloud clusters, LoadBalancer or Ingress.

---

Example Specification (For Reference)

Here's what a completed specification looks like:

Use this as a model, then customize it for YOUR agent and deployment preferences.

---

Generating Manifests from Specification

Once you've written your specification, you have two approaches:

Approach 1: Manual (Educational)

• Write each manifest yourself based on your specification
• Good for learning—you control every line
• Time-intensive

Approach 2: AI-Assisted (Practical)

• Copy your specification into a prompt
• Have AI generate the complete manifest suite
• Then review and validate the output

For this capstone, use Approach 2—this demonstrates the core AI-native workflow: Specification → AI Generation → Validation.

The Prompt Structure for AI

When asking AI to generate manifests, provide:

1. Your specification (copy/paste)
2. Context about your agent: What does it do? What does it need?
3. Deployment environment: Are you using Docker Desktop Kubernetes or a cloud cluster?
4. Success criteria: What must the manifests include to pass validation?

Here's a template:

---

Deployment Steps

Once you have your manifests (either written by hand or generated by AI), deploy them to your Kubernetes cluster.

Step 1: Verify Cluster Access

If using Docker Desktop, ensure Kubernetes is enabled (green indicator in Docker Desktop).

Step 2: Create Namespace (Optional but Recommended)

This isolates your deployment and makes cleanup easier.

Step 3: Apply Manifests

Or apply all at once:

Step 4: Verify Deployment

Step 5: Test External Access

For Docker Desktop + NodePort:

For kubectl port-forward (alternative):

For cloud cluster + LoadBalancer:

---

Validation Checklist

Run through this checklist to confirm your deployment succeeded:

Deployment Health

• All Pods are Running

  bash kubectl get pods # All should show STATUS: Running

• Desired Replicas Match Actual

  bash kubectl get deployment # DESIRED, CURRENT, READY should all be equal

• Readiness Probes Pass

  bash kubectl get pods # All Pods should show READY 1/1

Configuration Injection

• Environment Variables are Set

  bash kubectl exec [pod-name] -- env | grep OPENAI_API_KEY # Should show the key is populated

• ConfigMap Values are Injected

  bash kubectl exec [pod-name] -- env | grep LOG_LEVEL # Should show your configured value

Networking & Access

• Service Exists and Routes to Pods

  bash kubectl get endpoints agent-service # Should show IP addresses of Pods

• Agent Responds to Health Check

  bash curl http://[service-ip]:[port]/health # Should return HTTP 200

• External Access Works (NodePort or LoadBalancer)

  bash # Test from outside the cluster curl http://[external-ip]:[port]/health

Self-Healing Verification

• Pod Recovery Works

  bash

  WrapCopy

  # Record initial Pod name kubectl get pods POD_NAME=$(kubectl get pods -o jsonpath='{.items[0].metadata.name}') # Delete a Pod kubectl delete pod $POD_NAME # Wait a few seconds, verify new Pod was created kubectl get pods # New Pod should be Running (different name)

• Desired State Maintains Replicas

  bash

  WrapCopy

  # Delete multiple Pods kubectl delete pod --all # Wait for recovery kubectl get pods # Should have recreated all replicas automatically

Logging Verification

• Logs are Accessible

  bash kubectl logs [pod-name] # Should see your agent's startup logs

• Recent Requests are Logged

  bash # After making a request to your agent: kubectl logs [pod-name] --tail=20 # Should see request in logs

---

Try With AI

Use AI to help debug issues and explore advanced deployment scenarios. This section demonstrates the three-role collaboration that makes AI-native development effective.

Part 1: Validate Your Manifests

Ask AI:

What to evaluate:

• Does AI catch obvious errors (wrong image name, mismatched selectors)?
• Are the suggestions aligned with your specification?
• Did you miss any configuration that AI suggests?

Part 2: Troubleshoot Deployment Issues

If your deployment fails, use AI to diagnose:

Ask AI:

What to evaluate:

• AI correctly interprets kubectl output
• AI identifies the root cause (image pull error, resource constraints, etc.)
• AI's suggestion points to a specific fix you can try

Then refine: Based on AI's analysis, describe what you tried:

Part 3: Validate Self-Healing Behavior

Ask AI:

What to evaluate:

• AI correctly interprets the before/after Pod states
• AI confirms that a new Pod was created (different name, recent age)
• AI explains why this proves self-healing works

Part 4: Test External Access

Ask AI:

What to evaluate:

• AI identifies if port forwarding is needed vs NodePort vs LoadBalancer
• AI suggests debugging steps specific to your deployment environment
• AI's advice is actionable and tests the right thing

Part 5: Final Validation Synthesis

Ask AI:

What to evaluate:

• AI acknowledges which checks you've completed successfully
• AI identifies any gaps remaining before the capstone is done
• AI confirms that your specification has been fully validated in practice

---

Remember: The goal of this capstone is not just to deploy your agent, but to understand how specification-first development works. Your specification is the contract. The manifests implement it. Kubernetes ensures the contract is maintained (desired state = observed state, always).

When self-healing works (Pod dies, new one starts), you're seeing the declarative model in action.