Kubernetes Deployment with Helm

Deploy FastSkill as a production-ready service in Kubernetes using the official Helm chart. The chart supports two deployment modes: simple proxy-only for small teams, or full registry with S3 backend for advanced use cases.

Overview

This chart supports two deployment modes:

Proxy Only - Simple deployment, no external dependencies
Full Registry + Proxy - Advanced deployment with S3 backend and Git-based registry index

Prerequisites

Common (Both Modes)

Kubernetes 1.19+
Helm 3.0+
Persistent storage

Proxy Only Mode

No additional requirements

Full Registry Mode

S3-compatible storage (AWS S3, MinIO, DigitalOcean Spaces, etc.)
GitHub Personal Access Token (repo scope)
Git repository for registry index
OpenAI API key (optional, for semantic search)

Deployment Mode 1: Proxy Only (Recommended for Small Teams)

What You Get

Proxy server that intercepts Anthropic API calls and injects skills
Skills loaded from local directory/PVC
No S3 or GitHub setup required
Simple, fast deployment

Installation Steps

Create namespace
Install chart with registry disabled
Populate skills directory
Verify deployment

Complete Example

# Step 1: Create namespace
kubectl create namespace fastskill

# Step 2: Install chart (proxy only)
helm install fastskill ./tools/fastskill/helm/fastskill \
  --namespace fastskill \
  --set registry.enabled=false \
  --set proxy.enabled=true \
  --set persistence.skills.size=5Gi

# Step 3: Populate skills directory
# Option A: Copy skills from local directory
# First, get the pod name
POD_NAME=$(kubectl get pods -n fastskill -l app.kubernetes.io/component=proxy -o jsonpath='{.items[0].metadata.name}')
kubectl cp ./my-skills fastskill/$POD_NAME:/app/skills

# Option B: Use existing PVC with pre-populated skills
helm upgrade fastskill ./tools/fastskill/helm/fastskill \
  --namespace fastskill \
  --set registry.enabled=false \
  --set proxy.enabled=true \
  --set persistence.skills.existingClaim=my-skills-pvc

# Step 4: Verify deployment
kubectl get pods -n fastskill
kubectl port-forward -n fastskill svc/fastskill-proxy 8081:8081

# Test health endpoint
curl http://localhost:8081/health

# Test proxy with Anthropic API call
curl -X POST http://localhost:8081/v1/messages \
  -H "x-api-key: YOUR_ANTHROPIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-3-sonnet-20240229", "messages": [{"role": "user", "content": "Hello"}]}'

Configuration Options

Use values-proxy-only.yaml or set values directly:

registry:
  enabled: false

proxy:
  enabled: true
  replicaCount: 1
  resources:
    limits:
      cpu: "500m"
      memory: "512Mi"
    requests:
      cpu: "250m"
      memory: "256Mi"

persistence:
  skills:
    enabled: true
    size: 5Gi
    # Option: Use existing PVC with pre-populated skills
    # existingClaim: "my-skills-pvc"
  registryIndex:
    enabled: false

fastskill:
  logLevel: INFO

Install with custom values:

helm install fastskill ./tools/fastskill/helm/fastskill \
  -f ./tools/fastskill/helm/fastskill/values-proxy-only.yaml \
  --namespace fastskill

Deployment Mode 2: Full Registry with S3 Backend (Advanced)

What You Get

Registry server with web UI for skill management
Skill publishing via REST API
S3 blob storage for skill packages
Git-based registry index for version control
Proxy server with skill injection
Optional semantic search with OpenAI

Installation Steps

Create S3 bucket and IAM credentials
Create GitHub repository for registry index
Create Kubernetes secrets
Install chart with registry enabled
Verify deployment

Complete Example

# Step 1: Create S3 bucket (AWS example)
aws s3 mb s3://my-fastskill-registry --region us-east-1
aws s3api put-public-access-block \
  --bucket my-fastskill-registry \
  --public-access-block-configuration \
  "BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"

# Create IAM user with S3 access
aws iam create-user --user-name fastskill-registry
aws iam attach-user-policy \
  --user-name fastskill-registry \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess
aws iam create-access-key --user-name fastskill-registry
# Save the AccessKeyId and SecretAccessKey

# Step 2: Create GitHub repository for registry index
# Create empty repo: https://github.com/your-org/fastskill-registry-index
# Create GitHub PAT with repo scope: https://github.com/settings/tokens

# Step 3: Create Kubernetes secrets
kubectl create namespace fastskill

kubectl create secret generic fastskill-github-token \
  --from-literal=GITHUB_TOKEN=ghp_your_token_here \
  --namespace fastskill

kubectl create secret generic fastskill-s3-credentials \
  --from-literal=AWS_ACCESS_KEY_ID=AKIA... \
  --from-literal=AWS_SECRET_ACCESS_KEY=secret... \
  --namespace fastskill

# Optional: OpenAI API key for semantic search
kubectl create secret generic fastskill-openai-key \
  --from-literal=OPENAI_API_KEY=sk-... \
  --namespace fastskill

# Step 4: Install chart with registry enabled
helm install fastskill ./tools/fastskill/helm/fastskill \
  --namespace fastskill \
  --set s3.bucket=my-fastskill-registry \
  --set s3.region=us-east-1 \
  --set s3.blobBaseUrl=https://my-fastskill-registry.s3.amazonaws.com/skills \
  --set registryIndex.url=https://github.com/your-org/fastskill-registry-index.git

# Or use values file
helm install fastskill ./tools/fastskill/helm/fastskill \
  -f ./tools/fastskill/helm/fastskill/values-registry-s3.yaml \
  --namespace fastskill

# Step 5: Verify deployment
kubectl get pods -n fastskill
kubectl wait --for=condition=ready pod -l app.kubernetes.io/component=registry -n fastskill --timeout=300s
kubectl wait --for=condition=ready pod -l app.kubernetes.io/component=proxy -n fastskill --timeout=300s

# Test registry API
kubectl port-forward -n fastskill svc/fastskill-registry 8080:8080
curl http://localhost:8080/api/status

# Access web UI
open http://localhost:8080/registry

# Test proxy
kubectl port-forward -n fastskill svc/fastskill-proxy 8081:8081
curl http://localhost:8081/health

S3-Compatible Storage Options

AWS S3 (Default)

s3:
  bucket: "my-fastskill-registry"
  region: "us-east-1"
  endpoint: ""  # Leave empty for AWS S3
  blobBaseUrl: "https://my-fastskill-registry.s3.amazonaws.com/skills"

MinIO (Self-hosted)

s3:
  bucket: "fastskill-registry"
  region: "us-east-1"
  endpoint: "http://minio.example.com:9000"
  blobBaseUrl: "http://minio.example.com:9000/fastskill-registry/skills"

DigitalOcean Spaces

s3:
  bucket: "my-space-name"
  region: "nyc3"
  endpoint: "https://nyc3.digitaloceanspaces.com"
  blobBaseUrl: "https://my-space-name.nyc3.digitaloceanspaces.com/skills"

Cloudflare R2

s3:
  bucket: "my-r2-bucket"
  region: "auto"
  endpoint: "https://ACCOUNT_ID.r2.cloudflarestorage.com"
  blobBaseUrl: "https://ACCOUNT_ID.r2.cloudflarestorage.com/my-r2-bucket/skills"

Configuration Options

Use values-registry-s3.yaml or set values directly:

registry:
  enabled: true
  replicaCount: 1
  resources:
    limits:
      cpu: "1"
      memory: "1Gi"
    requests:
      cpu: "500m"
      memory: "512Mi"

proxy:
  enabled: true
  replicaCount: 1

persistence:
  skills:
    enabled: true
    size: 10Gi
  registryIndex:
    enabled: true
    size: 5Gi

s3:
  bucket: "my-fastskill-registry"
  region: "us-east-1"
  endpoint: ""  # Leave empty for AWS S3
  blobBaseUrl: "https://my-fastskill-registry.s3.amazonaws.com/skills"

registryIndex:
  url: "https://github.com/your-org/fastskill-registry-index.git"
  branch: main

openai:
  enabled: false  # Enable for semantic search

fastskill:
  logLevel: INFO

Values Reference

Component Toggles

Parameter	Description	Default
`registry.enabled`	Enable registry server	`true`
`proxy.enabled`	Enable proxy server	`true`

Resource Configuration

Parameter	Description	Default
`registry.replicaCount`	Number of registry replicas	`1`
`registry.resources.limits.cpu`	Registry CPU limit	`"1"`
`registry.resources.limits.memory`	Registry memory limit	`"1Gi"`
`registry.resources.requests.cpu`	Registry CPU request	`"500m"`
`registry.resources.requests.memory`	Registry memory request	`"512Mi"`
`proxy.replicaCount`	Number of proxy replicas	`1`
`proxy.resources.limits.cpu`	Proxy CPU limit	`"500m"`
`proxy.resources.limits.memory`	Proxy memory limit	`"512Mi"`
`proxy.resources.requests.cpu`	Proxy CPU request	`"250m"`
`proxy.resources.requests.memory`	Proxy memory request	`"256Mi"`

Storage Configuration

Parameter	Description	Default
`persistence.skills.enabled`	Enable skills PVC	`true`
`persistence.skills.size`	Skills storage size	`10Gi`
`persistence.skills.existingClaim`	Use existing PVC	`""`
`persistence.registryIndex.enabled`	Enable registry index PVC	`true`
`persistence.registryIndex.size`	Registry index storage size	`5Gi`

S3 Configuration (Registry Mode Only)

Parameter	Description	Default
`s3.bucket`	S3 bucket name	`""` (required for registry)
`s3.region`	AWS region	`us-east-1`
`s3.endpoint`	S3-compatible service endpoint	`""`
`s3.blobBaseUrl`	Base URL for published packages	`""`

Registry Index Configuration (Registry Mode Only)

Parameter	Description	Default
`registryIndex.url`	Git repository URL	`""` (required for registry)
`registryIndex.branch`	Git branch	`main`

Optional Configuration

Parameter	Description	Default
`openai.enabled`	Enable OpenAI integration	`false`
`fastskill.logLevel`	Logging level	`INFO`
`ingress.enabled`	Enable ingress	`false`

Environment-Specific Values

Development (`values-dev.yaml`)

Lower resource limits
Debug logging
Smaller storage sizes
Ingress disabled (use port-forward)

Staging (`values-staging.yaml`)

Production-like resources
Info logging
Standard storage sizes
Ingress with staging certificates

Production (`values-prod.yaml`)

Higher resource limits
Multiple replicas for HA
Warn/Error logging
Larger storage sizes
Production ingress with TLS

Accessing Services

Port Forwarding (Development)

# Registry server
kubectl port-forward -n fastskill svc/fastskill-registry 8080:8080

# Proxy server
kubectl port-forward -n fastskill svc/fastskill-proxy 8081:8081

Ingress (Production)

Registry UI: https://fastskill.example.com/registry
Registry API: https://fastskill.example.com/api/*
Proxy: https://fastskill.example.com/proxy/*

Health Checks

Registry Server

Readiness: GET /api/status
Liveness: GET /api/status
Returns JSON with service status

Proxy Server

Readiness: GET /health
Liveness: GET /health
Returns plain text “Proxy server is running”

API Endpoints

Registry Server

GET /api/status - Service status
GET /api/skills - List all skills
GET /api/skills/:id - Get skill details
POST /api/search - Search skills
POST /api/registry/publish - Publish skill package
GET /registry - Web UI

Proxy Server

GET /health - Health check
POST /v1/messages - Proxy Anthropic API calls

Upgrading

# Upgrade with new values
helm upgrade fastskill ./tools/fastskill/helm/fastskill \
  -f ./tools/fastskill/helm/fastskill/values-prod.yaml \
  --namespace fastskill

# Upgrade with new image tag
helm upgrade fastskill ./tools/fastskill/helm/fastskill \
  --set image.tag=v0.2.0 \
  --namespace fastskill

Uninstalling

helm uninstall fastskill --namespace fastskill

This does not delete PVCs. To remove storage:

kubectl delete pvc -n fastskill -l app.kubernetes.io/name=fastskill

Architecture

Components

Registry Deployment: Runs fastskill serve --enable-registry
- Requires: S3 storage, GitHub token, registry index path
- Provides: REST API, Web UI, skill publishing
Proxy Deployment: Runs fastskill proxy
- Requires: Skills directory (read-only)
- Provides: Anthropic API proxy with skill injection
Init Container: Clones registry index Git repository
- Runs only if registry index path is empty
- Uses GitHub token for authentication

Storage

Skills PVC: Shared between registry and proxy
- Mount path: /app/skills
- Access mode: ReadWriteOnce (or ReadWriteMany for scaling)
Registry Index PVC: Registry server only
- Mount path: /app/registry-index
- Access mode: ReadWriteOnce

Networking

Registry Service: ClusterIP on port 8080
Proxy Service: ClusterIP on port 8081
Ingress: Optional, for external access

Troubleshooting

Registry Server Won’t Start

Error: “Registry enabled but blob storage not configured” Solution: Ensure S3 configuration is set:

s3:
  bucket: your-bucket
  region: us-east-1

Error: “Registry enabled but registry index path not configured” Solution: Ensure registry index URL is set:

registryIndex:
  url: "https://github.com/org/repo.git"

Init Container Fails

Error: “Failed to clone registry index” Solution:

Verify GitHub token has repository access
Check registry index URL is correct
Ensure network connectivity to GitHub

Storage Issues

Error: “PVC not found” Solution:

Check storage class exists: kubectl get storageclass
Verify PVC was created: kubectl get pvc -n fastskill
Check storage class in values.yaml matches cluster

Secret Access Issues

Error: “Secret not found” Solution:

Verify secrets exist: kubectl get secrets -n fastskill
Check secret names match values.yaml
Ensure secrets are in the correct namespace

Health Check Failures

Error: “Readiness probe failed” Solution:

Check pod logs: kubectl logs -n fastskill <pod-name>
Verify service is listening on correct port
Check network policies allow health check traffic
Increase initialDelaySeconds if service takes longer to start

S3 Connection Issues

Error: “Failed to connect to S3” Solution:

Verify AWS credentials are correct
Check S3 bucket exists and is accessible
For S3-compatible services, ensure s3.endpoint is set
Verify network connectivity to S3 endpoint

Security Considerations

Secrets Management: Never commit secrets to version control. Use Kubernetes secrets or external secret management.
Network Policies: Consider implementing network policies to restrict pod-to-pod communication.
RBAC: Service account has minimal permissions. Adjust as needed for your environment.
TLS: Always use TLS in production. Configure ingress with valid certificates.
Image Security: Use specific image tags (not latest) in production. Scan images for vulnerabilities.

Chart Location

The Helm chart is located at:

tools/fastskill/helm/fastskill/

For detailed chart documentation, see the chart README.

Getting Started

Configuration

Skill Management

Discovery & Routing

Tool Calling

Progressive Loading

API Reference

CLI Reference

Registry

Examples & Tutorials

Advanced Topics

Integration

Community

​Kubernetes Deployment with Helm

​Overview

​Prerequisites

​Common (Both Modes)

​Proxy Only Mode

​Full Registry Mode

​Deployment Mode 1: Proxy Only (Recommended for Small Teams)

​What You Get

​Installation Steps

​Complete Example

​Configuration Options

​Deployment Mode 2: Full Registry with S3 Backend (Advanced)

​What You Get

​Installation Steps

​Complete Example

​S3-Compatible Storage Options

​AWS S3 (Default)

​MinIO (Self-hosted)

​DigitalOcean Spaces

​Cloudflare R2

​Configuration Options

​Values Reference

​Component Toggles

​Resource Configuration

​Storage Configuration

​S3 Configuration (Registry Mode Only)

​Registry Index Configuration (Registry Mode Only)

​Optional Configuration

​Environment-Specific Values

​Development (values-dev.yaml)

​Staging (values-staging.yaml)

​Production (values-prod.yaml)

​Accessing Services

​Port Forwarding (Development)

​Ingress (Production)

​Health Checks

​Registry Server

​Proxy Server

​API Endpoints

​Registry Server

​Proxy Server

​Upgrading

​Uninstalling

​Architecture

​Components

​Storage

​Networking

​Troubleshooting

​Registry Server Won’t Start

​Init Container Fails

​Storage Issues

​Secret Access Issues

​Health Check Failures

​S3 Connection Issues

​Security Considerations

​Chart Location

Kubernetes Deployment with Helm

Overview

Prerequisites

Common (Both Modes)

Proxy Only Mode

Full Registry Mode

Deployment Mode 1: Proxy Only (Recommended for Small Teams)

What You Get

Installation Steps

Complete Example

Configuration Options

Deployment Mode 2: Full Registry with S3 Backend (Advanced)

What You Get

Installation Steps

Complete Example

S3-Compatible Storage Options

AWS S3 (Default)

MinIO (Self-hosted)

DigitalOcean Spaces

Cloudflare R2

Configuration Options

Values Reference

Component Toggles

Resource Configuration

Storage Configuration

S3 Configuration (Registry Mode Only)

Registry Index Configuration (Registry Mode Only)

Optional Configuration

Environment-Specific Values

Development (`values-dev.yaml`)

Staging (`values-staging.yaml`)

Production (`values-prod.yaml`)

Accessing Services

Port Forwarding (Development)

Ingress (Production)

Health Checks

Registry Server

Proxy Server

API Endpoints

Registry Server

Proxy Server

Upgrading

Uninstalling

Architecture

Components

Storage

Networking

Troubleshooting

Registry Server Won’t Start

Init Container Fails

Storage Issues

Secret Access Issues

Health Check Failures

S3 Connection Issues

Security Considerations

Chart Location