diff --git a/docs/pages/includes/helm.mdx b/docs/pages/includes/helm.mdx index 6c103c579d020..aeed999ef7ed8 100644 --- a/docs/pages/includes/helm.mdx +++ b/docs/pages/includes/helm.mdx @@ -1,4 +1,4 @@ -Verify that helm and kubernetes are installed and up to date. +Verify that Helm and Kubernetes are installed and up to date. ```code $ helm version diff --git a/docs/pages/includes/kubernetes-access/helm-k8s.mdx b/docs/pages/includes/kubernetes-access/helm-k8s.mdx index 4a46640ed007c..c0a92b0531f98 100644 --- a/docs/pages/includes/kubernetes-access/helm-k8s.mdx +++ b/docs/pages/includes/kubernetes-access/helm-k8s.mdx @@ -1,7 +1,7 @@ - [Kubernetes](https://kubernetes.io) >= v(=kubernetes.major_version=).(=kubernetes.minor_version=).0 - [Helm](https://helm.sh) >= (=helm.version=) -Verify that helm and kubernetes are installed and up to date. +Verify that helm and Kubernetes are installed and up to date. ```code $ helm version diff --git a/docs/pages/kubernetes-access/getting-started/agent.mdx b/docs/pages/kubernetes-access/getting-started/agent.mdx index d517cffbc1c74..d68f18edee80c 100644 --- a/docs/pages/kubernetes-access/getting-started/agent.mdx +++ b/docs/pages/kubernetes-access/getting-started/agent.mdx @@ -3,35 +3,86 @@ title: Connect a Kubernetes Cluster to Teleport description: Connecting a Kubernetes cluster to Teleport --- - -You can use this guide with Teleport Open Source, Teleport Enterprise, and Teleport Cloud. - - ## Prerequisites -- Installed and running Teleport cluster, self-hosted or cloud-hosted. -- Tool `jq` to process `JSON` output. + + + +- A running Teleport cluster. For details on how to set this up, see one of our + [Getting Started](../../getting-started.mdx) guides. + +- The `jq` tool to process `JSON` output. This is available via common package managers. + +- The `tctl` admin tool version >= (=teleport.version=). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + See [Installation](../../installation.mdx) for details. + + (!docs/pages/includes/tctl.mdx!) + + + + +- A running Teleport cluster. For details on how to set this up, see one of our + [Getting Started](../../getting-started.mdx) guides. + +- The `jq` tool to process `JSON` output. This is available via common package managers. + +- The `tctl` admin tool version >= (=teleport.version=), which you can download + by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- The `jq` tool to process `JSON` output. This is available via common package + managers. + +- The Enterprise version of the `tctl` admin tool. To download this, visit +the [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + + + (!docs/pages/includes/kubernetes-access/helm-k8s.mdx!) (!docs/pages/includes/tctl.mdx!) - -For self-hosted Teleport instances the `kube_listen_addr` setting in the `proxy_service` is required to enable Kubernetes Access. This is already enabled for Cloud and the Teleport `teleport-cluster` helm chart. -```yaml -proxy_service: - # ... - public_addr: proxy.example.com:3080 +## Deployment overview - kube_listen_addr: 0.0.0.0:3026 - ``` - +In this guide, we deploy the Teleport Kubernetes Service, which connects +Kubernetes cluster `cookie` to Teleport cluster `tele.example.com`: -## Deployment overview + -In this guide, we deploy a Teleport agent that connects kubernetes cluster `cookie` to -Teleport cluster `tele.example.com`: +In your Teleport Cloud account, the name of your cluster will be your tenant +domain name, e.g., `mytenant.teleport.sh`, rather than `teleport.example.com`. + +
![Kubernetes agent](../../../img/k8s/agent.svg) @@ -39,31 +90,58 @@ Teleport cluster `tele.example.com`: ## Step 1/2. Get a join token -Start a lightweight agent in your Kubernetes cluster `cookie` and connect it to `tele.example.com`. -We would need a join token from `tele.example.com`: +In order to start the Teleport Kubernetes Service, we will need to request a +join token from the Teleport Auth Service: ```code -# Create a join token for the cluster cookie to authenticate +# Create a join token for the Teleport Kubernetes Service to authenticate $ TOKEN=$(tctl nodes add --roles=kube --ttl=10000h --format=json | jq -r '.[0]') $ echo $TOKEN ``` ## Step 2/2. Deploy teleport-kube-agent -Switch `kubectl` to the Kubernetes cluster `cookie` and run: + + + + +Switch `kubectl` to the Kubernetes cluster `cookie` and run the following +commands, assigning `PROXY_ADDR` to the address of your Auth Service or Proxy +Service. + +```code +# Add teleport-agent chart to charts repository +$ PROXY_ADDR=tele.example.com:443 +$ helm repo add teleport https://charts.releases.teleport.dev +$ helm repo update + +# Install Kubernetes agent. It dials back to the Teleport cluster at $PROXY_ADDR +$ CLUSTER='cookie' +$ helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \ + --set proxyAddr=${PROXY_ADDR?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent +``` + + + + +Switch `kubectl` to the Kubernetes cluster `cookie` and run the following +commands, assigning `PROXY_ADDR` to the address of your Teleport Cloud tenant. ```code # Add teleport-agent chart to charts repository +$ PROXY_ADDR=mytenant.teleport.sh $ helm repo add teleport https://charts.releases.teleport.dev $ helm repo update -# Install Kubernetes agent. It dials back to the Teleport cluster tele.example.com. +# Install Kubernetes agent. It dials back to the Teleport cluster at $PROXY_ADDR $ CLUSTER='cookie' -$ PROXY='tele.example.com:443 - replace me with your cluster' $ helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \ - --set proxyAddr=${PROXY?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent + --set proxyAddr=${PROXY_ADDR?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent ``` + + + List connected clusters using `tsh kube ls` and switch between them using `tsh kube login`: @@ -78,7 +156,7 @@ $ tsh kube ls $ tsh kube login cookie # Logged into kubernetes cluster "cookie" -# kubectl command executed on `cookie` but is routed through `tele.example.com` cluster. +# kubectl command executed on `cookie` but is routed through the Teleport cluster. $ kubectl get pods ``` diff --git a/docs/pages/kubernetes-access/guides/federation.mdx b/docs/pages/kubernetes-access/guides/federation.mdx index f28e5d63019c4..48b7bd010723d 100644 --- a/docs/pages/kubernetes-access/guides/federation.mdx +++ b/docs/pages/kubernetes-access/guides/federation.mdx @@ -1,17 +1,18 @@ --- -title: Teleport Kubernetes Access and Trusted Clusters +title: Federated Kubernetes access with Trusted Clusters description: Federated Access using Teleport Trusted Clusters. --- -## Federated Kubernetes access with Trusted Clusters - There are cases when you have Kubernetes clusters that have to operate independently, for example, they are part of a different organization or have intermittent connectivity. You can take advantage of [Trusted Clusters](../../setup/admin/trustedclusters.mdx) to federate trust across Kubernetes clusters. -When multiple trusted clusters are present behind a Teleport proxy, the + + + +When multiple Trusted Clusters are present behind the Teleport Proxy Service, the `kubeconfig` generated by [tsh login](../../setup/reference/cli.mdx#tsh-login) will contain the Kubernetes API endpoint determined by the `` argument to [tsh login](../../setup/reference/cli.mdx#tsh-login). @@ -19,10 +20,10 @@ login](../../setup/reference/cli.mdx#tsh-login). For example, consider the following setup: - There are three Teleport/Kubernetes clusters: `main`, `east`, and `west`. These are the names set in `cluster_name` setting in their configuration files. -- The clusters `east` and `west` are trusted clusters for `main`. +- The clusters `east` and `west` are Trusted Clusters for `main`. - Users always authenticate against `main` but use their certificates to access - SSH nodes and Kubernetes API in all three clusters. -- The DNS name of the main proxy server is `main.example.com` + SSH nodes and the Kubernetes API in all three clusters. +- The DNS name of the main Proxy Service is `main.example.com`. In this scenario, users usually log in using this command: @@ -39,3 +40,37 @@ $ tsh --proxy=main.example.com login east # User's `kubeconfig` now contains the entry for the "east" Kubernetes # endpoint, i.e. `east.main.example.com`. ``` + + + + +When multiple Trusted Clusters are present behind the Teleport Proxy Service, the +`kubeconfig` generated by [tsh login](../../setup/reference/cli.mdx#tsh-login) will contain the +Kubernetes API endpoint determined by the `` argument to [tsh +login](../../setup/reference/cli.mdx#tsh-login). + +For example, consider the following setup: + +- There are two Teleport/Kubernetes clusters, `east` and `west`. These are the names set in `cluster_name` setting in their configuration files. +- The clusters `east` and `west` are Trusted Clusters for a Teleport Cloud tenant, `mytenant.teleport.sh`. +- Users always authenticate against `mytenant.teleport.sh` but use their certificates to access + SSH nodes and the Kubernetes API in all three clusters. + +In this scenario, users usually log in using this command: + +```code +# Using login without arguments +$ tsh --proxy=mytenant.teleport.sh login + +# User's `kubeconfig` now contains one entry for the main Kubernetes +# endpoint, i.e. `mytenant.teleport.sh`. + +# Receive a certificate for "east": +$ tsh --proxy=mytenant.teleport.sh login east + +# User's `kubeconfig` now contains the entry for the "east" Kubernetes +# endpoint, i.e. `east.mytenant.teleport.sh`. +``` + + + diff --git a/docs/pages/kubernetes-access/guides/multiple-clusters.mdx b/docs/pages/kubernetes-access/guides/multiple-clusters.mdx index 37e15817bc992..30cb44262b3ac 100644 --- a/docs/pages/kubernetes-access/guides/multiple-clusters.mdx +++ b/docs/pages/kubernetes-access/guides/multiple-clusters.mdx @@ -7,18 +7,90 @@ This guide will show you how to use Teleport as an access plane for multiple Kub ## Prerequisites -- [Kubernetes](https://kubernetes.io) >= v(=kubernetes.major_version=).(=kubernetes.minor_version=).0 -- [Helm](https://helm.sh) >= (=helm.version=) -- Installed and running Teleport cluster (Open Source, Enterprise, or Teleport Cloud) + + + +- A Teleport cluster running on Kubernetes, version >= + v(=kubernetes.major_version=).(=kubernetes.minor_version=).0. We will assume + that you have followed the + [Kubernetes with SSO](../getting-started/cluster.mdx) guide + +- The `jq` tool to process `JSON` output. This is available via common package managers + +- An additional Kubernetes cluster version >= + v(=kubernetes.major_version=).(=kubernetes.minor_version=).0 + +- Helm >= (=helm.version=) (!docs/pages/includes/helm.mdx!) + + + + +- A Teleport cluster running on Kubernetes, version >= + v(=kubernetes.major_version=).(=kubernetes.minor_version=).0. We will assume + that you have followed the + [Kubernetes with SSO](../getting-started/cluster.mdx) guide + +- The `jq` tool to process `JSON` output. This is available via common package managers + +- An additional Kubernetes cluster version >= + v(=kubernetes.major_version=).(=kubernetes.minor_version=).0 + +- Helm >= (=helm.version=) + +(!docs/pages/includes/helm.mdx!) + + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial + +- The Teleport Kubernetes Service running in a Kubernetes cluster, version >= + v(=kubernetes.major_version=).(=kubernetes.minor_version=).0. We will assume + that you have already followed + [Connect a Kubernetes Cluster to Teleport](../getting-started/agent.mdx) + +- The `jq` tool to process `JSON` output. This is available via common package + managers + +- The Enterprise version of the `tctl` admin tool. To download this, visit +the [customer portal](https://dashboard.gravitational.com/web/login) + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + +- An additional Kubernetes cluster version >= + v(=kubernetes.major_version=).(=kubernetes.minor_version=).0 + +- Helm >= (=helm.version=) + +(!docs/pages/includes/helm.mdx!) + + + + + ## Connecting clusters + + + Teleport can act as an access plane for multiple Kubernetes clusters. -We have set up the Teleport cluster `tele.example.com` in [SSO and Kubernetes](../getting-started.mdx). -Let's start a lightweight agent in another Kubernetes cluster `cookie` and connect it to `tele.example.com`. +We will assume that the domain of your Teleport cluster is `tele.example.com`. + +Let's start a lightweight agent in another Kubernetes cluster `cookie` and +connect it to `tele.example.com`. We will need a join token from `tele.example.com`: @@ -33,12 +105,11 @@ $ echo $TOKEN Switch `kubectl` to the Kubernetes cluster `cookie` and run: ```code -# Add teleport chart repository +# Add Teleport chart repository $ helm repo add teleport https://charts.releases.teleport.dev # Deploy a Kubernetes agent. It dials back to the Teleport cluster tele.example.com. $ CLUSTER='cookie' -# For Cloud users this will be similar to mytenant.teleport.sh $ PROXY='tele.example.com:443' $ helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \ --set proxyAddr=${PROXY?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent @@ -57,8 +128,61 @@ $ tsh kube ls # kubeconfig now points to the cookie cluster $ tsh kube login cookie -# Logged into kubernetes cluster "cookie" +# Logged into Kubernetes cluster "cookie" -# kubectl command executed on `cookie` but is routed through `tele.example.com` cluster. +# kubectl command executed on `cookie` but is routed through the `tele.example.com` cluster. $ kubectl get pods ``` + + + + +Teleport can act as an access plane for multiple Kubernetes clusters. + +We will assume that the domain of your Teleport cluster is `mytenant.teleport.sh`. + +Let's start a lightweight agent in another Kubernetes cluster `cookie` and +connect it to `mytenant.teleport.sh`. + +We will need a join token from `mytenant.teleport.sh`: + +```code +# Create a join token for the cluster cookie to authenticate +$ TOKEN=$(tctl nodes add --roles=kube --ttl=10000h --format=json | jq -r '.[0]') +$ echo $TOKEN +``` + +Switch `kubectl` to the Kubernetes cluster `cookie` and run: + +```code +# Add Teleport chart repository +$ helm repo add teleport https://charts.releases.teleport.dev + +# Deploy a Kubernetes agent. It dials back to the Teleport cluster mytenant.teleport.sh. +$ CLUSTER='cookie' +$ PROXY='mytenant.teleport.sh' +$ helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \ + --set proxyAddr=${PROXY?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent +``` + +List connected clusters using `tsh kube ls` and switch between +them using `tsh kube login`: + +```code +$ tsh kube ls + +# Kube Cluster Name Selected +# ----------------- -------- +# cookie +# mytenant.teleport.sh * + +# kubeconfig now points to the cookie cluster +$ tsh kube login cookie +# Logged into Kubernetes cluster "cookie" + +# kubectl command executed on `cookie` but is routed through the `mytenant.teleport.sh` cluster. +$ kubectl get pods +``` + + + diff --git a/docs/pages/kubernetes-access/guides/standalone-teleport.mdx b/docs/pages/kubernetes-access/guides/standalone-teleport.mdx index 0e709cb571363..621d03f4b1d46 100644 --- a/docs/pages/kubernetes-access/guides/standalone-teleport.mdx +++ b/docs/pages/kubernetes-access/guides/standalone-teleport.mdx @@ -1,30 +1,93 @@ --- -title: Kubernetes Access from standalone Teleport +title: Kubernetes Access from a Standalone Teleport Cluster description: Connecting standalone Teleport installations to Kubernetes clusters. --- -## Standalone Teleport installation - -Teleport can connect to external Kubernetes clusters without using the Teleport Helm chart or running a pod inside of the Kubernetes cluster. To do this, Teleport needs a `kubeconfig` file to authenticate against the Kubernetes API. +Teleport can connect to external Kubernetes clusters without using the Teleport +Helm chart or running a pod inside of the Kubernetes cluster. To do this, +Teleport needs a `kubeconfig` file to authenticate against the Kubernetes API. (!docs/pages/includes/permission-warning.mdx!) -## Generating kubeconfig +## Prerequisites + + + + +- A running Teleport cluster. For details on how to set this up, see one of our + [Getting Started](../../getting-started.mdx) guides. + +- **Optional:** the `tctl` admin tool version >= (=teleport.version=). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + See [Installation](../../installation.mdx) for details. + + (!docs/pages/includes/tctl.mdx!) + + + + +- A running Teleport cluster. For details on how to set this up, see one of our + [Getting Started](../../getting-started.mdx) guides. + +- **Optional:** the `tctl` admin tool version >= (=teleport.version=), which you can download + by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- A host deployed on your own infrastructure to run the Teleport Kubernetes + Service. See [Installing Teleport](../../installation.mdx) for more details. + +- **Optional:** the Enterprise version of the `tctl` admin tool. To download this, visit +the [customer portal](https://dashboard.gravitational.com/web/login). -First, configure your local `kubectl` command to point at the Kubernetes -cluster you want to register. You can use `kubectl config get-contexts` to -verify that the correct cluster is selected, or `kubectl config use-context -${CONTEXT_NAME?}` to switch to cluster `CONTEXT_NAME`. + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + + + + +## Step 1/2. Generate a kubeconfig + +First, configure your local `kubectl` command to point at the Kubernetes cluster +you want to register. You can use `kubectl config get-contexts` to verify that +the correct cluster is selected, or `kubectl config use-context ${CONTEXT_NAME?}` +to switch to cluster `CONTEXT_NAME`. Next, use [get-kubeconfig.sh](https://github.com/gravitational/teleport/blob/master/examples/k8s-auth/get-kubeconfig.sh) to create a `kubeconfig` for Teleport to use. You can connect multiple Kubernetes clusters to Teleport from one `kubeconfig` if it contains multiple entries. Use [merge-kubeconfigs.sh](https://github.com/gravitational/teleport/blob/master/examples/k8s-auth/merge-kubeconfigs.sh) to combine multiple `kubeconfigs` generated by `get-kubeconfig.sh`. -## Adding kubeconfig to Teleport +## Step 2/2. Add your kubeconfig to Teleport -In your Teleport Proxy or a new separate instance, add the following to -`teleport.yaml`: + + + +In your Teleport Proxy, add the following to `teleport.yaml`, replacing +`example.com` with the domain name of your Teleport cluster: ```yaml # ... @@ -43,6 +106,24 @@ kubernetes_service: kubeconfig_file: "path/to/kubeconfig" ``` + + + +On the host you will use to run the Teleport Kubernetes Service, add the +following to `teleport.yaml`. + +```yaml +# ... +kubernetes_service: + enabled: yes + listen_addr: 0.0.0.0:3027 + # Replace this path with the actual path for your generated kubeconfig + kubeconfig_file: "path/to/kubeconfig" +``` + + + + When using `kubeconfig_file`, EKS users may need to replace illegal characters in the `context` names. Supported characters are alphanumeric characters, `.`, `_`, and `-`. EKS typically includes `:` and `@` diff --git a/docs/pages/kubernetes-access/introduction.mdx b/docs/pages/kubernetes-access/introduction.mdx index 792a420eccbb3..760e95479170b 100644 --- a/docs/pages/kubernetes-access/introduction.mdx +++ b/docs/pages/kubernetes-access/introduction.mdx @@ -5,8 +5,8 @@ description: Teleport Kubernetes Access introduction, demo, and resources. Teleport provides secure access for Kubernetes clusters. -- Users can receive short-lived kubeconfigs (and certificates) using Single Sign-On (SSO) and switch between clusters without logging in twice. -- Admins can use *roles* to implement policies like the best practice that *developers must not access production* and enforce dual authorization using [access requests](../enterprise/workflow/index.mdx) for privileged operations. +- Users can receive short-lived kubeconfig files (and certificates) using Single Sign-On (SSO) and switch between clusters without logging in twice. +- Admins can use roles to implement policies, such as the best practice that developers must not access production. - Organizations can achieve compliance by capturing `kubectl` events and session recordings for `kubectl`. ## SSO and Audit for Kubernetes Clusters @@ -33,7 +33,7 @@ Set up SSO, capture audit events, and sessions with Teleport running in a Kubern ## Getting started -Configure Kubernetes Access in a 10 minute [Getting Started](./getting-started.mdx) guide. +Configure Kubernetes Access in a ten-minute [Getting Started](./getting-started.mdx) guide. ## Guides