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

deploy loads one workload from a file; the other commands accept files or directories with -f.

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

• deploy applies the workload definition, including image and secret updates.
• status shows the workload's state on each VM.
• restart restarts the deployed workload with its existing image and environment.
• remove removes the workload 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:
    - name: APP_ENV
      value: production
    - name: DATABASE_URL
      valueFrom:
        secretKeyRef:
          name: projects/acme-prod/secrets/database-url
          version: latest

http:
  containerPort: 3000
  startupProbe:
    httpGet:
      path: /up

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"]

Secrets

Sunstone can fill environment variables from Google Secret Manager. During deployment, it reads each VM’s secrets over SSH using that VM’s service account. The account must have access to the secrets before Sunstone can change the workload’s containers.

In the workload file, valueFrom.secretKeyRef identifies the secret by name and version. For example, if gcp.project is acme-prod, the name database-url means projects/acme-prod/secrets/database-url. To read a secret from another project, use its full name, such as projects/other-project/secrets/database-url. The version can be latest or a quoted number like "3". Secrets can sit alongside plain value entries, and plain environment maps still work.

Restarts and VM reboots reuse deployed secret values. Run sunstone deploy to pick up changed secrets.

These values pass through Sunstone’s memory and remain visible through docker inspect.

Inspiration

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