Pizza Order Controller 🎮

Pizza Order Controller: Detailed Documentation

Overview

The Pizza Order Controller is a custom Kubernetes controller that forms the core of the Kubernetes Pizza Observability project. It's responsible for watching PizzaOrder custom resources, processing these orders by interacting with the Dominos Pizza API, and updating their status within the Kubernetes cluster. This enables the automated ordering of pizza when specific cluster conditions (like high CPU usage) are met.

Architecture

The controller is built using Go and the controller-runtime library, adhering to the Kubernetes operator pattern. Its main architectural components are:

PizzaOrder Custom Resource Definition (CRD): Defines the PizzaOrder custom resource, which represents a pizza order within the Kubernetes cluster. This CRD includes fields for customer details, delivery address, pizza specifications, and payment information.
Reconciler (pizza-controller.go): Contains the primary reconciliation logic. The Reconcile function is triggered when PizzaOrder resources are created, updated, or deleted. It handles the entire lifecycle of a pizza order.
Dominos API Integration: A set of functions responsible for communicating with the Dominos Pizza API. This includes finding the nearest store, validating the order, pricing the order, and placing the order.
RBAC Configuration (pizza-controller-deployment.yaml): Defines the necessary ServiceAccount, ClusterRole, and ClusterRoleBinding to grant the controller appropriate permissions to interact with Kubernetes API resources (e.g., PizzaOrder CRDs, Secrets).

How It Works

The controller's workflow is as follows:

Resource Watching: The controller continuously watches for changes to PizzaOrder custom resources in the cluster.
Order Processing Trigger: When a new PizzaOrder resource is created with the spec.placeOrder field set to true, or an existing one is updated to this state, the reconciler is invoked.
Order Validation & Preparation:
- Retrieves customer and delivery details from the PizzaOrder spec.
- Fetches payment information from a Kubernetes Secret referenced in spec.paymentSecret.name.
- Validates the order details with the Dominos API (e.g., address validation, store lookup).
Order Placement:
- Prices the order using the Dominos API.
- If validation and pricing are successful, places the order with the Dominos API.
Status Update: After attempting to place the order, the controller updates the status subresource of the PizzaOrder CRD with:
- orderId: The ID returned by Dominos API upon successful order placement.
- status: The current status of the order (e.g., "Pending", "Placed", "Failed", "Delivered").
- price: The total price of the order.
- lastUpdateTime: Timestamp of the last status update.
Order Tracking (Future Enhancement): While the current implementation focuses on order placement, a future enhancement could involve periodic polling of the Dominos API to track the order through its various stages (e.g., preparation, baking, out for delivery) and update the PizzaOrder status accordingly.

Deployment

Prerequisites

A running Kubernetes cluster (e.g., Minikube, Kind, AKS, GKE, EKS).
kubectl configured to communicate with your cluster.
The PizzaOrder CRD must be installed in the cluster.
A Kubernetes Secret containing Dominos payment information must be created.
Docker (if building the image locally).
Helm 3.x (if deploying via Helm).

Building the Controller (Optional)

If you've made changes to the controller code, you'll need to rebuild the Docker image:

# Navigate to the controller directory
cd kubernetes/controller

# Build the Docker image
docker build -t your-registry/pizza-controller:latest .

# Push to your container registry (e.g., Docker Hub, ACR, GCR)
# docker login your-registry
docker push your-registry/pizza-controller:latest

Make sure to update the image path in kubernetes/controller/pizza-controller-deployment.yaml or your Helm values.yaml if you use a custom registry or tag.

Deployment Methods

1. Using Helm (Recommended)

This is the easiest way to deploy the controller along with all its dependencies (CRD, RBAC, etc.).

# From the project root directory
helm install k8s-pizza helm/k8s-pizza-observability-chart --namespace k8s-pizza

Ensure your values.yaml for the Helm chart correctly points to the controller image and configures any necessary parameters.

2. Manual Deployment using `kubectl`

If you prefer manual deployment or are not using Helm:

# 1. Apply the PizzaOrder CRD
kubectl apply -f kubernetes/crds/pizzaorders.yaml

# 2. Create the Dominos Payment Secret (see Configuration section below)
kubectl apply -f kubernetes/dominos-payment-secret.example.yaml # Modify with real data first!

# 3. Deploy the Controller
kubectl apply -f kubernetes/controller/pizza-controller-deployment.yaml

Configuration

Payment Information (`dominos-payment-secret`)

The controller requires payment information to place orders. This is securely stored in a Kubernetes Secret. Create a Secret named dominos-payment-secret in the same namespace as the controller.

Example dominos-payment-secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: dominos-payment-secret
  namespace: default # or your chosen namespace
type: Opaque
stringData:
  cardType: "Credit" # or "Debit"
  cardNumber: "4100123456789010" # Example card number (use a real one)
  cardExpiration: "01/25" # MM/YY format
  cardSecurityCode: "123" # CVV
  cardPostalCode: "90210" # Billing ZIP/postal code

PizzaOrder Custom Resource

To create a pizza order, you need to create a PizzaOrder custom resource. Here's an example:

apiVersion: k8spizza.com/v1alpha1
kind: PizzaOrder
metadata:
  name: pepperoni-special
spec:
  customer:
    firstName: "Pizza"
    lastName: "Lover"
    email: "pizza@example.com"
    phone: "1234567890"
  delivery:
    street: "123 Main St"
    city: "Anytown"
    state: "NY"
    zipCode: "10001"
  pizza:
    size: "large"
    type: "pepperoni"
  paymentSecret:
    name: "dominos-payment-secret"
  placeOrder: true # Set to true to actually place the order

Monitoring

Controller Logs

To view the controller logs:

kubectl logs deployment/pizza-controller

PizzaOrder Status

To check the status of pizza orders:

# List all pizza orders
kubectl get pizzaorder

# Get detailed information about a specific order
kubectl describe pizzaorder pepperoni-special

Troubleshooting

Common Issues

Order Placement Fails: Check the controller logs for detailed error messages. Common issues include invalid payment information, invalid delivery address, or API connectivity problems.
CRD Not Found: Ensure the PizzaOrder CRD is installed in the cluster.
Permission Errors: Verify that the controller's ServiceAccount has the necessary RBAC permissions.
Secret Not Found: Ensure the payment secret exists in the same namespace as the controller and is correctly referenced in the PizzaOrder resource.

Debugging Tips

Increase the controller's log verbosity by setting the --v flag in the deployment.
Test the Dominos API integration separately using the provided test scripts.
Verify the format of the payment information in the secret.

Development

Local Development

To develop and test the controller locally:

# Clone the repository
git clone https://github.com/yourusername/k8s-pizza-observability.git
cd k8s-pizza-observability/kubernetes/controller

# Build the controller
go build -o pizza-controller

# Run the controller locally (pointing to your kubeconfig)
./pizza-controller --kubeconfig=$HOME/.kube/config

Adding Features

To extend the controller with new features:

Modify the PizzaOrder CRD to include new fields if necessary.
Update the reconciliation logic in pizza-controller.go.
Add new functions for any additional API integrations.
Build and deploy the updated controller.

Future Enhancements

Potential improvements for the controller include:

Real-time order tracking and status updates.
Support for more pizza providers beyond Dominos.
Integration with other notification systems (e.g., email, SMS).
Advanced order customization options.

Pizza Order Controller 🎮