Skip to content

Latest commit

 

History

History
199 lines (145 loc) · 6.37 KB

static-kubeconfig.mdx

File metadata and controls

199 lines (145 loc) · 6.37 KB
title description
Register a Kubernetes Cluster with a Static kubeconfig
Connecting standalone Teleport installations to Kubernetes clusters.

While you can register a Kubernetes cluster with Teleport by running the Teleport Kubernetes Service on that cluster, you can also run the Teleport Kubernetes Service on a Linux host outside the cluster. This is useful if you want to decouple your Teleport deployment from the Kubernetes clusters you want to manage access to.

In this setup, the Teleport Kubernetes Service uses a kubeconfig file to authenticate to the API server of your chosen Kubernetes cluster.

(!docs/pages/includes/permission-warning.mdx!)

Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

  • A Kubernetes cluster you would like to access.
  • A Linux host deployed on your own infrastructure to run the Teleport Kubernetes Service. This can run outside of your Kubernetes cluster.
  • The kubectl command line tool installed on your workstation.
  • (!docs/pages/includes/tctl.mdx!)

Step 1/4. Generate a kubeconfig file

The Teleport Kubernetes Service uses a kubeconfig file to authenticate to your Kubernetes cluster. In this section, we will generate a kubeconfig file so we can configure the Teleport Kubernetes Service to use it later in this guide.

Ensure your context is correct

First, configure your local kubectl command to point at the Kubernetes cluster you want to register. You can use the following command to verify that the correct cluster is selected:

$ kubectl config get-contexts

Use this command to switch to the cluster assigned to :

# e.g., my-context
$ kubectl config use-context <Var name="context-name" />}

Run the script

On your workstation, download Teleport's get-kubeconfig.sh script, which you will use to generate the kubeconfig file:

$ curl -OL \
https://raw.githubusercontent.com/gravitational/teleport/v(=teleport.version=)/examples/k8s-auth/get-kubeconfig.sh

get-kubeconfig.sh creates a service account for the Teleport Kubernetes Service that can get Kubernetes pods as well as impersonate users, groups, and other service accounts. The Teleport Kubernetes Service uses this service account to manage access to resources in your Kubernetes cluster. The script also ensures that there is a Kubernetes Secret in your cluster to store service account credentials.

get-kubeconfig.sh also creates a namespace called teleport for the resources it deploys, though you can choose a different name by assigning the TELEPORT_NAMESPACE environment variable in the shell where you run the script.

After creating resources, get-kubeconfig.sh writes a new kubeconfig file called kubeconfig in the directory where you run the script.

Run the get-kubeconfig.sh script:

$ bash get-kubeconfig.sh

The script is successful if you see this message:

Done!

Move the kubeconfig file to the host you are using to run the Teleport Kubernetes Service. We will assume that the kubeconfig file exists at /var/lib/teleport/kubeconfig.

You can connect multiple Kubernetes clusters to Teleport from one kubeconfig file if it contains multiple entries. Use merge-kubeconfigs.sh to combine multiple kubeconfig files generated by get-kubeconfig.sh.

Step 2/4. Set up the Teleport Kubernetes Service

In this step, you will install the Teleport Kubernetes Service and configure it to use the kubeconfig file you generated to access a Kubernetes cluster.

Get a join token

Establish trust between your Teleport cluster and your new Kubernetes Service instance by creating a join token:

$ tctl tokens add --type=kube --format=text --ttl=1h
(=presets.tokens.first=)

Assign to your join token. On the host where you are running the Teleport Kubernetes Service, create a file called /tmp/token that consists only of your token:

$ echo <Var name="join-token" /> | sudo tee /tmp/token

Install the Teleport Kubernetes Service

Run the following commands on the host where you will install the Teleport Kubernetes Service:

(!docs/pages/includes/install-linux.mdx!)

Configure the Teleport Kubernetes Service

Assign with the host and port of your Teleport Proxy Service or Teleport Cloud tenant, e.g., mytenant.teleport.sh:443. On the host where you will run the Teleport Kubernetes Service, create a file at /etc/teleport.yaml with the following content:

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: <Var name="teleport.example.com:443" />
auth_service:
  enabled: off
proxy_service:
  enabled: off
ssh_service:
  enabled: off
kubernetes_service:
  enabled: "yes"
  kubeconfig_file: "/var/lib/teleport/kubeconfig"
  labels:
    "region": "us-east1"

When using kubeconfig_file, Amazon EKS users may need to replace illegal characters in the context names. Supported characters are alphanumeric characters, ., _, and -. EKS typically includes : and @ in their kubeconfig files, which are not allowed in Teleport.

Start the Teleport Kubernetes Service

(!docs/pages/includes/start-teleport.mdx service="the Teleport Kubernetes Service"!)

Step 3/4. Grant access to your Teleport user

Enable your Teleport user to access resources in your Kubernetes cluster so you can connect to the cluster later in this guide.

(!docs/pages/includes/kubernetes-access/rbac.mdx!)

Step 4/4. Access your Kubernetes cluster

After Teleport starts with the above config, you should be able to see all new clusters:

$ tsh kube ls
Kube Cluster Name                       Labels           Selected
--------------------------------------- ------           --------
my-cluster                              region=us-east-1

To access your cluster, run the following command, replacing my-cluster with the name of the cluster you would like to access:

$ tsh kube login my-cluster
Logged into kubernetes cluster "my-cluster". Try 'kubectl version' to test the connection.