vm

package
v0.0.0-...-6f76ffe Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package vm is the cloud-independent description of a virtual machine, or of a pool of them. It is the config tier behind three delivery paths that all want the same thing from a machine and would otherwise each grow their own copy of cloud-init, SSH readiness and key handling:

  • compose on one VM (P5),
  • k3s that SC stands up itself (P3),
  • a machine the operator brought (the `byo` driver — the zeroth cloud).

See forge/docs/design/2026-10-13/sc-russia-market-readiness/vm-matrix.md (D9).

Index

Constants

View Source
const (
	// AcmeStoreProject / AcmeStoreContainer: one per fleet, on host 0, in its own
	// compose project for the same reason the ingress has one — it belongs to the
	// RESOURCE and must survive a `docker compose down` of any stack.
	AcmeStoreProject   = "sc-acme-store"
	AcmeStoreContainer = "sc-acme-store"
	// AcmeStoreDataVolume holds the fleet's certificates and its ACME account key.
	//
	// External, like CaddyDataVolume and for the same reason, except that here the
	// stake is the whole fleet rather than one machine: `docker compose -p
	// sc-acme-store down -v` must not be able to delete the store every node reads
	// from. Losing it is a Let's Encrypt rate-limit event (50 certificates per
	// registered domain per week) and the fleet serves unencrypted until it clears.
	AcmeStoreDataVolume = "sc-acme-store-data"
	// AcmeStoreIdentity is the single S3 identity in the generated config. One
	// identity, used by every node: this store exists to be shared, and a per-node
	// credential would buy nothing (they already share the bucket, the prefix, the
	// locks and the certificates) at the cost of N secrets to rotate.
	AcmeStoreIdentity = "acme"

	// DefaultAcmeStoreImage is SeaweedFS, pinned.
	//
	// SeaweedFS and not minio, and the reason is licensing rather than taste: minio's
	// server is AGPL-3.0, and SC would be shipping it as the default component of a
	// commercial platform's fleet. SeaweedFS is Apache-2.0. It is also one static
	// binary with an S3 gateway built in (`weed server -s3`), which is the whole of
	// what is needed here — this store holds a few kilobytes of certificates and a
	// lock file, not objects.
	//
	// Pinned to an exact tag, not `latest`, because this is a server every node's TLS
	// depends on and a silent upgrade underneath a running fleet is not something an
	// operator asked for. 4.50 is the version the 3-VPS fleet stand ran
	// (digest sha256:b2e5156274…, amd64); bump it deliberately, with a smoke.
	DefaultAcmeStoreImage = "chrislusf/seaweedfs:4.50"
	// DefaultAcmeStorePort is SeaweedFS's conventional S3 port.
	DefaultAcmeStorePort = 8333
	// DefaultAcmeStoreBucket is the bucket SC creates in it.
	DefaultAcmeStoreBucket = "sc-acme"

	// AcmeStoreManagedCredential is what the config tier puts in the synthesized
	// AcmeStorage's credential fields.
	//
	// It is a SENTINEL, never a value, and nothing ever sends it anywhere: the
	// Caddyfile renderer only tests these fields for emptiness and then writes
	// `{$SC_ACME_S3_ACCESS_KEY}` placeholders, so what matters is that they are
	// non-empty and that a reader of a dumped config can tell this store's credential
	// is generated rather than configured. The real values are created at provision
	// time (pkg/clouds/pulumi/vm/acme_store.go) and delivered only in the two 0600
	// files that need them: the ingress env file on every node, and the store's own
	// s3 config on host 0.
	AcmeStoreManagedCredential = "<managed-by-sc>"
)

The SC-managed certificate store: the thing `ingress.acmeStore.enable: true` stands up on the FIRST machine of the fleet so that `ingress.acmeStorage` has a bucket to point at on a hoster that sells none.

Why it exists at all. A fleet needs one shared certificate store or it has no origin HTTPS (see VmIngress.AcmeStorage for the mechanism). On Yandex and GCP the bucket is a resource in the same parent stack and `acmeStorage` is the whole answer. On Cloud.ru, MWS and byo there is no bucket to buy, and the operator's only remaining option was to run an S3 server themselves — which is the one piece of a fleet SC was asking a human to assemble by hand, including its credentials.

View Source
const (
	// ImageDeliveryRegistry builds, pushes to a registry and pulls on the machine —
	// the same path every other target uses.
	ImageDeliveryRegistry = "registry"
	// ImageDeliverySshTar streams the image over SSH (`sc image ship`, P5.1) and needs
	// no registry at all. It is the default, because "no registry" is the reason this
	// delivery path exists: see compose-on-vm.md §5 (and §5.4 for what it costs).
	ImageDeliverySshTar = "ssh-tar"
)

How the built image gets onto the machine.

View Source
const (
	// ExternalImagesShip pulls the image on the runner and streams it to the machine
	// in the same `sc image ship` as everything else. The machine needs no registry;
	// the RUNNER needs one. Private third-party images therefore need a `docker
	// login` + `docker pull` in CI before `sc deploy` — the ship only fetches what is
	// absent from the runner, so a pre-pulled image is simply shipped.
	ExternalImagesShip = "ship"
	// ExternalImagesPull leaves them to the machine's own `docker compose pull`. The
	// right choice when the machine has a route (or a `registryMirrors` entry) and the
	// runner does not, and the only choice for a private third-party registry the
	// runner cannot log into.
	ExternalImagesPull = "pull"
)

What happens to the images SC does NOT build — a `mongo:7` or a `redis:7` that a compose service only declares an `image:` for.

The default under `ssh-tar` is ExternalImagesShip, and that is the point of the setting existing at all: `ssh-tar` promises "the machine needs no registry", and until these were shipped too the promise held only for a stack with no third-party image in it. Everything else about the delivery was registry-free while a `mongo:7` quietly required the machine to reach Docker Hub — which, inside Russia, is the difference between a stack that comes up and one that does not (compose-on-vm.md §5.4, §8.3).

View Source
const (
	// StrategyBlueGreen brings the new slot up next to the old one, gates on its
	// health, flips Caddy and only then stops the old slot. Zero downtime, at the cost
	// of running both slots at once (compose-on-vm.md §9.1).
	StrategyBlueGreen = "blue-green"
	// StrategyRecreate stops the old containers and starts the new ones. A few seconds
	// of 502 in exchange for not doubling memory — the honest choice on a small
	// machine, and the operator's to make.
	StrategyRecreate = "recreate"
)

How a new version replaces the running one.

View Source
const (
	EnvCloud      = "SIMPLE_CONTAINER_CLOUD"
	EnvCloudVm    = "vm"
	EnvPort       = "PORT"
	EnvSlot       = "SIMPLE_CONTAINER_SLOT"
	EnvDeployment = "SIMPLE_CONTAINER_VERSION"
)

EnvCloudVm is set on every container SC runs on a VM, alongside PORT. It is the value `SIMPLE_CONTAINER_CLOUD` takes on this delivery path.

Known gap, load-bearing for the first live stand: go-aws-lambda-sdk serves plain HTTP only when SIMPLE_CONTAINER_CLOUD is "yandex" or LOCAL_DEBUG is set (pkg/service/service.go Start, pkg/service/yandex.go IsYandexCloudRuntime), so an image built on that SDK calls lambda.Start on a VM and never answers Caddy. The fix belongs in the SDK — treat any non-AWS cloud as HTTP mode — not here: setting SIMPLE_CONTAINER_CLOUD=yandex on a Cloud.ru VM would be SC lying about where the container runs, and the next reader of that env would believe it.

View Source
const (
	MountTypeVolume = "volume"
	MountTypeTmpfs  = "tmpfs"
)

Mount types SC renders. A `bind` mount is refused at conversion time: its source is a path on the developer's machine, which does not exist on the VM.

View Source
const (
	TextVolumeMode       = "0644"
	TextVolumeSecretMode = "0600"
)

TextVolumeMode / TextVolumeSecretMode are the modes of a rendered `textVolumes` entry. A config file is world-readable; one whose content came from `${secret:…}` is not — mixed config-with-a-secret-inside is the common case, and defaulting it to 0644 would quietly publish it to every user and every other container that bind-mounts the directory (§7.2).

View Source
const (
	// MeshInterface is the link name, which must be ≤ 15 bytes (IFNAMSIZ) — `sc-mesh`
	// is 7.
	MeshInterface = "sc-mesh"
	// MeshConfigPath is the wg-quick config. 0600: it names every peer, and on a
	// host that inlined its key it would hold one (SC's does not — see
	// MeshPrivateKeyPath).
	MeshConfigPath = "/etc/wireguard/" + MeshInterface + ".conf"
	// MeshPrivateKeyPath is where the machine keeps the key it generated itself.
	//
	// The key is generated ON the host (`wg genkey`) and never leaves it: the
	// provisioning step's stdout is the PUBLIC key only, so no private key enters
	// the Pulumi checkpoint, a command's input set, or a preview diff. Persistence
	// is this file being present, not SC having stored the value — which also means
	// a re-imaged machine simply generates a new key on the next provision and the
	// peers learn it in the same run, with nothing to push back at it.
	//
	// The config references it through `PostUp = wg set %i private-key …` rather than
	// inlining it, so that the rendered config is a pure function of the fleet's
	// public facts and SC never has to template a secret into a file.
	MeshPrivateKeyPath = "/etc/wireguard/" + MeshInterface + ".key"
	// MeshUnit is the systemd unit wg-quick generates for the interface.
	MeshUnit = "wg-quick@" + MeshInterface

	// DefaultMeshCidr is the overlay's address range.
	//
	// 10.88.0.0/24 is a deliberate choice of an UNFASHIONABLE corner of RFC 1918:
	// it has to not collide with the machines' real private networking (the clouds
	// hand out 10.0.x, 10.13-10.15.x, 172.31.x, 192.168.x), with docker's default
	// bridge (172.17.0.0/16) or its compose networks (172.18+), or with k3s's pod
	// and service CIDRs (10.42.0.0/16 and 10.43.0.0/16 — the two that would be a
	// genuinely confusing outage). A collision is the one failure here SC cannot
	// detect, so the field is overridable and this is only a default.
	DefaultMeshCidr = "10.88.0.0/24"
	// DefaultMeshPort is WireGuard's IANA-registered port.
	DefaultMeshPort = 51820

	// MeshKeepalive keeps a NAT binding open from both ends, in seconds.
	//
	// Set on every peer rather than only on the ones believed to be behind NAT,
	// because SC cannot know which those are and the cost of being wrong is
	// asymmetric: a keepalive on a directly-addressable peer is one 32-byte packet
	// every 25 s, and a missing one on a NATed peer is a tunnel that works until the
	// first idle minute and then silently stops carrying the certificate store.
	MeshKeepalive = 25
)

The names SC gives its own WireGuard tunnel on a machine.

`sc-mesh` and not `wg0`, which is not cosmetic: `wg0` is what every hand-written WireGuard tutorial calls the operator's own tunnel, and a byo machine may well already have one. An SC-managed interface that silently took that name would bring down the operator's access to the box it is provisioning, and `wg-quick down wg0` in a teardown would do it deliberately. Everything here is namespaced so that SC's mesh and whatever else the machine runs can coexist, and so that the teardown can only ever remove SC's own.

View Source
const (
	// CaddyProject is the compose project. It carries no stack-env prefix, which is
	// the one documented exception to the rule in NamePrefix: there is exactly one
	// of it per machine and its name is what an operator types.
	CaddyProject = "sc-caddy"
	// CaddyContainer is also `container_name`, because the blue-green flip reloads
	// Caddy with `docker exec sc-caddy …` and a generated container name would make
	// that command depend on the project's numbering.
	CaddyContainer = "sc-caddy"
	// CaddyDataVolume holds the ACME account key and every issued certificate.
	//
	// A named volume, NOT a path inside the config tree, and this is the single most
	// consequential choice in P5.3: Let's Encrypt allows 50 certificates per domain
	// per week, so an ingress that loses /data on every recreate burns through the
	// quota and then serves a site with no certificate at all. The config tree is
	// mounted read-only, which is also incompatible with Caddy writing into it —
	// compose-on-vm.md §3.1 draws `data/` under /etc/sc/caddy, and that part of the
	// drawing is wrong (§8.3 point 3 is the rule).
	CaddyDataVolume = "sc-caddy-data"
	// CaddyConfigVolume is Caddy's own config/autosave directory.
	CaddyConfigVolume = "sc-caddy-config"
	// CaddyContainerConfigDir is where the config tree is mounted INSIDE the
	// container. The paths written into the generated Caddyfile are container paths,
	// so they must not be derived from CaddyDir.
	CaddyContainerConfigDir = "/etc/caddy"
)

The ingress (Caddy) names. One Caddy per machine, in its own compose project, owned by the `vm` RESOURCE rather than by any stack — several stacks share one port 443, so the thing that holds it cannot belong to one of them (compose-on-vm.md §3, D15).

View Source
const (
	EnvAcmeEabKeyID  = "SC_ACME_EAB_KEY_ID"
	EnvAcmeEabMacKey = "SC_ACME_EAB_MAC_KEY"
)

The ingress env file's variable names. They are referenced from the generated Caddyfile as `{$...}` placeholders so that the credential lives only in a 0600 file delivered over stdin, and not in a config file an operator may paste into a ticket.

View Source
const (
	EnvAcmeS3AccessKey     = caddyassets.EnvAcmeS3AccessKey
	EnvAcmeS3SecretKey     = caddyassets.EnvAcmeS3SecretKey
	EnvAcmeS3EncryptionKey = caddyassets.EnvAcmeS3EncryptionKey

	DefaultAcmeStoragePrefix    = caddyassets.DefaultAcmeStoragePrefix
	DefaultAcmeStorageRegion    = caddyassets.DefaultAcmeStorageRegion
	AcmeStorageEncryptionKeyLen = caddyassets.AcmeStorageEncryptionKeyLen
)

The shared certificate store's names and defaults. Aliased from pkg/clouds/caddy, which both edges render from — the Kubernetes edge needs the same three env names and the same defaults, and a second copy of them is a second thing to get right.

SC_ACME_S3_ACCESS_KEY is not itself secret, but it travels with the other two so that the three lines of the `storage` block that carry credentials look the same in the generated Caddyfile — a reader should not have to know which of them is safe.

View Source
const (
	SlotA = "a"
	SlotB = "b"
)

The two blue-green slots. A stack-env occupies one of them at a time; a deploy brings up the other and flips Caddy to it (compose-on-vm.md §9.1).

View Source
const (
	HostPortRangeStart = 20000
	HostPortRangeEnd   = 30000
)

The host-port window SC publishes a stack's ingress on when Caddy is not fronting it — either because Caddy is not there yet (P5.2) or because the operator set `ingress.enable: false` (compose-on-vm.md §8.4).

View Source
const (
	PortLabelSsh     = "ssh"
	PortLabelHttp    = "http"
	PortLabelHttps   = "https"
	PortLabelHttpsH3 = "https-h3"
	// PortLabelMesh is the WireGuard overlay's listen port (see VmMesh).
	//
	// Opened to the INTERNET and not marked Internal, which looks like a mistake
	// next to the kubelet and etcd rules below and is not: a peer's endpoint is its
	// PUBLIC address — building the inner network is what the mesh is for, so there
	// is no inner network for this one hole to be scoped to. It is safe because
	// WireGuard answers a packet that does not authenticate against a known peer's
	// key with nothing at all: no reset, no error, no response. The port does not
	// appear in a scan and cannot be spoken to without a key from the fleet's own
	// config.
	PortLabelMesh = "mesh"
	ProtocolTcp   = "tcp"
	ProtocolUdp   = "udp"
)

The ports SC opens on every machine it created, regardless of what is deployed onto it.

22 always — it is the entire delivery path. 80 and 443 only when the machine runs the ingress: a host serving stacks on a published port has no business answering on 443, and opening it anyway is what makes a later "why is this reachable" audit expensive.

443/udp is HTTP/3, and it is opened because the Caddy compose project publishes it (caddy.go — `443:443/udp` alongside the TCP one). A container bound to UDP 443 behind a firewall that drops it is worse than not serving h3 at all: Caddy still advertises Alt-Svc, so every browser spends a connection attempt on a port that black-holes before falling back to TCP, and Chrome remembers the broken alt-svc.

View Source
const (
	// IngressPresetK3s is the k3s API port plus the NodePort range.
	IngressPresetK3s = "k3s"
	// IngressPresetVmCompose is the host-port range `vm-compose` publishes into.
	IngressPresetVmCompose = "vm-compose"
	// IngressPresetHttp is 80 and 443 (on both protocols) — what `ingress.enable`
	// opens, for a machine that serves the web WITHOUT SC's own Caddy in front.
	//
	// The live case it exists for: a k3s stand with `ingress` left off so that k3s
	// keeps 80/443, publishing a Service as `cloudExtras.serviceType: LoadBalancer`
	// through klipper-lb. Kubernetes binds the node's ports and reports success, and
	// the cloud firewall drops the traffic — a Service with an address that nothing
	// can reach.
	IngressPresetHttp = "http"
)

The presets a vm resource's `ingressPorts` may name instead of spelling out port numbers that belong to one of SC's own delivery paths rather than to the operator's service.

A preset exists for exactly the ranges an operator cannot reasonably be expected to know: that k3s allocates NodePorts from 30000-32767, and that `vm-compose` derives a stack's host port by hashing its name into HostPortRangeStart..End. The roadmap item this closes (sc-cloudru-vm-no-ingress-ports) was filed because a smoke needed both of those ranges opened by hand to be reachable at all.

View Source
const (
	LogMaxSize = "50m"
	LogMaxFile = "3"
)

LogMaxSize / LogMaxFile bound the json-file log driver. Unbounded container logs filling the disk is the single most common way a long-lived VM dies, and it presents as the application failing rather than as a full disk.

View Source
const (
	// DriverByo takes machines the operator created by hand (or by any means SC
	// knows nothing about) and only connects to them. It is the one driver that
	// works in every cloud on earth, and the one P5 and K.0 are proven on first.
	DriverByo = "byo"

	DriverYandex    = "yc-vm"
	DriverOpenstack = "openstack-vm"
	DriverVkcs      = "vkcs-vm"
	DriverMws       = "mws-vm"
	DriverCloudru   = "cloudru-vm"
	DriverTimeweb   = "timeweb-vm"

	// DriverCloudruEvolution creates machines in Cloud.ru **Evolution**, which is a
	// different cloud from DriverCloudru's Cloud.ru **Advanced** (ex-SberCloud)
	// despite the shared brand and console: different API, different credentials
	// (a service-account key pair, not AK/SK), different regions, and no Terraform
	// provider with open sources. Two drivers rather than one `cloudru` with a mode
	// flag, because an account generally has one estate and not the other — the
	// operator's own project has only Evolution, which is why this driver exists.
	DriverCloudruEvolution = "cloudru-evolution-vm"
)

The drivers named by a vm resource's `provider:` field. The string is the public contract of a parent stack — renaming one turns an existing stack into "unknown vm provider", so treat these as frozen.

View Source
const (
	// DefaultSshUser is deliberately not root and not the image's stock account
	// (`ubuntu`/`debian`/`centos`): root login is closed on part of the images and
	// an image-dependent user name means an `if` by image in the deploy path.
	// vm-matrix.md §3.2.
	DefaultSshUser = "sc"
	DefaultSshPort = 22
	// DefaultImage is an SC-level alias; each driver maps it to its own image id.
	DefaultImage = "ubuntu-2404-lts"

	// DefaultCores and DefaultMemory size the machine when `size` is absent or
	// half-filled.
	//
	// There has to be a default, and it has to live here rather than per driver: a
	// cloud driver picks a flavour by FILTERING the cloud's flavour list on cores and
	// memory, so "no size given" is not "the cloud's default machine" — it is a filter
	// that matches hundreds of flavours, and the one that gets used is whichever the
	// API happened to list first. Deploying a different machine shape on the next
	// `sc deploy` is not a defensible default.
	//
	// 2 cores / 4Gi is the smallest shape that runs a compose stack plus the Caddy
	// ingress without the docker build cache pushing it into swap.
	DefaultCores  = 2
	DefaultMemory = "4Gi"

	// ConfigDir holds rendered configuration (compose files, env files, Caddy).
	ConfigDir = "/etc/sc"
	// StateDir holds state SC manages on the machine (shipped images, markers).
	StateDir = "/var/lib/sc"
	// CloudInitDoneMarker is the ONLY valid "this machine is ready" signal.
	//
	// SSH answers well before cloud-init has finished installing docker, so a
	// deploy that waits for SSH alone fails intermittently on
	// `docker: command not found`. Same class of mistake as a green YC deploy with
	// zero revisions: success reported before readiness. vm-matrix.md §3.1.
	CloudInitDoneMarker = StateDir + "/cloud-init.done"
)
View Source
const DefaultDockerInstallScript = "curl -fsSL " + DockerInstallURL + " | sh"

DefaultDockerInstallScript is the fallback way to get docker onto a fresh machine SC created. It runs from cloud-init, which is already root — see ByoDockerInstallScript for the same install over SSH as an unprivileged user.

View Source
const DefaultKeepImages = 3

DefaultKeepImages is how many previous versions stay on the machine for rollback. Rollback on a VM is faster than in Kubernetes precisely because the image is already there (compose-on-vm.md §9.3).

View Source
const DefaultSingleImagePort = 8080

DefaultSingleImagePort is the port a `type: single-image` stack is told to listen on.

StackConfigSingleImage has no ports field at all — on Lambda and YC Serverless Container the runtime decides. On a VM somebody has to pick one, so SC picks it and passes it in `PORT`, which is the variable both of those runtimes already use.

View Source
const DockerInstallURL = "https://get.docker.com"

DockerInstallURL is Docker's own convenience installer.

It is one of the four egress paths whose reachability from inside Russia is being measured before anything is promised about it (roadmap item sc-ru-market-readiness, B0).

PackageMirror does NOT cover this: it rewrites apt's sources, and this is a curl to a host of Docker's own. The script then adds Docker's apt repository and installs from THERE, not from the distribution — so a machine that cannot reach download.docker.com cannot be fixed by an apt mirror either. The two answers for such a machine are an image that already ships docker (the install is skipped — see InstallDocker below, and ByoDockerInstallScript) or a private mirror of Docker's repository; neither is expressible as a one-line field, which is why there is no flag pretending to be one.

View Source
const EnvFileMode = "0600"

EnvFileMode is the mode of the rendered env file on the machine. It holds every secret of the stack, so it is readable by its owner only (compose-on-vm.md §7.1).

View Source
const GeneratedHeader = `` /* 209-byte string literal not displayed */

GeneratedHeader goes on top of every file SC writes onto the machine.

The file WILL be read, and probably edited, by a human during an incident — so it has to say immediately that edits do not survive and where the source is (compose-on-vm.md §6 point 6). The doc writes this header in Russian; it is English here because `api` is a public repository whose artifacts are English throughout.

View Source
const IngressNetwork = "sc-ingress"

IngressNetwork is the one docker network shared by every stack on the machine. Only ingress containers join it, so that Caddy can reach them by name without two stacks seeing each other's `mongo` (compose-on-vm.md §6 rule 1, §11 rule 2).

It is created out of band (`docker network create sc-ingress || true` on every deploy) and referenced as `external: true`, because it outlives any one compose project and must survive a reboot and a `docker compose down` of either slot.

View Source
const ProviderType = "vm"

ProviderType is the discriminator VmConfig reports from ProviderType(), the key pkg/clouds/pulumi/vm registers its Provider under, and the directory generated schemas land in (docs/schemas/vm).

It is "vm" rather than a cloud name on purpose: which cloud creates the machine is the resource's `provider:` field, and dispatching on it is the driver tier's job (pkg/clouds/pulumi/vm/driver.go). Everything above the driver — cloud-init, readiness, the SSH connection, compose, k3s — is written once.

View Source
const ResourceTypeVm = "vm"

ResourceTypeVm is the `type:` a parent stack's resource declares.

View Source
const SingleImageService = "app"

SingleImageService is the compose service name a `type: single-image` stack is projected onto. The client config names no service — it has one image — and the generated compose file needs a name for it; "app" is what the operator will see in `docker ps` and in the Caddy upstream.

View Source
const TemplateTypeVmCompose = "vm-compose"

TemplateTypeVmCompose is the `type:` of the template that delivers a client stack to a `vm` resource as a generated docker compose project.

Variables

AllHostRoles is every spelling `hosts[].role` accepts, in the order the validation error lists them. Kept next to the constants so adding a role is one edit rather than two places that drift.

View Source
var Drivers = map[string]DriverInfo{
	DriverByo: {
		Implemented: true,
		RoadmapItem: "sc-vm-compose-single-vm",
		Capabilities: Capabilities{

			CloudInit:       false,
			MultiAZInRegion: 1,
		},
	},
	DriverYandex:    {RoadmapItem: "sc-ru-clouds-beyond-yandex"},
	DriverOpenstack: {RoadmapItem: "sc-ru-clouds-beyond-yandex"},
	DriverVkcs:      {RoadmapItem: "sc-ru-clouds-beyond-yandex"},
	DriverMws:       {RoadmapItem: "sc-ru-clouds-beyond-yandex"},
	DriverCloudru: {
		Implemented:      true,
		MigratedToPlugin: true,

		Unverified: "it addresses Cloud.ru **Advanced** (ex-SberCloud), and the only Cloud.ru estate SC has " +
			"ever provisioned is **Evolution** — if your project is Evolution (which new accounts get by " +
			"default), use `provider: cloudru-evolution-vm`, which is live-verified end to end",
		RoadmapItem: "sc-ru-clouds-beyond-yandex",
		Capabilities: Capabilities{
			CloudInit: true,

			CloudInitNeedsEgress: true,
			PrivateNetwork:       true,
			FloatingIP:           true,
			SecurityGroups:       true,

			ContainerRegistry: true,

			DNSInIaC: true,
		},
	},
	DriverCloudruEvolution: {
		Implemented:      true,
		MigratedToPlugin: true,
		RoadmapItem:      "sc-cloudru-evolution-vm-driver",
		Capabilities: Capabilities{

			Regionless: true,

			CloudInit: false,

			CloudInitNeedsEgress: false,

			PrivateNetwork: true,
			FloatingIP:     true,
			SecurityGroups: true,

			ContainerRegistry: true,

			DNSInIaC: true,
		},
	},
	DriverTimeweb: {RoadmapItem: "sc-ru-clouds-beyond-yandex"},
}

Drivers is the whole driver table.

Only `byo` carries real capability values. The cloud rows are intentionally left zeroed: vm-matrix.md §2 verified a great deal about each cloud's *resources*, but several of these fields (MultiAZInRegion above all) are marked "не проверено" there, and a table of half-guesses that shared code branches on is worse than an empty one. Each driver fills its own row when it lands, from the cloud's API.

View Source
var Slots = []string{SlotA, SlotB}

Slots is every slot a stack-env can occupy, in flip order.

Functions

func AcmeStoreComposePath

func AcmeStoreComposePath() string

AcmeStoreComposePath is the store's compose file on host 0.

func AcmeStoreDir

func AcmeStoreDir() string

AcmeStoreDir is the store's configuration directory on host 0.

func AcmeStoreS3ConfigPath

func AcmeStoreS3ConfigPath() string

AcmeStoreS3ConfigPath is SeaweedFS's S3 identity file on host 0: mode 0600, written over stdin, holding the credential every node of the fleet authenticates with.

func ByoDockerInstallScript

func ByoDockerInstallScript(user string) string

ByoDockerInstallScript gets docker + the compose v2 plugin onto a machine SC did NOT create, over SSH, as `user`.

Why this exists at all, given that the byo readiness gate deliberately installs nothing (`ensureReady`): the vm resource's Caddy ingress is a docker container, and it is brought up during `sc provision`, inside the same per-host loop. So an ingressed byo host needs docker strictly EARLIER than the compose path's preflight can ask for it, and the operator who has not installed it by hand gets `failed to create docker network sc-ingress` — a message that names neither docker nor what to do. Live-caught on all three hosts of the first 3-VPS fleet provision, 2026-11-08; the operator's answer was "ideally Docker & Compose must be installed on the VPSs on provision".

The cloud drivers have always done exactly this from cloud-init (DefaultDockerInstallScript, guarded by `command -v docker`). Running the same guarded install over SSH is the same action through a different transport, so what changes here is not the policy but which hosts it reaches.

Four things that are easy to get wrong and are each one failed provision:

  • The install needs root; the ingress commands that follow run as `user`. So the install goes through sudo and the user is added to the docker group — and a group added here does NOT apply to the session that added it. The next command SC runs is a fresh SSH login and picks it up, so the unprivileged check is performed only when the user was ALREADY in the group; otherwise this script would fail on the machine it just fixed.
  • `curl` can be absent on a minimal image, and the failure of a piped curl is swallowed by the pipe. Checked up front by name.
  • compose v2 is a plugin, not a binary: `docker-compose` v1 can be present while `docker compose` is not. The installer ships the plugin, so a miss here means docker came from somewhere else, and the message has to say which half is missing.
  • the daemon can be installed and not running (a stopped unit on a rebooted box, an image that ships docker masked). `systemctl enable --now` is attempted and its failure is NOT fatal — a container-ish or non-systemd host can still have a working daemon — but an unreachable daemon afterwards is.

func CaddyComposePath

func CaddyComposePath() string

CaddyComposePath is the ingress's own compose file.

func CaddyConfDir

func CaddyConfDir() string

CaddyConfDir holds one file per stack-env. A deploy writes its own file and reloads; it never edits a file another stack owns, which is what lets two stacks deploy concurrently without a lock (compose-on-vm.md §8.2).

func CaddyDefaultSitePath

func CaddyDefaultSitePath() string

CaddyDefaultSitePath is the catch-all, written once when the ingress is created.

It answers an unknown Host with a 503 — the same decision, and for the same reason, as the Kubernetes edge's default entry (kubernetes/caddy.go): without it `import conf.d/*.caddy` on a machine with no stacks yet matches nothing, and Caddy refuses a config with no site at all. The `00-` prefix only keeps it first in the glob for a human reading the directory; Caddy does not care about order here.

func CaddyDir

func CaddyDir() string

CaddyDir is the ingress configuration tree on the machine, mounted read-only at CaddyContainerConfigDir.

func CaddyEnvPath

func CaddyEnvPath() string

CaddyEnvPath is the ingress env file (0600): the ACME External Account Binding credential, when there is one. It exists even when empty, because compose fails a project whose `env_file` is missing.

func CaddyPagesDir

func CaddyPagesDir() string

CaddyPagesDir holds the error pages the `handle_server_error` snippet serves. Same files as the Kubernetes edge — they come from the same embedded asset tree.

func CaddySitePath

func CaddySitePath(stack, env string) string

CaddySitePath is one stack-env's file in conf.d.

func CaddyfilePath

func CaddyfilePath() string

CaddyfilePath is the generated global Caddyfile: the ACME configuration, the shared snippet library, and an `import` of everything in conf.d.

func ComposeFilePath

func ComposeFilePath(stack, env, slot string) string

ComposeFilePath is the generated compose file of one slot.

One file per slot, not the single `docker-compose.yaml` of compose-on-vm.md §3.1: a blue-green deploy has both slots up at once (§9.1 steps 1–2), and a single path means rendering the new slot overwrites the description of the slot still serving traffic — which is exactly the file an operator reaches for when the new slot fails its health gate.

func DataComposeFilePath

func DataComposeFilePath(stack, env string) string

DataComposeFilePath is the generated compose file of the stateful project.

func DataProjectName

func DataProjectName(stack, env string) string

DataProjectName is the compose project holding the services that must NOT be duplicated by blue-green: anything with a writable named volume. Two Mongos on one volume corrupt it, so a stateful service lives outside the slots and the flip never touches it (compose-on-vm.md §9.1).

func DockerDaemonJSON

func DockerDaemonJSON(registryMirrors []string) (string, error)

DockerDaemonJSON renders /etc/docker/daemon.json: the mandatory log caps plus any registry mirrors. Built through encoding/json rather than string concatenation so a mirror URL cannot produce a file the daemon refuses to parse — which it answers by not starting at all.

func EnvFilePath

func EnvFilePath(stack, env string) string

EnvFilePath is the `env_file` every service of the stack-env reads. Mode 0600, owned by the ssh user; values never appear in the generated compose file (compose-on-vm.md §7.1).

func ExternalVolumeName

func ExternalVolumeName(stack, env, volume string) string

ExternalVolumeName is the real docker volume behind a named volume written in the customer's compose file. It is created out of band and declared `external: true`, so that cleaning up the previous slot (`docker compose -p <prefix>-a down -v`) cannot delete the data (compose-on-vm.md §6 rule 4).

func FormatPortSpec

func FormatPortSpec(ports []PortRange) string

FormatPortSpec renders a port list for a stack output, as `http=tcp/80,ssh=tcp/22,vm-compose-host-ports=tcp/20000-30000`.

It crosses the stack boundary because the template that publishes a host port runs in the CHILD stack and the firewall is described in the parent — so the only way for a deploy to say "the port you are publishing is not open" is for the parent to export what it opened. A string rather than a structured output because a Pulumi stack output of a struct slice round-trips as `[]any` of `map[string]any` and every reader would re-parse it anyway.

func ImagesDir

func ImagesDir(stack, env string) string

ImagesDir holds the shipped image archives of one stack-env, kept for rollback (`keepImages`, compose-on-vm.md §9.3).

func IngressHostPort

func IngressHostPort(stack, env string) int

IngressHostPort derives a stable host port for a stack-env.

Stable matters more than pretty: the port goes into a firewall rule, a bookmark and somebody's smoke script, so it must not move when an unrelated stack is added to the machine. Hashing the name gives that without SC having to keep a port registry; the cost is that two stack-envs on one machine can collide, which the deploy detects when docker refuses to bind and reports with both names.

func InternalNetworkName

func InternalNetworkName(stack, env string) string

InternalNetworkName is the private network of one stack-env — shared by both slots AND by the data project, which is why it is external rather than a compose `default`.

Deviation from compose-on-vm.md §6, worth stating: the example renders a per-slot `default` network named `<stack>-<env>-<slot>-internal`. That cannot work together with §9.1's rule that stateful services live in their own project — a compose default network is scoped to its project, so the backend in slot B would not resolve `mongo` in the data project. One external network per stack-env satisfies both rules; the isolation that matters (§6 rule 1, §11 rule 1) is between stack-envs, and that is preserved.

func KnownDrivers

func KnownDrivers() []string

KnownDrivers lists every `provider:` value a vm resource accepts, implemented or not, so an error message can name them all.

The union of the built-in table and the drivers the loaded plugins advertised. A plugin driver that is installed but whose name the operator mistyped has to appear here, or the message tells them to use a list that does not contain the driver they just installed.

func KnownIngressPresets

func KnownIngressPresets() []string

KnownIngressPresets names every accepted preset, so a refusal can list them.

func MeshAddressIn

func MeshAddressIn(cidr string, i int) (string, error)

MeshAddressIn is MeshAddress with the range passed explicitly, for callers that have the CIDR but not the whole config.

func MeshKeygenScript

func MeshKeygenScript() string

MeshKeygenScript is pass 1 of standing the overlay up on one machine: get `wireguard-tools`, prove the kernel can carry a WireGuard link, and generate the machine's keypair if it does not already have one.

STDOUT IS THE PUBLIC KEY AND NOTHING ELSE. Every other word this script says goes to stderr, because the caller reads stdout as a key and pastes it into every sibling's config — a progress line on the wrong stream becomes a `PublicKey =` value. The caller checks the shape too (ValidMeshPublicKey), so a mistake here fails the provision rather than producing a mesh that cannot handshake.

The private key never leaves the machine. It is generated here, into a 0600 file owned by root, and persistence is that file being present rather than SC having stored the value — so no private key enters the Pulumi checkpoint, a command's input set, a preview diff or a CI log. A re-imaged machine generates a new one and its peers learn the new public key in the same provision, with nothing to push back at it.

No `Delete` belongs on the command that runs this (see MeshTeardownScript for what the teardown does remove): this installs a package on a machine SC does not own, and the precedent is ByoDockerInstallScript's — uninstalling an operator's packages because a stack was destroyed is not SC's business.

func MeshTeardownScript

func MeshTeardownScript() string

MeshTeardownScript removes SC's interface, its config and its key when the vm resource is destroyed.

What it does NOT remove is the `wireguard-tools` package, for the reason ByoDockerInstallScript's missing Delete gives: SC installed it on a machine it does not own, and the operator may be using it. Everything removed here is namespaced to `sc-mesh` (see MeshInterface) — a hand-made `wg0` on the same host is untouched.

func MeshUpScript

func MeshUpScript(conf string) string

MeshUpScript is pass 2: write this machine's peer list and apply it.

`conf` is the output of RenderMeshConfig and is NOT a secret — the private key is referenced by path, never inlined — so it travels in the command string like the Caddyfile rather than over stdin.

The applying half is the part with a decision in it. A running interface is updated with `wg syncconf`, which replaces the peer set in place and does not touch established sessions; `wg-quick down && up` is used only when the interface's own ADDRESS changed, because that is the one thing syncconf cannot apply. The reason is not speed: the mesh carries the fleet's certificate store, so a down/up on every provision is a real interruption of it, on a provision that may have changed nothing and that reports success either way. A flap that brief would be invisible in every log SC writes and visible only as an occasional failed renewal weeks later.

func NamePrefix

func NamePrefix(stack, env string) string

NamePrefix is the `<stack>-<env>-` prefix that goes on EVERY name SC puts on the machine: compose project, external volume, ingress alias, the file in Caddy's conf.d, the image directory. compose-on-vm.md §11 rule 3 — one exception breaks a neighbouring stack, and it diagnoses as mysticism rather than as a name clash.

func OtherSlot

func OtherSlot(active string) string

OtherSlot returns the slot a deploy should bring up given the active one. An unknown or empty active slot yields SlotA, so a machine with no recorded state deploys into A.

func PluginForDriver

func PluginForDriver(driver string) string

PluginForDriver names the plugin that provides a driver, or "" for a built-in. This is what routes a vm resource to the VmHosts RPC instead of an in-tree driver (pkg/clouds/pulumi/vm's driverFor). A row that is metadata and not an implementation (coreOwned above) is NOT a true built-in — defer to the plugin table so dispatch routes to the registered plugin's RPC.

func PortsReachable

func PortsReachable(ports []PortRange, port int, protocol string) bool

PortsReachable reports whether any range makes a port reachable FROM THE INTERNET. Node-to-node ranges do not count: the question every caller asks is whether a client outside the cloud can connect, and answering "yes, from the other nodes" would silence exactly the warning this is called to produce.

func ProjectName

func ProjectName(stack, env, slot string) string

ProjectName is the compose project of one slot. Compose isolates by project name, so two slots are two projects, two sets of containers — and one shared internal network and one shared set of data volumes.

func ReadComposeTemplateConfig

func ReadComposeTemplateConfig(config *api.Config) (api.Config, error)

func ReadVmConfig

func ReadVmConfig(config *api.Config) (api.Config, error)

func RegisterPluginDriver

func RegisterPluginDriver(pluginName, driver string, info DriverInfo) error

RegisterPluginDriver adds a plugin-advertised driver to the table.

Refuses to shadow a true built-in and refuses a second registration of the same name, in both cases naming the plugins involved. Both are configuration errors an operator can fix (uninstall one of the plugins), and neither may resolve silently: which plugin won would decide which cloud a machine is created in.

"True built-in" is coreOwned above: a row flagged `MigratedToPlugin: true` and a row that was never implemented are both metadata, and a plugin may claim either.

func RenderAcmeStoreCompose

func RenderAcmeStoreCompose(cfg *VmConfig) (string, error)

RenderAcmeStoreCompose is the store's own compose project, on host 0.

func RenderAcmeStoreS3Config

func RenderAcmeStoreS3Config(accessKey, secretKey string) (string, error)

RenderAcmeStoreS3Config is SeaweedFS's `-s3.config` file: one identity, the credential SC generated, and the five actions a certmagic store needs.

Takes the credential as arguments rather than reading it off the config, because it does not exist in the config — it is generated at provision time and this file is rendered inside the apply that resolves it.

`Admin` is in the action list and the others would not be enough on their own: SeaweedFS gates bucket creation on it, and SC creates the bucket with this same identity rather than inventing a second one. The actions are unscoped (no `:<bucket>` suffix), which is the whole store — correct, because this store has one bucket and one user by construction.

func RenderCaddyCompose

func RenderCaddyCompose(cfg *VmConfig) (string, error)

RenderCaddyCompose is the ingress's own compose project.

func RenderCaddyDefaultSite

func RenderCaddyDefaultSite() string

RenderCaddyDefaultSite is the catch-all site, written once with the ingress.

Same answer as the Kubernetes edge's default entry and copied from it deliberately (kubernetes/caddy.go, `defaultCaddyFileEntry`): a 503 with Retry-After, served from the same 503.html. A 404 or an empty 200 for an unknown Host is invisible to monitoring — which is the failure this shape exists to avoid — and `import conf.d/*.caddy` matching nothing on a machine with no stacks yet would leave Caddy with a config containing no site at all, which it refuses to load.

`http://` only, and no `import hsts`: this block answers any Host, and Caddy has no certificate for a name it was never told about, so an HTTPS catch-all would fail the TLS handshake instead of answering — and an HSTS header from a catch-all is meaningless.

func RenderCaddyEnvFile

func RenderCaddyEnvFile(cfg *VmConfig, managed map[string]string) (string, error)

RenderCaddyEnvFile is the ingress env file. Mode EnvFileMode, content delivered over stdin — EnvAcmeEabMacKey is a credential.

Written even when there is nothing to put in it, because compose refuses a project whose `env_file` does not exist, and an ingress that silently stops starting after an operator removes `acmeEabKeyId` would be a genuinely hard failure to read.

`managed` carries the credentials of a store SC runs itself (`ingress.acmeStore`), which do not exist in the config — they are generated at provision time, so the provisioning tier resolves them and calls this inside the apply. It is nil for every other resource. A name present in both wins from `managed`: the config's value for a managed store is the AcmeStoreManagedCredential sentinel, and writing a sentinel into the file the fleet authenticates with would be the worst available outcome — a store that exists, a Caddy that starts, and certificates that never issue.

func RenderCaddySite

func RenderCaddySite(in *VmComposeInput, opts RenderOptions) (string, error)

RenderCaddySite produces one stack-env's file in conf.d.

The directive order is the Kubernetes edge's, kept the same on purpose (kubernetes/simple_container.go, `caddyfileEntryTemplate`). It is load-bearing in two places that have both already been bugs: `${imports}` and `siteExtraHelpers` sit at SITE level, below the reverse_proxy block, so that a `rate_limit` or a catch-all `respond` wired through siteExtraHelpers cannot shadow the proxy; and `request_buffers` sits INSIDE the proxy block, where a chunked upload is buffered into a Content-Length the application can read (Django #28668).

The one difference from Kubernetes is the upstream address, and it carries the slot: `http://<stack>-<env>-<service>-<slot>:<port>` instead of a cluster-DNS name. Writing this file with the other slot's alias and reloading IS the blue-green flip.

func RenderCaddyfile

func RenderCaddyfile(cfg *VmConfig) (string, error)

RenderCaddyfile produces the machine's global Caddyfile.

The snippet library is INLINED from the embedded asset tree rather than imported from a second file. Importing would be one line shorter and gives the operator two files to read instead of one; inlining also sidesteps the question of whether a snippet defined in an imported file is registered at the top level, which is a detail of Caddy's parser that this code has no business depending on.

There is deliberately no `admin off`, which compose-on-vm.md §8.1 asks for. It cannot coexist with §8.2's `docker exec sc-caddy caddy reload`: reload is a client that talks to the admin API, so turning the API off turns every subsequent deploy into a full container restart — which drops in-flight connections and, worse, makes a config error visible only after the old config is already gone. Caddy's default admin endpoint is localhost:2019 INSIDE the container and the compose project publishes no port for it, so it is reachable exactly through `docker exec` and from nowhere else. Amendment dated 2026-10-17 in the design doc.

A machine with a shared certificate store does get `persist_config off` — which is a different directive with a different reason (keeping the store's credentials out of the config autosave) and leaves the API, and therefore reload, working. See writeAdminConfigPersistOff.

func RenderCloudInit

func RenderCloudInit(cfg *VmConfig, role HostRole, keys HostKeys) (string, error)

RenderCloudInit builds the user-data for one machine.

func RenderEnvFile

func RenderEnvFile(input *VmComposeInput, extra map[string]string) (string, error)

RenderEnvFile renders the `env_file` every service of the stack-env reads.

It is `env_file` and not compose `environment:` deliberately: values must not land in the generated YAML, which is read by eye during an incident and may end up pasted into a ticket (§7.1). The file is written through the command's Stdin, never through an argument or an environment variable — see compose_stack.go for why.

`extra` carries the variables the compute context contributes at provisioning time (`${resource:…}` expansions from parent resources). It wins over `env` and loses to `secrets`, matching the precedence of every other target.

func RenderMeshConfig

func RenderMeshConfig(spec MeshSpec) (string, error)

RenderMeshConfig renders a wg-quick config for one machine.

Pure, and that is why it is here rather than in the provisioning tier: the file's content is the fleet's public facts and nothing else, so it can be tested without a Pulumi context and diffed in review.

The private key is NOT in it. `PostUp` loads it from MeshPrivateKeyPath, which keeps a secret out of a rendered file and lets the machine own the only copy. Note that `wg-quick strip` — what `wg syncconf` is fed on a re-provision — drops PostUp lines, which is correct here: a running interface already holds its key.

func ResetPluginDrivers

func ResetPluginDrivers()

ResetPluginDrivers drops every registered plugin driver. For tests, and for a second `sc` operation in the same process after the plugins were torn down.

func ServesDomain

func ServesDomain(in *VmComposeInput, ingressEnabled bool) bool

ServesDomain reports whether this stack-env gets a site file in conf.d, and is the one predicate the deploy branches on: a stack that serves a domain through Caddy publishes NO host port, which is what lets both slots run at once.

`prefix` without `domain` is not servable here. On the Kubernetes edge a prefix-only stack is grafted into an aggregator site that owns the machine's domain; on a VM there is no such site and nothing to graft onto, so SC publishes the host port and says so rather than inventing a hostname.

func SlotAlias

func SlotAlias(stack, env, service, slot string) string

SlotAlias is the network alias of one service in one slot. Caddy proxies to it on the ingress network, and it is also added on the internal network so that a sidecar can address one specific slot.

It carries the slot, which is what makes the flip a one-line change in Caddy's config, and the stack-env prefix, without which two stacks that both call their service `backend` would collide on the shared ingress network.

Services keep their bare compose name as well (compose adds it as an alias on every network), which is what lets `MONGO_URI=mongodb://mongo:27017` keep working unchanged. During the overlap window of a blue-green deploy the bare name resolves to either slot's container; that ambiguity is inherent to running two slots at once.

func StackDir

func StackDir(stack, env string) string

StackDir is where rendered configuration for one stack-env lives.

func StatePath

func StatePath(stack, env string) string

StatePath records which slot is active and which version it runs.

func TextVolumeDir

func TextVolumeDir(stack, env string) string

TextVolumeDir holds the files rendered from `textVolumes`.

func TextVolumePath

func TextVolumePath(stack, env, name string) string

TextVolumePath is one rendered `textVolumes` entry on the machine.

func ToVmComposeConfig

func ToVmComposeConfig(tpl any, composeCfg compose.Config, stackCfg *api.StackConfigCompose) (any, error)

ToVmComposeConfig converts a `vm-compose` template plus a `cloud-compose` client stack into the provisioning input.

The container set comes from the SAME k8s.ConvertComposeToContainers the Kubernetes path uses, deliberately: `runs`, `env`, `size`, probes and image-build inputs then behave identically here and on GKE. What this function adds on top is the three things compose expresses and a Kubernetes Deployment does not (mounts by type, depends_on, the verbatim healthcheck) and the §2.2 validation.

func ToVmComposeSingleImageConfig

func ToVmComposeSingleImageConfig(tpl any, stackCfg *api.StackConfigSingleImage) (any, error)

ToVmComposeSingleImageConfig converts a `vm-compose` template plus a `single-image` client stack into the provisioning input.

It exists because the first stack this path has to carry (forge-atrium) is `single-image`, not `cloud-compose`. The projection is deliberate and total: a synthetic StackConfigCompose with one service, so that everything downstream — render, env file, Caddy site, blue-green — has exactly one shape to handle. Fields that have no meaning on a VM are refused or warned about here, never dropped silently.

func ValidMeshPublicKey

func ValidMeshPublicKey(s string) bool

ValidMeshPublicKey reports whether s is shaped like a WireGuard key: 32 raw bytes in standard base64, which is always 44 characters ending in `=`.

Checked rather than trusted because the value arrives as a remote command's stdout. Length alone is not enough — a 44-character log line would pass — so the decode is done too.

func ValidateNames

func ValidateNames(stack, env string) error

ValidateNames refuses a stack or environment name that cannot be part of a docker compose project name. It fails at render time, with the offending name, rather than as a confusing collision between two stacks on the machine.

Types

type CaddyAsset

type CaddyAsset struct {
	Path    string `json:"path" yaml:"path"`
	Content string `json:"content" yaml:"content"`
}

CaddyAsset is one static file the ingress needs on disk, with the absolute path it takes on the machine.

func CaddyAssets

func CaddyAssets() ([]CaddyAsset, error)

CaddyAssets returns every embedded asset except the snippet library, which RenderCaddyfile inlines instead.

Today that is the four error pages. It walks the tree rather than naming them, because the consumer that must not drift is the `handle_server_error` snippet — it serves `/etc/caddy/pages/{rp.status_code}.html`, so a page added to the shared asset tree for the Kubernetes edge has to appear here too, and a list of filenames in this file is a list somebody will forget.

type Capabilities

type Capabilities struct {
	// CloudInit — user-data is executed by cloud-init on first boot.
	CloudInit bool
	// CloudInitNeedsEgress — cloud-init needs a public address AT CREATION TIME,
	// which forces the floating IP to be created before the machine (Timeweb).
	CloudInitNeedsEgress bool
	// Regionless — the cloud's API has NO region dimension: one global endpoint,
	// and placement is by availability zone alone.
	//
	// The zero value is the common case (a region is required), so only a cloud
	// that genuinely has none sets this. Cloud.ru Evolution is the first: its
	// compute API is `compute.api.cloud.ru` with no region in the host, the path or
	// any request, and placement is the `ru.AZ-*` availability zone. Requiring
	// `region:` there would be a mandatory field with nowhere to go — exactly the
	// dead config this package refuses elsewhere.
	Regionless bool
	// MultiAZInRegion is how many availability zones are usable in one region.
	// Zero means "not measured yet" — do not validate against it until a driver
	// fills it in from the cloud's own API.
	MultiAZInRegion int
	// PrivateNetwork — instances can talk over a private network.
	PrivateNetwork bool
	// FloatingIP — a public address is a separate resource rather than something
	// the instance hands out.
	FloatingIP bool
	// SecurityGroups — filtering is per-instance rather than one global firewall.
	SecurityGroups bool
	// BlockStorageCSI — there is a CSI driver for Kubernetes volumes.
	BlockStorageCSI bool
	// ContainerRegistry — the cloud offers a private registry manageable from IaC.
	// False forces image delivery over SSH instead of push/pull.
	ContainerRegistry bool
	// DNSInIaC — public DNS zones are managed by the same provider, so SC can be
	// its own registrar instead of depending on Cloudflare.
	DNSInIaC bool
}

Capabilities describes what a cloud physically does, so that the differences between clouds live in exactly one table instead of becoming `if provider == …` branches scattered through shared code.

It is also what turns "you asked for three zones, this cloud has one in that region" into a validation error instead of a failure twenty minutes into a deploy (vm-matrix.md §1.1, D4).

type ComposeTemplateConfig

type ComposeTemplateConfig struct {
	api.Credentials            `json:",inline" yaml:",inline"`
	docker.RegistryCredentials `json:",inline" yaml:",inline"`

	// VmResource is the NAME of a `type: vm` resource in the same parent stack.
	VmResource string `json:"vmResource" yaml:"vmResource"`
	// ImageDelivery is ImageDeliverySshTar (default) or ImageDeliveryRegistry.
	ImageDelivery string `json:"imageDelivery,omitempty" yaml:"imageDelivery,omitempty"`
	// ExternalImages is ExternalImagesShip or ExternalImagesPull. It defaults to
	// `ship` under `ssh-tar` and to `pull` under `registry`, where the machine is
	// already talking to a registry and shipping would be strictly more work.
	ExternalImages string `json:"externalImages,omitempty" yaml:"externalImages,omitempty"`
	// Strategy is StrategyBlueGreen (default) or StrategyRecreate.
	Strategy string `json:"strategy,omitempty" yaml:"strategy,omitempty"`
	// KeepImages is how many previous versions to keep for rollback. Defaults to
	// DefaultKeepImages; 0 is a valid explicit choice and means "keep none".
	KeepImages *int `json:"keepImages,omitempty" yaml:"keepImages,omitempty"`
}

ComposeTemplateConfig is the `vm-compose` template config.

It holds delivery behaviour ONLY. Everything about the machine — provider, region, size, image, sshUser, ingress — belongs to the `vm` resource this references by name, exactly as gcp-gke-autopilot references gkeClusterResource. That split is what lets several stacks share one machine and lets the delivery strategy change without touching the machine description (compose-on-vm.md §2.1, the operator's 2026-10-14 correction).

func (*ComposeTemplateConfig) CredentialsValue

func (c *ComposeTemplateConfig) CredentialsValue() string

CredentialsValue mirrors VmConfig.CredentialsValue: the resolved `${auth:...}` blob verbatim, "{}" when none was given. Empty is the normal case here — `byo` has no cloud credentials, and the registry ones (when imageDelivery is `registry`) are their own fields, not this.

func (*ComposeTemplateConfig) EffectiveExternalImages

func (c *ComposeTemplateConfig) EffectiveExternalImages() string

EffectiveExternalImages resolves what to do with third-party images.

The default follows the delivery mode rather than being a constant, because the two defaults are each right for their mode and a single one would be wrong for the other: under `registry` the machine is pulling from a registry anyway, so shipping a `mongo:7` through the runner would move bytes for nothing.

func (*ComposeTemplateConfig) EffectiveImageDelivery

func (c *ComposeTemplateConfig) EffectiveImageDelivery() string

func (*ComposeTemplateConfig) EffectiveKeepImages

func (c *ComposeTemplateConfig) EffectiveKeepImages() int

func (*ComposeTemplateConfig) EffectiveStrategy

func (c *ComposeTemplateConfig) EffectiveStrategy() string

func (*ComposeTemplateConfig) ProjectIdValue

func (c *ComposeTemplateConfig) ProjectIdValue() string

ProjectIdValue is "n/a" for the same reason it is on VmConfig — there is no cloud project behind an SSH connection.

func (*ComposeTemplateConfig) ProviderType

func (c *ComposeTemplateConfig) ProviderType() string

func (*ComposeTemplateConfig) ShipsExternalImages

func (c *ComposeTemplateConfig) ShipsExternalImages() bool

ShipsExternalImages reports whether this deploy streams third-party images to the machine itself.

`registry` delivery never does, even when asked: there is no `sc image ship` in that mode at all, and adding one so that a third-party image could arrive by a different route than the stack's own would be two delivery paths in one deploy. Validate says so out loud rather than letting the setting be silently ignored.

func (*ComposeTemplateConfig) Validate

func (c *ComposeTemplateConfig) Validate() error

Validate refuses a template config SC cannot honour. Like VmConfig.Validate it runs in the provisioning tier and never in the config reader, because cmd/schema-gen drives every reader with an empty config and silently drops the ones that error.

type DriverInfo

type DriverInfo struct {
	Implemented bool
	// Unverified, when non-empty, says the driver's code exists and compiles but has
	// never provisioned a machine on the cloud it addresses — and the string says
	// why not. Validate refuses such a driver unless the resource sets
	// `allowUnverifiedProvider: true`, and quotes this reason verbatim.
	//
	// "Implemented" and "known to work" are different claims, and the DSL had no way
	// to tell them apart: `cloudru-vm` shipped as `Implemented: true` next to
	// `cloudru-evolution-vm`, which had been provisioned end to end — so the one
	// thing an operator could not learn from the config reference was which of the
	// two had ever run. Clear this field when a driver is smoked, in the same change
	// that records the smoke.
	Unverified string
	// RoadmapItem is the forge roadmap item that tracks this driver. It is quoted
	// verbatim in the refusal an unimplemented driver returns, so an operator who
	// hits it can find the state of the work rather than guessing.
	RoadmapItem  string
	Capabilities Capabilities
	// Plugin names the SC plugin that advertised this driver, and is empty for a
	// driver SC core ships itself. Set by RegisterPluginDriver — a row in the
	// `Drivers` literal below must never set it.
	//
	// It is what routes the resource: a non-empty Plugin means the machines are
	// created by that plugin's VmHosts RPC rather than by an in-tree driver.
	Plugin string
	// MigratedToPlugin, when true, marks a `Drivers` row that is RETAINED only
	// for its metadata (Capabilities, Unverified, RoadmapItem) because an SC
	// plugin now owns the actual provisioning. The plugin reads this row via
	// `Drivers[name].ToProto(name)` to populate its SchemaResponse.VmDrivers —
	// so removing the entry would silently zero the plugin's advertised
	// capabilities. Instead, we keep the row AND:
	//
	//   - RegisterPluginDriver allows a plugin to register the same driver
	//     name without "cannot replace a built-in" errors (plugin_drivers.go)
	//   - LookupDriver treats this row as absent and falls through to the
	//     plugin table — plugin registration becomes the source of truth
	//   - PluginForDriver returns the registering plugin's name, so dispatch
	//     routes to its VmHosts RPC instead of an in-tree driver (there is no
	//     in-tree driver — the extraction is already done; the row is pure
	//     capability metadata)
	//
	// Live-caught 2026-10-30 on a two-peaks deploy: sc-plugin-cloudru advertises
	// `cloudru-evolution-vm`, api v2026.10.54 refused the registration against
	// the then-collision-strict check, every cloudru deploy went red with
	// "plugin %q advertises vm provider %q, which SC core provides itself".
	// The data was always the plugin's; this flag just stops api claiming it.
	MigratedToPlugin bool
}

DriverInfo is one row of the driver table: whether the driver exists today, where the work to add it is tracked, and what its cloud can do.

func DriverInfoFromProto

func DriverInfoFromProto(spec *scpluginv1.VmDriverSpec) DriverInfo

DriverInfoFromProto converts a plugin's advertised spec into a driver-table row.

Every field is taken verbatim, including `unverified` and `roadmap_item`: those are quoted back to the operator by Validate, and a plugin that ships a driver it has never run against a real project must be able to say so in its own words — the same claim the in-tree `cloudru-vm` row makes.

Plugin is left empty; RegisterPluginDriver fills it from the plugin's own name.

func LookupDriver

func LookupDriver(driver string) (DriverInfo, bool)

LookupDriver resolves a `provider:` value against the built-in table first and the plugin table second. The ordering is the no-shadowing rule above, enforced a second time at read: a built-in always wins — except a row that is metadata rather than an implementation (coreOwned above: migrated, or never implemented). For those we fall through to the plugin table, so a registered plugin driver with the same name wins. If no plugin has registered, the row's metadata (Capabilities, Unverified, RoadmapItem) still answers so Validate's keyed-off-capabilities checks keep working — a `provider: mws-vm` with no plugin installed still reads "not implemented yet, see roadmap item X".

func (DriverInfo) ToProto

func (i DriverInfo) ToProto(driver string) *scpluginv1.VmDriverSpec

ToProto renders the row as the wire spec a plugin returns from Schema().

`driver` is the `provider:` value operators write in client.yaml; it is not part of DriverInfo because in-tree rows are keyed by it in the Drivers map.

Plugin is deliberately NOT carried: it names the plugin that advertised the driver, which only core can know (it is the name from the parent stack's `plugins:` block, not something a plugin gets to claim for itself), and RegisterPluginDriver sets it on the way in.

type HostKeys

type HostKeys struct {
	// DeployPublicKey is the public half of the key pair SC connects with (D10,
	// vm-matrix.md §3.3). Required: a machine with no authorised key is a machine SC
	// cannot deploy to, and discovering that after creation means destroying and
	// recreating it. The PRIVATE half never appears in user-data.
	DeployPublicKey string

	// HostPrivateKey / HostPublicKey pin the machine's own ed25519 host key, in
	// OpenSSH formats (`-----BEGIN OPENSSH PRIVATE KEY-----…` and
	// `ssh-ed25519 AAAA…`). Optional as a pair — omit both and the machine generates
	// its own, which no deploy can then verify.
	//
	// Why SC supplies them rather than reading the machine's key afterwards: no cloud
	// API returns a host key, so the alternatives are to trust the first connection
	// (no protection against anyone who can answer on that address before SC does) or
	// to make the operator paste `ssh-keyscan` output for a machine that does not
	// exist yet. Generating the key first is the only one of the three that verifies
	// anything.
	//
	// The private half does ride in user-data, which anything on the instance can
	// read from the metadata service and any console reader can read from the API.
	// That is accepted: both of those already imply control of the machine. What it
	// protects against is a DIFFERENT machine answering on the address — which is
	// exactly the deploy-time risk, since the deploy carries the deploy key and every
	// `${secret:...}` of every stack.
	HostPrivateKey string
	HostPublicKey  string
}

HostKeys is the key material a machine SC creates is born with. Both halves of both pairs are generated inside the parent stack and persisted in its checkpoint, so they are stable across deploys — which matters because user-data is replace-on-change on every cloud: a key that moved would rebuild the machine.

type HostRole

type HostRole string

HostRole is what the machine is being prepared for. The cloud-init body is the same for both — the difference is what gets installed on top afterwards — but the role is carried explicitly so a future k3s-specific tweak has a place to go that is not a flag on VmConfig.

const (
	// RoleCompose is a machine that runs stacks under `docker compose`.
	RoleCompose HostRole = "compose"
	// RoleK3sServer is a k3s control-plane node.
	RoleK3sServer HostRole = "k3s-server"
	// RoleK3sAgent is a k3s worker node.
	RoleK3sAgent HostRole = "k3s-agent"
)

func (HostRole) IsK3s

func (r HostRole) IsK3s() bool

IsK3s reports whether the role makes the machine a node of a k3s cluster, as opposed to a host running stacks under `docker compose`.

type MeshPeer

type MeshPeer struct {
	// Name is the host's SC name, written into the config as a comment so that
	// `wg show` output and the file can be read side by side.
	Name string
	// PublicKey is the peer's WireGuard public key, as the peer's own `wg genkey |
	// wg pubkey` printed it.
	PublicKey string
	// MeshAddress is the peer's overlay address — its `AllowedIPs`, as a /32. A /32
	// and not the whole range: every peer owns exactly one address, and a wider
	// AllowedIPs would make one peer a catch-all route for addresses it does not own.
	MeshAddress string
	// Endpoint is the peer's PUBLIC address, where its UDP port is reached. There is
	// no inner network to use here — building one is what this whole mesh is for.
	Endpoint string
}

MeshPeer is one other machine of the fleet, as the local machine's config needs to name it.

type MeshSpec

type MeshSpec struct {
	Name        string
	MeshAddress string
	PrefixLen   int
	ListenPort  int
	Peers       []MeshPeer
}

MeshSpec is the whole input of RenderMeshConfig: the local machine's own facts plus its peers.

type PortRange

type PortRange struct {
	Label    string
	Protocol string
	From     int
	To       int
	// Internal restricts the hole to the other machines of this vm resource rather
	// than opening it to the internet.
	//
	// It exists because a multi-node k3s cluster needs ports that must NOT be
	// public: the kubelet (10250) serves `exec` into any pod on the node, and
	// embedded etcd (2379-2380) is the cluster's entire state. Opening those to
	// 0.0.0.0/0 is a cluster anyone can take over, so the choice is per-range and
	// not per-resource.
	//
	// How it is enforced is the driver's business, because the clouds differ: on
	// Cloud.ru Advanced the rule's source is the machine's own security group, and
	// on Evolution — where SC does not get to choose the group and every VM of the
	// project joins the default one — it is the private subnet's CIDR.
	Internal bool
}

PortRange is one hole in a machine's firewall: a closed port range on one protocol, carrying the label SC names the rule after.

The label is part of the contract, not decoration: on Cloud.ru Advanced it becomes the Pulumi resource name of the rule (`<vm>-secgroup-<label>`, so renaming one replaces a rule), and on Cloud.ru Evolution it becomes the rule's description, which is the ONLY thing a destroy can use to tell SC's rules apart from the ones the project's shared default group came with.

func ParsePortSpec

func ParsePortSpec(spec string) []PortRange

ParsePortSpec reads back what FormatPortSpec wrote. An entry it cannot parse is skipped rather than refused: this is read on the deploy path to produce a warning, and a parse error must not be the thing that fails a deploy.

func (PortRange) Covers

func (p PortRange) Covers(port int, protocol string) bool

Covers reports whether this range permits a port on a protocol. Used to tell an operator that the host port their stack is about to publish is not open, rather than letting them discover it as a timeout against a green deploy.

func (PortRange) Spec

func (p PortRange) Spec() string

Spec renders the range as `proto/from` or `proto/from-to`.

func (PortRange) String

func (p PortRange) String() string

type RenderOptions

type RenderOptions struct {
	Stack string
	Env   string
	Slot  string
	// Version is the deploy version (CalVer `YYYY.MM.DD-<sha>` in CI). It is passed to
	// every container so that a running container can report what it is.
	Version string
	// Images maps a service name to the image reference to run. A service missing from
	// the map keeps whatever `image:` the conversion produced; a service with neither
	// is an error, because compose would try to build it on the machine.
	Images map[string]string
	// IngressHostPort publishes the ingress service's port on the host. Set before
	// Caddy exists (P5.2) and for `ingress.enable: false` (§8.4); 0 publishes nothing
	// and leaves the service reachable only over the docker network.
	IngressHostPort int
	// NoOriginTls renders the site on `http://` instead of on the bare domain,
	// because `ingress.originTls: false` is set on the vm resource this stack deploys
	// onto and the machine terminates no TLS.
	//
	// It arrives here as a field rather than being read off the vm config because
	// RenderCaddySite is given the STACK's input and the flag belongs to the parent's
	// resource; the deploy reads it out of the parent's exports and passes it down.
	// Negative-named to match that export, where the zero value has to mean the
	// behaviour every resource had before the field existed.
	NoOriginTls bool
}

RenderOptions are the deploy-time facts the render needs and the conversion cannot know: which slot is being brought up, which image each service runs, and whether the ingress port is published on the host.

type RenderedCompose

type RenderedCompose struct {
	// SlotProject / SlotFile is the blue-green slot: everything that can safely run in
	// two copies at once.
	SlotProject string
	SlotFile    string
	// DataProject / DataFile is the stateful project, which the flip never touches.
	// Both are empty when the stack has no stateful service (§9.1).
	DataProject string
	DataFile    string

	SlotServices []string
	DataServices []string
}

RenderedCompose is what the deploy writes to the machine.

func Render

func Render(input *VmComposeInput, opts RenderOptions) (*RenderedCompose, error)

Render produces the compose file(s) for one slot of one stack-env.

It is a pure function on purpose — no Pulumi, no SSH, no clock. The generated file is the thing an operator will stare at when a deploy misbehaves, and being able to produce it in a unit test from a client.yaml is what keeps it reviewable.

type TextVolumeFile

type TextVolumeFile struct {
	Path      string `json:"path" yaml:"path"`
	MountPath string `json:"mountPath" yaml:"mountPath"`
	Content   string `json:"content" yaml:"content"`
	Mode      string `json:"mode" yaml:"mode"`
}

TextVolumeFile is one rendered `textVolumes` entry, ready to be written.

func TextVolumeFiles

func TextVolumeFiles(input *VmComposeInput, stack, env string) []TextVolumeFile

TextVolumeFiles returns the `textVolumes` to write on the machine, with the mode each should get.

type VmAcmeStorage

type VmAcmeStorage = caddyassets.AcmeStorage

VmAcmeStorage is the vm resource's shared certificate store. The type and every rendering rule it carries live in pkg/clouds/caddy, because the Kubernetes edge configures the same module from a different struct and the module's two silent parser traps must not be encoded twice.

type VmAcmeStore

type VmAcmeStore struct {
	// Enable turns the store on. Nothing else here is required.
	Enable bool `json:"enable" yaml:"enable"`
	// Image overrides DefaultAcmeStoreImage — to pin a different version, or to point
	// at a mirror on a machine with no route to Docker Hub.
	Image string `json:"image,omitempty" yaml:"image,omitempty"`
	// Port is the S3 port the store listens on, on the mesh address only. Overriding
	// it is for a machine where something else already holds 8333.
	Port int `json:"port,omitempty" yaml:"port,omitempty"`
	// Bucket is the bucket SC creates inside the store. Defaults to `sc-acme`.
	//
	// Worth setting only when one store serves several fleets — and note that two
	// fleets sharing a bucket AND a prefix share locks and certificates, which is
	// correct only if they also share every domain name.
	Bucket string `json:"bucket,omitempty" yaml:"bucket,omitempty"`
}

VmAcmeStore asks SC to run the fleet's certificate store itself, on the first machine, and to point every node's Caddy at it.

Mutually exclusive with `ingress.acmeStorage`: that field names a store someone else owns, this one makes SC the owner, and a resource that said both would be declaring two stores and using one. The refusal says which to delete.

What it is NOT: highly available. One container on one machine. Losing host 0 does not take the fleet down — every node keeps serving from its own cached certificates — but it stops RENEWALS, and that is a failure that surfaces up to 60 days later on a machine nobody is watching. It is the right trade for a hoster with no bucket, and the wrong one where a managed bucket exists; `acmeStorage` is cheaper and safer wherever it is available.

type VmComposeInput

type VmComposeInput struct {
	ComposeTemplateConfig `json:"templateConfig" yaml:"templateConfig"`
	Deployment            k8s.DeploymentConfig `json:"deployment" yaml:"deployment"`

	Mounts       []VmMount                `json:"mounts,omitempty" yaml:"mounts,omitempty"`
	DependsOn    map[string][]VmDependsOn `json:"dependsOn,omitempty" yaml:"dependsOn,omitempty"`
	HealthChecks map[string]VmHealthCheck `json:"healthChecks,omitempty" yaml:"healthChecks,omitempty"`

	// SingleImage records that this input was projected from a `type: single-image`
	// client stack rather than read from a compose file.
	SingleImage bool `json:"singleImage,omitempty" yaml:"singleImage,omitempty"`

	// Warnings are the things SC accepted but could not honour literally, and anything
	// it had to invent. The provisioning tier logs them; the rule they serve is that a
	// field is either supported or refused, never silently dropped
	// (compose-on-vm.md §2.2).
	Warnings []string `json:"warnings,omitempty" yaml:"warnings,omitempty"`
}

VmComposeInput is what the provisioning tier receives for a `vm-compose` stack.

Deployment is the same k8s.DeploymentConfig the Kubernetes path builds, reused rather than re-derived — that is what keeps `env`, `secrets`, `size`, `runs` and cloudExtras behaving the same here as on GKE. The three maps beside it carry what compose expresses and Kubernetes does not (see VmMount, VmDependsOn, VmHealthCheck).

func (*VmComposeInput) DependsOnResources

func (i *VmComposeInput) DependsOnResources() []api.StackConfigDependencyResource

func (*VmComposeInput) ExternalVolumes

func (i *VmComposeInput) ExternalVolumes() []string

ExternalVolumes lists the named volumes the deploy must create before `up`, sorted. They are external to every compose project on purpose (compose-on-vm.md §6 rule 4).

func (*VmComposeInput) MountsOf

func (i *VmComposeInput) MountsOf(service string) []VmMount

MountsOf returns the mounts of one service in declaration order.

func (*VmComposeInput) MountsOfVolume

func (i *VmComposeInput) MountsOfVolume(volume string) []VmMount

MountsOfVolume returns every mount of one named volume, across services.

func (*VmComposeInput) OverriddenBaseZone

func (i *VmComposeInput) OverriddenBaseZone() string

func (*VmComposeInput) StatefulServices

func (i *VmComposeInput) StatefulServices() []string

StatefulServices lists the services that must run outside the blue-green slots, sorted for a stable render.

func (*VmComposeInput) Uses

func (i *VmComposeInput) Uses() []string

type VmConfig

type VmConfig struct {
	// Driver selects which cloud (or none) creates the machine. The YAML key is
	// `provider`, matching the design and the rest of SC's DSL.
	Driver string `json:"provider" yaml:"provider"`

	Region string   `json:"region,omitempty" yaml:"region,omitempty"`
	Zones  []string `json:"zones,omitempty" yaml:"zones,omitempty"`
	// Nodes is how many machines a cloud driver creates for this resource. Not
	// valid with DriverByo, where the count is `len(hosts)`.
	//
	// Default (see NodeCount): `len(zones)` when zones are listed, else 1. So
	// `zones: [a, b, c]` alone means three machines, one per zone, which is the
	// common case and needs no second field — and `nodes: 3` with one zone means
	// three machines in that zone, which is the other one.
	//
	// Machine i goes in zone i%len(zones) (ZoneForNode): deterministic and
	// index-stable, so a later apply that raises the count never moves an existing
	// machine to a different zone. Moving one would mean destroying it.
	Nodes int `json:"nodes,omitempty" yaml:"nodes,omitempty"`
	// Image is an SC alias (see DefaultImage), resolved per cloud by the driver.
	Image    string     `json:"image,omitempty" yaml:"image,omitempty"`
	Size     *VmSize    `json:"size,omitempty" yaml:"size,omitempty"`
	SshUser  string     `json:"sshUser,omitempty" yaml:"sshUser,omitempty"`
	PublicIP bool       `json:"publicIP,omitempty" yaml:"publicIP,omitempty"`
	Network  *VmNetwork `json:"network,omitempty" yaml:"network,omitempty"`
	Ingress  *VmIngress `json:"ingress,omitempty" yaml:"ingress,omitempty"`

	// Mesh builds an SC-managed WireGuard overlay across this resource's machines,
	// giving each one an address its siblings can reach it on even when the hoster
	// provides no private network. See VmMesh (mesh.go).
	Mesh *VmMesh `json:"mesh,omitempty" yaml:"mesh,omitempty"`

	// IngressPorts are additional ports SC opens in the machine's firewall, on top
	// of SSH (and 80/443 when `ingress.enable` is on) and on top of what SC infers
	// from this vm's consumers in the same parent stack. See VmIngressPort and
	// FirewallPorts (ports.go).
	IngressPorts []VmIngressPort `json:"ingressPorts,omitempty" yaml:"ingressPorts,omitempty"`

	// AllowUnverifiedProvider opts into a driver whose code exists but has never
	// provisioned a machine on the cloud it addresses (see DriverInfo.Unverified).
	// Refused when the driver IS verified, so the flag cannot linger as dead config
	// reading like a standing exception.
	AllowUnverifiedProvider bool `json:"allowUnverifiedProvider,omitempty" yaml:"allowUnverifiedProvider,omitempty"`

	// RegistryMirrors and PackageMirror exist for deployments that cannot reach
	// Docker Hub or the distribution's package mirrors — the normal case inside
	// Russia, and the reason reachability is being measured before anything is
	// promised about it (roadmap item sc-ru-market-readiness, B0).
	RegistryMirrors []string `json:"registryMirrors,omitempty" yaml:"registryMirrors,omitempty"`
	PackageMirror   string   `json:"packageMirror,omitempty" yaml:"packageMirror,omitempty"`

	// ExtraSshKeys are additional public keys authorised on the machine. Prefer the
	// cloud's own console for incident access; every key added here is a second,
	// permanent access path (vm-matrix.md §3.3).
	ExtraSshKeys []string `json:"extraSshKeys,omitempty" yaml:"extraSshKeys,omitempty"`

	// HostKey pins the SSH host key of a machine SC created but could not give an
	// identity to, as one authorized_keys line. Valid only with a driver whose cloud
	// has no cloud-init (today: DriverCloudruEvolution) — see validateCloud.
	//
	// It exists because of a cloud that accepts no user-data at all: SC cannot
	// pre-seed a host key there, so the FIRST connection has nothing to verify and
	// trust-on-first-use is the only thing left. That is a real exposure (the deploy
	// key and every secret of every stack on the machine ride that connection), and
	// an operator who reads the key off the cloud's console can close it by pasting
	// it here on the next provision. Same semantics and same format as
	// `hosts[].hostKey` — `ssh-keyscan -t ed25519 <address>` output pastes verbatim.
	HostKey string `json:"hostKey,omitempty" yaml:"hostKey,omitempty"`

	// Hosts is valid only with DriverByo.
	Hosts []VmHost `json:"hosts,omitempty" yaml:"hosts,omitempty"`

	api.Credentials `json:",inline" yaml:",inline"`
}

VmConfig is the resource config of `type: vm`.

It lives only in a parent stack's `resources:` section. The `templates:` section never configures a machine — it references one by name, exactly as gcp-gke-autopilot references gkeClusterResource (vm-matrix.md §1.2, compose-on-vm.md §2.1). That split is what lets two stacks share one machine and lets the delivery strategy change without touching the machine description.

func (*VmConfig) AcmeStorageEnabled

func (r *VmConfig) AcmeStorageEnabled() bool

AcmeStorageEnabled reports whether this resource has a shared certificate store.

func (*VmConfig) AcmeStoreBucket

func (r *VmConfig) AcmeStoreBucket() string

AcmeStoreBucket resolves the bucket SC creates in the store.

func (*VmConfig) AcmeStoreEnabled

func (r *VmConfig) AcmeStoreEnabled() bool

AcmeStoreEnabled reports whether SC stands up this resource's certificate store.

The helper is consulted FIRST and the order is not cosmetic: `s != nil` already implies a non-nil receiver with a non-nil `ingress`, whereas IngressEnabled nil-guards neither and panics on a nil config. Written the other way round, this accessor's own nil-safety claim was half-true.

func (*VmConfig) AcmeStoreEndpoint

func (r *VmConfig) AcmeStoreEndpoint() (string, error)

AcmeStoreEndpoint is the S3 base URL every node's Caddy points at.

Plain `http://`, not https. The store runs on a private overlay, and the honest options on it are an unencrypted hop inside a WireGuard tunnel or a self-signed certificate plus `insecure: true` — which is TLS whose verification is switched off, i.e. the same security with more moving parts and a worse name. On a mesh the hop is encrypted by WireGuard itself. On a `privateAddress` network it is as private as the operator's own network, which is the same assumption everything else in the fleet already makes about that address.

func (*VmConfig) AcmeStoreHost

func (r *VmConfig) AcmeStoreHost() (string, error)

AcmeStoreHost is the address the OTHER machines dial the store on — host 0's address on whatever node-to-node network this fleet has.

The mesh when there is one, else host 0's `privateAddress`. Nothing else, and in particular never host 0's public address: the credential this store accepts is logged in cleartext by certmagic-s3 on every node that uses it (`sc-certmagic-s3-creds-in-container-logs`), so a store reachable from the internet is a store whose credential is one `docker logs` away from a bucket holding every private key the fleet owns. The firewall hole SC opens for the mesh is a WireGuard port, which answers an unauthenticated packet with silence; there is deliberately no hole for this port at all.

Returns an error rather than falling back, because every fallback available here is the wrong one.

func (*VmConfig) AcmeStoreImage

func (r *VmConfig) AcmeStoreImage() string

AcmeStoreImage resolves the store's image.

func (*VmConfig) AcmeStorePort

func (r *VmConfig) AcmeStorePort() int

AcmeStorePort resolves the store's S3 port.

func (*VmConfig) CredentialsValue

func (r *VmConfig) CredentialsValue() string

CredentialsValue returns the resolved `${auth:...}` blob verbatim, and "{}" when none was given.

Deliberately NOT yandex.AccountConfig's behaviour of serialising the whole config as a fallback: a byo VmConfig carries host private keys, and serialising them into a value whose entire purpose is to be handed to other code is how a credential ends up somewhere nobody looked. A cloud driver reads its own AccountConfig out of this blob with api.ConvertAuth and fails on its own required fields if it is empty.

func (*VmConfig) DeclaresHostRoles

func (r *VmConfig) DeclaresHostRoles() bool

DeclaresHostRoles reports whether the operator named `hosts[].role` at all.

It is the question a consumer that derives roles itself has to ask before trusting VmHost.EffectiveRole, which cannot distinguish "the operator said compose" from "the operator said nothing" — RoleCompose is the answer to both. Validation guarantees all-or-none (validateHostRoles), so one host naming a role is enough to know the whole pool did.

func (*VmConfig) DriverType

func (r *VmConfig) DriverType() string

DriverType implements api.VmConfigAware so that the parse-time plugin requirement walker can reach a vm's `provider:` string. The driver — not just the resource's `type: vm` — is what selects which plugin is needed (cloudru-evolution-vm, future mws-vm, …).

func (*VmConfig) EffectiveAcmeStorage

func (r *VmConfig) EffectiveAcmeStorage() (*VmAcmeStorage, error)

EffectiveAcmeStorage is the one shared certificate store of this resource, whichever way it was declared: the operator's own `acmeStorage`, or the one SC stands up. nil means this resource has none, which is correct for a single machine.

Validate refuses both at once, so the order here is not a precedence.

func (*VmConfig) EffectiveImage

func (r *VmConfig) EffectiveImage() string

func (*VmConfig) EffectiveIngressImageDelivery

func (r *VmConfig) EffectiveIngressImageDelivery() string

EffectiveIngressImageDelivery resolves how the Caddy image reaches the machine. Defaults to ImageDeliveryRegistry — see the field comment for why the default is not the other way round.

func (*VmConfig) EffectiveSize

func (r *VmConfig) EffectiveSize() VmSize

EffectiveSize resolves the machine size, filling in DefaultCores/DefaultMemory for whichever half was left out. Disk is left empty when unset: unlike cores and memory it is not a flavour filter, and every cloud has a sane per-image root-disk default that is better than one SC invents.

func (*VmConfig) EffectiveSshUser

func (r *VmConfig) EffectiveSshUser() string

func (*VmConfig) FirewallPorts

func (r *VmConfig) FirewallPorts(inferredPresets ...string) ([]PortRange, error)

FirewallPorts is every hole SC opens on a machine it created: the base ports above, the resource's own `ingressPorts`, and the presets the caller inferred from this vm's consumers in the same parent stack.

Deduplicated by the hole rather than by the label, so a preset inferred from a `k3s-cluster` resource and the same preset written out by hand are one rule. The result is sorted by label because the label is what the Advanced driver names its Pulumi resources after, and an unstable order there is a diff on every preview.

func (*VmConfig) IngressEnabled

func (r *VmConfig) IngressEnabled() bool

IngressEnabled reports whether Caddy should be installed in front of the stacks on this machine.

func (*VmConfig) IngressImage

func (r *VmConfig) IngressImage() string

IngressImage is the Caddy image to run, defaulted. Same expression the Kubernetes edge uses (kubernetes/caddy.go), so the two paths run the same build of Caddy with the same plugin set unless an operator deliberately pins one of them elsewhere.

func (*VmConfig) ManagedAcmeStorage

func (r *VmConfig) ManagedAcmeStorage() (*VmAcmeStorage, error)

ManagedAcmeStorage synthesizes the `acmeStorage` struct that the managed store implies, so that the Caddyfile renderer has exactly one input shape to deal with whether the bucket is Yandex's, GCP's, an operator's minio or SC's own container.

The credential fields carry AcmeStoreManagedCredential rather than real values. See that constant: the renderer only tests them for emptiness before writing `{$VAR}` placeholders, and the real values exist only at provision time.

func (*VmConfig) MeshAddress

func (r *VmConfig) MeshAddress(i int) (string, error)

MeshAddress is machine i's address on the overlay.

A pure function of the config — the CIDR and the index — and that is the property that earns its keep. The certificate store runs on machine 0 and every other machine has to be told where it is; because this is computable, the store's endpoint is a constant in the rendered Caddyfile instead of a Pulumi Output threaded from one host's provisioning step into every other host's.

Index-stable by construction, so raising the node count never re-addresses an existing machine. Host addresses start at .1 (the network address itself is not usable), so machine i is network+i+1.

func (*VmConfig) MeshCidr

func (r *VmConfig) MeshCidr() string

MeshCidr is the overlay range, defaulted.

func (*VmConfig) MeshEnabled

func (r *VmConfig) MeshEnabled() bool

MeshEnabled reports whether SC should stand up the overlay on this resource.

func (*VmConfig) MeshPort

func (r *VmConfig) MeshPort() int

MeshPort is the listen port, defaulted.

func (*VmConfig) MeshPrefixLen

func (r *VmConfig) MeshPrefixLen() (int, error)

MeshPrefixLen is the CIDR's prefix length, which is what goes on the interface's own `Address` line so that wg-quick installs a route for the whole overlay.

func (*VmConfig) NodeCount

func (r *VmConfig) NodeCount() int

NodeCount is how many machines this resource describes.

It is the one place the default lives, so a driver never computes it from `nodes` and `zones` itself — two drivers disagreeing about whether `zones: [a, b]` means one machine or two would be a fleet that is one size in preview and another after apply.

func (*VmConfig) OriginTlsEnabled

func (r *VmConfig) OriginTlsEnabled() bool

OriginTlsEnabled reports whether this machine's Caddy terminates TLS.

Defaults to true on an unset field and on no ingress at all, so that every caller reads "yes" for every resource that predates `ingress.originTls` — the flag only ever turns behaviour off, never on. The parent stack exports the NEGATION of this for the same reason (ToIngressNoOriginTlsExport): a child reading a parent that has never heard of the field gets a zero bool, and the zero has to mean the old behaviour.

func (*VmConfig) ProjectIdValue

func (r *VmConfig) ProjectIdValue() string

ProjectIdValue has no meaning for a machine: the project/folder id lives inside the cloud credentials a cloud driver rehydrates, and a byo host has no cloud at all. Returning the k8s-style "n/a" keeps `${resource:...projectId}` from interpolating to something that looks real.

func (*VmConfig) ProviderType

func (r *VmConfig) ProviderType() string

func (*VmConfig) ShipsIngressImage

func (r *VmConfig) ShipsIngressImage() bool

ShipsIngressImage reports whether the provision streams Caddy to the machine from the runner instead of letting the machine pull it.

func (*VmConfig) Validate

func (r *VmConfig) Validate() error

Validate enforces the rule that makes this DSL safe to extend: **either support a field or refuse it**. A field accepted and silently ignored is a future incident in which the operator is certain the setting applied (compose-on-vm.md §2.2, D4).

It is called from the provisioning tier rather than from ReadVmConfig, because the config readers are also driven with an empty config by cmd/schema-gen — a reader that rejects an empty config drops the whole resource out of the generated schema.

func (*VmConfig) ZoneForNode

func (r *VmConfig) ZoneForNode(i int) string

ZoneForNode is where machine i goes: round-robin over `zones`, empty when the operator listed none (the driver then picks, normally the cloud's default zone).

Index-stable on purpose — see VmConfig.Nodes. Raising `nodes` from 3 to 5 must leave machines 0..2 exactly where they are, because a machine cannot change zone without being destroyed and recreated.

type VmDependsOn

type VmDependsOn struct {
	Service   string `json:"service" yaml:"service"`
	Condition string `json:"condition,omitempty" yaml:"condition,omitempty"`
}

VmDependsOn is one `depends_on` edge, carried over from the customer's compose file as written (compose-on-vm.md §6.1). It is enough for "Mongo before the backend" and is not a guarantee of anything: a Mongo restart does not restart the backend, so the application still has to survive its dependency being away.

type VmHealthCheck

type VmHealthCheck struct {
	Test        []string `json:"test" yaml:"test"`
	Interval    string   `json:"interval,omitempty" yaml:"interval,omitempty"`
	Timeout     string   `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	StartPeriod string   `json:"startPeriod,omitempty" yaml:"startPeriod,omitempty"`
	Retries     *int     `json:"retries,omitempty" yaml:"retries,omitempty"`
	// Synthesized marks a check SC invented because the customer declared none. It is
	// weak on purpose and the operator is told so.
	Synthesized bool `json:"synthesized,omitempty" yaml:"synthesized,omitempty"`
}

VmHealthCheck is a compose healthcheck, carried over verbatim.

It cannot come from DeploymentConfig either: ConvertComposeToContainers turns a compose healthcheck into a Kubernetes-shaped HTTP probe and drops the test command. On a VM the test command IS the check, and for the ingress service it is the gate the blue-green flip waits on (compose-on-vm.md §9.2).

type VmHost

type VmHost struct {
	Address string `json:"address" yaml:"address"`
	User    string `json:"user,omitempty" yaml:"user,omitempty"`
	Port    int    `json:"port,omitempty" yaml:"port,omitempty"`
	// PrivateKey is the SSH private key in PEM form, normally written as
	// `${secret:...}`. It never reaches a Pulumi resource unwrapped — see
	// pkg/clouds/pulumi/vm/byo.go.
	PrivateKey string `json:"privateKey,omitempty" yaml:"privateKey,omitempty"`
	// PrivateKeyPassword decrypts PrivateKey when it is an encrypted PEM.
	PrivateKeyPassword string `json:"privateKeyPassword,omitempty" yaml:"privateKeyPassword,omitempty"`
	// HostKey pins the machine's SSH host key as one authorized_keys line
	// (`ssh-ed25519 AAAA…`). The output of `ssh-keyscan -t ed25519 <address>` can be
	// pasted verbatim too — it is known_hosts format, one field wider, and the
	// leading address is discarded rather than checked (see
	// imageship.TestHostKeyCallbackAcceptsRawSshKeyscanOutput).
	//
	// Optional, and the one optional field here whose absence has a real cost. A
	// deploy onto a VM carries the stack's entire env file, every `${secret:...}` in
	// it, and the deploy key itself; without a pinned host key the SSH client has
	// nothing to check the machine against, so all of that goes to whoever answers on
	// that address (compose-on-vm.md §5.5). CI cannot fall back to known_hosts the way
	// a workstation does — a runner's is empty — so there is no safe implicit default
	// and the provisioning tier warns loudly when this is unset.
	//
	// Not a secret: it is the machine's PUBLIC key, and keeping it readable is what
	// lets an operator compare it against the console by eye.
	HostKey string `json:"hostKey,omitempty" yaml:"hostKey,omitempty"`

	// Role is what this machine is prepared for: one of the HostRole values
	// (`compose`, `k3s-server`, `k3s-agent`).
	//
	// It exists because SC cannot infer which of three machines should run etcd. On
	// a cloud driver the machines are interchangeable — SC creates them, so it
	// assigns the roles by index. On byo they are not: the operator knows which box
	// has the disk, the memory and the stable address, and that knowledge has no
	// other way into the config.
	//
	// Optional, and optional in a load-bearing way: when every host leaves it empty
	// the role is inferred from what consumes the vm resource, which is exactly
	// what every single-host stack written before this field did (see
	// EffectiveRole). Either every host names a role or none does — a pool where
	// host 0 says `k3s-server` and host 1 says nothing is a pool whose host 1 is a
	// guess, and the guess decides whether it joins the cluster at all.
	Role string `json:"role,omitempty" yaml:"role,omitempty"`

	// PrivateAddress is the address this machine's SIBLINGS should use to reach it.
	// `address` is what SC dials from outside; this is what the fleet dials from
	// inside, and on a multi-node k3s pool they are not interchangeable.
	//
	// Required for a multi-host k3s pool, and the reason is worth stating here
	// rather than only in the error: k3s is told nothing about addressing by SC
	// (`--node-ip`, `--node-external-ip` and `--flannel-iface` are set nowhere), so
	// it defaults node-ip to the address of the default-route interface. On a cloud
	// VM reached through a floating/NAT IP that is already the private address and
	// everything is correct. On a single-NIC VPS with a directly attached public IP
	// it is the PUBLIC address — and then etcd peer traffic (the cluster's entire
	// state, every Secret) and flannel's VXLAN overlay (unencrypted; see
	// pkg/clouds/k3s/cluster.go) cross the public internet, on a `byo` host that has
	// no firewall to stop them (pkg/clouds/pulumi/vm/byo.go). That deploy SUCCEEDS,
	// which is why this is a refusal and not a warning.
	//
	// Not required for a compose fleet: those machines never talk to each other (the
	// only shared state is the ACME store, reached outbound over HTTPS), so there is
	// no node-to-node traffic to misdirect.
	//
	// Hosters without private networking have no value to put here. That case is
	// what `mesh.enable: true` is for (see VmMesh): SC builds a WireGuard overlay
	// across the resource's machines and assigns each one an address on it, which
	// lifts the requirement above entirely. Leave this empty there — the two are
	// alternatives, and where a cloud has real private networking it is the cheaper
	// one.
	PrivateAddress string `json:"privateAddress,omitempty" yaml:"privateAddress,omitempty"`
}

VmHost is one machine the operator brought — the whole input of DriverByo.

func (VmHost) EffectivePort

func (h VmHost) EffectivePort() int

func (VmHost) EffectivePrivateAddress

func (h VmHost) EffectivePrivateAddress() string

EffectivePrivateAddress is the address siblings of this machine should dial: `privateAddress` when the operator named one, else `address`.

The fallback is only reached on shapes that do not need the distinction — a compose fleet, or a single-host pool — because validateHostRoles refuses a multi-host k3s pool that names none (see VmHost.PrivateAddress).

func (VmHost) EffectiveRole

func (h VmHost) EffectiveRole() HostRole

EffectiveRole resolves the machine's role, falling back to RoleCompose — which is what the provisioning tier hardcoded for every byo host before `role:` existed, so a config that names no role behaves exactly as it did.

A consumer that derives roles itself (the k3s cluster resource, which assigns by index when the pool declares none) must ask DeclaresHostRoles first: this method cannot distinguish "the operator said compose" from "the operator said nothing".

func (VmHost) EffectiveUser

func (h VmHost) EffectiveUser(fallback string) string

EffectiveUser resolves the login name: the host's own, else the resource-level default, else DefaultSshUser.

type VmIngress

type VmIngress struct {
	Enable bool `json:"enable" yaml:"enable"`
	// OriginTls is whether THIS machine terminates TLS. Unset means true, which is
	// every vm resource that existed before this field.
	//
	// Set it to false when something in front already terminates — Cloudflare's
	// proxy, a cloud load balancer, an existing reverse proxy — and Caddy then serves
	// plain HTTP on port 80 and runs no ACME at all. That is the ONE front-door
	// arrangement a fleet can have without a shared certificate store (see
	// AcmeStorage, which explains why per-machine ACME behind N A records cannot
	// work), so on a cloud with no bucket resource and no appetite for running minio
	// it is not a downgrade, it is the option.
	//
	// It is also what makes `domainProxied: true` legal on a stack: that refusal
	// exists because a proxied domain breaks the HTTP-01 challenge Caddy runs itself,
	// and here Caddy runs none. The refusal therefore moved out of the convert tier
	// (which cannot see this field — it belongs to the parent stack) and into the
	// deploy, where the parent's exports are readable.
	//
	// What it does NOT do is secure the hop. Edge-to-origin is cleartext over the
	// public internet unless the machine's firewall admits only the edge's addresses
	// — Cloudflare publishes theirs, and `ingressPorts` on this resource is where
	// they go. Said plainly because "my site is HTTPS" is true for the visitor and
	// false for the leg SC is responsible for.
	OriginTls *bool `json:"originTls,omitempty" yaml:"originTls,omitempty"`
	// Email is the ACME account address. Required when Enable is set and this machine
	// terminates TLS, because a certificate authority will not issue without one.
	Email string `json:"email,omitempty" yaml:"email,omitempty"`
	// Image is the Caddy image to run. Defaults to the same `simplecontainer/caddy`
	// tag the Kubernetes edge uses, which is what makes `lbConfig.siteExtraHelpers`
	// mean the same thing on both paths — the plugins (`rate_limit`, certmagic
	// storage) are in that image and not in the official one. Override to pin a tag
	// or to run a local mirror.
	Image string `json:"image,omitempty" yaml:"image,omitempty"`
	// ImageDelivery is how that image reaches the machine: ImageDeliveryRegistry
	// (default — the machine pulls it) or ImageDeliverySshTar (the runner pulls it
	// and streams it over the provision's SSH connection).
	//
	// The default is "the machine pulls" because that is what every existing vm
	// resource already does, and because shipping makes `sc provision` need a local
	// docker daemon it has never needed before. `ssh-tar` is for the case this whole
	// delivery path exists for: a machine with no route to Docker Hub
	// (compose-on-vm.md §8.3). Caddy is the one image SC itself insists on, so
	// without this the ingress is the last thing on such a machine that still needs
	// a registry — `externalImages: ship` on the template covers a stack's own
	// images and the third-party ones beside them, and stops at the ingress because
	// the ingress belongs to the resource, not the stack.
	ImageDelivery string `json:"imageDelivery,omitempty" yaml:"imageDelivery,omitempty"`
	// AcmeCa points Caddy at a certificate authority other than Let's Encrypt.
	//
	// This field exists because of the Russian market specifically
	// (compose-on-vm.md §8.3): a `.ru` domain opened from inside Russia in a browser
	// without foreign roots wants a certificate from the Russian Trusted CA, and
	// Let's Encrypt may not even be reachable from a closed network. Whether that CA
	// speaks ACME is UNVERIFIED — the field is here because without it there is no
	// option at all, not because the path is known to work.
	AcmeCa string `json:"acmeCa,omitempty" yaml:"acmeCa,omitempty"`
	// AcmeEabKeyID / AcmeEabMacKey are External Account Binding, which a private or
	// enterprise ACME CA generally requires and Let's Encrypt does not.
	//
	// AcmeEabMacKey is a credential: write it as `${secret:...}`. It never appears in
	// the rendered Caddyfile — both values are delivered in the ingress env file
	// (0600, over stdin) and referenced as `{$...}` placeholders, so they stay out of
	// the Pulumi checkpoint and out of a file an operator might paste into a ticket.
	AcmeEabKeyID  string `json:"acmeEabKeyId,omitempty" yaml:"acmeEabKeyId,omitempty"`
	AcmeEabMacKey string `json:"acmeEabMacKey,omitempty" yaml:"acmeEabMacKey,omitempty"`
	// AcmeStorage points every machine of this resource at ONE shared certificate
	// store. Leave it unset for a single machine; set it for a fleet.
	//
	// On a fleet it is not a tuning knob, it is the thing that makes HTTPS possible.
	// SC's Caddy image carries no `dns.*` provider, so HTTP-01 is the only ACME
	// challenge available, and a name with N A records sends the CA's validator to an
	// arbitrary machine — which 404s a token a sibling minted. certmagic's distributed
	// solver shares that challenge state through the storage module, so one store turns
	// N machines into one ACME client holding one certificate instead of N. Without it
	// a fleet either serves plain HTTP on the origin (see `domainProxied`) or walks
	// into a rate-limit lockout.
	AcmeStorage *VmAcmeStorage `json:"acmeStorage,omitempty" yaml:"acmeStorage,omitempty"`
	// AcmeStore asks SC to RUN that store itself, on the fleet's first machine, and
	// point every node at it. For a hoster that sells no bucket — Cloud.ru, MWS, a
	// rented VPS — where `acmeStorage` has nothing to name.
	//
	// Mutually exclusive with AcmeStorage, and the weaker of the two wherever a
	// managed bucket exists: see VmAcmeStore, which also says what it is not (it is
	// one container on one machine, and losing that machine stops renewals).
	AcmeStore *VmAcmeStore `json:"acmeStore,omitempty" yaml:"acmeStore,omitempty"`
}

VmIngress configures the Caddy front door that terminates TLS on the machine. It is a property of the machine, not of the delivery template, because several stacks share one machine and therefore one port 443 (compose-on-vm.md §3, D15).

type VmIngressPort

type VmIngressPort struct {
	// Preset names a bundle of ranges (see IngressPresetK3s). Mutually exclusive
	// with Port.
	Preset string `json:"preset,omitempty" yaml:"preset,omitempty"`
	// Port is the first (or only) port of the range.
	Port int `json:"port,omitempty" yaml:"port,omitempty"`
	// PortEnd closes an inclusive range that starts at Port. Omit for a single port.
	PortEnd int `json:"portEnd,omitempty" yaml:"portEnd,omitempty"`
	// Protocol is `tcp` (the default) or `udp`.
	Protocol string `json:"protocol,omitempty" yaml:"protocol,omitempty"`
}

VmIngressPort is one entry of a vm resource's `ingressPorts`: either a preset, or a port (optionally a range).

It exists because the `vm` resource genuinely cannot know what will be put on the machine. SC infers the presets of the consumers it can see in the same parent stack (a `vm-compose` template or a `k3s-cluster` resource naming this vm), and this list is how an operator states the rest — the port their own service binds, a second service, a UDP listener — without that inference having to be clairvoyant.

type VmMesh

type VmMesh struct {
	Enable bool `json:"enable" yaml:"enable"`
	// Cidr is the overlay's range. Machine i gets host address i+1 within it
	// (MeshAddress), so a /24 holds 254 machines.
	//
	// Override it when it collides with something on the machines — see
	// DefaultMeshCidr for the list of ranges the default was chosen to avoid, and
	// note that changing it later re-addresses every node, which flaps the mesh once.
	Cidr string `json:"cidr,omitempty" yaml:"cidr,omitempty"`
	// Port is the UDP port every machine listens on. It is open to the INTERNET and
	// not to the fleet — a peer's endpoint is its public address, so there is no
	// inner network for the hole to be scoped to.
	//
	// That is sound, and it is worth saying why rather than leaving it to look like
	// an oversight: WireGuard sends no reply at all to a packet that does not
	// authenticate against a known peer's key, so the port is invisible to a scan
	// and unreachable to anyone without a key in the fleet's own config. It is the
	// one piece of the mesh whose exposure is deliberate.
	Port int `json:"port,omitempty" yaml:"port,omitempty"`
}

VmMesh is an SC-managed WireGuard overlay across the machines of one vm resource.

It exists because two things the fleet needs — a shared certificate store and a multi-node k3s pool — both require the machines to reach each other on an address that is not the public internet, and a large part of the hosting market provides no private networking at all. Without it those topologies are either refused (see VmHost.PrivateAddress) or quietly insecure.

What it is not: a substitute for a cloud's own private network. Where one exists, `privateAddress` is cheaper, faster and already trusted by the cloud's firewall — the mesh is for the machines that have no such thing, and for the case where the machines are in different clouds entirely.

type VmMount

type VmMount struct {
	Service   string `json:"service" yaml:"service"`
	Type      string `json:"type" yaml:"type"`
	Name      string `json:"name" yaml:"name"`
	MountPath string `json:"mountPath" yaml:"mountPath"`
	ReadOnly  bool   `json:"readOnly" yaml:"readOnly"`
	// Size is a tmpfs size, when the customer set one.
	Size string `json:"size,omitempty" yaml:"size,omitempty"`
}

VmMount is one volume mount of one service, classified while the customer's compose file is still in hand.

k8s.DeploymentConfig flattens every mount into a PersistentVolume and keeps neither the mount type nor the read-only flag — on a VM both decide real behaviour: which volume must be external (and therefore survive a slot teardown) and which service is stateful (and therefore must not be duplicated by blue-green).

func (VmMount) IsStateful

func (m VmMount) IsStateful() bool

IsStateful reports whether this mount makes its service unsafe to run in two slots at once. Two writers on one volume corrupt it, so such a service lives outside the slots (compose-on-vm.md §9.1).

type VmNetwork

type VmNetwork struct {
	ID string `json:"id,omitempty" yaml:"id,omitempty"`
	// Subnets maps a zone name to the subnet id to use in that zone.
	Subnets map[string]string `json:"subnets,omitempty" yaml:"subnets,omitempty"`
}

VmNetwork pins an existing private network instead of letting SC create one. Everything in it is optional; empty means "create".

type VmSize

type VmSize struct {
	Cores int `json:"cores,omitempty" yaml:"cores,omitempty"`
	// Memory and Disk are quantities in the style the rest of SC's DSL uses
	// (`8Gi`, `60Gi`), not raw byte counts.
	Memory   string `json:"memory,omitempty" yaml:"memory,omitempty"`
	Disk     string `json:"disk,omitempty" yaml:"disk,omitempty"`
	DiskType string `json:"diskType,omitempty" yaml:"diskType,omitempty"`
}

VmSize is the machine shape, in SC's own units rather than a per-cloud flavor name. Each driver maps it onto what its cloud actually takes (YC's resources{cores,memory}, OpenStack's flavor_name, Timeweb's preset_id, …).

Directories

Path Synopsis
Package imageship moves locally-held docker images onto a remote docker host over SSH, without a registry and without the docker CLI on the machine doing the shipping.
Package imageship moves locally-held docker images onto a remote docker host over SSH, without a registry and without the docker CLI on the machine doing the shipping.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL