Shuttle Annotation Conventions¶
Annotations are metadata, not selectable. They carry provenance, trigger rollout semantics, and integrate with external platforms (DigitalOcean CCM, Prometheus ecosystem, cert-manager). Every annotation Shuttle applies is cataloged here so engineers have a single source of truth.
§24B.1 Provenance Annotations (On All Service Resources)¶
| Annotation | Value | Purpose |
|---|---|---|
starform.io/deployment-id |
Deployment UUID | Which deployment created this resource version |
starform.io/build-id |
Build UUID | Which build produced the image |
starform.io/git-sha |
Full commit SHA | Source commit reference |
starform.io/git-ref |
e.g. refs/heads/main |
Source ref at build time |
starform.io/git-repo |
e.g. github.com/acme/api |
Source repository |
starform.io/image-ref |
Full image ref with digest | Exact image running (digest, not tag) |
starform.io/deployed-at |
ISO-8601 timestamp | When Shuttle applied this version |
starform.io/deployed-by |
User UUID | Who triggered the deployment |
kubernetes.io/change-cause |
Deployment <dep_id> by <user_email> |
Shown in kubectl rollout history |
§24B.2 Rollout Trigger Annotations (On Pod Template)¶
Changing these annotations forces a new ReplicaSet and triggers a rolling restart without requiring an image change. Used when non-image configuration changes (e.g., Var Group rotation).
| Annotation | Value | When It Changes |
|---|---|---|
starform.io/var-group-checksum |
sha256:<hex> of sorted JSON of all attached Var Group values |
When any attached Var Group entry value changes |
starform.io/config-checksum |
sha256:<hex> of service config (ports, probes, resource limits) |
When service config changes |
starform.io/restart-nonce |
Random UUID | When user explicitly clicks "Restart" in dashboard |
Checksum computation (Var Group): Shuttle sorts attached Var Groups by attach_order,
serializes each group's entries (sorted by key) to canonical JSON, concatenates, and hashes with
SHA-256. Any change to any attached value produces a new checksum, which bumps the pod template
hash, which triggers a zero-downtime rolling restart. See
§38.7.
§24B.3 Customer-Facing Metadata Annotations¶
| Annotation | Value | Purpose |
|---|---|---|
starform.io/service-url |
e.g. api-ws_abc.starform.app |
Auto-generated public URL |
starform.io/custom-domains |
Comma-separated domain list | Customer-configured domains |
starform.io/environment-label |
e.g. Production, Staging |
Human-readable env name (distinct from the label value used for selectors) |
§24B.4 DigitalOcean Cloud Controller Manager Annotations¶
Applied to the Envoy Gateway Service (the LoadBalancer-type Service that fronts the cluster):
| Annotation | Typical Value | Purpose |
|---|---|---|
service.beta.kubernetes.io/do-loadbalancer-size-unit |
1–200 |
LB size (scales with cluster load; Starbase manages) |
service.beta.kubernetes.io/do-loadbalancer-protocol |
tcp |
Transport; TLS terminates at Envoy |
service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol |
true |
Preserves client IP for Envoy |
service.beta.kubernetes.io/do-loadbalancer-healthcheck-port |
10256 |
Health check endpoint |
service.beta.kubernetes.io/do-loadbalancer-healthcheck-protocol |
tcp |
Health check protocol |
The full DO LB annotation set is maintained in a Go constant in Starbase's DO adapter package; this table lists the subset managed via desired state.
§24B.5 Prometheus / vmagent Scrape Annotations¶
Applied to pods that expose a /metrics endpoint:
| Annotation | Value | Purpose |
|---|---|---|
prometheus.io/scrape |
true |
Opt-in to metric scraping |
prometheus.io/port |
e.g. 9090 |
Metrics port |
prometheus.io/path |
Default /metrics |
Metrics endpoint path |
prometheus.io/scheme |
http or https |
Scheme |
vmagent's relabel configs (set once during cluster bootstrap,
§35.2) promote all starform.io/* labels
into metric labels automatically, so queries can filter by workspace/project/environment without
per-service configuration.
§24B.6 Var Group Secret Annotations¶
Applied to K8s Secrets created from Var Groups (§38):
| Annotation | Value |
|---|---|
starform.io/var-group-id |
Var Group UUID |
starform.io/var-group-name |
Var Group display name |
starform.io/var-group-version |
Monotonic version, bumped on value change |
starform.io/environment |
Environment this Secret is scoped to |
starform.io/project-id |
Owning project |
starform.io/encrypted-at-rest |
true — indicates upstream Postgres storage is encrypted |
§24B.7 Namespace Annotations¶
| Annotation | Value |
|---|---|
starform.io/project-created-at |
ISO-8601 |
starform.io/project-owner-email |
For debugging; customer-visible |
starform.io/cluster-assignment-reason |
e.g., "region=eu-west,plan=pro" — why this cluster was picked |
starform.io/soft-delete-at |
Set on project deletion; namespace GC removes after retention window |
§24B.8 HTTPRoute Annotations¶
| Annotation | Value |
|---|---|
starform.io/custom-domain-validated-at |
When domain ownership was validated (cert-manager or manual DNS) |
starform.io/tls-cert-ref |
Reference to the Secret holding the TLS cert (cert-manager-managed) |
cert-manager.io/cluster-issuer |
letsencrypt-prod (post-MVP, when cert-manager lands) |
§24B.9 Consumer Contracts¶
Each annotation has a defined consumer. Changes to annotation names or semantics require updating all consumers:
| Annotation prefix | Consumer |
|---|---|
starform.io/* |
Shuttle (filtering, rollout triggers), Fluent Bit (log enrichment), vmagent (metric labels), Stardeck (dashboard display), billing cron (aggregation) |
service.beta.kubernetes.io/do-* |
DigitalOcean Cloud Controller Manager |
prometheus.io/* |
vmagent scrape config |
cert-manager.io/* |
cert-manager controller |
kubernetes.io/change-cause |
kubectl rollout history |
app.kubernetes.io/* |
Third-party K8s tools (Lens, k9s, Headlamp) |