Tutorial: 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           # 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.

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:

  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: 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.

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

Theory on platform engineering workflows