7 min • read

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:

• configure: Initial configuration setup for Telepresence that is needed to run the actions successfully.
• install: Installs Telepresence in your CI server with latest version or the one specified by you.
• login: Logs into Telepresence, you can create a personal intercept. You'll need a Telepresence API key and set it as an environment variable in your workflow. See the acquiring an API key guide for instructions on how to get one.
• 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:

• If Telepresence is installed, you also need to know the version of Telepresence running in the cluster. You can run the command kubectl describe service traffic-manager -n namespace. The version is listed in the labels section of the output.

• 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).

Does your environment look different? We're actively working on making GitHub Actions for Telepresence more useful for more

Initial configuration setup

To be able to use the GitHub Actions for Telepresence, you need to do an initial setup to configure Telepresence so the repository is able to run your workflow. To complete the Telepresence setup:

1. In your main branch, create a `.github/workflows` directory in your GitHub repository if it does not already exist. 1. Next, in the `.github/workflows` directory, create a new YAML file named `configure-telepresence.yaml`:

1. Push the configure-telepresence.yaml file to your repository.
2. Run the Configuring Telepresence Workflow manually in your repository's Actions tab.

When the workflow runs, the action caches the configuration directory of Telepresence and a Telepresence configuration file if is provided by you. This configuration file should be placed in the/.github/telepresence-config/config.yml with your own Telepresence config. If you update your this file with a new configuration, you must run the Configuring Telepresence Workflow action manually on your main branch so your workflow detects the new configuration.

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.
• 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 the 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 "Actions" tab.