Skip to content
    OpafraDocs

    Environments

    An environment is a named group of servers and the place policy lives. Targeting one keeps a plan correct as hosts come and go.

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    An environment is a named group of servers, such as production or staging. It is also where policy lives: whether runs against those hosts need approval, who may touch them, and which variable values apply.

    A server belongs to one environment.

    Why target an environment#

    Targeting a plan at production rather than at three hostnames means the plan keeps working when the fourth host is added. Nobody has to remember to update it, and the plan that silently missed a host stops being a category of mistake.

    It also means policy is applied to the plan you have not written yet. A rule attached to the environment covers every plan that touches it, including plans written later by people who never read the policy.

    Tiers#

    An environment has a tier: Production, Staging, Development or Other. The tier drives how the environment is presented, and it sets defaults. Creating a Production environment turns on the approval gate by default.

    It is a default and not a lock. You can turn it off, and you can turn it on for a Development environment if that is what your team needs. The tier is stored and editable rather than guessed from the name, so an environment called prod-eu is not treated differently from one called production unless you say so.

    Two independent flags#

    Both sound like "locked down" and they do different things:

    Requires approval gates the change. Any run whose targets land in this environment pauses before its first step and waits for an approver. People can still see the environment and still start runs. This is covered in full under approval gates.

    Protected gates the people. Even an Operator needs an explicit grant to view, run against, or manage the environment. Without a grant the environment is not visible, which is the safer default: something you cannot see is something you cannot accidentally target.

    An environment can have either flag, both, or neither.

    Granting access to a protected environment#

    A grant gives a specific person a role on a specific environment, and it can carry an expiry. A grant that expires closes on its own, which is the property that makes temporary access actually temporary rather than permanent access that someone intended to revoke.

    Someone without access can request it. The request is a record: who asked, for which environment, and who decided. An approver can grant it for a fixed number of hours rather than indefinitely.

    Variables#

    An environment holds variable values. The same key can have a different value in each environment, so one plan referring to {{ vars.app_port }} resolves it differently against staging and against production.

    This is what lets a single plan be the same plan everywhere. The differences between your environments live in the environments, not in forked copies of the plan that drift apart.

    When a run's targets span more than one environment, Opafra asks which environment supplies the values, because the answer cannot be inferred. When the targets are all in one environment, that one is used.

    Default bastion#

    An environment can name a default bastion, used by every host in it that does not name its own. For a private subnet reached through a single jump host, this is one setting instead of one per server. A host that names its own bastion keeps it.

    Next steps#