Version: 19.x (unreleased)

Workload Clusters

Is this page helpful?

workload_cluster resources can be used to automatically provision and deprovision Teleport Cloud clusters. When a workload cluster is created, Teleport Cloud also creates a Bot, token, and role in the provisioned Teleport Cloud cluster so that automation can create, read, and update users and roles in that cluster.

This guide covers how to:

Create a workload_cluster resource in a parent Teleport Cloud cluster.
Wait for the child Teleport Cloud cluster to become active.
Configure tbot to join the child Teleport Cloud cluster.
Use the identity generated by tbot to create, read, and update users and roles in the child Teleport Cloud cluster with tctl.

How it works

Creating a workload_cluster resource in a parent Teleport Cloud cluster tells Teleport Cloud to provision a child Teleport Cloud cluster.

A child Teleport Cloud cluster is a separate Teleport Cloud cluster whose lifecycle is managed from a parent Teleport Cloud cluster. It is not the same thing as a trusted cluster.

Changes to the parent Teleport Cloud cluster do not affect the child Teleport Cloud cluster. The parent Teleport Cloud cluster can only provision and deprovision child Teleport Cloud clusters.

When the child Teleport Cloud cluster is provisioned, Teleport Cloud also creates:

A Bot in the child Teleport Cloud cluster
A join token for that Bot
A role for that Bot

That Bot can then join the child Teleport Cloud cluster using IAM joining via tbot. The identity generated by tbot can be used to create, read, and update users and roles in the child Teleport Cloud cluster.

Prerequisites

This guide uses AWS IAM joining for the child Teleport Cloud cluster Bot because workload_cluster currently supports IAM joining only. Learn more about IAM joining in the join methods reference.

A Teleport Cloud cluster to use as the parent cluster.

Feature availability

Teleport Cloud customers must contact support at [email protected] to enable the workload cluster feature.

tctl and tbot installed. For installation and deployment guidance, see the Machine & Workload Identity deployment guides.
An AWS identity that matches the IAM join token rules configured for the child Teleport Cloud cluster Bot.

Step 1/5. Configure RBAC in the parent cluster

To create and delete workload_cluster resources, the Teleport user in the parent cluster needs permission to manage that resource type.

If the user already has access to manage workload_cluster resources, skip this step.

Create a file called workload-cluster-editor.yaml:

kind: role
version: v8
metadata:
  name: workload-cluster-editor
spec:
  allow:
    rules:
    - resources:
      - workload_cluster
      verbs:
      - create
      - delete
      - list
      - read
      - update

Use tctl to create the role:

tctl create -f workload-cluster-editor.yaml

Assign the role to a user in the parent cluster. Replace alice with the Teleport username and include any roles that user already needs:

tctl users update --set-roles editor,workload-cluster-editor alice

Step 2/5. Create a workload cluster

Create a file called workload-cluster.yaml:

kind: workload_cluster
version: v1
metadata:
  name: company-organization
spec:
  regions:
    - name: us-west-2
  bot:
    name: example-iam
  token:
    join_method: iam
    allow:
      - aws_account: "123456789012"
        aws_arn: "arn:aws:sts::123456789012:assumed-role/example-tbot-role/session-name"

Replace:

company-organization with the name of the Teleport Cloud cluster that Teleport Cloud should create.
us-west-2 with the Teleport Cloud region for the child Teleport Cloud cluster. See Teleport Cloud architecture for available auth regions.
example-iam with the Bot and token name that tbot will use.
123456789012 and arn:aws:sts::123456789012:assumed-role/example-tbot-role/session-name with values that match the AWS identity from which tbot will join.

Use tctl to create the resource in the parent cluster:

tctl --auth-server parent.teleport.sh:443 create -f workload-cluster.yaml

Immutable configuration

After creation, workload cluster configuration cannot be modified.

The Teleport Cloud cluster domain is derived from the resource name. In this example, the child Teleport Cloud cluster will use the domain company-organization.teleport.sh.

Step 3/5. Wait for the child Teleport Cloud cluster to become active

Retrieve the resource until the status.state field is active:

tctl --auth-server parent.teleport.sh:443 get workload_cluster/company-organization

Example output:

kind: workload_cluster
version: v1
metadata:
  name: company-organization
spec:
  regions:
    - name: us-west-2
  bot:
    name: example-iam
  token:
    join_method: iam
    allow:
      - aws_account: "123456789012"
        aws_arn: "arn:aws:sts::123456789012:assumed-role/example-tbot-role/session-name"
status:
  domain: company-organization.teleport.sh
  state: active

Once the resource is active, use the status.domain value when connecting tbot and tctl to the child Teleport Cloud cluster.

Step 4/5. Use `tbot` to join the child Teleport Cloud cluster

Create a file called tbot.yaml:

version: v2
oneshot: true
proxy_server: company-organization.teleport.sh:443
onboarding:
  join_method: iam
  token: example-iam
storage:
  type: memory
services:
  - type: identity
    destination:
      type: directory
      path: ./tbot-output

Replace:

company-organization.teleport.sh:443 with the child Teleport Cloud cluster's proxy address from status.domain.
example-iam with the Bot name from spec.bot.name.

Before running tbot, authenticate to AWS using an identity that satisfies the token's IAM join rules.

Then run tbot:

tbot start -c ./tbot.yaml

This writes an identity file to ./tbot-output/identity. Use that identity with tctl to create, read, and update users and roles in the child Teleport Cloud cluster.

Step 5/5. Manage users and roles in the child Teleport Cloud cluster

Create a role definition for the child Teleport Cloud cluster in child-role.yaml:

kind: role
version: v8
metadata:
  name: child-auditor
spec:
  allow:
    rules:
    - resources:
      - role
      - user
      verbs:
      - list
      - read

Create the role in the child Teleport Cloud cluster using the identity produced by tbot:

tctl --auth-server company-organization.teleport.sh:443 -i ./tbot-output/identity create -f child-role.yaml

Now create a user in the child Teleport Cloud cluster and assign the new role:

tctl --auth-server company-organization.teleport.sh:443 -i ./tbot-output/identity users add --roles child-auditor example-user

The same identity can also inspect roles in the child Teleport Cloud cluster:

tctl --auth-server company-organization.teleport.sh:443 -i ./tbot-output/identity get role/child-auditor

Delete the workload cluster

When the child Teleport Cloud cluster is no longer needed, remove the workload_cluster resource from the parent cluster:

tctl --auth-server parent.teleport.sh:443 rm workload_cluster/company-organization

After the workload_cluster resource is deleted, Teleport Cloud keeps the child Teleport Cloud cluster in a 14-day grace period. During that period, the cluster name cannot be reused. Contact support at [email protected] to restore access to the cluster or to request an expedited deletion.

Use the Go SDK instead of `tctl`

Teleport's Go SDK can be used to automate this workflow instead of relying on client tools such as tctl.

For general Teleport API guidance, see Using the Teleport API and Getting Started with the Teleport API.

Teleport's repository includes an example using the Go SDK that does the following:

Creates a Teleport API client connected to the parent Teleport Cloud cluster.
Creates a workload_cluster resource in the parent Teleport Cloud cluster.
Waits for the workload_cluster resource to report being active.
Uses the tbot binary to retrieve an identity file for the child Teleport Cloud cluster.
Creates a role and user in the child Teleport Cloud cluster.
Creates an invite link for the new user.
Deletes the workload_cluster resource in the parent Teleport Cloud cluster.

Please follow the below steps to run the workload cluster Go example.

Log in to the parent Teleport Cloud cluster (replace parent.teleport.sh with the Teleport Cloud cluster's address):
```
tsh login --proxy parent.teleport.sh
```

Clone the Teleport repository:

git clone --depth=1 https://github.com/gravitational/teleport

Navigate to the workload clusters example:
```
cd ./teleport/examples/workload-clusters/
```
Replace parent.teleport.sh, company-organization, account, and arn with the parent Teleport Cloud cluster address, desired workload cluster name, a valid AWS account ID, and a valid AWS ARN that tbot can use for IAM joining in main.go.
Authenticate to AWS using the identity referenced in the workload_cluster resource, then run the Go program:
```
go run ./
```

Next steps

Read the Workload Cluster resource reference for the complete schema.
Read the Machine & Workload Identity configuration reference for more tbot options.
Review the role resource reference to define more precise RBAC in parent and child Teleport Cloud clusters.

Was this page helpful?

How it works​

Prerequisites​

Step 1/5. Configure RBAC in the parent cluster​

Step 2/5. Create a workload cluster​

Step 3/5. Wait for the child Teleport Cloud cluster to become active​

Step 4/5. Use tbot to join the child Teleport Cloud cluster​

Step 5/5. Manage users and roles in the child Teleport Cloud cluster​

Delete the workload cluster​

Use the Go SDK instead of tctl​

Next steps​