# Deploying tbot on GitLab CI In this guide, you will use Teleport Machine & Workload Identity to allow a GitLab pipeline to securely connect to a Teleport SSH node without the need for long-lived secrets. Machine & Workload Identity for GitLab works with GitLab's cloud-hosted option and with self-hosted GitLab installations. **The minimum supported GitLab version is 15.7**. This mitigates the risk of long-lived secrets such as passwords or SSH private keys being exfiltrated from your GitLab organization and provides many of the other benefits of Teleport such as auditing and fine-grained access control. ## Prerequisites - A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/ver/19.x/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/ver/19.x/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 19.0.0-dev CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. * A GitLab project to connect to Teleport. This can either be on GitLab's cloud-hosted offering (gitlab.com) or on a self-hosted GitLab instance. **When using a self-hosted GitLab instance, your Teleport Auth Service must be able to connect to your GitLab instance and your GitLab instance must be configured with a valid TLS certificate.** ## Step 1/4. Create a Bot Next, you need to create a Bot. A Bot is a Teleport identity for a machine or group of machines. Like users, bots have a set of roles and traits which define what they can access. Create `bot.yaml`: ``` kind: bot version: v1 metadata: # name is a unique identifier for the Bot in the cluster. name: example spec: # roles is a list of roles to grant to the Bot. Don't worry if you don't know # what roles you need to specify here, the Access Guides will walk you through # creating and assigning roles to the already created Bot. roles: [] ``` Make sure you replace `example` with a unique, descriptive name for your Bot. Use `tctl` to apply this file: ``` $ tctl create bot.yaml ``` ## Step 2/4. Create a join token To allow GitLab CI to authenticate to your Teleport cluster, you'll first need to create a join token. A GitLab join token contains allow rules that describe which pipelines can use that token in order to join the Teleport cluster. A rule can contain multiple fields, and any pipeline that matches all the fields within a single rule is granted access. In this example, you will create a token with a rule that grants access to any GitLab CI job within a specific GitLab project. Determine the fully qualified path of your GitLab project. This will include your username (or group) and the name of your project, e.g. `my-user/my-project`. Create a file named `bot-token.yaml`. Ensure you substitute any values as suggested by the comments in this example: ``` kind: token version: v2 metadata: name: example-bot spec: # The Bot role indicates that this token grants access to a bot user, rather # than allowing a node to join. This role is built in to Teleport. roles: [Bot] join_method: gitlab # The bot_name indicates which bot user this token grants access to. This # should match the name of the bot that you created in step 1. bot_name: example gitlab: # domain should be the domain of your GitLab instance. If you are using # GitLab's cloud hosted offering, omit this field entirely. domain: gitlab.example.com # allow specifies rules that control which GitLab tokens will be accepted # by Teleport. Tokens not matching any allow rule will be denied. allow: # project_path should be the fully qualified path of your GitLab # project that you determined earlier. This will grant access to any # GitLab CI run in that project. - project_path: my-user/my-project ``` You can find a full list of the token configuration options for GitLab joining on the [join tokens reference page.](https://goteleport.com/docs/ver/19.x/reference/deployment/join-methods.md#gitlab-gitlab) Apply this to your Teleport cluster using `tctl`: ``` $ tctl create -f bot-token.yaml ``` ## Step 3/4. Configure a GitLab Pipeline With the bot and join token created, you can now configure a GitLab pipeline that sets up `tbot` to use these. To configure `tbot`, a YAML file will be used. In this example we'll store this within the repository itself, but this could be generated or created by the CI pipeline itself. Create `tbot.yaml` within your repository: ``` version: v2 proxy_server: example.teleport.sh:443 onboarding: join_method: gitlab token: example-bot oneshot: true storage: type: memory # services will be filled in during the completion of an access guide. services: [] ``` Replace: - example.teleport.sh with the address of your Teleport Proxy or Auth Service. Prefer using the address of a Teleport Proxy. - `example-bot` with the name of the token you created in the second step Now, the GitLab CI pipeline can be defined. Before the pipeline can use `tbot`, it must be available within the environment. For this example, we'll show downloading `tbot` as part of the CI step, but in a production implementation you may wish to build a docker image that contains this binary to avoid depending on the Teleport CDN. Create `.gitlab-ci.yml` within your repository: ``` stages: - deploy deploy-job: stage: deploy # id_tokens configures ID Tokens that GitLab will automatically inject into # the environment of your GitLab run. # # See https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html # for further explanation of the id_tokens configuration in GitLab. id_tokens: TBOT_GITLAB_JWT: # aud for TBOT_GITLAB_JWT must be configured with the name of your # Teleport cluster. This is not necessarily the address of your Teleport # cluster and will not include a port or scheme (http/https) # # This helps the Teleport Auth Service know that the token is intended for # it, and not a different service or Teleport cluster. aud: example.teleport.sh script: - curl "https://example.teleport.sh:443/scripts/install.sh" | bash - 'TELEPORT_ANONYMOUS_TELEMETRY=1 tbot start -c tbot.yaml' ``` Replace: - example.teleport.sh for `aud` with the name of your Teleport cluster. This is not necessarily the address of your Teleport cluster and will not include a port or scheme (e.g. http/https). - example.teleport.sh with the address of your Teleport Proxy Service. `TELEPORT_ANONYMOUS_TELEMETRY` enables the submission of anonymous usage telemetry. This helps us shape the future development of `tbot`. You can disable this by omitting this. Commit and push these two files to the repository. Check your GitLab CI status, and examine the log results from the commit for failure. ## Step 4/4. Configure services You have now prepared the base configuration for `tbot`. At this point, it identifies itself to the Teleport cluster and renews its own credentials but does not output any credentials for other applications to use. Follow one of the [access guides](https://goteleport.com/docs/ver/19.x/machine-workload-identity/access-guides.md) to configure a service that meets your access needs. ## Further steps - For more information about GitLab joining, read the [join method reference page.](https://goteleport.com/docs/ver/19.x/reference/deployment/join-methods.md#gitlab-gitlab) - For more information about GitLab itself, read [their documentation](https://docs.gitlab.com/ee/ci/). - Follow the [access guides](https://goteleport.com/docs/ver/19.x/machine-workload-identity/access-guides.md) to finish configuring `tbot` for your environment. - Read the [configuration reference](https://goteleport.com/docs/ver/19.x/reference/machine-workload-identity/configuration.md) to explore all the available configuration options. - [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](https://goteleport.com/docs/ver/19.x/reference/machine-workload-identity/telemetry.md)