Protected environments

A protected environment restricts deployments to an environment. Only those who are explicitly allowed can run a deployment job, and a deployment can additionally require approvals before the job runs. Protection is typically used for environments that serve users, such as production.

Protection is configured in a project for an environment name, and in a group for a deployment tier. A group rule applies to every project of the group and its subgroups.

How protected environments work

The “Allowed to deploy” list of a rule names who can run a deployment job for the environment, and who can change, stop, or delete the environment itself. The “Approval rules” list names whose approval a deployment needs, and how many approvals each subject must give.

The rule owner determines what the rule name means:

The tier of an environment comes from the deployment_tier keyword in the CI/CD configuration file. If the keyword is omitted, Deckhouse Code derives the tier from the environment name, looking for the following substrings regardless of their case:

The rows are checked in this order, and the first match determines the tier. The dev-live environment gets the development tier. A name that contains none of these substrings gets the other tier.

A deployment to an environment is governed by the project rule for its name together with the group rules for its tier, and all these rules apply at the same time. To run the deployment job, a user must be listed in “Allowed to deploy” of every applicable rule. To deploy, the approvals required by the approval rules of every applicable rule must be collected.

Instance administrators can deploy under any rule and approve through any approval rule. These privileges, and every other administrator exemption named on this page, work independently of admin mode.

An administrator who is not a member of the project gets access to the project and its jobs after switching into admin mode, when it is enabled on the instance. A deployment created by their own job is the exception. It follows “Approving your own deployment” like any other.

Prerequisites

Before configuring protected environments, make sure the following requirements are met:

• CI/CD is enabled in the project.
• The CI/CD configuration file contains a job with the environment keyword.
• The user has the Maintainer or Owner role to configure project rules, or the Owner role in the group to configure group rules.

A project rule can be configured before the environment is created. Once the environment is created, it is protected immediately if its name matches the rule name.

Protecting an environment in a project

You can protect a project environment through the web interface or API.

curl --request POST --header "PRIVATE-TOKEN: <TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "production",
    "deploy_access_levels": [{ "access_level": 40 }],
    "approval_rules": [{ "access_level": 40, "required_approvals": 2 }]
  }' \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments"

# All project rules, sorted by name.
curl --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments"

# Rules inherited from the project group hierarchy, with their owner group.
curl --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/inherited"

# One rule.
curl --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/<ENVIRONMENT_NAME>"

# Changing the lists of an existing rule.
curl --request PUT --header "PRIVATE-TOKEN: <TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{ "approval_rules": [{ "access_level": 40, "required_approvals": 1 }] }' \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/<ENVIRONMENT_NAME>"

# Removing protection.
curl --request DELETE --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/<ENVIRONMENT_NAME>"

Protecting environments in a group

A group rule protects environments by deployment tier, so one rule covers the environments of that tier in every project of the group and its subgroups.

To create a group rule:

1. Open the group.
2. Go to “Settings” → “CI/CD”.
3. Expand the “Protected environments” section.
4. Click “Add protected environment”.
5. In “Environment name”, select the deployment tier:
   • “Production”
   • “Staging”
   • “Testing”
   • “Development”
   • “Other”
6. In “Allowed to deploy” and “Approval rules”, select the subjects.
7. Click “Create protected environment”.

Subjects of a group rule are limited to the group hierarchy:

In the settings of a project, group rules are displayed in the “Inherited protected environments” table with a link to the owner group in the “Inherited from” column, and a “Deployment tier” badge next to the name. Such a rule cannot be changed or deleted in the project. Use the settings of the owner group.

To create a group rule via API, use /groups/:id/protected_environments with the same parameters as for a project rule. The name parameter must contain only a deployment tier; the API returns 400 for any other value.

Deployment permissions

The “Allowed to deploy” list determines who can run a deployment job for the environment. The list combines roles, individual users, and groups, and a user gets access if they match at least one entry.

Available options:

The “Group membership” selector accepts the following values:

If the “Allowed to deploy” list is empty, the table displays “No one”. In this case:

• Project members cannot run a deployment job for this environment, regardless of their role.
• Instance administrators can still deploy.
• An empty list of any applicable rule blocks deployment to the environment even if another applicable rule allows it.
• An empty list of a group rule overrides what the project rule permits.

An edit that would leave the list with no entries is rejected. However, the list can become empty if the listed users or groups lose access to the project, for example when a project member is removed or a group’s access is revoked.

A user without permission to deploy to a protected environment cannot perform the following actions on its deployment job:

• Run it.
• Cancel it.
• Retry it.
• Erase it.

Changes to a role or group membership are taken into account immediately when permissions are checked.

Approval rules

An approval rule specifies a subject and the required number of approvals. “Required approvals” accepts a value from 1 to 5. For a user subject the value is always 1, because one user records one decision per rule.

Subjects are selected the same way as in the “Allowed to deploy” list. A subject of an approval rule does not have to be able to deploy. A user who matches an approval rule can approve a deployment without permission to run its job.

A decision belongs to one rule, and the approvals of all rules are combined.

• A deployment is approved when the required number of approvals has been collected for every rule of every applicable protected environment.
• A user who matches several rules records a decision for each of them separately. If a project rule and a group rule specify the same subject, approvals for those rules are counted independently, so one person records a decision for each of them.
• An approval counts while its author still matches the rule it was recorded for. If the author loses the role or the group membership the rule names, the approval stops being counted, and the deployment waits for the remaining approvals.
• A rejection keeps standing after its author loses the rule.
• After the first rejection, the deployment counts as rejected, whichever approvals have already been given.

When the rules of a protected environment change, previously recorded decisions are preserved but are counted according to the new rules.

Managing a protected environment

Changing any setting of a protected environment, and stopping or deleting the environment, require the user to be listed in “Allowed to deploy”. The Maintainer role alone does not grant these actions. Instance administrators are not restricted.

The “Clean up environments” action stops stale environments except protected ones. Environments whose name is specified by a project rule, and environments whose tier is specified by an inherited group rule, stay running.

Approving a deployment

While a deployment waits for approvals, its job stays manual and cannot be run. The “Deployment approvals” section on the deployment page shows the progress of every applicable approval rule.

To open the deployment page, go to “Deployments” → “Environments”, open the environment, and select the required deployment in its history. If the deployment waits for approvals, its history shows the “Waiting” status and the “View deployment approvals” button, while the “Environments” list and the page header show the “Needs Approval” badge.

curl --request POST --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/deployments/<DEPLOYMENT_ID>/approval?status=approved"

Approving your own deployment

If a user’s job created the deployment and the user matches an approval rule, the user can reject the deployment but cannot approve it by default.

To allow this user to approve the deployment, go to “Settings” → “CI/CD” → “Protected environments”. In the “Approval options” section, select “Allow pipeline triggerer to approve deployments” and click “Save changes”. The setting applies to the entire project and is disabled by default.

The author of a deployment is the user of its job, and for a job without a user, the user of the deployment.

Deployment job behavior

Before a runner is assigned to a job that deploys to a protected environment, Deckhouse Code checks the permissions of the job user. If the job has no user, it checks the permissions of the pipeline user.

The result of the check determines what happens to the job.

• If the applicable rules contain approval rules, Deckhouse Code creates the deployment and switches the job to manual, whichever permissions the pipeline author has. The job cannot be run while approvals are pending or the deployment is rejected.
• Once every rule has collected its approvals, the job is not started automatically. A user runs it manually. The permission to run the job and the “Allowed to deploy” lists are checked for the user who starts it.
• If the applicable rules contain no approval rules and the user is not allowed to deploy, the job fails with the “protected environment failure” reason before the deployment is created and before a runner is assigned.
• A job that deploys to an unprotected environment runs as usual.

The checks are repeated before a runner is assigned. If approvals become required for the job at that point, it returns to the manual state and waits for them.

Rejected deployment

The first recorded rejection fails the deployment job with the “deployment rejected” reason, and the deployment moves to the failed state. A background job applies the state, so it changes with a short delay.

The retry keyword does not restart a rejected deployment job; only a user can retry it. The rejected deployment keeps this status until the job is retried. Retrying creates a new job and a new deployment, which collects approvals again without carrying over decisions from the previous deployment.

Access to protected environments

Available actions depend on the user’s role and the rules of the environment:

Except for auditors, membership is required even in a public project. A user who is neither a project member nor an auditor reads neither its protected environments nor the approval state of its deployments.

Protected environment export and import

A project export contains the protected environments of the project with their “Allowed to deploy” entries and approval rules. Recorded approval decisions are not exported because they belong to a specific deployment, while the export carries only the project configuration.

To find subjects on the target instance, the export stores:

• The full path of the subject group
• The full path of the group that owns the project
• The username of the subject user

On import, a group subject is looked up by its full path, keeping the path relative to the target group, while a user subject is looked up first among the imported members and then by username.

If a subject cannot be matched, or the deprecated required_approval_count field of the export carries any value other than 0, the whole project import is refused. An import that dropped a subject would produce weaker protection than the source configuration.

Audit events

Deckhouse Code records the following audit events for protected environments:

A configuration change event belongs to the project or group that owns the rule and also contains information about the protected environment and the subject of the entry. For an updated entry, the values before and after the change are also recorded.

Changing a recorded decision creates a new event, while repeating the same decision does not.

Removing a member from the project, and revoking the access of a group to the project, delete the deploy access entries and approval rules of that subject without an event of their own. The removal itself is already recorded.

Troubleshooting

Most troubleshooting cases come down to which rules apply to the environment: the project rule for its name and the group rules for its tier.

Deployment job failed with the protected environment failure reason

The user of the job is not listed in the “Allowed to deploy” list of one of the applicable rules, or the account of this user has been deleted. Check the following:

• The user must match at least one entry in each “Allowed to deploy” list of the project rule for this environment name and of the group rules for its tier.
• The “Allowed to deploy” lists are not empty. An empty list denies deployment to everyone.
• The role of the user in the project is not lower than the role selected in the list.

Deployment job cannot be run

If the environment has approval rules, the job stays manual until every rule collects its approvals. Open the deployment page and check the state of the rules in the “Deployment approvals” section.

The job is also unavailable to a user who is not listed in the “Allowed to deploy” list, even after the deployment is approved.

Environment cannot be edited, stopped, or deleted

Changing any setting of a protected environment, and stopping or deleting it, are available to the users listed in “Allowed to deploy”. Add the user to that list in the rule for this environment name, and in the group rules for its tier.

Approval form is not displayed

Check the following:

• The deployment waits for approvals. Its job is manual, and the summary state is not “All required approvals have been given” or a rejection.
• Your account matches an approval rule of this environment, or you have already recorded a decision for one of its rules.
• The deployment was not created by your own job, or “Allow pipeline triggerer to approve deployments” is enabled in the project. The author of a deployment can reject it without this setting.

Subject cannot be added to a rule

The message “This subject already has a rule for this protected environment” means the role, user, or group is already present in the list you are editing. One subject holds one entry in “Allowed to deploy” and one entry in “Approval rules”. Change the existing entry instead of adding a second one.

How rule changes affect existing decisions

The state of a deployment is computed from the current rules.

If the author of an approval stopped matching the rule the approval was recorded for, the approval stops being counted, and the deployment waits for the remaining approvals. The decision itself is kept and is counted again once the author matches the rule again.

If an approval rule is removed, decisions recorded for it are no longer counted. Adding the same subject again creates a new rule for which approvals are collected from the beginning.

A rejection keeps standing in either case.

Rule of a group is not applied to an environment

Check that the tier of the environment matches the name of the group rule, and that the project belongs to the group that owns the rule or to one of its subgroups. The tier is set by the deployment_tier keyword in the CI/CD configuration file and otherwise derived from the environment name.

Project rule does not apply to an environment with a similar name

The environment name must exactly match the project rule name, including case. Therefore, a rule named Production does not protect the production environment, and a rule named production does not protect production/eu. To protect several environments at once, use a group rule for the corresponding deployment tier.

Inherited rule cannot be changed in a project

Rules displayed in the “Inherited protected environments” table belong to a group. Open the group from the “Inherited from” column and change the rule in its settings.

Additional resources

• Delivery (CI/CD)
• Protected branches