Simplifying FedRAMP Compliance with Teleport
Jun 27
Register Today
Teleport logoTry For Free
Fork me on GitHub


Deploy Login Rules using Kubernetes Operator

This guide will explain how to:

  • Use Teleport's Kubernetes Operator to deploy Login Rules to your Teleport cluster
  • Edit deployed Login Rules with kubectl

This guide is applicable if you self-host Teleport in Kubernetes using the teleport-cluster Helm chart.


  • A Teleport Enterprise license

  • A 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


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

    minikube start
  • Follow the Teleport operator guides to install the Teleport Operator in your Kubernetes cluster. Make sure to follow the Enterprise instructions if you're deploying the operator as part of the teleport-cluster chart.

    Confirm that the CRD (Custom Resource Definition) for Login Rules has been installed with the following command:

    kubectl explain TeleportLoginRule.spec
    KIND: TeleportLoginRuleVERSION:
    RESOURCE: spec <Object>
    DESCRIPTION: LoginRule resource definition v1 from Teleport
    FIELDS: priority <integer> Priority is the priority of the login rule relative to other login rules in the same cluster. Login rules with a lower numbered priority will be evaluated first.
    traits_expression <string> TraitsExpression is a predicate expression which should return the desired traits for the user upon login.
    traits_map <> TraitsMap is a map of trait keys to lists of predicate expressions which should evaluate to the desired values for that trait.

    If this fails, you may not have installed the Teleport Operator, or you may have installed an older version. The minimum version for Login Rule support is v12.1.5.

Step 1/2. Create a Login Rule using kubectl

Paste the following into a file called login-rules.yaml that describes two custom Login Rule resources:

# login-rules.yaml
kind: TeleportLoginRule
  name: example-traits-map-rule
    example: "true"
  # The rule with the lowest priority will be evaluated first.
  priority: 0

  # traits_map holds a map of all desired trait keys to lists of expressions
  # that determine the trait values.

    # The "logins" traits will be set to the external "username" trait converted
    # to lowercase, and any external "logins" trait.
      - 'strings.lower(external.username)'
      - 'external.logins'

    # The external "groups" trait will be passed through unchanged, all other
    # traits will be filtered out.
      - external.groups
kind: TeleportLoginRule
  name: example-traits-expression-rule
    example: "true"
  # This rule has a higher priority value, so it will be evaluated after the
  # "terraform-test-map-rule".
  priority: 1

  # traits_expression is an alternative to traits_map, which returns all desired
  # traits in a single expression.
  traits_expression: |
        option(external.groups.contains("admins"), external.groups.add("app-admins", "db-admins")),
        option(external.groups.contains("ops"), external.groups.add("k8s-admins")),
        option(true, external.groups)))

Create the Kubernetes resources:

kubectl apply -f login-rules.yaml

List the created Kubernetes resources:

kubectl get loginrules
NAME AGEexample-traits-expression-rule 8m8sexample-traits-map-rule 8m8s

Check that the Login Rules have been created in Teleport:

AUTH_POD=$(kubectl get pods -l app=teleport-cluster -o jsonpath='{.items[0]}')
kubectl exec -i $AUTH_POD -c teleport -- tctl get login_rules
kind: login_rulemetadata: id: 1680225062340767900 labels: example: "true" kubernetes name: example-traits-expression-rulespec: priority: 1 traits_expression: | external.put("groups", choose( option(external.groups.contains("admins"),external.groups.add("app-admins", "db-admins")), option(external.groups.contains("ops"),external.groups.add("k8s-admins")), option(true, external.groups)))version: v1---kind: login_rulemetadata: id: 1680225067068319000 labels: example: "true" kubernetes name: example-traits-map-rulespec: priority: 0 traits_map: groups: - external.groups logins: - strings.lower(external.username) - external.loginsversion: v1

Test the Login Rules by sending some example input traits to the standard input of the tctl login_rule test command and having it load all Login Rules from the cluster.

echo '{"groups": ["admins", "ops"], "username": ["Alice"], "logins": ["user", "root"]}' | \ kubectl exec -i $AUTH_POD -c teleport -- tctl login_rule test --load-from-cluster
groups:- admins- ops- app-admins- db-adminslogins:- alice- user- root

Step 2/2. Edit the Login Rules with kubectl

Edit the example-traits-map-rule to add an extra login example login.

--- a/login-rules.yaml
+++ b/login-rules.yaml
@@ -18,6 +18,7 @@ spec:
       - 'strings.lower(external.username)'
       - 'external.logins'
+      - 'example'

     # The external "groups" trait will be passed through unchanged, all other
     # traits will be filtered out.

Apply the update to the Kubernetes resource:

kubectl apply -f login-rules.yaml

Test the Login Rules again to see the extra example login:

echo '{"groups": ["admins", "ops"], "username": ["Alice"], "logins": ["user", "root"]}' | \ kubectl exec -i $AUTH_POD -c teleport -- tctl login_rule test --load-from-cluster
groups:- ops- app-admins- db-admins- adminslogins:- root- user- example- alice

Next Steps