#Kubernetes Deployment

Zephyr's Kubernetes deployment option allows you to run the Zephyr edge worker on your own Kubernetes infrastructure. This deployment model provides maximum control over your infrastructure while leveraging Zephyr's deployment and versioning capabilities.

#Overview

The Kubernetes edge worker is a containerized service that handles asset uploads and serves your deployed applications. It integrates with:

• S3-compatible storage (AWS S3, MinIO, Ceph, etc.) for asset storage
• Redis-compatible KV store for environment configuration and snapshots

#Configuration

The recommended way to configure the worker is using a JSON config file mounted as a Kubernetes Secret. This approach keeps all your configuration in one place and makes it easier to manage secrets securely.

Alternatively, you can use environment variables directly, though this is less recommended for production deployments.

#JSON Config File (Recommended)

Create a JSON file containing all your configuration. All keys use the ZE_WORKER_ prefix:

// Example configuration
{
  "ZE_WORKER_JWT_SECRET": "your-secret-key",
  "ZE_WORKER_S3_ENDPOINT": "https://s3.amazonaws.com",
  "ZE_WORKER_S3_REGION": "us-east-1",
  "ZE_WORKER_S3_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
  "ZE_WORKER_S3_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "ZE_WORKER_S3_BUCKET": "zephyr-assets",
  "ZE_WORKER_S3_FORCE_PATH_STYLE": "false",
  "ZE_WORKER_REDIS_HOST": "redis.default.svc.cluster.local",
  "ZE_WORKER_REDIS_PORT": "6379",
  "ZE_WORKER_REDIS_PASSWORD": "your-redis-password",
  "ZE_WORKER_REDIS_TLS": "true",
  "ZE_WORKER_PORT": "8080",
  "ZE_WORKER_LOG_LEVEL": "info",
  "ZE_WORKER_DELIMITER": "-",
}

#Health Check Endpoints

The worker exposes the following health check endpoints for Kubernetes probes:

#Configuration Reference

Below is the complete reference for all available configuration options. These can be set in your JSON config file or as environment variables.

#Required Options

#Server Options

#S3 Options

#Redis Options

#Replication Options

#Using Environment Variables

While the JSON config file is recommended, you can also configure the worker using environment variables directly. This can be useful for simple setups or when integrating with external secret management systems.

Set ZE_WORKER_CONFIG_JSON to the path of your config file. If both are provided, values in the JSON file take precedence over environment variables.

env:
  - name: ZE_WORKER_JWT_SECRET
    valueFrom:
      secretKeyRef:
        name: ze-worker-secrets
        key: jwt-secret
  - name: ZE_WORKER_S3_ENDPOINT
    value: 'https://s3.us-west-2.amazonaws.com'
  - name: ZE_WORKER_S3_ACCESS_KEY_ID
    valueFrom:
      secretKeyRef:
        name: ze-worker-secrets
        key: s3-access-key
  # ... additional environment variables

#Scaling and Replication

Zephyr workers support two scaling modes that can be used independently or combined:

Check worker logs on startup to verify replication:

# Workers with REPLICAS_URLS set (replicate to other regions)
[K8s Worker] Replica mode enabled
[K8s Worker] Replica name: us-east-1
[K8s Worker] Replicating to 1 replica(s): https://ze.eu.example.com

# Workers without REPLICAS_URLS (receive-only, share storage with primary)
[K8s Worker] Replica mode enabled
[K8s Worker] Replica name: us-east-2
[K8s Worker] No replica URLs configured (receive-only mode)

#Same-Region Scaling

Multiple workers sharing the same S3 bucket and Redis instance. All workers read/write to the same storage, so no data replication is needed.

All workers use identical config. Only ZE_WORKER_REPLICA_NAME differs:

// US East - Worker 1
{
  "ZE_WORKER_REPLICA_NAME": "us-east-1-worker-1",
  "ZE_WORKER_S3_BUCKET": "zephyr-us-east",
  "ZE_WORKER_REDIS_HOST": "redis-us-east.example.com",
}

#Multi-Region Replication

Each region has its own S3 and Redis. One primary worker per region replicates data to other regions' primaries via HTTP sync.

Each region lists other regions' load balancer URLs:

// US East
{
  "ZE_WORKER_REPLICA_NAME": "us-east-1",
  "ZE_WORKER_REPLICAS_URLS": [
    "https://ze.eu.example.com",
    "https://ze.ap.example.com",
  ],
  "ZE_WORKER_S3_BUCKET": "zephyr-us-east",
  "ZE_WORKER_REDIS_HOST": "redis-us-east.example.com",
}

#Combined: Multi-Region with Scaling

Multiple workers per region (shared storage) + cross-region replication. All workers in a region replicate to one worker per other region.

All workers have ZE_WORKER_REPLICAS_URLS pointing to other regions' load balancers:

#Troubleshooting

#Common Issues

#Worker fails to start

1. Verify all required configuration options are set
2. Check that S3 endpoint is reachable from within the cluster
3. Ensure Redis host is resolvable and accessible
4. Check the worker logs using kubectl

#Readiness probe failing

1. Check S3 bucket exists and credentials have read/write access
2. Verify Redis connection (host, port, password, TLS settings)
3. Review worker logs for specific error messages

#Assets not serving correctly

1. Confirm ZE_WORKER_DELIMITER matches your DNS configuration
2. Verify S3 bucket policy allows the worker to read objects
3. Check that the Ingress or load balancer is routing traffic correctly

#Getting Help

If you encounter issues with your Kubernetes deployment, reach out to your Zephyr account representative or contact us on Discord.