Environments

Users with Owner or Developer Roles can create new or change existing Environments on their own without support.

The Platform Orchestrator allows developers to easily create, manage, and delete Environments. Developers can specify the configuration and resources needed for each Environment, such as the type and size of compute instances, the amount of storage, and the type of database.

An Environment is a space where an instance of an Application can be deployed. Environments consist of a Kubernetes namespace and any shared Resources (as configured by relevant Matching Rules).

An Application can serve many Environments.

Use Environment Types

The Platform Orchestrator has a concept of Environment Types. These allow Environments to be specialized for different purposes. Typical types of Environment are development, staging, pre-production, and production. You can define Environment Types to group and manage Environment for your team. Every Environment in the Platform Orchestrator has exactly one Environment Type.

Environment Types can be used with Resources Definitions to manage where resources such as databases are provisioned or even which Kubernetes cluster to deploy to.

For information on Environment Types constraints, see Constraints. For information on using ephemeral Environments with your pipeline, see Deploy ephemeral Environments

Example

Let’s look at a simple example of how Environment Types can be used when building an Internal Developer Platform. It is common to use different infrastructure for development vs. production environment. Let’s assume a team wants to use the infrastructure listed below in their day-to-day work.

Infrastructure Development Production
Kubernetes Cluster EKS cluster with namespace separation Dedicated AKS cluster
DNS Dynamically generated URLs Static URL
Databases Dynamically generated RDS databases Static self-managed databases
File Storage Dynamically generated S3 buckets Static Azure File Storage

The easiest way to achieve this setup in Humanitec is to use two different Environment Types (for example, development and production) to define the infrastructure that should be used/provisioned depending on the type of environment. The following sections explain how to achieve this step by step.

Manage Environments

Each new Application in Humanitec is created with a default Environment called Development. You can add as many other Environments to the App as you need.

Default Environment cannot be deleted without deleting the entire App. This section explains how to create a new Environment based on an existing Environment.

Create an Environment

The Platform Orchestrator treats creating a new Environment as creating a copy of an existing Deployment in an existing Environment.

  1. From the Applications overview, select the name of the Application you’d like to create an environment with.
  2. In the Environments section, select the + Create new environment button.
  3. Enter the following details and choose Create to create a new environment.
    1. From the Clone from dropdown, choose an Environment name.
    2. From the Environment type dropdown, choose an Environment type.
    3. Enter an Environment’s name.

Use the humctl create command to create an Application in the current context.

humctl create env $ENV_ID --type=${ENV_TYPE} --name="${ENV_NAME}" --from=${FROM_ENV_ID}

Where the following environment variables are set:

Variable Example Description
ENV_ID my-env The ID of the Environment. Must be lower case letters, numbers or dashes. Cannot start or end with a dash.
ENV_TYPE test The *Environment Type that the environment should have.
ENV_NAME My Env A Human friendly name for the Environment. Can contain any characters.
FROM_ENV_ID development The ID of the Environment that the new Environment should be created from. 

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${APP_ID}/envs" \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "'${ENV_ID}'",
  "name": "'${ENV_NAME}'",
  "type": "'${ENV_TYPE}'",
  "from_deploy_id": "'${FROM_DEPLOY_ID}'"
}'

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with at least Manager role on the Organization.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the Application.
ENV_ID my-env The ID of the Environment.
ENV_NAME My Env A Human friendly name for the Environment. Can contain any characters.
ENV_TYPE test The Environment Type that the environment should have.
FROM_DEPLOY_ID 175d7af0d89 The ID of the deployment that the Environment should be based on.

Not yet supported by the Terraform Provider.

Delete an Environment

Delete an Environment to remove it from the Application.

  1. From the Applications overview, select the name of the Application and the Environment you’d like to delete.
  2. In the Delete environment section, select Delete environment.
  3. Select Delete to confirm.

Use the humctl delete command to delete an Application.

humctl delete env ID

Where the following environment variables are set:

Variable Example Description
ENV_ID my-env The ID of the Environment to delete. 

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${APP_ID}/envs/${ENV_ID}" \
  -X DELETE \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with at least Owner role on the Application.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the Application the Environment is in.
ENV_ID my-env The ID of the Environment to delete.

Not yet supported by the Terraform Provider.

Pause an Environment

Pause an Environment to scale down Kubernetes Deployment down to 0 replicas.

  1. From the Applications overview, select the name of the Application and the Environment that you’d like to pause.
  2. Select Pause environment and then click Pause environment to confirm.

There is no specific command to pause an Environment in the CLI, but the api command can be used to perform the same action.

humctl api put "/orgs/${HUMANITEC_ORG}/apps/${APP_ID}/envs/${ENV_ID}/runtime/paused" -d 'true'

Where the following environment variables are set:

Variable Example Description
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the Application.
ENV_ID my-env The ID of the Environment to pause. 

curl "/orgs/${HUMANITEC_ORG}/apps/${APP_ID}/envs/${ENV_ID}/runtime/paused" \
  -X PUT \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d 'true'

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with at least Deployer role on the Environment Type and Developer role on the Application.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the Application.
ENV_ID my-env The ID of the Environment to pause.

This action cannot be performed via Terraform as it involves updating ephemeral state.

When an Environment is paused, you can’t:

  • Deploy the environment within Humanitec.
  • Scale the number of replicas running of any workload.

Resume an Environment

On resume requests, all the Kubernetes Deployment resources are scaled up to the number of replicas running before the environment was paused.

  1. From the Applications overview, select the name of the Application and the Environment that you’d to resume.
  2. Choose Resume environment.

There is no specific command to pause an Environment in the CLI, but the api command can be used to perform the same action.

humctl api put "/orgs/${HUMANITEC_ORG}/apps/${APP_ID}/envs/${ENV_ID}/runtime/paused" -d 'false'

Where the following environment variables are set:

Variable Example Description
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the Application.
ENV_ID my-env The ID of the Environment to pause. 

curl "/orgs/${HUMANITEC_ORG}/apps/${APP_ID}/envs/${ENV_ID}/runtime/paused" \
  -X PUT \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d 'false'

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with at least Deployer role on the Environment Type and Developer role on the Application.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the Application.
ENV_ID my-env The ID of the Environment to pause.

This action cannot be performed via Terraform as it involves updating ephemeral state.

Schedule an Environment to Pause or Resume

The following example shows how to schedule an Environment to pause and resume using a Cron Job.

  1. Add a new Workload to your Application.
  2. In a draft, select + Create new workload and enter the name of the Workload.
    1. Choose default-cronjob as the profile.
  3. Open that workload, select + Add container and choose an image.
    1. Enter curlimages/curl:8.1.1 as the image name.
    2. Select Add image.
    3. Enter a name for the container.
  4. Select + Add cronjob schedule.
    1. Enter a name for the Cron Job.
    2. Select the time for the Cron Job.
    3. Select Save changes.
  5. Define the Container overrides.
    1. Provide alternative commands and arguments to run when this container starts up.
  6. Select Save changes and deploy your Workload.

  1. Add a new workload to your Application and choose the profile default-cronjob instead of default-module
  2. Add a container to the Workload and choose Add by image name.
    1. Enter curlimages/curl:8.1.1
  3. Set your Environment variables to the container.
  4. Add a Cron Job to Schedule the pausing of an Environment to the Workload.
  5. Define the time for the Cron Job.
  6. Define Container overrides
curl "/orgs/$(HUMANITEC_ORG)/apps/$(APP_ID)/envs/$(ENV_ID)/runtime/paused" \
 -X PUT \
 -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
 -H "Content-Type: application/json" \
 -d 'true'

Use true to pause the Environment and false to resume it.

Set Environment variables

In Humanitec, Environment Variables can be defined at different levels. This allows developers to manage and organize their environment variables and secrets in a more flexible and scalable way.

  • Application level: Available to all Workloads in the Application, regardless of which Environment they are running in. This can be useful for defining variables and secrets that are shared across all Workloads in the Application, such as database credentials or API keys.

  • Environment level: Available to Workloads running in that specific Environment. This can be useful for defining variables and secrets that are specific to a particular Environment, such as test or production environments.

  • Workload level: Available to a specific Workload, regardless of which Environment it is running in. This can be useful for defining variables and secrets that are specific to a particular Workload, such as configuration settings or resource requirements.

The hierarchical nature of Environment Variables allows developers to manage and organize their variables and secrets in a flexible and scalable way.

Clone Environments

The Platform Orchestrator makes it easy to promote or clone individual Workloads or entire Applications between Environments. This involves updating the target Environment with all environment agnostic configuration from the source Environment.

  • Promote implies moving up the Environment release train: for example, from a development, to test to UAT to production.
  • Clone is used to describe the general updating of Environments with Workload configuration from other Environments.

By cloning a deployment, you can create a separate Environment where you can test and make changes without affecting the original production environment.

Clone a deployment to an existing Environment

  1. From the Applications overview, select the name of the Application you’d like to clone.
  2. Under the Active deployment or Past deployments section, choose a Workload you’d like to clone.
  3. Select Clone to.. and choose the Environment you’d like to clone the deployment to.
  4. Select the Workloads you’d like to include and select Clone n workloads Where n is the number of Workloads chosen.

To deploy the draft, select Review & Deploy and then Deploy.

This involves constructing a Delta including all the workloads to be included in the new environment under the add operation.

This involves constructing a Delta including all the workloads to be included in the new environment under the add operation.

This is not possible in Terraform.

Clone an Environment from a deployment

When cloning an Environment from a deployment, select all or some Workloads.

  1. From the Applications overview, select the name of the Application you’d like to clone.
  2. In the Environments section, select the + Create new environment.
  3. Choose from the following options and then select Create.
    1. Select where you’d like to clone from.
    2. Select the Environment type.
    3. Enter an Environment name.

CLI instructions coming soon.

API instructions coming soon.

Terraform instructions coming soon.

Deployments

Set and Deltas