Sunstone

Deploy containers without deploying an orchestrator.

Sunstone deploys container images directly to Google Cloud VMs while the machines and surrounding infrastructure remain yours.

Sunstone is under development.

Principles

Orchestrators like Kubernetes solve important problems. For applications that fit comfortably on a few VMs, Sunstone follows a simpler path.

1. Pay for workloads, not orchestration. A few well-sized VMs can take an application far.
2. Zero downtime for HTTP workloads. Sunstone switches traffic only after the replacement is ready.
3. Security comes first. Sunstone builds on GCP’s security model to make good practices part of every deployment.
4. Keep deployment direct. Sunstone talks to machines without a control plane in between.
5. Leave state to managed services. Databases and durable data deserve systems built to protect them.

How Sunstone works

What’s in the mix

Container-Optimized OS (COS) is Google’s minimal, container-focused operating system for Compute Engine. It includes Docker and containerd, has a read-only verified root filesystem, and removes packages that a container host does not need. Sunstone targets COS to provide one small, predictable host environment instead of supporting arbitrary Linux distributions.

Private Compute Engine VMs run without external IP addresses. Application traffic reaches HTTP workloads through Cloud Load Balancing, while deployment traffic reaches the VMs through IAP. This keeps the machines off the public internet and avoids exposing SSH directly. The VPC must provide the required access to Google APIs and outbound services.

IAP, OS Login, and SSH each serve a different purpose. IAP creates an IAM-controlled tunnel to a VM’s internal address. OS Login controls who may log in using Google identities and IAM roles. SSH carries Sunstone’s commands through that tunnel. Together, they avoid public SSH endpoints, bastion hosts, and manually managed SSH keys.

Sunbeam runs once on each VM. It routes requests to HTTP workloads, waits for replacements to become ready, switches traffic, and drains old containers. Background workloads run without the proxy.

Google Cloud services provide the surrounding capabilities. Artifact Registry stores images, Secret Manager supplies secrets, Cloud Logging receives logs, and managed services such as Cloud SQL, Memorystore, and Cloud Storage hold durable state.

Terraform or OpenTofu provisions the VPC, VMs, IAM policies, load balancer, and managed services. CI/CD builds container images and runs Sunstone to deploy them.

A workload runs one container on one or more VMs. Sunstone replaces containers one VM at a time.

For HTTP workloads, the replacement starts alongside the container serving traffic. Sunbeam switches traffic after the replacement is ready, then drains and stops the old container. Background workloads stop cleanly before their replacements start.

You provision projects, networks, IAM, VMs, and load balancers separately.

Commands

Use -f to pass a workload file or directory.

sunstone deploy  -f FILE_OR_DIRECTORY
sunstone status  -f FILE_OR_DIRECTORY
sunstone restart -f FILE_OR_DIRECTORY
sunstone remove  -f FILE_OR_DIRECTORY

• deploy validates and deploys the workload.
• status reports its state on each VM.
• restart restarts it one VM at a time.
• remove drains traffic and removes it while leaving the VMs and Sunbeam running.

Run sunstone COMMAND --help for complete usage and options.

Configuration

Each YAML document defines one workload and one container.

name: storefront-web

gcp:
  project: acme-prod
  instances:
    - zone: us-central1-a
      name: storefront-1
    - zone: us-central1-b
      name: storefront-2

container:
  image: us-central1-docker.pkg.dev/acme-prod/apps/storefront
  command: ["bin/web"]

  env:
    APP_ENV: production
    DATABASE_URL:
      secret: projects/acme-prod/secrets/database-url/versions/latest

  resources:
    cpu:
      shares: 1024
    memory:
      limit: 512MiB

  readinessProbe:
    httpGet:
      path: /up
      port: 3000

http:
  port: 3000
  routes:
    - host: shop.example.com

Sunstone configures CPU and memory differently because they behave differently when containers share a VM. CPU is compressible. A container can receive less CPU and keep running, only more slowly. CPU shares only matter when the VM is busy. Containers with more shares get more CPU. When the VM has spare CPU, any container can use it.

Memory is incompressible. A container cannot adapt to memory pressure merely by running more slowly. A hard memory limit protects other workloads on the host, and exceeding it can cause an out-of-memory kill.

HTTP workloads and background workloads use the same configuration format. Here is a background workload using that format.

name: storefront-jobs

gcp:
  project: acme-prod
  instances:
    - zone: us-central1-a
      name: storefront-jobs-1

container:
  image: us-central1-docker.pkg.dev/acme-prod/apps/storefront
  command: ["bin/jobs"]

Inspiration

• Kamal for its imperative deployment workflow.
• Knative for its workload and traffic model.
• Cloud Run for its container configuration and Google Cloud integration.