Self-service provisioning: make the request contract explicit

Last updated: 1 Oct 20266 min read

tutorial

A self-service form that creates resources is an API even when its interface is a template. The request must validate requester authority, environment, data classification, region, cost center, quota, naming identity, and the desired retention period before side effects begin. The response must expose a durable request ID and a clear distinction between accepted, ready, rejected, and failed. Resource creation without an owner or cleanup rule moves toil from the requestor to the platform team and leaves orphaned infrastructure behind.

Operational decision

A product team requests a review environment for the claims API. The platform validates that the team owns the service, its allowed region matches the data classification, the requested database tier fits budget and provider quota, and the lease has an expiry. It records the requested specification and policy decision under an idempotency key before creating any cloud resource. Repeat the same request after a client timeout; the platform should return the original request state instead of creating a second database. Change the requested tier while reusing the key and require a conflict rather than silently mutating the first request. A policy denial should explain which field failed and how to request an exception without leaking secret values. Publish the resource owner, support boundary, monthly cost estimate, deletion rule, and handoff condition in the response. A successful form submission is not proof that the workload can connect to its database.

Claims environment request
Request ID: durable identifier
Idempotency key: caller plus operation identity
Service owner: team-claims
Classification: internal
Region: approved region
Capacity: database tier within quota and budget
Lease: expiry and renewal owner
Result: accepted, ready, rejected, or failed

Cost and verification

Admission checks can be O(1) with indexed ownership and quota data, while provisioning latency depends on external providers and may last minutes. Keeping request records and a reconciliation worker adds storage and operational cost but prevents duplicate resources after retries. Measure requests denied for clear reasons, duplicate side effects, time to usable environment, orphan rate, and resources without a cost owner. Recheck quotas at execution because capacity can change between approval and allocation.

Common Mistakes

Do not create resources before recording an idempotent request.
Do not call an accepted request ready before connectivity and ownership checks pass.
Do not hide policy failures behind a generic provisioning error.

Connected lessons

Practice and check

devops

platform-engineering