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 Environments 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
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 the 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.
- From the Application overview, select the name of the Application you’d like to create an environment with.
- In the Environments section, select the
+
button. - Enter the following details and choose Create to create a new environment.
- From the Clone from dropdown, choose an Environment name.
- From the Environment type dropdown, choose an Environment type.
- 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. |
<div class="w-100"> More help can be found via <code>humctl help create env</code>.</div>
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.
- From the Application overview, select the name of the Application you’d like to delete an environment from.
- In the Environments section, select
...
and choose Delete.
Instructions coming soon.
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. |
humctl help create app
.
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.
- From the Application overview, select the name of the Application you’d like an environment to pause for.
- In the Environments section, select
...
. - Choose Pause environment and then chose Pause 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 '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.
- From the Application overview, select the name of the Application you’d like an environment to resume for.
- In the Environments section, select
...
. - 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.
- Create a new Workload to your Application.
- Select + Create workload and enter the name of the Workload.
- Choose
default-cronjob
as the profile.
- Choose
- Select + Add container and add a image.
- Enter
curlimages/curl:8.1.1
as the image name. - Select Add image.
- Enter a name for the container.
- Enter
- Select + Add cronjob schedule.
- Enter a name for the Cron Job.
- Select the time for the Cron Job.
- Select Save changes.
- Define the Container overrides.
- Provide alternative commands and arguments to run when this container starts up.
- Select Save changes and deploy your Workload.
- Add a new workload to your Application and choose the profile
default-cronjob
instead ofdefault-module
- Add a container to the Workload and choose
Add by image name
.- Enter
curlimages/curl:8.1.1
- Enter
- Set your Environment variables to the container.
- Add a Cron Job to Schedule the pausing of an Environment to the Workload.
- Define the time for the Cron Job.
- 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.
Cloning between 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.
Clone a deployment to an existing Environment
- From the Application overview, select the name of the Application you’d like to clone.
- Under the Active deployment or Past deployments section, choose a Workload you’d like to clone.
- Select the … button, and select Clone deployment to and choose an Environment.
- Select or filter by Workloads and then select Choose
n
workloads. Wheren
is the number of Workloads chosen.
This involves constructing a Delta including all of the workloads to be included in the new environment under the add
operation.
This involves constructing a Delta including all of the workloads to be included in the new environment under the add
operation.
This is not possible in Terraform.
Humanitec does not automatically trigger a Deployment of the clone in the target Environment. Select Deploy to deploy the clone.
Ensure you deploy the clone before deleting the source Environment; otherwise, drafts containing these clones will be deleted.
Clone an Environment from a deployment
When cloning an Environment from a deployment, select all or some Workloads.
- From the Application overview, select the name of the Application you’d like to clone.
- In the Environments section, select the
+
button. - Choose from the following options and then select Create.
- Select where you’d like to clone from.
- Select the Environment type.
- Enter an Environment name.
CLI instructions coming soon.
CLI instructions coming soon.
Terraform instructions coming soon.