Introduction
In this tutorial, you will learn how to effectively enable dynamic preview environments on top of Kubernetes. In contrast to static environments, dynamic environments won’t block your deployment pipeline. They allow parallel processing and testing, are created as clean new environments without any legacy artifacts, dependencies or quirks, and thereby ensure faster and more reliable test automation. This is why dynamic environments are a must for every modern engineering organization.
Overview
In this tutorial, you will learn how to effectively enable dynamic preview environments on top of Kubernetes. In contrast to static environments, dynamic environments won’t block your deployment pipeline. They allow parallel processing and testing, are created as clean new environments without any legacy artifacts, dependencies or quirks, and thereby ensure faster and more reliable test automation. This is why dynamic environments are a must for every modern engineering organization.Overview
In this tutorial we will show you:
- Step 1: How to create a preview environment automatically when a new PR is opened
- Step 2: How to access the preview environment via a PR
- Step 3: How to keep the preview environment up-to-date with a PR
- Step 4: How to destroy the preview environment when a PR is closed
A preview environment is an ephemeral environment created with the code of your pull requests. It provides a realistic environment to see your changes live before merging to master. A link to the preview environment is added to the Pull Request (PR), so everyone in your team can see your changes live with just one click. Preview environments are great to test out code changes in a real life setup, without the code reviewer having to set everything up on their own machine.
For this particular example, we’ll use GitHub Actions and Humanitec to create preview environments on top of our K8s clusters to which we can deploy our sample application to. Before we get started, let’s establish a couple of definitions.
A Pull Request, or PR, is GitHub terminology to describe the process where a developer proposes some code change to be merged from a feature branch to a master branch.
In trunk-based development, the master branch is the main trunk, and PRs are based on feature branches. Once a PR is approved, it gets merged into the main trunk or master branch.
Now, if you overlay the concept of a preview environment on top of this PR flow, this is the target workflow we want to get to:
The lifecycle of the preview environment should be the same as the lifecycle of the PR, so when the PR is created the environment is automatically spun up by Humanitec. Once the PR is reviewed and merged into the master branch, the environment, and all associated resources are destroyed, so we don’t leave any resources unused in our setup.
Prerequisites
Before starting this tutorial, you’ll need:
- A Humanitec account
- A GitHub Action connected to Humanitec
- A Kubernetes cluster connected to Humanitec (in this case we use the default setup of our sample application)
Step 1: How to create a preview environment automatically when a new PR is opened
In this example, we will use GitHub Actions to define our workflow and call the Humanitec API on PR creation.
Once called, the Humanitec API will create a namespace on the target Kubernetes cluster for the environment and automatically generate a DNS name associated with it.
The last thing we'll set up on the Humanitec side is the automation rule, so every time the IDP gets notified by the CI pipeline that a new image has been built and is available, we can trigger a deployment to the target environment and namespace we dynamically created.
Once that is set up, we need to make sure our GitHub Actions hooks are properly configured to create a PR and trigger the environment creation from there. Here’s the GitHub Action code to create the preview environment:
/.github/workflows/create-preview-env.yml
<p> CODE:<script src="https://gist.github.com/eskilavelon/413f1fd1076567bd003c3f759bdfb184.js"></script>
The first thing we need to do is set the context, using HUMANITEC_TOKEN (which can be generated within Humanitec itself) to communicate with the Humanitec API and specify the org, app, and base environment. The base environment is what Humanitec will use as a baseline to clone from to create the preview environment, in this case, the development environment.
<p> CODE:<script src="https://gist.github.com/eskilavelon/537fb88a933a0dc7d28bd90def9c0926.js"></script>
Step 2: How to access the preview environment via a PR
We then generate a new env ID using the repo and the PR number and clone the BASE_ENV in the context of APP_ID to the new ENV_ID, enforcing a few checks.
<p> CODE:<script src="https://gist.github.com/eskilavelon/a9b91293415e1445b57d0fb371750300.js"></script>
Step 3: How to keep the preview environment up-to-date with a PR
Next, we set the automation rule so the new image gets deployed every time a new version on BRANCH_NAME is available and create a comment that points to the PR (issue.number) inside of GitHub.
<p> CODE:<script src="https://gist.github.com/eskilavelon/6fc5637b2c18413aebffb9c5f165b43d.js"></script>
Step 4: How to delete the environment
In addition, we have a similar GitHub Action set up to delete the environment once the PR is merged and closed.
/.github/workflows/delete-preview-env.yml
<p> CODE:<script src="https://gist.github.com/eskilavelon/d1b86956ddbd20d3a4b6364be97cfd66.js"></script>
Finally, we should add the following self-contained JavaScript file to our repository. This makes the calls to the Humanitec API in order for the above GitHub Actions to work.
/.github/js/humanitec.js
<p> CODE:<script src="https://gist.github.com/eskilavelon/9ce692a75b2f67de7d1ba227b5b4fd6b.js"></script>
And voila, we are ready to make a change, create a new PR and test our setup. Once all steps run, we should get a new environment up and running with our application deployed inside, ready to be tested in a real-life setup with all the required dependencies.
Once all checks are performed, we can merge the PR to the master branch, and our workflows will automatically sunset the preview environment and destroy all associated dynamic resources.
Summary
In this tutorial, you learned how to enable preview environments on top of Kubernetes. We tackled how to create a preview environment automatically when a new PR is opened, how to access the new environments, how to keep it up to date, and how to sunset it once it is not needed anymore.
If you’d like to learn more about the use of an IDP built with Humanitec, register for our next workshop or check the learning hub for more tutorials.
