Tutorial: Deploy ephemeral Environments
Set up ephemeral environments using Score with the Humanitec Platform Orchestrator.
- Introduction
- Prerequisites
- Describe your Workload using Score
- Configure pipelines
- Set environment variables
- Install Score-humanitec
- Create new Environment
- Trigger Deployment with the score-humanitec CLI
- Using ephemeral Environments
- Create a pull request
- Improve observability
- Delete Environments after use
- Recap
- Next steps
On this page
- Introduction
- Prerequisites
- Describe your Workload using Score
- Configure pipelines
- Set environment variables
- Install Score-humanitec
- Create new Environment
- Trigger Deployment with the score-humanitec CLI
- Using ephemeral Environments
- Create a pull request
- Improve observability
- Delete Environments after use
- Recap
- Next steps
Introduction
At its core, an ephemeral environment is a temporary, on-the-fly instance of an application. It’s built to mirror production settings but exists solely for the duration of a specific task, such as testing a feature or bug fix. Once the task is done, the environment is torn down.
The following tutorial will take you through each step needed to set up ephemeral environments using Score with the Humanitec Platform Orchestrator. You will learn how to:
- Configure repositories for ephemeral Environments
- Describe your Workload using Score
- Configure pipelines with variables and secrets
- Create a new Environment
- Trigger automated Deployments with Score
- Clean up Environments after use
A reference implementation can be found in this GitHub repository.
While this tutorial outlines the steps to set up ephemeral environments using GitHub Actions, the same can be achieved using any CI/CD tool. To leverage GitHub Actions for spinning up ephemeral environments, follow the steps below.
Prerequisites
- A Humanitec Organization. If you do not have one, sign up here for a free trial.
- A Humanitec API Token for your Organization.
- Git installed locally.
- A CI/CD system providing a Git repository you can commit to and a pipeline runner mechanism.
- GitHub is one such option, but other systems will work as well.
Describe your Workload using Score
Describe your service and its resources using Score. This is done by creating a score.yaml
file in the root directory of your repository.
apiVersion: score.dev/v1b1
metadata:
name: hello-world
# Define the ports that this service exposes
service:
ports:
www:
port: 80 # Exposed service port
targetPort: 3000 # Port the container listens on
# Define the service's containers
containers:
frontend:
image: registry.humanitec.io/public/sample-score-app:latest
variables:
MESSAGE: "Hello World"
PORT: "3000"
DB_DATABASE: ${resources.db.name}
DB_USER: ${resources.db.username}
DB_PASSWORD: ${resources.db.password}
DB_HOST: ${resources.db.host}
DB_PORT: ${resources.db.port}
# Specify required resources
resources:
dns: # DNS record for the service
type: dns
db: # Database for data storage
type: postgres
View the sample code here in our repo.
resources
of type dns
and postgres
will by default be provided by the Platform Orchestrator using its Default Resource Definitions for those types. You do not need to provide your own cloud environment to provision those Resources into.Configure pipelines
Create a new pipeline in GitHub Actions and set it to activate when a new pull request event occurs.
View the sample code here in our repo.
The configuration for this trigger is:
on:
pull_request:
types: [opened, reopened, synchronize]
Set environment variables
These variables are required for configuring the new Environment to be created in the Platform Orchestrator:
env:
BASE_ENVIRONMENT: 'development' # Base environment reference
ENVIRONMENT_TYPE: 'development' # Environment type
SCORE_HUMANITEC_VERSION: 0.8.0 # Score version
ENVIRONMENT_ID: pr-${{ github.event.number }} # New environment ID
ENVIRONMENT_NAME: PR-${{ github.event.number }} # New environment name
The pipeline run will also need this data to perform the calls into the Platform Orchestrator. If you are on GitHub, use variables and secrets to provide them across workflows and runs:
HUMANITEC_TOKEN # An API token for your Humanitec Organization
HUMANITEC_ORG # The ID of your Humanitec Organization. Must be all lowercase.
APP_NAME # The ID of your Humanitec Application.
Install Score-humanitec
Install the score-humanitec
binary into your pipeline runner:
- name: Install score-humanitec
run: |
wget https://github.com/score-spec/score-humanitec/releases/download/${{ env.SCORE_HUMANITEC_VERSION }}/score-humanitec_${{ env.SCORE_HUMANITEC_VERSION }}_linux_amd64.tar.gz
tar -xvf score-humanitec_${{ env.SCORE_HUMANITEC_VERSION }}_linux_amd64.tar.gz
chmod +x score-humanitec
mv score-humanitec /usr/local/bin
Create new Environment
Within the pipeline, make a call to the Humanitec Platform Orchestrator API to create a new environment:
- name: Create Humanitec Env
run: |
# Get deployment ID of the main development environment
curl \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer ${{ secrets.HUMANITEC_TOKEN }}' \
https://api.humanitec.io/orgs/${{ vars.HUMANITEC_ORG }}/apps/${{ vars.APP_NAME }}/envs/${{ env.BASE_ENVIRONMENT }} \
| jq -r ".last_deploy.id" > deploy_id.txt
# Create a new environment for the PR
curl -X POST \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer ${{ secrets.HUMANITEC_TOKEN }}' \
https://api.humanitec.io/orgs/${{ vars.HUMANITEC_ORG }}/apps/${{ vars.APP_NAME }}/envs \
--data-binary @- << EOF
{
"from_deploy_id": "$(cat deploy_id.txt)",
"id": "${{ env.ENVIRONMENT_ID }}",
"name": "${{ env.ENVIRONMENT_NAME }}",
"type": "${{ env.ENVIRONMENT_TYPE }}"
}
EOF
Trigger Deployment with the score-humanitec CLI
Lastly, configure the pipeline to execute the score-humanitec
CLI, which initiates the deployment:
- name: Run Score
run: |
score-humanitec delta \
--retry \
--deploy \
--token ${{ secrets.HUMANITEC_TOKEN }} \
--org ${{ vars.HUMANITEC_ORG }} \
--app ${{ vars.APP_NAME }} \
--env ${{ env.ENVIRONMENT_ID }}
Using ephemeral Environments
Once the initial setup is complete, developers can seamlessly integrate ephemeral environments into their daily workflows. This integration simplifies the review and testing process significantly.
Create a pull request
Creating a pull request triggers the pipeline, which then creates a new ephemeral environment. For example, let’s change the environment variable to “Hello Team!” in the score.yaml
file:
containers:
frontend:
image: registry.humanitec.io/public/sample-score-app:latest
variables:
MESSAGE: "Hello Team!"
Upon making this modification and submitting the pull request, the configured pipeline gets triggered. This process involves:
- Running the pipeline.
- Pushing the updated Score file to the Orchestrator.
- The Orchestrator then interprets the changes, formulates the necessary Application and infrastructure configurations, and subsequently establishes the new Environment.
Improve observability
Once the deployment is finalized, our pipeline is designed to append a comment on the pull request. This comment furnishes pertinent details about the newly created environment, ensuring developers have all the necessary information at their fingertips. See the pipeline code for details.
Delete Environments after use
To prevent incurring unnecessary costs, it’s advisable to automate the teardown of these Environments post their utility.
Implementation Steps:
- Pipeline Trigger on PR Closure
- Configure your pipeline to be invoked when a pull request concludes. This ensures the associated ephemeral environment is targeted for teardown.
- Request Deletion through the Humanitec Platform Orchestrator.
- Within the pipeline, send a DELETE request to the Platform Orchestrator API, instructing it to dismantle the Environment associated with the closed PR.
name: Close Pull Request
on:
pull_request:
types:
- closed
jobs:
cleanup:
runs-on: ubuntu-latest
steps:
- name: Delete Humanitec Env
run: |
curl -X DELETE \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer ${{ secrets.HUMANITEC_TOKEN }}' \
https://api.humanitec.io/orgs/${{ vars.HUMANITEC_ORG }}/apps/${{ vars.APP_NAME }}/envs/pr-${{ github.event.number }}
View the sample code here in our repo.
Recap
Congrats! You successfully completed the tutorial and learned how to set up ephemeral environments. You learned how to:
- Configure repositories for ephemeral Environments
- Describe your Workload using Score
- Configure pipelines with variables and secrets
- Create a new Environment
- Trigger automated Deployments with Score
- Clean up Environments after use
Next steps
See our documentation on Dynamic Previews for more information on setting up preview Environments.