As platform owner, how do you set a fleet-wide GOMAXPROCS policy for Go services in containers?

## The decision, stated honestly Somebody has to answer this once for every Go service in the fleet: **who decides GOMAXPROCS?** The runtime, the deployment template, or the code. It is a real ownership question, because the platform team can mandate an answer and a service owner who wants a different one has to win that argument. ## Option A — the runtime's container-aware default On a recent toolchain the runtime derives the value from the smaller of the visible CPUs and the cgroup CPU limit, and re-reads the limit as the process runs. **For:** one mechanism for the whole fleet; no per-service configuration to drift; correct automatically when a limit changes, including a live resize; a new service is right on day one with nobody thinking about it. **Against:** it only applies where the module's `go` directive is recent enough, since GODEBUG defaults follow that line, so the policy is really a *version* policy in disguise. It is also implicit — nothing in the manifest says what the value will be, which frustrates anyone reading the deployment to predict behaviour. ## Option B — inject the environment variable from the deployment Compute `GOMAXPROCS` from the CPU limit in a shared template and set it on every pod. **For:** explicit and reviewable in the manifest; works uniformly across toolchain versions; easy to reason about and to audit centrally. **Against:** it is a snapshot. Resize the workload and the injected value is now wrong, silently, until somebody re-renders and redeploys. Worse, because it is an explicit setting it *disables* the runtime's own updating, so it does not merely duplicate option A — it replaces a self-correcting mechanism with one that can go stale. It also requires plumbing the limit into the pod's environment, which is one more template that must be right. ## Option C — pin it in application code **For:** essentially nothing, at fleet scale. **Against:** invisible to operators, unfixable without a code change and a release, and prone to the legacy `runtime.GOMAXPROCS(runtime.NumCPU())` idiom, which actively reinstates the wrong number inside a container. If the fleet has these, finding and deleting them is the highest-value part of the whole exercise. ## What I would mandate 1. **Default: the runtime decides.** No `GOMAXPROCS` environment variable, no code call. 2. **Enforce the prerequisite, not the intent.** A minimum `go` directive in `go.mod` across the fleet, checked in CI. Without it the policy is a wish. 3. **Ban the override in libraries outright**, and confine it in applications to the start-up path, enforced by a lint rule rather than a convention. 4. **Make the value observable.** Every service logs `runtime.NumCPU()`, `runtime.GOMAXPROCS(0)` and the CPU limit it requested, in one line, at start-up. This is the single cheapest thing on the list and it converts an incident-time investigation into a glance. 5. **Export throttling.** The cgroup's throttled-period ratio as a metric per service, so the fleet can see who is losing time to over-subscription without anybody filing a ticket first. ## The escape hatch, and who pays for it A blanket rule with no exceptions gets routed around. Two legitimate exceptions exist: - **Deliberate over-subscription.** A batch or asynchronous tier that would rather burst above its quota and absorb throttling than leave burst capacity unused. That is a defensible position for throughput-oriented, latency-insensitive work, and never for a request path. - **A latency-sensitive service that has measured a better value.** Fine — with the numbers, and with the owner accepting that they now maintain that value against every future resize. Both exceptions carry the same obligations: written justification, the value logged at start-up, and the throttling metric watched by the team that asked for the exception. The point of the policy is not that nobody may deviate; it is that a deviation is a decision somebody made, rather than a default nobody chose. ## Sequencing the rollout Do not flip everything at once. Ship the start-up log first and collect the current values across the fleet — that alone usually surfaces a handful of services running with an absurd P count. Then bump `go.mod` versions in waves, watching the throttling metric and tail latency of the services that change. Delete code overrides last, once you can see what deleting one does. The order matters because the first two steps are observation, and only the third changes behaviour.