Telepresence with GitHub Actions

Telepresence combined with GitHub Actions allows you to run integration tests in your continuous integration/continuous delivery (CI/CD) pipeline without the need to run any dependant service. When you connect to the target Kubernetes cluster, you can intercept traffic of the remote services and send it to an instance of the local service running in CI. This way, you can quickly test the bugfixes, updates, and features that you develop in your project.

You can register here to get a free Ambassador Cloud account to try the GitHub Actions for Telepresence yourself.

GitHub Actions for Telepresence

Ambassador Labs has created a set of GitHub Actions for Telepresence that enable you to run integration tests in your CI pipeline against any existing remote cluster. The GitHub Actions for Telepresence are the following:

• install: Installs Telepresence in your CI server with latest version or the one specified by you.
• login: Logs into Telepresence and allows you to create a personal intercept. You'll need a Telepresence API key which you must set as an environment variable in your workflow. See the acquiring an API key guide for instructions on how to get one.
• helm: Installs the telepresence traffic manager in the cluster.
• connect: Connects to the remote target environment.
• intercept: Redirects traffic to the remote service to the version of the service running in CI so you can run integration tests.

Each action contains a post-action script to clean up resources. This includes logging out of Telepresence, closing the connection to the remote cluster, and stopping the intercept process. These post scripts are executed automatically, regardless of job result. This way, you don't have to worry about terminating the session yourself. You can look at the GitHub Actions for Telepresence repository for more information.

Using Telepresence in your GitHub Actions CI pipeline

Prerequisites

To enable GitHub Actions with telepresence, you need:

• A Telepresence API KEY and set it as an environment variable in your workflow.

• Access to your remote Kubernetes cluster, like a kubeconfig.yaml file with the information to connect to the cluster.

• If your remote cluster already has Telepresence installed, you need to know whether Telepresence is installed Cluster wide or Namespace only. If telepresence is configured for namespace only, verify that your kubeconfig.yaml is configured to find the installation of the Traffic Manager. For example:

• You need a GitHub Actions secret named TELEPRESENCE_API_KEY in your repository that has your Telepresence API key. See GitHub docs for instructions on how to create GitHub Actions secrets.

• You need a GitHub Actions secret named KUBECONFIG_FILE in your repository with the content of your kubeconfig.yaml).

Using Telepresence in your GitHub Actions workflows

1. In the .github/workflows directory create a new YAML file named run-integration-tests.yaml and modify placeholders with real actions to run your service and perform integration tests.

The previous is an example of a workflow that:

• Checks out the repository code.
• Has a placeholder step to run the service during CI.
• Creates the /opt/kubeconfig file with the contents of the secrets.KUBECONFIG_FILE to make it available for Telepresence.
• Installs Telepresence.
• Runs Telepresence Connect.
• Logs into Telepresence.
• Intercepts traffic to the service running in the remote cluster.
• Is a placeholder for an action that would run integration tests, such as one that makes HTTP requests to your running service and verifies it works while dependent services run in the remote cluster.

This workflow gives you the ability to run integration tests during the CI run against an ephemeral instance of your service to verify that any change that is pushed to the working branch works as expected. After you push the changes, the CI server will run the integration tests against the intercept. You can view the results on your GitHub repository, under the "Actions" tab.