Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Walk from a least-privilege provider identity to a healthy BYOCloud node without storing AWS keys or Azure client secrets.

​
Prerequisites

  • A provider account with lifecycle permissions
  • Dashboard access to the Nodes page
  • Provider quota for the selected instance, network, storage, and address resources

​
Workflow

1
Create the provider identity using the provider-specific contract below.
2
Save the connection and apply the returned AWS trust policy or Azure federation coordinates.
3
Validate exact effective permissions without creating resources.
4
Choose a tested region, StackShift tier, and node name.
5
Follow the durable operation through provider identity verification, signed bootstrap, enrollment, and healthy heartbeat.

​
Provider setup expectations

  • Hetzner: create a read/write token inside the owning Cloud project. Validation requires api_token:read_write.
  • DigitalOcean: scope the token to create/read/delete Droplets, firewalls, VPCs, block storage, snapshots, and Reserved IPs plus create/read tags.
  • AWS: enter the role ARN and default region, save, and apply the exact returned trust policy containing the StackShift principal and generated sts:ExternalId.
  • AWS validation assumes the role, reads caller identity, and simulates every required IAM/EC2 action. Access keys are rejected.
  • Azure: enter tenant, subscription, and client IDs, then create a federated credential with the returned issuer, connection-specific subject, and api://AzureADTokenExchange audience.
  • Azure validation exchanges a short-lived assertion and reads effective permissions. Client secrets are rejected.

​
Tested provider catalog

  • Hetzner: fsn1, nbg1, hel1; Starter/Growth/Pro map to CX23/CX33/CX43.
  • DigitalOcean: nyc3, ams3, fra1; tiers map to 1vCPU-2GB, 2vCPU-4GB, and 4vCPU-8GB.
  • AWS: us-east-1, us-west-2, eu-west-1; tiers map to t3.small, t3.medium, and t3.xlarge.
  • Azure: eastus, westeurope, southafricanorth; tiers map to Standard_B2s, Standard_B2ms, and Standard_A4_v2.
  • The API catalog, not arbitrary provider SKU input, is the source of truth.

​
Provisioning model

  • The operation progresses through requested, validating, creating, bootstrapping, enrolling, and active.
  • Deterministic tags allow StackShift to recover an existing resource after an ambiguous provider response.
  • Cloud-init includes only the short-lived ticket and signed bootstrap coordinates.
  • Provider instance identity and operation ownership are verified before ticket exchange.
  • A running provider instance is incomplete until WireGuard, mTLS, and heartbeat readiness pass.

​
Retry safely

Do not create a second node when a response is delayed or provisioning fails. Use Retry only when the operation reports retryable. The durable node ID, idempotency key, provider request identity, and deterministic tags prevent duplicate provider resources.

​
Expected result

A BYOCloud node is provisioned and ready to host projects, stacks, or database flows once healthy.

BYOCloud overview

Provision nodes in your own cloud account with scoped or federated access, durable operations, signed enrollment, private agent networking, and provider-confirmed cleanup.

BYOCloud cloud resources

Operate node-scoped provider inventory, volumes, snapshots, stable IPs, reboot, retry, refresh, and provider-confirmed deletion.

Maintenance mode

Use maintenance as a safety control before upgrades or disruptive host changes.