Draft

Draft automates Kubernetes app development by simplifying setup and configuration of Kubernetes deployment, services, and ingress resources.

Installation

macOS

# Homebrew installation
brew tap azure/draft
brew install draft

# Or download directly
curl https://raw.githubusercontent.com/Azure/draft/master/scripts/install-macos.sh | bash

# Verify installation
draft version

Linux

# Download latest release
DRAFT_VERSION=$(curl -s https://api.github.com/repos/Azure/draft/releases/latest | grep tag_name | cut -d '"' -f 4)
curl -L https://github.com/Azure/draft/releases/download/${DRAFT_VERSION}/draft-${DRAFT_VERSION}-linux-amd64.tar.gz | tar zx
sudo mv linux-amd64/draft /usr/local/bin/

# Verify
draft version

Windows

# Chocolatey
choco install draft

# Or Scoop
scoop install draft

# Or download from releases
# https://github.com/Azure/draft/releases
# Extract and add to PATH

Basic Commands

# Show version and info
draft version
draft info

# Get help
draft --help
draft create --help

# Initialize Kubernetes configuration
draft init

# Check Draft environment setup
draft config get-credentials

Project Setup

Create New Draft Project

# Initialize a new app in current directory
draft create

# Interactive setup - choose runtime and language
# Prompts for:
# - Language/framework detection
# - Port configuration
# - BuildPack selection

# Customize generated files after creation
cat Dockerfile
cat draft.toml
cat charts/

Draft Configuration Files

The draft.toml file:

# draft.toml
[build]
# Dockerfile to use
dockerfile = "Dockerfile"

# Build argument options
build-args = {}

# Registry for pushing images
registry = "myregistry.azurecr.io"

# Image name
image-name = "myapp"

# Image tag
image-tag = "latest"

[deploy]
# Helm values file path
values = "charts/values.yaml"

# Wait for deployment rollout
wait = true

# Timeout for deployment
timeout = "5m"

[variables]
# Environment variables for build/deploy
PORT = "8080"

BuildPacks

Detect Language Automatically

# Draft auto-detects language and generates Dockerfile
draft create

# Supported languages:
# - Go
# - Node.js
# - Python
# - Java
# - C#
# - Ruby
# - PHP
# - Rust

Custom BuildPack

# List available buildpacks
draft buildpack list

# Use specific buildpack
draft create --buildpack python

# Create with custom dockerfile
draft create --dockerfile ./custom.Dockerfile

Building and Testing

Local Testing

# Build Docker image locally
docker build -f Dockerfile -t myapp:latest .

# Run container locally to test
docker run -p 8080:8080 myapp:latest

# Test endpoint
curl http://localhost:8080

Using Draft Build

# Build image (without deploy)
draft build

# Build and push to registry
draft build --push

# Build with specific registry
draft build --registry myregistry.azurecr.io --push

# Build with custom tag
draft build --image-tag v1.0.0 --push

Kubernetes Deployment

Deploy to Kubernetes

# Deploy to connected Kubernetes cluster
draft up

# Interactive deployment:
# - Builds Docker image
# - Pushes to registry
# - Creates Helm chart
# - Deploys to cluster

# Deploy with specific namespace
draft up --namespace myapp

# Dry-run to see what would be deployed
draft up --dry-run

View Deployment

# List services and endpoints
kubectl get svc
kubectl get pods

# Port-forward to local machine
kubectl port-forward svc/myapp 8080:8080

# View logs
kubectl logs -f deployment/myapp

# Get deployment status
kubectl rollout status deployment/myapp

Update Deployment

# Redeploy after code changes
draft up

# Update specific deployment
kubectl set image deployment/myapp myapp=myregistry.azurecr.io/myapp:v1.1

# Rollback to previous version
kubectl rollout undo deployment/myapp

Helm Integration

Generated Helm Chart

Draft automatically generates a Helm chart in charts/ directory:

# View generated chart structure
ls -la charts/
cat charts/Chart.yaml
cat charts/values.yaml
cat charts/templates/

# Install chart manually
helm install myapp ./charts

# Upgrade chart
helm upgrade myapp ./charts

# Uninstall
helm uninstall myapp

Customize Helm Values

# charts/values.yaml
replicaCount: 2

image:
  repository: myregistry.azurecr.io/myapp
  tag: latest
  pullPolicy: IfNotPresent

service:
  type: LoadBalancer
  port: 8080
  targetPort: 8080

ingress:
  enabled: true
  hosts:
    - host: myapp.example.com
      paths:
        - path: /
          pathType: Prefix

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

autoscaling:
  enabled: true
  minReplicas: 1
  maxReplicas: 5
  targetCPUUtilizationPercentage: 80

Configuration Management

Environment Variables

# Set environment variables in deployment
export REGISTRY=myregistry.azurecr.io
export REGISTRY_USERNAME=myuser
export REGISTRY_PASSWORD=mypass

# Use in draft commands
draft build --registry $REGISTRY --push
draft up --namespace prod

Dockerfile Generation

# Auto-generated example for Python
FROM python:3.11-slim

WORKDIR /app

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

COPY . .

EXPOSE 8080
CMD ["python", "app.py"]

Service Configuration

# charts/templates/service.yaml - Auto-generated
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  type: LoadBalancer
  selector:
    app: myapp
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080

Multi-Environment Deployment

Development Environment

# Deploy to development
draft up --namespace development

# Expose locally for testing
kubectl port-forward -n development svc/myapp 8080:8080
curl http://localhost:8080

Staging Environment

# Deploy to staging with different values
helm upgrade --install myapp ./charts \
  --namespace staging \
  --values charts/values-staging.yaml \
  --set image.tag=v1.0.0-rc1

# Verify deployment
kubectl get pods -n staging

Production Environment

# Production deployment with resource limits
helm upgrade --install myapp ./charts \
  --namespace production \
  --values charts/values-prod.yaml \
  --set image.tag=v1.0.0 \
  --set replicaCount=3 \
  --set autoscaling.enabled=true

Troubleshooting

Check Cluster Access

# Verify kubectl is configured
kubectl cluster-info
kubectl get nodes

# Check Draft cluster config
draft config list

# Set kubeconfig context
kubectl config use-context my-cluster

# Get cluster credentials (AKS example)
az aks get-credentials --resource-group mygroup --name mycluster

Debug Deployment

# View pod logs
kubectl logs pod/myapp-xxxxx

# Describe pod for events
kubectl describe pod myapp-xxxxx

# Get deployment events
kubectl get events --namespace default

# SSH into pod for debugging
kubectl exec -it pod/myapp-xxxxx -- /bin/sh

# Port-forward for manual testing
kubectl port-forward pod/myapp-xxxxx 8080:8080

Image Pull Issues

# Check image availability
docker pull myregistry.azurecr.io/myapp:latest

# Verify registry credentials in cluster
kubectl get secrets
kubectl describe secret myregistry-secret

# Add registry secret if missing
kubectl create secret docker-registry myregistry-secret \
  --docker-server=myregistry.azurecr.io \
  --docker-username=$USERNAME \
  --docker-password=$PASSWORD \
  --docker-email=user@example.com

Advanced Workflows

CI/CD Integration

# Build in CI/CD pipeline
draft build --registry $ACR_LOGIN_SERVER --push

# Deploy from pipeline
draft up --namespace prod --wait

# Example GitHub Actions step
# - name: Deploy with Draft
#   run: |
#     draft up --namespace ${{ secrets.K8S_NAMESPACE }}

Draft with Docker Compose (Local Development)

version: '3.9'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      PORT: "8080"
    volumes:
      - .:/app

Best Practices

• Use draft create to scaffold new projects - avoid manual Dockerfile creation
• Test locally with docker run before pushing to registry
• Use meaningful image tags (semantic versioning) not just latest
• Configure resource requests and limits in Helm values
• Implement health checks and probes in Kubernetes deployment
• Use separate Helm values files for different environments (dev, staging, prod)
• Keep Dockerfile minimal - use multi-stage builds when possible
• Always specify image pull policy and registry secrets
• Use namespace isolation for different environments
• Monitor and log application health after deployment
• Implement GitOps workflow with Helm and Draft together
• Document custom modifications to auto-generated files

Resources

• Draft Official Documentation
• GitHub Repository
• Getting Started Guide
• Helm Documentation
• Kubernetes Documentation

---

Last updated: 2025-03-30