Deploy ephemeral Environments

Set up ephemeral environments using Score with the Humanitec Platform Orchestrator.

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 # The port that the service will be exposed on
      targetPort: 3000 # The port that the container will be listening on

# Define the containers that make up this service
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}

# Define the resources that this service needs
resources:
  dns: # We need a DNS record to point to the service 
    type: dns
  route: # We need a route attach to the DNS record 
    type: route
    params:
      host: ${resources.dns.host}
      path: /
      port: 80
  db:  # We need a database to store data
    type: postgres

View the sample code here in our repo.

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
  HUMCTL_VERSION: '0.23.0'                          # humctl CLI 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 the Humanitec CLI

Install the humctl CLI binary into your pipeline runner using the setup-cli-action GitHub action.

For a universal download approach outside of GitHub, refer to the humctl CLI installation instructions.

- uses: humanitec/setup-cli-action@v1
  with:
    version: ${{ env.HUMCTL_VERSION }}

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: |
      humctl create environment ${{ env.ENVIRONMENT_ID }} \
        --token ${{ secrets.HUMANITEC_TOKEN }} \
        --org ${{ vars.HUMANITEC_ORG }} \
        --app ${{ vars.APP_NAME }} \
        --name ${{ env.ENVIRONMENT_NAME }} \
        -t ${{ env.ENVIRONMENT_TYPE }} \
        --from ${{ env.BASE_ENVIRONMENT }} \
        || true

Trigger Deployment with the humctl CLI

Lastly, configure the pipeline to execute the humctl CLI, which initiates the deployment:

- name: Run Score
  run: |
    humctl score deploy \
        --token ${{ secrets.HUMANITEC_TOKEN }} \
        --org ${{ vars.HUMANITEC_ORG }} \
        --app ${{ vars.APP_NAME }} \
        --env ${{ env.ENVIRONMENT_ID }} \
        | tee score_output.json

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:

  1. Running the pipeline.
  2. Pushing the updated Score file to the Orchestrator.
  3. 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:

  1. 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.
  2. 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: Pull Request
on:
  pull_request:
    types:
      - closed
env:
  HUMCTL_VERSION: '0.23.0'
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: humanitec/setup-cli-action@v1
        with:
          version: ${{ env.HUMCTL_VERSION }}
      - name: Delete Humanitec Env
        run: |
          humctl delete env pr-${{ github.event.number }} \
              --token ${{ secrets.HUMANITEC_TOKEN }} \
              --org ${{ vars.HUMANITEC_ORG }} \
              --app ${{ vars.APP_NAME }}

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.

Perform daily developer activities (debug, rollback, diffs, logs)