Fork me on GitHub

Teleport

Connect a Kubernetes Cluster to Teleport

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise
Getting Started With Teleport 12 | Kubernetes Edition

Getting Started With Teleport 12 | Kubernetes Edition

Length: 14:35

In this guide, we will show you how to register a Kubernetes cluster with Teleport by deploying the Teleport Kubernetes Service on the Kubernetes cluster you want to register.

In this setup, the Teleport Kubernetes Service pod detects that it is running on Kubernetes and registers the cluster automatically.

You can also run the Teleport Kubernetes Service on a Linux host in a separate network from your Kubernetes cluster. Learn how in Kubernetes Access from a Standalone Teleport Cluster.

Prerequisites

  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.0.0.

    You can download these tools by visiting your Teleport account workspace.

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 14.0.0.

    See Installation for details.

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.0.0.

    You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21


tsh version

Teleport v13.3.9 go1.21

Proxy version: 13.3.9Proxy: teleport.example.com
  • Kubernetes >= 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+"}

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 14.0.0

    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.

Deployment overview

In this guide, we deploy the Teleport Kubernetes Service, which connects a Kubernetes cluster to a Teleport cluster:

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.

Step 1/3. Get a join token

In order to start the Teleport Kubernetes Service, we will need to request a join token from the Teleport Auth Service:

Create a join token for the Teleport Kubernetes Service to authenticate

TOKEN=$(tctl tokens add --type=kube,app,discovery --ttl=1h --format=text)
echo $TOKEN

Step 2/3. Deploy teleport-kube-agent

The Teleport Kubernetes Service version should be the same as the Teleport Cluster version or up to one major version back. You can set the version override with the override variable, ex: --set teleportVersionOverride=14.0.0.

To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add:

helm repo add teleport https://charts.releases.teleport.dev

To update the cache of charts from the remote repository, run helm repo update:

helm repo update

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.

PROXY_ADDR=teleport.example.com:443
CLUSTER=cookie

Create the values.yaml file

cat > values.yaml << EOFauthToken: "${TOKEN}"proxyAddr: "${PROXY_ADDR}"roles: "kube,app,discovery"joinParams: method: "token" tokenName: "${TOKEN}"kubeClusterName: "${CLUSTER}"EOF

Install the helm chart with the values.yaml setting

helm install teleport-agent teleport/teleport-kube-agent \ -f values.yaml \ --create-namespace \ --namespace=teleport-agent \ --version 14.0.0

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.

PROXY_ADDR=teleport.example.com:443
CLUSTER=cookie

Create the values.yaml file

cat > values.yaml << EOFauthToken: "${TOKEN}"proxyAddr: "${PROXY_ADDR}"roles: "kube,app,discovery"joinParams: method: "token" tokenName: "${TOKEN}"kubeClusterName: "${CLUSTER}"enterprise: trueEOF

Install the helm chart with the values.yaml setting

helm install teleport-agent teleport/teleport-kube-agent \ -f values.yaml \ --create-namespace \ --namespace=teleport-agent \ --version 14.0.0
Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

Make sure that the Teleport agent pod is running. You should see one Teleport agent pod pod with a single ready container:

kubectl -n teleport get pods
NAME READY STATUS RESTARTS AGEteleport-agent-0 1/1 Running 0 32s

Step 3/3 Access your Kubernetes cluster

Kubernetes authentication

To authenticate to a Kubernetes cluster via Teleport, your Teleport roles must allow access as at least one Kubernetes user or group. Ensure that you have a Teleport role that grants access to the cluster you plan to interact with.

Run the following command to get the Kubernetes user for your current context:

kubectl config view \-o jsonpath="{.contexts[?(@.name==\"$(kubectl config current-context)\")].context.user}"

Create a file called kube-access.yaml with the following content, replacing USER with the output of the command above.

kind: role
metadata:
  name: kube-access
version: v7
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_resources:
      - kind: '*'
        namespace: '*'
        name: '*'
        verbs: ['*']
    kubernetes_groups:
    - viewers
    kubernetes_users:
    # Replace USER with the Kubernetes user for your current context.
    - USER
  deny: {}

Apply your changes:

tctl create -f kube-access.yaml

Assign the kube-access role to your Teleport user by running the appropriate commands for your authentication provider:

  1. Retrieve your local user's configuration resource:

    tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
  2. Edit out.yaml, adding kube-access to the list of existing roles:

      roles:
       - access
       - auditor
       - editor
    +  - kube-access 
    
  3. Apply your changes:

    tctl create -f out.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

  1. Retrieve your github authentication connector:

    tctl get github/github --with-secrets > github.yaml

    Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.

  2. Edit github.yaml, adding kube-access to the teams_to_roles section.

    The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

    Here is an example:

      teams_to_roles:
        - organization: octocats
          team: admins
          roles:
            - access
    +       - kube-access
    
  3. Apply your changes:

    tctl create -f github.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

  1. Retrieve your saml configuration resource:

    tctl get --with-secrets saml/mysaml > saml.yaml

    Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.

  2. Edit saml.yaml, adding kube-access to the attributes_to_roles section.

    The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

    Here is an example:

      attributes_to_roles:
        - name: "groups"
          value: "my-group"
          roles:
            - access
    +       - kube-access
    
  3. Apply your changes:

    tctl create -f saml.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

  1. Retrieve your oidc configuration resource:

    tctl get oidc/myoidc --with-secrets > oidc.yaml

    Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.

  2. Edit oidc.yaml, adding kube-access to the claims_to_roles section.

    The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

    Here is an example:

      claims_to_roles:
        - name: "groups"
          value: "my-group"
          roles:
            - access
    +       - kube-access
    
  3. Apply your changes:

    tctl create -f oidc.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

Now that Teleport RBAC is configured, you can authenticate to your Kubernetes cluster via Teleport. To interact with your Kubernetes cluster, you will need to configure authorization within Kubernetes.

Kubernetes authorization

To configure authorization within your Kubernetes cluster, you need to create Kubernetes RoleBindings or ClusterRoleBindings that grant permissions to the subjects listed in kubernetes_users and kubernetes_groups.

For example, you can grant some limited read-only permissions to the viewers group used in the kube-access role defined above:

Create a file called viewers-bind.yaml with the following contents:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: viewers-crb
subjects:
- kind: Group
  # Bind the group "viewers", corresponding to the kubernetes_groups we assigned our "kube-access" role above
  name: viewers
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  # "view" is a default ClusterRole that grants read-only access to resources
  # See: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles
  name: view
  apiGroup: rbac.authorization.k8s.io

Apply the ClusterRoleBinding with kubectl:

kubectl apply -f viewers-bind.yaml

Log out of Teleport and log in again.

View pods in your cluster

List connected clusters using tsh kube ls and switch between them using tsh kube login:

tsh kube ls

Kube Cluster Name Selected

----------------- --------

cookie


kubeconfig now points to the cookie cluster

tsh kube login cookie

Logged into kubernetes cluster "cookie". Try 'kubectl version' to test the connection.


kubectl command executed on `cookie` but is routed through the Teleport cluster.

kubectl get pods

Next Steps