Environments

An environment is a named pointer at a spec version. staging, production, canary - the names are yours, because they have to match what your gateways already call themselves.

Without one, every gateway serving a proxy is held to that proxy's published version. With one, a gateway configured with

# apip.ymlreport  environment: staging

is held to whatever staging points at here, and everything unlabelled carries on with the published version.

Why a pointer

Versions are immutable and content-addressed, so a pointer is enough - and it makes two operations the same operation:

• Promotion is moving production to the version staging has been running.
• Rollback is moving it back.

That symmetry is the whole feature. A rollback that is a different procedure from a deploy is a procedure nobody has rehearsed, and 3am is a bad time to read it for the first time.

What cannot go wrong

Naming an environment can never take a gateway down. Three fallbacks, all deliberate:

• a gateway that names no environment gets the published version;
• a gateway naming an environment this proxy has never heard of gets the published version;
• an environment that exists but has not been pointed anywhere gets the published version.

Removing an environment does the same thing: the gateways reporting it fall back, on their next poll.

The name

Lowercase letters, digits, dash and underscore, up to 32 characters. It travels in your config file, in our registry feed, and on every violation record your gateway ships - so it is not a place for spaces or punctuation.

Timing

Pointing an environment is not a deploy. The fleet picks it up on its next registry poll: requests in flight finish on the version they started on, and new ones see the new one.

From a terminal

apip env 42
apip env set 42 staging 118      # point staging at version 118
apip env set 42 production 118   # promote the same bytes
apip env set 42 production 117   # and back again
apip env rm 42 canary