# Workload Clusters

`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](https://goteleport.com/docs/ver/19.x/reference/deployment/join-methods.md#aws-iam-role-iam).

- A Teleport Cloud cluster to use as the parent cluster.

---

FEATURE AVAILABILITY

Teleport Cloud customers must contact support at [](mailto:support@goteleport.com)<support@goteleport.com> to enable the workload cluster feature.

---

- `tctl` and `tbot` installed. For installation and deployment guidance, see the [Machine & Workload Identity deployment guides](https://goteleport.com/docs/ver/19.x/machine-workload-identity/deployment.md).
- 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](https://goteleport.com/docs/ver/19.x/reference/architecture/teleport-cloud-architecture.md#auth-service) 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 [](mailto:support@goteleport.com)<support@goteleport.com> 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](https://goteleport.com/docs/ver/19.x/zero-trust-access/api.md) and [Getting Started with the Teleport API](https://goteleport.com/docs/ver/19.x/zero-trust-access/api/getting-started.md).

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.

1. 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
   ```

2. Clone the Teleport repository:

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

3. Navigate to the workload clusters example:

   ```
   $ cd ./teleport/examples/workload-clusters/
   ```

4. 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`.

5. 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](https://goteleport.com/docs/ver/19.x/reference/infrastructure-as-code/teleport-resources/workload-cluster.md) for the complete schema.
- Read the [Machine & Workload Identity configuration reference](https://goteleport.com/docs/ver/19.x/reference/machine-workload-identity/configuration.md) for more `tbot` options.
- Review the [role resource reference](https://goteleport.com/docs/ver/19.x/reference/infrastructure-as-code/teleport-resources/role.md) to define more precise RBAC in parent and child Teleport Cloud clusters.