Manage Environments

A Permit environment is a silo (a logical grouping) of your policy (roles, conditions, etc.) and data (users, tenants, role assignments, etc.). You can create multiple environments for each of your projects. For example, you can create a production environment for your production deployment and a staging environment for your staging deployment. Environments can be used for CI/D flows, testing, and more.

Create new environment

Remember

Make sure you use an organization level api-key or project level api-key to create a new environment.

First of all we need to get our API_SECRET_KEY from the dashboard and get current project_id

• Follow this link to get your organization or project API_SECRET_KEY.
  
• To get your project_id.

Replace API_SECRET_KEY with your API_SECRET_KEY and project_id with your project_id in the following command.

curl 'https://api.permit.io/v2/projects/{project_id}/envs' \
  -H 'authorization: Bearer API_SECRET_KEY'\
  --data-raw '{"key":"new-env-name","name":"New Env Name"}'

The return environment object will look like this:

{
  "key": "new-env-key",
  "id": "f77b6ee3149e4b90ba3263ecd092xxxx",
  "organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
  "project_id": "3c4244c7bcab4c97990e5bc724dafe85",
  "created_at": "2023-07-30T15:56:21+00:00",
  "updated_at": "2023-07-30T15:56:21+00:00",
  "name": "New Env Name",
  "description": null,
  "custom_branch_name": null,
  "jwks": null,
  "settings": null
}

Copy Environment ( EAP )

The copy environment endpoint allows you to copy an existing environment to a new environment or an existing environment.
It allows you to copy the entire environment or a subset of the policy in a specific environment.
You can also exclude or include specific objects from the copy, it also supports * so you can exclude all the roles that starts with test*

You can either duplicates an existing environment to a new environment in the same project, or copies from an existing environment to another existing environment.

Copying environments across projects or organizations is not allowed.

Remember

Make sure you use an organization level api-key or project level api-key to copy an environment.

Supported objects

Copy Environment currently copies the following objects:

• Resource
  • Resource Actions
    • Resource Action Groups
  • Resource Attributes
  • Resource Roles
  • Resource Relations
• Roles
  • Role Permissions
  • Role Derivations
  • Role Hierarchy
• Condition Sets
  • User Sets
  • Resource Sets
  • Condition Sets Rules
  • Condition Sets Inheritance

Copy to a new environment

In this example I'm coping an environment called production environment to a new environment called staging.
And I'm excluding all the roles, resources, user_sets and resource_sets that starts with test*.

Example

First of all we need to get our API_SECRET_KEY from the dashboard and get current project_id and env_id

• Follow this link to get your organization or project API_SECRET_KEY.
  
• To get your project_id.

Replace API_SECRET_KEY with your API_SECRET_KEY and project_id with your project_id and env_id with your env_id in the following command.

#curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy' \
curl --location 'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}/copy' \
  -H 'authorization: Bearer API_SECRET_KEY'\
  --data '{
  "target_env": {
    "new": {
        "key": "prod",
        "name": "production"
    }
  },
  "scope": {
      "roles": {
          "exclude": ["test*"]
      },
      "resources": {
          "exclude": ["test*"]
      },
      "resource_sets": {
          "exclude": ["test*"]
      },
      "user_sets": {
          "exclude": ["test*"]
      }
  }
}'

You should get 201 response with the new environment object

Copy to an existing environment

In this example I'm coping an environment called production environment to an existing environment called staging.
And I'm overwriting any existing objects in the target environment. (conflict_strategy: overwrite)
I can also use the fail strategy to fail the copy if there is any conflict in the target environment.

Overwrite strategy

When using the overwrite strategy, the copy will overwrite any editable field in the existing objects in the target environment. We do not delete any high-level objects that exist in the target environment but do not exist in the source environment, such as roles, resources, and condition sets.

Remember

This feature is in EAP stage, which means it's in early access and might have some limitations. We recommend you to test it in a non-production environment before using it in production.

Example

First of all we need to get our API_SECRET_KEY from the dashboard and get current project_id and env_id

• Follow this link to get your organization or project API_SECRET_KEY.
  
• To get your project_id.

Replace API_SECRET_KEY with your API_SECRET_KEY and project_id with your project_id and env_id with your env_id in the following command.

#curl --location 'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}/copy' \
curl --location 'https://api.permit.io/v2/projects/default/envs/production/copy' \
  -H 'authorization: Bearer API_SECRET_KEY'\
  --data '{
  "target_env": {
    "existing": "staging"
  },
  "conflict_strategy": "overwrite",
}'

You should get 201 response with the new environment object

Copy Environment in a GitOps Project

When using GitOps and copying an environment to a new target environment, the target environment will also include the custom policies under custom directory.

If you are using GitOps and copying an environment to an existing target environment, the custom policies under custom directory will be copied only if the conflict strategy is overwrite.
If you have GitOps configured on your Project and you didn't set the strategy as overwrite it will ignore any custom policies in the source environment. You can modify the custom policies to copy with custom_policies key in the request "scope" object. For example:

{
   "target_env":{
      "existing":"production"
   },
   "conflict_strategy":"overwrite",
   "scope":{
      "custom_policies":{
         "include":[
            "tmp_policy.rego",
            "my_policy*"
         ],
         "exclude":[
            "ignored*"
         ]
      }
   }
}

Customize GitOps Branch Name

When setting up a Custom Branch name in your GitOps repository for an environment.
Permit will use the branch name to sync the environment policy with the repository.
Notice that the Policy Repo should be activated on the project for it to work properly, you can activate the Policy Repo by following the following guide.

Example

Create a new environment with a custom branch name.

curl 'https://api.permit.io/v2/projects/{project_id}/envs' \
  -H 'authorization: Bearer {API_SECRET_KEY}'\
  --data-raw '{"key":"new-env-name","name":"New Env Name", "custom_branch_name": "new-env-branch-name"}'

The response should look like this:

{
  "key": "new-env-name",
  "id": "f77b6ee3149e4b90ba3263ecd092xxxx",
  "organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
  "project_id": "3c4244c7bcab4c97990e5bc724dafe85",
  "created_at": "2023-07-30T15:56:21+00:00",
  "updated_at": "2023-07-30T15:56:21+00:00",
  "name": "New Env Name",
  "description": null,
  "custom_branch_name": "new-env-branch-name",
  "jwks": null,
  "settings": null
}

Or update an existing environment with a custom branch name.

curl 'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}' -X 'PATCH' \
  -H 'authorization: Bearer {API_SECRET_KEY}'\
  --data-raw '{"custom_branch_name": "new-env-branch-name"}'

The response should look like this:

{
  "key": "new-env-name",
  "id": "f77b6ee3149e4b90ba3263ecd092xxxx",
  "organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
  "project_id": "3c4244c7bcab4c97990e5bc724dafe85",
  "created_at": "2023-07-30T15:56:21+00:00",
  "updated_at": "2023-07-30T15:56:21+00:00",
  "name": "New Env Name",
  "description": null,
  "custom_branch_name": "new-env-branch-name",
  "jwks": null,
  "settings": null
}