Skip to content

Bring-up — labels & routes by hand

until Starbase + Shuttle ship

Part of the self-contained SRE guide

This chapter restates the starform.io/* label set and the HTTPRoute name format inline — the two things every pipeline reads off a workload — so the guide stands alone. Owned by PRD §20.1 / §20.2 / §24.1 / §32 — the PRD wins on conflict. The Reference collects every inlined contract with its provenance.

In plain words

Everything above reads two things off each workload: the starform.io/* labels and the HTTPRoute name. Shuttle normally generates both from desired state — but until it exists, nothing stamps them, so the vmagent parse, the cAdvisor↔KSM join, and Fluent Bit's enrichment all attribute to nothing. You apply them by hand. (The agents themselves — KSM + allowlist, vmagent, Fluent Bit, Alloy — come from chapter 8; this chapter is the per-workload identity Shuttle would add.)

How to build it

For every service you want observed, five steps — the IDs in steps 2–4 must match exactly:

1 · Create the project namespace — one per project; deploy the project's Services into it:

shell · create the namespace
kubectl create namespace proj-<project_slug>

2 · Mint the IDs once — and reuse them everywhere. The same 32-hex project_id and service_id must appear in both the labels (step 3) and the route name (step 4): the Envoy path derives identity from the route, the cAdvisor path from the label — if they differ, the two never line up on a dashboard. (environment is the plain RFC 1123 name in both places — no stripping.) Keep them in a registry so they stay stable:

shell · mint the IDs
project_id=$(uuidgen | tr -d '-')   # e.g. 1f2e3d4c5b6a79880011223344556677
service_id=$(uuidgen | tr -d '-')   # e.g. 0a9b8c7d6e5f40312233445566778899

3 · Label the Deployment's pod template (kube-state-metrics reads pod labels) with the full set. managed-by: shuttle must be exact — the recording rule joins kube_pod_labels{label_starform_io_managed_by="shuttle"}, and KSM's allowlist + Fluent Bit's Labels On key off the set:

Deployment · pod-template labels
spec:
  template:
    metadata:
      labels:
        starform.io/managed-by:   shuttle
        starform.io/workspace-id: <workspace-id>
        starform.io/project-id:   1f2e3d4c5b6a79880011223344556677   # 32-hex from step 2
        starform.io/service-id:   0a9b8c7d6e5f40312233445566778899
        starform.io/environment:  production
        starform.io/service-name: web
        starform.io/cluster-id:   <cluster-id>
        starform.io/tier:         mininova

4 · Name the HTTPRoute <project32><service32>-<environment> — the two 32-hex IDs concatenated (no separator between them), then - + environment. Envoy turns this into envoy_cluster_name = httproute/<ns>/<project32><service32>-<env>/rule/0, which the ch.2 parse reads. Only web services get a route (→ L7 metrics); workers and crons get CPU/mem/network from labels alone:

HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: 1f2e3d4c5b6a798800112233445566770a9b8c7d6e5f40312233445566778899-production
  namespace: proj-<project_slug>          # object names allow ≤253 chars — this fits
spec:
  parentRefs: [{ name: <envoy-gateway> }]
  rules: [{ backendRefs: [{ name: web, port: 80 }] }]

5 · Verify the hand-off. kubectl get pod --show-labels shows the set; kube_pod_labels{label_starform_io_managed_by="shuttle"} exposes them (KSM allowlist working, ch.2); a metric carries project_id/environment/service_id after the recording rule and the Envoy parse. Then ch.1–8's own Verify steps pass. (See ch.2 · ch.3.)

Gotchas & what lives elsewhere

  • Label values must be the 32-hex form for project-id / service-id — the same strings the route name uses. A hyphenated UUID in the label but hyphen-stripped in the route means the cAdvisor-path and Envoy-path metrics disagree and never join.
  • This is scaffolding. When Starbase + Shuttle ship they generate exactly these from desired state (§32) — delete the manual labels and routes and let desired state own them. Until then, a small project_id/service_id registry keeps IDs stable across redeploys.

PRD reference & inlined contracts

Owned by §20.1 (namespace), §20.2 (HTTPRoute name + parse), §24 / §24.1 (labels & tenant key), §32 (desired state — what Shuttle will own). The label set and route-name format are restated above so this guide stands alone — if they ever diverge, the PRD pages win. Canonical map: Canonical Sources.