# Machine & Workload Identity with Kubernetes Access Teleport protects and controls access to Kubernetes clusters. Machine & Workload Identity can be used to grant machines secure, short-lived access to these clusters. In this guide, you will configure `tbot` to produce credentials that can be used to access a Kubernetes cluster enrolled with your Teleport cluster. ## 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/17.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/17.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 ``` * If you have not already connected your Kubernetes cluster to Teleport, follow [Enroll a Kubernetes Cluster](https://goteleport.com/docs/ver/17.x/enroll-resources/kubernetes-access/getting-started.md). * 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 17.7.20 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. * To configure the Kubernetes cluster, your client system will need to have `kubectl` installed. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/) for installation instructions. * `tbot` must already be installed and configured on the machine that will access Kubernetes clusters. For more information, see the [deployment guides](https://goteleport.com/docs/ver/17.x/machine-workload-identity/deployment.md). * To demonstrate connecting to the Kubernetes cluster, the machine that will access Kubernetes clusters will need to have `kubectl` installed. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/) for installation instructions. ## Step 1/3. Configure Teleport and Kubernetes RBAC First, we need to configure the RBAC for both Teleport and Kubernetes in order to grant the bot the correct level of access. When forwarding requests to the Kubernetes API on behalf of a bot, the Teleport Proxy attaches the groups configured (using `kubernetes_groups`) in the bot's Teleport roles to the request. These groups are then used to configure a RoleBinding or ClusterRoleBinding in Kubernetes to grant specific permissions within the Kubernetes cluster to the bot. For the purpose of this guide, we will bind the `editor` group to the default `edit` ClusterRole that is preconfigured in most Kubernetes clusters to give the bot read and write access to resources in all the cluster namespaces. When configuring this for a production environment, you should consider: - If RoleBinding should be used instead of ClusterRoleBinding to limit the bot's access to a specific namespace. - If a Role should be created that grants the bot the least privileges necessary rather than using a pre-existing general Role such as `edit`. To bind the `editor` group to the `edit` Cluster Role, execute: ``` $ kubectl create clusterrolebinding teleport-editor-edit \ --clusterrole=edit \ --group=editor ``` With the appropriate RoleBinding configured in Kubernetes to grant access to a specific group, you now need to add this group to the role that the bot will impersonate when producing credentials. You also need to grant the bot access through Teleport to the cluster itself. This is done by creating a role that grants the necessary permissions and then assigning this role to a Bot. Create a file called `role.yaml` with the following content: ``` kind: role version: v7 metadata: name: example-role spec: allow: kubernetes_labels: '*': '*' kubernetes_groups: - editor kubernetes_resources: - kind: "*" namespace: "*" name: "*" verbs: ["*"] ``` Replace `example-role` with a descriptive name related to your use case. Adjust the `allow` field for your environment: - `kubernetes_labels` should be adjusted to grant access to only the clusters that the bot will need to access. The value shown, `'*': '*'` will grant access to all Kubernetes clusters. - `editor` must match the name of the group you specified in the RoleBinding or ClusterRoleBinding. - `kubernetes_resources` can be used to apply additional restrictions to what the bot can access within the Kubernetes cluster. These restrictions are layered upon the RBAC configured within the Kubernetes role itself. Use `tctl create -f ./role.yaml` to create the role. --- TIP You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit. --- Now, use `tctl bots update` to add the role to the Bot. Replace `example` with the name of the Bot you created in the deployment guide and `example-role` with the name of the role you just created: ``` $ tctl bots update example --add-roles example-role ``` ## Step 2/3. Configure a Kubernetes `tbot` output service Now, `tbot` needs to be configured with an output service to produce the Kubernetes credentials and client configuration file. This is done using the `kubernetes` service type. The Kubernetes cluster you want the credentials to have access to must be specified using the `kubernetes_cluster` field. In this example, `example-k8s-cluster` will be used. The output must be configured with a destination and the name of the Kubernetes cluster that should be encoded in the credentials produced by `tbot`. At this time, each output can only contain credentials for a single Kubernetes cluster. If your bot needs to connect to multiple Kubernetes clusters, create an output for each cluster. Output services must also be configured with a destination. In this example, the `directory` type will be used. This will write artifacts to a specified directory on disk. Ensure that this directory can be written to by the Linux user that `tbot` runs as, and that it can be read by the Linux user that will be accessing the Kubernetes cluster. Modify your `tbot` configuration to add a `kubernetes` service: ``` services: - type: kubernetes # Specify the name of the Kubernetes cluster you wish the credentials to # grant access to. kubernetes_cluster: example-k8s-cluster destination: type: directory # For this guide, /opt/machine-id is used as the destination directory. # You may wish to customize this. Multiple output services cannot # share the same destination. path: /opt/machine-id ``` Ensure you replace `example-k8s-cluster` with the name of the Kubernetes cluster as registered in Teleport and adjust `/opt/machine-id` if you wish If operating `tbot` as a background service, restart it. If running `tbot` in one-shot mode, it must be executed before you attempt to use the credentials. ## Step 3/3. Connect to your Kubernetes cluster Once `tbot` has been run with the new service configured, a file called `kubeconfig.yaml` should have been generated in the destination directory you specified. This contains all the information necessary for `kubectl` to connect to the Kubernetes cluster through the Teleport Proxy. To use `kubeconfig.yaml` with `kubectl`, the `--kubeconfig` flag or `KUBECONFIG` environment variable can be provided to `kubectl`: ``` $ kubectl --kubeconfig /opt/machine-id/kubeconfig.yaml get pods -A Or, set the KUBECONFIG environment variable: $ export KUBECONFIG=/opt/machine-id/kubeconfig.yaml $ kubectl get pods -A ``` Whilst this guide has demonstrated `kubeconfig.yaml` being used with `kubectl`, this format is compatible with most Kubernetes tools including: - Helm - Lens - ArgoCD ## Next steps - Read the [configuration reference](https://goteleport.com/docs/ver/17.x/reference/machine-id/configuration.md) to explore all the available configuration options. - Read the [Teleport Kubernetes RBAC guide](https://goteleport.com/docs/ver/17.x/enroll-resources/kubernetes-access/controls.md) for more details on controlling Kubernetes access.