Fork me on GitHub


Teleport Kubernetes Operator (Preview)


Teleport Kubernetes Operator is currently in Preview mode.

The Teleport Kubernetes Operator provides a way for Kubernetes users to manage some Teleport resources through Kubernetes, following the Operator Pattern.

The Teleport Kubernetes Operator is deployed alongside its custom resource definitions. Once deployed, users can use a Kubernetes client like kubectl or their existing CI/CD Kubernetes pipelines to create Teleport custom resources. The Teleport Kubernetes Operator watches for those resources and does API calls to Teleport to reach the desired state.

Currently supported Teleport resources are:

  • users
  • roles

This guide covers how to:

  • Install Teleport Operator on Kubernetes.
  • Manage Teleport users and roles using Kubernetes.


  • A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.

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

    tctl version

    Teleport v11.3.1 go1.19

    tsh version

    Teleport v11.3.1 go1.19

    See Installation for details.

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

  • The tctl admin tool and tsh client tool version >= 11.3.1, which you can download by visiting the customer portal.

    tctl version

    Teleport v11.3.1 go1.19

    tsh version

    Teleport v11.3.1 go1.19

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 11.2.1. To download these tools, visit the Downloads page.

    tctl version

    Teleport v11.2.1 go1.19

    tsh version

    Teleport v11.2.1 go1.19

  • Kubernetes cluster (with or without teleport-cluster Helm chart already deployed);
  • Helm
  • kubectl

Validate Kubernetes connectivity by running the following command:

kubectl cluster-info

Kubernetes control plane is running at

CoreDNS is running at

Metrics-server is running at


Users wanting to experiment locally with the operator can use minikube to start a local Kubernetes cluster:

minikube start

Step 1/3. Install teleport-cluster Helm chart with the operator

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

helm repo add teleport

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

helm repo update

Install the Helm chart for the Teleport Cluster with operator.enabled=true:

helm install teleport-cluster teleport/teleport-cluster \ --create-namespace --namespace teleport-cluster \ --set clusterName=teleport-cluster.teleport-cluster.svc.cluster.local \ --set operator.enabled=true \ --version 11.3.1

Create a namespace for your Teleport cluster resources:

kubectl create namespace teleport-cluster

Obtain your Teleport Enterprise license file from the Teleport Customer Portal. Create a secret called "license" in the namespace you created:

kubectl -n teleport-cluster create secret generic license --from-file=license.pem

Deploy your Teleport cluster and the Teleport Kubernetes Operator:

helm install teleport-cluster teleport/teleport-cluster \ --namespace teleport-cluster \ --set enterprise=true \ --set clusterName=teleport-cluster.teleport-cluster.svc.cluster.local \ --set operator.enabled=true \ --version 11.3.1

This command installs the required Kubernetes CRDs and deploys the Teleport Kubernetes Operator next to the Teleport cluster. All resources (except CRDs, which are cluster-scoped) are created in the teleport-cluster namespace.

All subsequent commands will take place in the teleport-cluster namespace, so let's use it by default:

kubectl config set-context --current --namespace teleport-cluster

Step 2/3. Manage Teleport users and roles using kubectl

Create a manifest called teleport-resources.yaml that describes two custom resources: a TeleportUser and a TeleportRole:

kind: TeleportRole
  name: myrole
      - resources: ['user', 'role']
        verbs: ['list','create','read','update','delete']
kind: TeleportUser
  name: myuser
  roles: ['myrole']

Apply the manifests to the Kubernetes cluster:

kubectl apply -f teleport-resources.yaml

List the created Kubernetes resources:

kubectl get teleportroles


myrole 10m

kubectl get teleportusers


myuser 10m

Check the user myuser has been created in Teleport and has been granted the role myrole:

PROXY_POD=$(kubectl get po -l app=teleport-cluster -o jsonpath='{.items[0]}')
kubectl exec -it "$PROXY_POD" -c teleport -- tctl users ls

User Roles

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

bot-teleport-operator-sidecar bot-teleport-operator-sidecar

myuser myrole

At this point the Teleport Kubernetes Operator is functional and Teleport users and roles can be managed from Kubernetes.

Step 3/3. Explore the Teleport CRDs

Available fields can be browsed with kubectl explain in a cluster with Teleport CRDs installed. For example the command:

kubectl explain teleportroles.spec

Returns the following fields:

KIND:     TeleportRole

RESOURCE: spec <Object>

    Role resource definition v5 from Teleport

   allow	<Object>
     Allow is the set of conditions evaluated to grant access.

   deny	<Object>
     Deny is the set of conditions evaluated to deny access. Deny takes priority
     over allow.

   options	<Object>
     Options is for OpenSSH options like agent forwarding.


Resource is not reconciled in Teleport

The Teleport Operator watches for new resources or changes in Kubernetes. When a change happens, it triggers the reconciliation loop. This loop is in charge of validating the resource, checking if it already exists in Teleport and making calls to the Teleport API to create/update/delete the resource. The reconciliation loop also adds a status field on the Kubernetes resource.

If an error happens and the reconciliation loop is not successful, an item in status.conditions will describe what went wrong. This allows users to diagnose errors by inspecting Kubernetes resources with kubectl:

kubectl get teleportusers myuser -o yaml

For example, if a user has been granted a nonexistent role the status will look like:

kind: TeleportUser
# [...]
  - lastTransitionTime: "2022-07-25T16:15:52Z"
    message: Teleport resource has the Kubernetes origin label.
    reason: OriginLabelMatching
    status: "True"
    type: TeleportResourceOwned
  - lastTransitionTime: "2022-07-25T17:08:58Z"
    message: 'Teleport returned the error: role my-non-existing-role is not found'
    reason: TeleportError
    status: "False"
    type: SuccessfullyReconciled

Here SuccessfullyReconciled is False and the error is role my-non-existing-role is not found.

If the status is not present or does not give sufficient information to solve the issue, check the operator logs:

$ kubectl logs "$PROXY_POD" -c operator

In case of multi-replica deployments, only one operator instance is running the reconciliation loop. This operator is called the leader and is the only one producing reconciliation logs. The other operator instances are waiting with the following log:

leaderelection.go:248] attempting to acquire leader lease teleport/

To diagnose reconciliation issues, you will have to inspect all pods to find the one reconciling the resources.

Next Steps

Helm Chart parameters are documented in the teleport-cluster Helm chart reference.

See the Helm Deployment guides detailing specific setups like running teleport on AWS or GCP.

Check out access controls documentation