Environments

Environments are a sub-partitioning of projects. They are usually isolated instantiations of the same project representing a stage in its development lifecycle, e.g. from “development” through to “production”. Environments receive deployments.

An environment is of exactly one environment type.

An environment has a runner linked to it at any time so it is ready to receive deployments. The runner maintains the Terraform/OpenTofu state for the environment.

An environment with a succesful deployment contains a resource graph that is visualized in the Orchestrator console.

Basic example

resource.tf (view on GitHub ) :

resource "platform-orchestrator_environment" "example" {
  id           = "my-environment"
  project_id   = "my-project"
  env_type_id  = "development"
  display_name = "My Development Environment"
}



hctl create environment my-project my-environment [email protected]

where environment-config.yaml is:

env_type_id: development
display_name: Development Environment

Note: the parent project id and the environment id are part of the CLI command, e.g. humctl create environment my-project my-environment, and therefore not shown as part of the configuration.

Configuration

An environment configuration consists of these elements:

Refer to the resource schema in the Terraform  or OpenTofu  provider documentation.

# The id of the existing environment type for this environment
env_type_id: development
# Optional human friendly display name for the project
display_name: Development Environment

Lifecycle

On first deployment, the environment will be linked to a runner based on the existing runner rules. If the rules cannot match any runner, the deployment will fail. Find more details on runners and environments below.

The environment type of an environment cannot be changed.

See destroying environments for more details and options around environment deletion.

Projects and environments

A project is a container for zero or more environments, each of which is of one specific environment type.

Projects & Environments

Runners and environments

Each environment must have exactly one runner linked to it as a result of the runner rules in order to perform a deployment into that environment.

The runner creates the link to the Terraform/OpenTofu state for that environment through its state storage configuration.

Orchestrator runners and configs

The environment remains linked to a runner even when the runner rules change until the refresh_runner API is called on the environment. This is because changing a runner may lead to dropping access to the previously used Terraform/OpenTofu state and thus a potentially undesired destruction of resources.

Refresh the runner for an environment

An environment remains linked to a runner even when the runner rules change. Execute the refresh_runner command on the environment to re-assign a runner based on the current runner rules.

Use the dry_run flag to test the result of the command without applying any change.

curl https://api.humanitec.dev/orgs/my-org/projects/my-project/envs/my-environment/actions/refresh_runner \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '
{
  "dry_run": false
}'

If a runner could be identified for the environment, the command will return that runner’s id.

If no runner could be identified, the command will return an error and the environment will remain associated with the previous runner.

Available resource types

You may query the resource types which are effectively available for deployments into a project environment using the CLI:

hctl get available-resource-types my-project my-environment

The list shows the resource types of any modules which can be matched to that environment via module rules.

The command only shows resource types with the is_developer_accessible property set to true, i.e. resource types which are available for use in manifests.

Promoting deployments between environments

You can promote deployments between environments within the same project. This is usually done to perform the rollout of updates to a project’s resources into the next stage. Promoting a deployment in this way does require access to the manifest that was used to deploy into an upstream environment.

Use this command to promote a deployment:

# Promote the last deployment in the "staging" environment into the "production" environment
# in the project "my-project"
hctl deploy my-project production environment://staging

Projects

Environment types