{"token_count": 2489} # Get Started with Kubernetes Application Discovery Teleport can automatically detect applications running in your Kubernetes clusters and register them with your Teleport cluster. In this setup, users with Kubernetes-hosted infrastructure can configure secure access to any new applications they deploy with no need for manual intervention beyond the initial setup step. In this guide, you will enable Kubernetes application auto-discovery. ## How it works The Teleport Discovery Service queries the API server of the Kubernetes cluster in which you want to detect applications, maintaining dynamic `app` resources to match the Kubernetes services that it detects within the cluster. The Teleport Application Service queries the Teleport Auth Service to fetch `app` resources, and proxies applications based the dynamically generated configuration. ## Prerequisites - A running Teleport cluster accessible at a hostname with a valid TLS certificate. 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/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: **Mac/Linux** ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` **Windows - Powershell** ``` $ $TELEPORT_DOMAIN = "teleport.example.com:443" $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").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/installation/single-machine.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 ``` Connecting with TLS routing disabled This guide's commands assume your Teleport cluster uses TLS routing (`proxy_listener_mode: multiplex`), where the `tctl` and `tsh` clients reach every Teleport service through the Proxy Service's web address on port `443`. If you're not sure whether this applies to your cluster, check with whoever manages it. If your cluster uses separate listener ports instead, adjust ports as follows: - **`tsh` commands** (e.g., `tsh login --proxy=...`): continue using the Proxy Service web address on port `3080` (or `443` if behind a load balancer). Do not change these to port `3025`. - **Direct `tctl` or Auth Service API commands**: use port `3025` for the Auth Service gRPC listener: ``` $ tctl status --auth-server=teleport.example.com:3025 ``` * A Kubernetes cluster version >= v1.17.0 * Helm >= 3.4.2 Verify that Helm and Kubernetes are installed and up to date. ``` $ helm version version.BuildInfo{Version:"v3.4.2"} $ kubectl version Client Version: version.Info{Major:"1", Minor:"17+"} Server Version: version.Info{Major:"1", Minor:"17+"} ``` * Check that you can connect to your Teleport cluster and verify that you can run `tctl` and `tsh` commands using your current credentials. 1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username. 2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not. **In an interactive shell:** Run the following command. By default, this triggers a multi-factor authentication prompt: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.10.0 CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` **On non-interactive environments:** If you are running `tsh` and `tctl` as an AI agent, in a CI/CD environment, or similar, make sure the `TELEPORT_IDENTITY_FILE` environment variable is assigned to a valid file path with credentials for your cluster. `tsh` and `tctl` read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you [set up Machine ID](https://goteleport.com/docs/machine-workload-identity/getting-started.md) to provision one automatically. When executing `tctl` commands with an identity file, you must pass the `--auth-server` flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, `tctl` connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to `3025` if you are contacting the Auth Service directly with `tctl`: ``` $ tctl status --auth-server=teleport.example.com:443 ``` For `tsh` commands that read an identity file, you must pass the `--proxy` flag, which points `tsh` to the address of the Teleport Proxy Service: ``` $ tsh status --proxy=teleport.example.com ``` Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file: ``` $ export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}" ``` Add the `--auth-server` or `--proxy` flags to all subsequent `tctl` and `tsh` commands. 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. ## Step 1/2. Create a join token Create a join token for a new Teleport Agent that will run the Teleport Kubernetes Service, Application Service, and Discovery Service: ``` $ tctl tokens add --type=kube,app,discovery ``` Enabling the `discovery` role by default will automatically start the discovery of Kubernetes services and registration of Teleport applications from them. And enabling `app` role on the chart will start the process of proxying all new Teleport applications created from discovered Kubernetes services. ## Step 2/2. Deploy the agent If you want to install a new Teleport Agent in your Kubernetes cluster, you can use the `teleport-kube-agent` Helm chart. If you already have a Teleport Agent installed, you can upgrade it to enable the Kubernetes Application Discovery by adding the `kube`, `app`, and `discovery` to roles as shown below. **Install a new agent** Deploy a new Teleport Agent running your configured services by installing the `teleport-kube-agent` Helm chart, assigning proxy-address to the host and port of your Teleport Proxy Service and token to the join token you created earlier: ``` $ helm install teleport-agent teleport/teleport-kube-agent \ --set roles=kube\,app\,discovery \ --set kubeClusterName=main-cluster \ --set proxyAddr=proxy-address \ --set authToken=token \ --create-namespace \ --namespace=teleport ``` **Upgrade an existing agent** If you want to have an existing `teleport-kube-agent` installation and want to enable Kubernetes App Discovery, you need to update the existing installation role to include `kube`, `app`, and `discovery` roles: ``` $ helm upgrade teleport-agent teleport/teleport-kube-agent \ --reuse-values \ --set roles=kube\,app\,discovery \ --set authToken=token \ --namespace=teleport ``` ## Troubleshooting First, make sure that all expected agents for the Teleport Discovery, Application, and Kubernetes Services are running. The token you created for them must have the required roles. If agents are running, but you don't see expected apps appearing in Teleport, there could be two main reasons: - The Teleport Discovery Service can't find relevant Kubernetes services. - The Teleport Application Service can't proxy discovered applications. Make sure that Kubernetes service account under which the Discovery Service is running has enough permissions to list the cluster's services. Also make sure that labels and namespaces configuration is correct. For the Application Service, make sure that labels in `resources` field are defined correctly, specifically that label `teleport.dev/kubernetes-cluster` matches `discovery_group` field of the Discovery Service running in the Kubernetes cluster. ## Next steps You can configure the scope of the Discovery Service. For more information, see [`teleport-kube-agent` helm chart documentation](https://goteleport.com/docs/reference/helm-reference/teleport-kube-agent.md).