Skip to main content

Managing Scoped Resources using IaC

Report an Issue

In this guide, you will run Infrastructure-As-Code (IaC) tools in scoped mode and use them to reconcile scoped resources.

See the Scoped RBAC page for more details about scopes.

Active development

Scopes are an actively developed feature of Teleport. Not every Teleport feature is supported within a scope yet, and breaking changes may still be introduced. Scoped resources and credentials created with one Teleport version may not work with another.

When operating in a scoped session, commands and APIs that have not yet been updated to understand scopes will commonly fail with a scoped identities not supported error. This is expected for features outside the currently supported set listed below.

How it works​

Scopes are a hierarchical organization system for Teleport resources and permissions. A scope is a path-like attribute (for example /staging/west or /prod) attached to resources and permission grants. Permissions assigned at a scope apply to resources within that scope and all of its descendant scopes, but cannot reach across to orthogonal scopes or up to ancestor scopes.

In this guide, you will grant access to the /test scope to the IaC tools. The tool will be able to manage the content of the /test scope, but will not be allowed to create resources in other scopes such as /example.

Operator scope restriction

The Teleport Kubernetes operator is currently restricted to its own scope. It cannot write resources in nested scopes of its own.

For example: An operator in the /test scope cannot manage resources in the /test/sub scope.

It can still grant roles in nested scopes by specifying nested scopes as scoped_role_assignment targets.

Prerequisites​

  • A running Teleport cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025
  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email@example.com to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=email@example.com
      tctl status
      Cluster  teleport.example.com
      Version  19.0.0-dev
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    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.
  • All Teleport instances (Auth Service, Proxy Service, and Agents) must be running the same Teleport version, and must have the TELEPORT_UNSTABLE_SCOPES=yes environment variable set.
  • The Auth Service must also have the TELEPORT_UNSTABLE_AGENT_SCOPE_PIN=yes environment variable set before you use scoped tokens to join Agent roles other than SSH Services (node) and Bots. This includes scoped Kubernetes Services and Application Services.

No additional prerequisites.

Step 1/4. Grant scoped access to IaC tool​

In this step, you will create the required Scoped RBAC and other Teleport resources so that the IaC tool can connect to Teleport and managed scoped resources in the /test scope.

The user already has access to the / scope as per the prerequisites.

Step 2/4. Deploy the IaC tool​

In this step, you will configure and deploy the IaC tool if applicable.

Validate that tctl works by running:

tctl status

Then, validate that you have permissions to list scoped resources:

tctl get scoped_role --format=text

tctl get scoped_role_assignment --format=text

The commands should not return permission errors.

Step 3/4. Create the scoped resource using IaC​

In this step, you will create scoped resources in the /test scope, allowing a /test::server-enroller fictive service to create scoped tokens in /test/team-a and /test/team-b scopes.

You will configure 4 resources using IaC:

  • a scoped_role /test::token-creator that allows token creation and can be granted in /test/** nested scopes
  • a bot /test::server-enroller that will be used by the fictive service to create tokens and enroll servers
  • a scoped_role_assignment /test::server-enroller that grants the scoped role /test::token-creatorto the bot inside the /test/team-a and /test/team-b
  • a scoped_token /test::server-enroller that allows the bot to join from a Kubernetes cluster

Create the following scoped-resources.yaml manifest:

kind: scoped_role
version: v1
metadata:
  name: "token-creator"
scope: "/test"
spec:
  assignable_scopes: ["/test/**"]
  rules:
    - resources: ["scoped_token"]
      verbs    : ["read", "list", "create", "update", "delete"]
---
kind: bot
version: v1
metadata:
  name: "server-enroller"
scope: "/test"
spec: {}
---
kind: scoped_role_assignment
sub_kind: dynamic
version: v1
metadata:
  name: "server-enroller"
scope: "/test"
spec:
  assignments:
  - role: "/test::token-creator"
    scope: "/test/team-a"
  - role: "/test::token-creator"
    scope: "/test/team-b"
  bot: "/test::server-enroller"
---
kind: scoped_token
version: v1
metadata:
  name: "server-enroller"
scope: "/test"
spec:
  bot: "/test::server-enroller"
  join_method: "kubernetes"
  kubernetes:
    allow:
      - service_account_name: "pod-sa"
        service_account_namespace: "default"
    oidc:
      # fake OIDC issuer, where the bot would run
      issuer: "https://kubernetes.example.com/cluster-a"
    type: "oidc"
  roles: ["Bot"]
  usage_mode: "bot"

Apply the manifests using tctl:

tctl create -f scoped-resources.yaml

scoped_role "/test::token-creator" has been upsertedBot "server-enroller" has been createdscoped_role_assignment "/test::server-enroller" has been upsertedscoped_token "server-enroller" has been updated

Step 4/4. Validate resources were created​

At this point, the scoped resources should have been created in Teleport. Validate that they were by running:

tctl get scoped_role --format=text

ID------------------------------------/::operator/::terraform-provider/test::token-creator
tctl get scoped_role_assignment --format=text

SubKind ID                       Assignee                      Assigns------- ------------------------ ----------------------------- --------------------------------------------------------------------------dynamic /test::operator          bot: /test::operator          /::operator -> /testdynamic /test::server-enroller   bot: /test::server-enroller   /test::token-creator -> /test/team-a, /test::token-creator -> /test/team-b
tctl get scoped_token --format=text

Token                  Type Assigns Scope  Labels                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     Expiry Time (UTC)---------------------- ---- -------------- ----------------------------------------------------------- ---------------------------------/test::operator        Bot                                                                             never/test::server-enroller Bot                 resources.teleport.dev/owner-email=your-name@example.com... never
tctl get bot --format=text

Name                     Roles------------------------ -----/test::operator/test::server-enroller