BYOCloud overview

​

Goal

Understand the production security, ownership, operation, reconciliation, and deletion contract before connecting a cloud account.

​

Prerequisites

• A StackShift account
• A supported provider account for Hetzner, DigitalOcean, AWS, or Azure

​

Workflow

​

What BYOCloud includes

• Versioned AEAD-encrypted Hetzner and DigitalOcean tokens bound to tenant, provider, and connection ID
• AWS assumed roles with server-generated external IDs and Azure five-minute workload-federated assertions
• Provisioning StackShift nodes in customer-owned Hetzner, DigitalOcean, AWS, and Azure accounts
• Signed bootstrap, exact provider identity verification, WireGuard-only agent access, rotating mTLS, health tracking, retry, reboot, cleanup, and reconciliation
• Node-scoped cloud resource operations such as volumes, snapshots, placement metadata, and stable public IP actions where supported
• Provider metadata surfaced through StackShift node concepts instead of provider-native consoles

​

Provider identity contract

• Hetzner accepts a project-scoped read/write token.
• DigitalOcean accepts a scoped token for Droplets, firewalls, tags, VPCs, volumes, snapshots, and Reserved IPs.
• AWS accepts a role ARN and region only; access keys and session tokens are rejected.
• Azure accepts tenant, subscription, and client IDs plus the returned workload-federation coordinates; client secrets are rejected.
• Validation uses reads, permission simulation, or non-creating probes and returns exact missing actions.

​

Network and node identity

• StackShift creates an isolated managed network unless a customer-selected network is explicitly validated.
• Provider firewalls expose workload ports only; agent TCP 8443 and SSH are never opened by default.
• Cloud-init carries only a short-lived enrollment ticket and signed bootstrap coordinates.
• Instance ID, operation tag, region, node tag, and provider ownership are verified before ticket exchange.
• The agent listens only on its allocated overlay address and presents the exact node certificate.
• Registry access uses 15-minute pull-only grants for immutable digests assigned to the node.

​

How StackShift production prepares the trust authorities

The production deployment prepares the required authorities idempotently; a platform operator does not paste generated private values into Compose or create a qualification JSON file by hand. This separation keeps enrollment available without making the existing management tunnel disposable or turning private signing material into application configuration.

• A local mode-0600 Ed25519 seed signs the immutable bootstrap manifest and six OS/architecture host profiles. Only its derived public key is supplied to the running control plane.
• The control-plane host creates an online node intermediate signed by the existing worker-agent CA, plus separate provider-federation and registry-grant signing keys. These remain owner-only host files mounted read-only into the API.
• Deployment reads the public key of the already-running ssmgmt0 interface and requires an exact match before starting the overlay peer controller.
• The peer controller never recreates the interface, private key, address, listen port, routes, or existing deployment-host peer. It keeps a separate inventory and changes only BYOS/BYOC peers that StackShift added.
• A partial keyset, invalid certificate chain, changed WireGuard public key, or unreadable owner-only file stops preparation instead of overwriting working infrastructure.

​

Durable operation contract

• Provision, reboot, retry, deletion, volume, snapshot, stable-IP, and refresh mutations require idempotency keys.
• Operations persist revision, lease owner and expiry, next attempt, provider request identity, progress, cleanup state, and structured errors.
• Workers claim work with PostgreSQL row locks and SKIP LOCKED and transition with compare-and-swap revisions.
• A lost provider response triggers deterministic tagged discovery instead of duplicate creation.
• Expired leases are recovered by another worker with bounded exponential backoff.

​

Reconciliation and tombstones

• Tenant refresh is node-scoped; it never starts a fleet-wide reconciliation pass.
• A separately leased worker checks drift, orphans, credentials, certificates, overlay state, and stuck operations.
• Node and provider-resource tombstones remain for 90 days for operations, snapshots, billing, ownership, and audit evidence.

​

Safe deletion

Deletion returns a structured 409 blocker response while projects, stacks, databases, volumes, or snapshots remain. After blockers are cleared, StackShift removes add-ons, confirms provider instance absence, revokes identity, and soft-deletes the node. Provider errors remain persisted and retryable; deletion is never reported optimistically.

​

Expected result

​

Common failures

​

Related guides