7 min • read

Telepresence with GitHub Actions

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. You can learn more about GitHub Actions.

Telepresence combined with GitHub Actions allows you to run integration tests in your CI pipeline without having 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.

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:

  1. Get a free account: Register here to get a free account. No credit card required.
  2. configure: Initial configuration setup for Telepresence that is needed to run the actions successfully.
  3. install: Installs Telepresence in your CI server with latest version or the one specified by you.
  4. 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.
  5. connect: Connects to the remote target environment.
  6. 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 will 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:

    yaml
    apiVersion: v1
    clusters:
    - cluster:
    server: https://127.0.0.1
    extensions:
    - name: telepresence.io
    extension:
    manager:
    namespace: traffic-manager-namespace
    name: example-cluster
  • 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`:
shell
```yaml
name: Configuring telepresence
on: workflow_dispatch
jobs:
configuring:
name: Configure telepresence
runs-on: ubuntu-latest
env:
TELEPRESENCE_API_KEY: ${{ secrets.TELEPRESENCE_API_KEY }}
steps:
- name : Checkout
uses: actions/checkout@v3
#---- here run your custom command to connect to your cluster
#- name: Connect to cluster
# shell: bash
# run: ./connnect to cluster
#----
- name: Congifuring Telepresence
uses: datawire/telepresence-actions/configure@v1.0-rc
with:
version: latest
```
  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.

    yaml
    name: Run Integration Tests
    on:
    push:
    branches-ignore:
    - 'main'
    jobs:
    my-job:
    name: Run Integration Test using Remote Cluster
    runs-on: ubuntu-latest
    env:
    TELEPRESENCE_API_KEY: ${{ secrets.TELEPRESENCE_API_KEY }}
    KUBECONFIG_FILE: ${{ secrets.KUBECONFIG_FILE }}
    KUBECONFIG: /opt/kubeconfig
    steps:
    - name : Checkout
    uses: actions/checkout@v3
    with:
    ref: ${{ github.event.pull_request.head.sha }}
    #---- here run your custom command to run your service
    #- name: Run your service to test
    # shell: bash
    # run: ./run_local_service
    #----
    # First you need to log in to Telepresence, with your api key
    - name: Create kubeconfig file
    run: |
    cat <<EOF > /opt/kubeconfig
    ${{ env.KUBECONFIG_FILE }}
    EOF
    - name: Install Telepresence
    uses: datawire/telepresence-actions/install@v1.0-rc
    with:
    version: 2.5.8 # Change the version number here according to the version of Telepresence in your cluster or omit this parameter to install the latest version
    - name: Telepresence connect
    uses: datawire/telepresence-actions/connect@v1.0-rc
    - name: Login
    uses: datawire/telepresence-actions/login@v1.0-rc
    with:
    telepresence_api_key: ${{ secrets.TELEPRESENCE_API_KEY }}
    - name: Intercept the service
    uses: datawire/telepresence-actions/intercept@v1.0-rc
    with:
    service_name: service-name
    service_port: 8081:8080
    namespace: namespacename-of-your-service
    http_header: "x-telepresence-intercept-id=service-intercepted"
    print_logs: true # Flag to instruct the action to print out Telepresence logs and export an artifact with them
    #---- here run your custom command
    #- name: Run integrations test
    # shell: bash
    # run: ./run_integration_test
    #----

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.