diff --git a/docs/config.json b/docs/config.json index 2d12b4949b560..cd899f3b8c551 100644 --- a/docs/config.json +++ b/docs/config.json @@ -241,6 +241,16 @@ "destination": "/enroll-resources/machine-id/deployment/spacelift/", "permanent": true }, + { + "source": "/machine-id/access-guides/terraform/", + "destination": "/admin-guides/infrastructure-as-code/terraform-provider/dedicated-server/", + "permanent": true + }, + { + "source": "/enroll-resources/machine-id/deployment/terraform/", + "destination": "/admin-guides/infrastructure-as-code/terraform-provider/dedicated-server/", + "permanent": true + }, { "source": "/machine-id/deployment/aws/", "destination": "/enroll-resources/machine-id/deployment/aws/", @@ -1013,7 +1023,7 @@ }, { "source": "/machine-id/access-guides/terraform/", - "destination": "/enroll-resources/machine-id/access-guides/terraform/", + "destination": "/admin-guides/infrastructure-as-code/terraform-provider/dedicated-server/", "permanent": true }, { diff --git a/docs/cspell.json b/docs/cspell.json index 5a78458ef0a3c..daece02d4b15d 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -806,6 +806,7 @@ "rtrzn", "runcommand", "runscript", + "runtimes", "russellhaering", "russjones", "rwxr", diff --git a/docs/pages/admin-guides/infrastructure-as-code/managing-resources/import-existing-resources.mdx b/docs/pages/admin-guides/infrastructure-as-code/managing-resources/import-existing-resources.mdx new file mode 100644 index 0000000000000..0ca2464ec2a7b --- /dev/null +++ b/docs/pages/admin-guides/infrastructure-as-code/managing-resources/import-existing-resources.mdx @@ -0,0 +1,87 @@ +--- +title: Import Teleport Resources into Terraform +description: How to import your existing Teleport resources into Terraform +--- + +This guide shows you how to import existing dynamic Teleport resources as +Terraform resources. + +If you already created Teleport resources using another client tool like `tctl` +or the Kubernetes Operator, and want to manage all Teleport resources using your +Terraform configuration, follow these steps to generate a `.tf` file that +contains `resource` blocks that represent your existing Teleport resources. + +By defining all Teleport resources in one place, you can help ensure that your +cluster configuration matches your expectations. + +## Step 1/3. Add an `import` block + +1. On your workstation, navigate to your root Teleport Terraform module. + +1. Open a file in your text editor to configure Terraform imports. To keep your + configuration tidy, open a new file called `imports.tf`. + +1. Add an `import` block to `imports.tf`. Use the `to` field to indicate the + name of the resource you want to generate configuration for in Terraform. The + following example imports a Teleport role called `myrole`: + + ```hcl + import { + to = teleport_role.myrole + } + ``` + +## Step 2/3. Retrieve the ID of your resource + +1. Retrieve the ID of the resource. The method to use depends on the resource + type. Use the following rules to do so: + + If the resource is `teleport_provision_token`, the ID is the `metadata.id` of + the resource. + + If the resource can only have one instance, use the name of the resource type + without the `teleport` prefix. For example: + + | Resource | ID | + |---------------------------------------|------------------------------| + | `teleport_cluster_maintenance_config` | `cluster_maintenance_config` | + | `teleport_cluster_networking_config` | `cluster_networking_config` | + + For all other resources, the ID is always the `metadata.name` of the resource. + + For example, the `teleport_role` resource uses the role's `metadata.name` + field for its ID. To find all possible role IDs, run the following command: + + ```code + $ tctl get roles --format json | jq '.[].metadata.name' + ``` + +1. In the `import` block, assign the `id` field to the resource ID you retrieved + earlier. For example, to import a Teleport role with a `metadata.name` of + `myrole`, add the following: + + ```diff + import { + to = teleport_role.myrole + + id = "myrole" + } + ``` + +## Step 3/3. Generate a configuration file + +1. Generate a resource configuration + + ```code + $ terraform plan -generate-config-out=imported-resources.tf + ``` + +1. Inspect the resulting file, `imported-resources.tf`. If the new `resource` + block looks correct, you can check the file into source control. + +## Next steps + +- Follow [the user and role IaC guide](user-and-role.mdx) to use the Terraform + Provider to create Teleport users and grant them roles. +- Explore the full list of supported [Terraform provider + resources](../../../reference/terraform-provider.mdx). +- See [the list of supported Teleport Terraform setups](../terraform-provider.mdx): diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider.mdx index 8a673ddbb0bd0..4f4919dedfd78 100644 --- a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider.mdx +++ b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider.mdx @@ -1,292 +1,37 @@ --- -title: Set up the Teleport Terraform Provider +title: Configuring Teleport with Terraform description: How to manage dynamic resources using the Teleport Terraform provider. videoBanner: YgNHD4SS8dg --- -This guide demonstrates how to set up the Terraform provider for Teleport on -Linux and macOS. +The Teleport Terraform provider allows Teleport administrators to use Terraform to configure Teleport via +dynamic resources. -Terraform is intended to be used with Machine ID, Teleport's feature for providing identities to -machines and services, rather than users. This tutorial will show you how to use -a local Machine ID bot to try it out. +## Setup For instructions on managing users and roles via Terraform, read the ["Managing users and roles with IaC" guide](managing-resources/user-and-role.mdx). -For instructions on managing the Teleport dynamic resources as code using -GitOps, read the guide to using the Teleport Terraform provider with [Spacelift -and Machine ID](../../enroll-resources/machine-id/deployment/spacelift.mdx). +The provider must obtain an identity to connect to Teleport. The method to obtain it depends on where the Terraform code +is executed. You must pick the correct guide for your setup: -## Prerequisites +| Guide | Use-case | How it works | +|---------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| [Run the Teleport Terraform provider locally](./terraform-provider/local.mdx) | This is the best way to get started with the Teleport terraform provider, write some initial Terraform code and get familiar with IaC. | You're using you local credentials to create a temporary bot, obtain short-lived credentials, and store them in environment variables. | +| [Run the Teleport Terraform provider in CI or a cloud VM](./terraform-provider/ci-or-cloud.mdx) | You already have a working Terraform module configuring Teleport and want to run it in CI to benefit from review and audit capabilities from your versioning system (e.g. git). | You're using a proof provided by your runtime (CI engine, cloud provider) to prove your identity and join using MachineID. | +| [Run the Teleport Terraform provider from a server](./terraform-provider/dedicated-server.mdx) | You have working Terraform code and want to run it on a dedicated server. The server is long-lived, like a bastion or a task runner. | You setup a MachineID daemon (`tbot`) that obtains and refreshes credentials for the Terraform provider. | +| [Run the Teleport Terraform provider with long-lived credentials.](./terraform-provider/long-lived-credentials.mdx) | This method is discouraged as less secure than the 3 others. This should be used when none of the other methods work in your case (short-lived CI environments that don't have dedicated Teleport join methods). | You sign one long lived certificate allowing the Terraform provider to connect to Teleport. | -(!docs/pages/includes/edition-prereqs-tabs.mdx!) +## Resource guides -- [Terraform >= (=terraform.version=)+](https://learn.hashicorp.com/tutorials/terraform/install-cli) +Once you have a functional Teleport Terraform provider, you will want to configure your resources with it. - ```code - $ terraform version - # Terraform v(=terraform.version=) - ``` +You can find the list of supported resources and their fields is +available [in the Terraform reference](../../reference/terraform-provider.mdx). - To import existing Teleport resources as Terraform resources, you must have - Terraform version `v1.5.0` or above. +Some resources have their dedicated Infrastructure-as-Code (IaC) step-by step guides such as: +- [Managing Users And Roles With IaC](managing-resources/user-and-role.mdx) +- [Creating Access Lists with IaC](managing-resources/access-list.mdx) +- [Registering Agentless OpenSSH Servers with IaC](managing-resources/agentless-ssh-servers.mdx) -- (!docs/pages/includes/tctl.mdx!) - -## Step 1/4. Create Teleport credentials for Terraform - -Terraform needs a signed identity file from the Teleport cluster certificate -authority to manage resources in the cluster. To prepare credentials using a local Teleport bot: - -1. Create a folder called `teleport-terraform` to hold temporary files: - - ```code - $ mkdir -p teleport-terraform - $ cd teleport-terraform - ``` - -1. Terraform needs a Teleport role that gives it permission to manage your - cluster's resources. The bot creates identity documents that have this role. - Configure the necessary role by pasting the following content into a - `terraform_role.yaml` file: - - ```yaml - kind: role - metadata: - name: terraform - spec: - allow: - db_labels: - '*': '*' - app_labels: - '*': '*' - node_labels: - '*': '*' - rules: - - resources: - - app - - bot - - cluster_auth_preference - - cluster_networking_config - - db - - device - - github - - login_rule - - oidc - - okta_import_rule - - role - - saml - - session_recording_config - - token - - trusted_cluster - - user - - access_list - - node - - installer - verbs: ['list','create','read','update','delete'] - version: v7 - ``` - - These settings configure a role named `terraform` with the permissions - required to manage resources in your Teleport cluster. - -1. Create the `terraform` role by running the following command: - - ```code - $ tctl create terraform_role.yaml - role 'terraform' has been created - ``` - -1. Create two scripts that let you quickly and repeatably create and destroy our - local Terraform bot. First, create a new file called - `create_and_run_terraform_bot.sh`, open it in an editor, and paste in the - following content: - - ```shell - #! /usr/bin/env bash - - TOKEN=$(tctl bots add terraform-test --roles=terraform --format=json | jq -r '.token_id') - tbot start \ - --destination-dir=./terraform-identity \ - --token="$TOKEN" \ - --data-dir=./tbot-data \ - --join-method=token \ - --auth-server=tele.example.com:443 - # Replace with the host and port of your Teleport Auth Service - # or Teleport Proxy Service - ``` - - When run, this creates a new bot with the token retrieved from the JSON output. That token - is piped into the start command. For security reasons, we don't allow bot join tokens to be - created in any way other than adding a bot, so for local development work, you must manually - manage the bot and its token. - - The bot manages its state data in a folder called `tbot-data` in the current - working directory. - -1. Edit `create_and_run_terraform_bot.sh` to replace `tele.example.com:443` with - the domain name and port of the Teleport Proxy Service in your cluster. - -1. Create another file called `remove_terraform_bot.sh`, open it in an editor, and -paste in the following content: - - ```shell - #! /usr/bin/env bash - - tctl bots rm terraform-test - rm -rfv ./terraform-identity - rm -rfv ./tbot-data - ``` - - This script will be used later to clean up our bot in between runs and when we're done. - -1. In a new terminal window, run the `create_and_run_terraform_bot.sh` script to create the new bot - and start it: - - ```code - $ chmod +x create_and_run_terraform_bot.sh - $ ./create_and_run_terraform_bot.sh - ``` - -## Step 2/4. Prepare a Terraform configuration file - -To prepare a Terraform configuration file: - -1. Create a new file called `provider.tf` and open it in an editor. - -1. Use the Teleport Terraform provider and connect it to your Teleport cluster - by pasting the following content into the `provider.tf` file: - - - - ```hcl - (!examples/resources/terraform/provider-cloud.tf!) - ``` - - - ```hcl - (!examples/resources/terraform/provider-self-hosted.tf!) - ``` - - - -## Step 3/4. Validate the configuration - -To apply the configuration: - -1. Check the contents of the `teleport-terraform` folder: - - ```code - $ ls - # provider.tf terraform-identity/ create_and_run_terraform_bot.sh remove_terraform_bot.sh terraform_role.yaml - ``` - -1. Initialize the working directory that contains Terraform configuration files - by running the following command: - - ```code - $ terraform init - ``` - -1. Execute the Terraform plan defined in the configuration file by running the - following command: - - ```code - $ terraform apply - ``` - -1. When you're done, use Ctrl-C to stop the Terraform bot. Then run the `remove_terraform_bot.sh` script to remove the bot and clean up the `terraform-identity` folder: - - ```code - $ chmod +x remove_terraform_bot.sh - $ ./remove_terraform_bot.sh - ``` - - If you need to start the bot back up, you can run the two bot scripts as many times as necessary. - -## Step 4/4. [Optional] Import existing resources - -This section shows you how to import existing dynamic Teleport resources as -Terraform resources. - -If you already created Teleport resources using another client tool like `tctl` -or the Kubernetes Operator, and want to manage all Teleport resources using your -Terraform configuration, follow these steps to generate a `.tf` file that -contains `resource` blocks that represent your existing Teleport resources. - -By defining all Teleport resources in one place, you can help ensure that your -cluster configuration matches your expectations. - -### Add an `import` block - -1. On your workstation, navigate to your root Teleport Terraform module. - -1. Open a file in your text editor to configure Terraform imports. To keep your - configuration tidy, open a new file called `imports.tf`. - -1. Add an `import` block to `imports.tf`. Use the `to` field to indicate the - name of the resource you want to generate configuration for in Terraform. The - following example imports a Teleport role called `myrole`: - - ```hcl - import { - to = teleport_role.myrole - } - ``` - -### Retrieve the ID of your resource - -1. Retrieve the ID of the resource. The method to use depends on the resource - type. Use the following rules to do so: - - If the resource is `teleport_provision_token`, the ID is the `metadata.id` of - the resource. - - If the resource can only have one instance, use the name of the resource type - without the `teleport` prefix. For example: - - | Resource | ID | - |---------------------------------------|------------------------------| - | `teleport_cluster_maintenance_config` | `cluster_maintenance_config` | - | `teleport_cluster_networking_config` | `cluster_networking_config` | - - For all other resources, the ID is always the `metadata.name` of the resource. - - For example, the `teleport_role` resource uses the role's `metadata.name` - field for its ID. To find all possible role IDs, run the following command: - - ```code - $ tctl get roles --format json | jq '.[].metadata.name' - ``` - -1. In the `import` block, assign the `id` field to the resource ID you retrieved - earlier. For example, to import a Teleport role with a `metadata.name` of - `myrole`, add the following: - - ```diff - import { - to = teleport_role.myrole - + id = "myrole" - } - ``` - -### Generate a configuration file - -1. Generate a resource configuration - - ```code - $ terraform plan -generate-config-out=imported-resources.tf - ``` - -1. Inspect the resulting file, `imported-resources.tf`. If the new `resource` - block looks correct, you can check the file into source control. - -## Next steps - -- Follow [the user and role IaC guide](managing-resources/user-and-role.mdx) to use the Terraform - Provider to create Teleport users and grant them roles. -- Explore the full list of supported [Terraform provider - resources](../../reference/terraform-provider.mdx). -- See how to use Machine ID with Terraform in - [production](../../enroll-resources/machine-id/access-guides/terraform.mdx). +Finally, you can [import your existing resources in Terraform](managing-resources/import-existing-resources.mdx). diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx new file mode 100644 index 0000000000000..9f9602237ba08 --- /dev/null +++ b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx @@ -0,0 +1,468 @@ +--- +title: Run the Teleport Terraform Provider in CI or Cloud +description: How to manage dynamic resources using the Teleport Terraform provider from your CI pipelines or Cloud provider. +--- + +This guides covers how to run the Teleport Terraform Provider from: + +- your CI/CD pipelines on: + - GitHub Actions (we'll use the `github` join method) + - GitlabCI (we'll use the `gitlab` join method) + - CircleCI (we'll use the `circleci` join method) +- a cloud VM on: + - AWS (we'll use the `aws` join method) + - GCP (we'll use the `gcp` join method) + + +Running the Terraform provider with native MachineID is supported on Azure, inside a Kubernetes pod, +and on servers with Trusted Platform Module (TPM). While those setups are not described in details in this guide, +you can follow their regular MachineID guides and replace the "Configure `tbot`" step by passing the +join method and token to the provider. + +- [Azure MachineID guide](../../../enroll-resources/machine-id/deployment/azure.mdx) +- [Kubernetes MachineID guide](../../../enroll-resources/machine-id/deployment/kubernetes.mdx) +- [TPM MachineID guide](../../../enroll-resources/machine-id/deployment/linux-tpm.mdx) + + + +This guide does not cover running Teleport locally or on a dedicated server. +If you are in one of those cases, follow the dedicated guides: +- [Run the Terraform Provider locally](./local.mdx) +- [Run the Teleport Terraform Provider on a server](./dedicated-server.mdx) + +## How it works + +This setup asks the runtime (the CI/CD system, cloud provider, container engine, ...) for an identity +proof. This proof is then used directly by the Terraform provider to connect to Teleport and obtain credentials. +In this setup, there is no `tbot` daemon involved as the Terraform provider can natively obtain the identity proof +and join the Teleport cluster. + +The setup only works for select runtimes which Teleport +has [a delegated join method](../../../reference/join-methods.mdx#delegated-join-methods) for (e.g. GitHub Actions, +GitLab CI, ...) + +## Prerequisites + +You need either: +- A GCP or AWS VM with terraform installed +- A git repo able to run GitHub Actions, GitLab CI or CircleCI jobs + +You also need: + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +## Step 1/4. Create the Terraform provider bot + +In this step you will create [a bot](../../../reference/architecture/machine-id-architecture.mdx#what-is-a-bot) named `terraform`. + +Create a file named `terraform-bot.yaml`: + +```yaml +kind: bot +version: v1 +metadata: + name: terraform +spec: + # The terraform-provider is a default role shipped in Teleport granting access + # to every resource supported by the terraform provider. + roles: ["terraform-provider"] +``` + +Then apply it with `tctl`: + +```code +$ tctl create terraform-bot.yaml + +This is an admin-level action and requires MFA to complete +Tap any security key +Detected security key tap +bot "terraform" has been created +``` + +At this point, you should see your new bot: +```code +$ tctl bots ls + +Bot User Roles +--------- ------------- ------------------ +terraform bot-terraform terraform-provider +``` + +## Step 2/4. Create the bot join token + +In this step you will create a token allowing a process to connect to Teleport as the `terraform` bot you created +earlier. + +The token type and configuration depends on where the Terraform provider is running. +See [the joining reference](../../../reference/join-methods.mdx) for more details about the joining process, +the different join methods, types of tokens, and the fields they support. + + + +To allow the Terraform Provider to join from GitHub Actions workflows in , +create the following `terraform-bot-token.yaml`: + +```yaml +kind: token +version: v2 +metadata: + name: terraform-bot +spec: + roles: [Bot] + join_method: github + bot_name: terraform + github: + # allow specifies rules that control which GitHub Actions runs will be + # granted access. Those not matching any allow rule will be denied. + allow: + - repository: +``` + + + +To allow the Terraform Provider to join from GitLab CI pipelines in on +the GitLab instance, create the following `terraform-bot-token.yaml`: + +```yaml +kind: token +version: v2 +metadata: + name: terraform-bot +spec: + roles: [Bot] + join_method: gitlab + bot_name: terraform + gitlab: + # domain should be the domain of your GitLab instance. If you are using + # GitLab's cloud hosted offering, omit this field entirely. + domain: + # allow specifies rules that control which GitLab tokens will be accepted + # by Teleport. Tokens not matching any allow rule will be denied. + allow: + - project_path: +``` + + + +(!docs/pages/includes/machine-id/recover-circle-ci-claims.mdx!) + +Then, create the following `terraform-bot-token.yaml`: + +```yaml +kind: token +version: v2 +metadata: + name: terraform-bot +spec: + roles: [Bot] + join_method: circleci + bot_name: terraform + circleci: + organization_id: + # allow specifies the rules by which the Auth Server determines if `tbot` + # should be allowed to join. + allow: + - context_id: +``` + + +Make sure you have: +- An AWS IAM role that you wish to grant access to your Teleport cluster. This role must be granted `sts:GetCallerIdentity`. In this guide, this role will be named . +- An AWS EC2 virtual machine configured with the IAM role attached where you want to run the Terraform provider. +- The AWS account ID: + +Then, create the following `terraform-bot-token.yaml`: + +```yaml +kind: token +version: v2 +metadata: + name: terraform-bot +spec: + roles: [Bot] + bot_name: terraform + join_method: iam + allow: + - aws_account: "" + aws_arn: "arn:aws:sts:::assumed-role//i-*" +``` + + +Make sure you have: +- A GCP Service Account (SA) attached to the VM you want to run the provider on. This cannot be the default compute SA. In this guide, this SA will be named . +- The GCP project ID: + +Then, create the following `terraform-bot-token.yaml`: + +```yaml +kind: token +version: v2 +metadata: + name: terraform-bot +spec: + roles: [Bot] + bot_name: terraform + join_method: gcp + gcp: + allow: + - project_ids: + - "" + service_accounts: + - "@.iam.gserviceaccount.com" +``` + + + +Create the bot token described by the `terraform-bot-token.yaml` manifest: + +```code +$ tctl create -f terraform-bot-token.yaml + +This is an admin-level action and requires MFA to complete +Tap any security key +Detected security key tap +provision_token "terraform-bot" has been created +``` + +## Step 3/4. Configure your Terraform provider + + +In this step you will write a minimal Terraform code that configures the provider to connect to your Teleport cluster +and join with the token you previously created. + +To do this you need: + - your Teleport cluster domain including the port: . + You can find this in the URL when accessing the Web UI. + - the join method of the token you've created. This is the `spec.join_method` field in the `terraform-bot-token.yaml`: + . + +Create this minimal `main.tf` file: + +```var +terraform { + required_providers { + teleport = { + source = "terraform.releases.teleport.dev/gravitational/teleport" + version = "~> (=teleport.major_version=).0" + } + } +} + +provider "teleport" { + addr = "" + join_method = "" + join_token = "terraform-bot" +} + +# We must create a test role, if we don't declare resources, Terraform won't try to +# connect to Teleport and we won't be able to validate the setup. +resource "teleport_role" "test" { + version = "v7" + metadata = { + name = "test" + description = "Dummy role to validate Terraform Provider setup" + labels = { + test = "yes" + } + } + + spec = {} +} +``` + + + +Copy the `main.tf` file in the GitHub repo that runs GitHub Actions pipelines. + + +Copy the `main.tf` file in the GitLab repo that runs GitLab CI pipelines. + + +Copy the `main.tf` file in the Git repo that runs CircleCI pipelines. + + +Copy the `main.tf` file on the AWS VM you will run Terraform from. + + +Copy the `main.tf` file on the GCP VM you will run Terraform from. + + + +### Step 4/4. Run Terraform + +This step shows minimal examples on how to run Terraform based on your environment. This code uses the default local +backend which is not fit for production purposes. Especially in CI, you must +use [non-local Terraform backends](https://developer.hashicorp.com/terraform/language/settings/backends/configuration) +so the Terraform state is persisted across CI pipelines. + + + +In the repo containing your Terraform code, create a `.github/workflows/teleport-terraform.yaml` file with the +following content: + +```yaml +name: Teleport Terraform Demo +# This is a basic workflow to help you get started. +# It will take the following action whenever a push is made to the "main" branch. +on: + push: + branches: + - main +jobs: + demo: + permissions: + # The "id-token: write" permission is required or Machine ID will not be + # able to authenticate with the cluster. + id-token: write + contents: read + name: terraform-plan + runs-on: ubuntu-latest + + # You can find more advanced TF workflows at https://github.com/hashicorp/setup-terraform + steps: + - uses: actions/checkout@v4 + - uses: hashicorp/setup-terraform@v3 + - name: Terraform Init + id: init + run: terraform init + - name: Terraform Plan + id: plan + run: terraform plan -no-color +``` + +Commit the changes and push to the `main` branch to trigger the GitHub Actions workflow. +You should see a successful Terraform plan in the workflow logs. + + + + +Recover your cluster name: +```code +$ tctl status + +Cluster +Version 16.2.0 +# ... +``` + +In the repo containing your Terraform code, create the `.gitlab-ci.yaml` file if it does exist, and add the following +content: + +```yaml +stages: + - plan +image: + name: hashicorp/terraform:1.9 + entrypoint: [""] +terraform-job: + stage: plan + # id_tokens configures ID Tokens that GitLab will automatically inject into + # the environment of your GitLab run. + # + # See https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html + # for further explanation of the id_tokens configuration in GitLab. + id_tokens: + TBOT_GITLAB_JWT: + # aud for TBOT_GITLAB_JWT must be configured with the name of your + # Teleport cluster. This is not necessarily the address of your Teleport + # cluster and will not include a port or scheme (http/https) + # + # This helps the Teleport Auth Server know that the token is intended for + # it, and not a different service or Teleport cluster. + aud: "" + script: + - terraform init + - terraform plan +``` + +Commit the changes and push to any branch to trigger a Gitlab CI pipeline. +You should see a successful Terraform plan in the pipeline logs. + + + +In the repo containing your Terraform code add the following CircleCI config in `.circleci/config.yml`: +```yaml +version: '2.1' +orbs: + terraform: circleci/terraform@3.1 +workflows: + deploy_infrastructure: + jobs: + - terraform/init: + tag: 1.9.5 + checkout: true + context: + - terraform/plan: + tag: 1.9.5 + context: + requires: + - terraform/init +``` + +Commit the changes and push to any branch to trigger a CircleCI pipeline. +You should see a successful Terraform plan in the pipeline logs. + + + +Run the Terraform commands on the EC2 instance: + +```code +$ terraform init +Initializing the backend... + +Initializing provider plugins... +- Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ... + +$ terraform plan +Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + +Terraform will perform the following actions: + + # teleport_role.test will be created + + resource "teleport_role" "test" { + + id = (known after apply) + + kind = (known after apply) + + metadata = { + + name = "test" + + namespace = (known after apply) + } + + spec = {} + + version = "v7" + } + +Plan: 1 to add, 0 to change, 0 to destroy. +``` + + +Run the Terraform commands on the GCP VM: + +```code +$ terraform init +Initializing the backend... + +Initializing provider plugins... +- Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ... + +$ terraform plan +Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + +Terraform will perform the following actions: + + # teleport_role.test will be created + + resource "teleport_role" "test" { + + id = (known after apply) + + kind = (known after apply) + + metadata = { + + name = "test" + + namespace = (known after apply) + } + + spec = {} + + version = "v7" + } + +Plan: 1 to add, 0 to change, 0 to destroy. +``` + + diff --git a/docs/pages/enroll-resources/machine-id/access-guides/terraform.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/dedicated-server.mdx similarity index 52% rename from docs/pages/enroll-resources/machine-id/access-guides/terraform.mdx rename to docs/pages/admin-guides/infrastructure-as-code/terraform-provider/dedicated-server.mdx index 2f4e79c6e8a97..66861e260297e 100644 --- a/docs/pages/enroll-resources/machine-id/access-guides/terraform.mdx +++ b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/dedicated-server.mdx @@ -1,21 +1,29 @@ --- -title: Machine ID with the Teleport Terraform Provider -description: How to use Machine ID with the Teleport Terraform provider to manage your Teleport configuration as IaC +title: Run the Teleport Terraform Provider on a Server +description: How to manage dynamic resources using the Teleport Terraform provider from a dedicated deployment server with MachineID. --- -The Teleport Terraform provider can be used to configure your Teleport cluster -using Terraform. This Terraform provider requires a way to authenticate with -Teleport and Machine ID credentials can be used for this purpose. +This guide demonstrates how to set up the Terraform provider for Teleport on a persistent Linux or macOS server. -In this guide, you will configure `tbot` to produce credentials for the Teleport -Terraform Provider and use Terraform to configure a Teleport role. +This guide does not cover running the Terraform provider locally, or in temporary environments such as +CI/CD and short-lived cloud VMs. If you are in one of those cases, please follow the dedicated guides: + +- [Run the Terraform Provider in CI or cloud VMs](./ci-or-cloud.mdx) +- [Run the Terraform Provider locally](./local.mdx) + +This guide will setup MachineID on the server. MachineID is Teleport's feature +for providing identities to machines and services, rather than users. + +## How it works + +This setup relies on a MachineID daemon (`tbot`) to join the Teleport cluster, obtain and refresh credentials for the +Terraform provider. The daemon stores its identity on the disk and refresh the terraform credentials, typically every +30 minutes. ## Prerequisites (!docs/pages/includes/edition-prereqs-tabs.mdx!) -- (!docs/pages/includes/tctl.mdx!) - - [Terraform >= (=terraform.version=)+](https://learn.hashicorp.com/tutorials/terraform/install-cli) ```code @@ -23,66 +31,33 @@ Terraform Provider and use Terraform to configure a Teleport role. # Terraform v(=terraform.version=) ``` -- `tbot` must already be installed and configured on the machine that will - run Terraform. For more information, see the - [deployment guides](../deployment.mdx). +- (!docs/pages/includes/tctl.mdx!) -## Step 1/3. Configure RBAC +- A Linux host that you wish to run the Teleport Terraform provider onto. -First, Teleport must be configured to allow the credentials produced by `tbot` -to modify the Teleport configuration. This is done by creating a role that -grants the necessary permissions and then assigning this role to a Bot. +- A Linux user on that host that you wish Terraform and `tbot` to run as. In the guide, + we will use for this. -Create a file called `role.yaml` with the following content: +## Step 1/4. Install `tbot` on your server -```yaml -kind: role -version: v6 -metadata: - name: example-role -spec: - allow: - rules: - - resources: - # These currently represent all the resources that can be configured by - # Terraform. You may wish to remove resources that you do not intend to - # configure with Terraform from this list to reduce blast radius. - - app - - cluster_auth_preference - - cluster_networking_config - - db - - device - - github - - login_rule - - oidc - - okta_import_rule - - role - - saml - - session_recording_config - - token - - trusted_cluster - - user - verbs: - - create - - read - - update - - delete - - list -``` +You must install `tbot` and make it join the Teleport cluster. +To do so, follow [the `tbot` deployment guide for Linux](../../../enroll-resources/machine-id/deployment/linux.mdx) +until step 3. -Replace `example-role` with a descriptive name related to your use case. +## Step 2/4. Configure RBAC -Use `tctl create -f ./role.yaml` to create the role. +At this point, `tbot` is installed and configured on the machine that will run Terraform. -Now, use `tctl bots update` to add the role to the Bot. Replace `example` -with the name of the Bot you created in the deployment guide and `example-role` -with the name of the role you just created: +(!docs/pages/includes/management/dynamic-resources/terraform-role.mdx!) + +Use the `tctl bots update` command to add the role to the Bot. Replace `example` +with the name of the Bot you created in the deployment guide. ```bash -$ tctl bots update example --add-roles example-role +$ tctl bots update example --add-roles terraform-provider ``` -## Step 2/3. Configure `tbot` output +## Step 3/4. Configure `tbot` output Now, `tbot` needs to be configured with an output that will produce the credentials needed by the Terraform provider. As the Terraform provider will be @@ -115,7 +90,7 @@ You should now see an `identity` file under `/opt/machine-id`. This contains the private key and signed certificates needed by the Terraform provider to authenticate with the Teleport Auth Server. -## Step 3/3. Use Terraform with the identity output +## Step 4/4. Run Terraform Start by creating a new Terraform working directory: @@ -125,14 +100,7 @@ $ terraform init ``` In order to configure the Teleport Terraform provider to use the credentials -output by Machine ID, we use the `identity_file_path` option. Whilst is is -possible to configure the Terraform provider using the TLS certificate, the -identity file provides support across more Teleport configurations. - -This example creates a simple role for demonstrative purposes, this role is -unlikely to be useful within your Teleport Cluster. Therefore, once you have -confirmed that you have configured Terraform correctly, this resource should be -modified to suit your needs. +output by Machine ID, we use the `identity_file_path` option. In this directory, create `main.tf`: @@ -154,9 +122,8 @@ provider "teleport" { identity_file_path = "/opt/machine-id/identity" } -# This is an example. Replace this with the resource you wish to be managed -# with Terraform. See the following reference for supported options: -# https://goteleport.com/docs/reference/terraform-provider/ +# We must create a test role, if we don't declare resources, Terraform won't try to +# connect to Teleport and we won't be able to validate the setup. resource "teleport_role" "terraform-test" { version = "v7" metadata = { @@ -178,6 +145,8 @@ then this should also be replaced. Now, execute Terraform to test the configuration: ```code +$ terraform init +$ terraform plan $ terraform apply ``` @@ -192,5 +161,5 @@ $ tctl get role/terraform-test - Explore the [Terraform provider resource reference](../../../reference/terraform-provider.mdx) to discover what can be configured with the Teleport Terraform provider. -- Read the [configuration reference](../../../reference/machine-id/configuration.mdx) to explore +- Read the [tbot configuration reference](../../../reference/machine-id/configuration.mdx) to explore all the available `tbot` configuration options. diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/local.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/local.mdx new file mode 100644 index 0000000000000..59c49dd2e831f --- /dev/null +++ b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/local.mdx @@ -0,0 +1,166 @@ +--- +title: Run the Teleport Terraform Provider Locally +description: How to manage dynamic resources using the Teleport Terraform provider from your workstation. +--- + +This guide covers how to run the Teleport terraform provider from your local computer, +where you are already logged in Teleport as yourself. + +This guide does not cover running Teleport in remote environments such as a cloud VM, an on-prem server, +or CI/CD pipelines. If you are in one of those cases, please follow the dedicated guides: +- [Run the Terraform Provider in CI or cloud VMs](./ci-or-cloud.mdx) +- [Run the Terraform Provider on a server](./dedicated-server.mdx) + +## How it works + +This setup relies on the user's local credentials (from `tsh login`) to create a temporary bot in Teleport, +connect as the bot to obtain short-lived credentials, and export those credentials in the shell's environment variables. +Every Terraform command run in this same terminal will then read credentials from environment variables and be able to +connect to Teleport as the temporary bot. + +## Prerequisites + +- A running Teleport Cluster whose version is higher than 16.2 +- Local tsh/tctl clients with versions higher than 16.2 +- Being locally logged in Teleport with a role that allows creating Bot and Token resources. + You can use the default `editor` role for this. + +To check that you can connect to your Teleport cluster, sign in with `tsh login`, then +verify that you can run `tctl` commands using your current credentials. +`tctl` is supported on macOS and Linux machines. + +For example: + +```code +$ tsh login --proxy= --user= +$ tctl status +# Cluster (=teleport.url=) +# Version (=teleport.version=) +# CA pin (=presets.ca_pin=) +``` + +Validate that you meet the version requirements (16.2 or greater) by running: + +```code +$ tsh status +Teleport v(=teleport.version=) go(=teleport.golang=) +Proxy version: (=teleport.version=) +Proxy: +``` + +## Step 1/2. Generate temporary bot credentials + +In this step, you will use `tctl` and your local credentials to create a temporary bot in Teleport for the Terraform +provider. The bot will exist for one hour and will be granted the default `terraform-provider` role that can edit every +resource the TF provider supports. + +`tctl` will then obtain credentials for the temporary bot and export them in your shell's environment variables. +If [MFA for Administrative Actions](../../../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx) +is enabled on your cluster, `tctl` will prompt for your MFA. + +Run the following command, do not remove the `eval` as it is required to load credentials in your shell: + +```code +$ eval "$(tctl terraform env)" +🔑 Detecting if MFA is required +This is an admin-level action and requires MFA to complete +Tap any security key +Detected security key tap +⚙️ Creating temporary bot "tctl-terraform-env-82ab1a2e" and its token +🤖 Using the temporary bot to obtain certificates +🚀 Certificates obtained, you can now use Terraform in this terminal for 1h0m0s +``` + + +## Step 2/2. Run the Terraform provider + +At this point, you got valid credentials in your shell's environment variables for one hour. +You can run the Teleport Terraform provider from this shell. + + + Only the shell you ran `eval "$(tctl terraform env)"` in has the Bot credentials. + If you close this shell or open a new one, you will need to do the first step again. + + + +1. Create a `main.tf` file containing this minimal Terraform code: + + ```var + terraform { + required_providers { + teleport = { + source = "terraform.releases.teleport.dev/gravitational/teleport" + version = "~> (=teleport.major_version=).0" + } + } + } + + provider "teleport" { + addr = '' + } + + # We must create a test role, if we don't declare resources, Terraform won't try to + # connect to Teleport and we won't be able to validate the setup. + resource "teleport_role" "test" { + version = "v7" + metadata = { + name = "test" + description = "Dummy role to validate Terraform Provider setup" + labels = { + test = "yes" + } + } + + spec = {} + } + ``` + +1. Then, init your Terraform working directory to download the Teleport provider: + + ```code + $ terraform init + Initializing the backend... + + Initializing provider plugins... + - Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ... + ``` + +1. Finally, run a Terraform plan: + + ```code + $ terraform plan + Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + + Terraform will perform the following actions: + + # teleport_role.test will be created + + resource "teleport_role" "test" { + + id = (known after apply) + + kind = (known after apply) + + metadata = { + + name = "test" + + namespace = (known after apply) + } + + spec = {} + + version = "v7" + } + + Plan: 1 to add, 0 to change, 0 to destroy. + ``` + +If the plan succeeds, the Terraform provider successfully connected to Teleport. +You can now start developing locally with the Teleport Terraform provider. + +Do not forget to obtain new temporary credentials every hour by re-running `eval $(tctl terraform env)`. + +## Next steps + +- Follow [the user and role IaC guide](../managing-resources/user-and-role.mdx) to use the Terraform + Provider to create Teleport users and grant them roles. +- Consult the list of Terraform-supported + resources [in the Terraform reference](../../../reference/terraform-provider.mdx). +- Once you have working Terraform code that configures your Teleport cluster, you might want to run it in the CI or + from a bastion instead of running it locally. To do this, please follow the dedicated guides: + - [Run the Terraform Provider in CI or cloud VMs](./ci-or-cloud.mdx) + - [Run the Terraform Provider on a dedicated server](./dedicated-server.mdx) diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/long-lived-credentials.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/long-lived-credentials.mdx new file mode 100644 index 0000000000000..9c54a81f88730 --- /dev/null +++ b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/long-lived-credentials.mdx @@ -0,0 +1,204 @@ +--- +title: Run the Teleport Terraform Provider with Long-Lived Credentials +description: How to manage dynamic resources using the Teleport Terraform provider from anywhere with long-lived credentials. +--- + +This guide explains you how to create a Terraform user and have the Teleport Auth Service sign long-lived credentials +for it. The Teleport Terraform Provider can then user those credentials to interact with Teleport. + + + +Long-lived credentials are less secure and their usage is discouraged. You must protect and rotate the credentials as +they hold full Teleport administrative access. You should prefer +using [`tbot`](./dedicated-server.mdx), [native MachineID joining](./ci-or-cloud.mdx) in CI or Cloud environments, +or [create temporary bots for local use](./local.mdx) when possible. + +See [the list of possible Terraform provider setups](../terraform-provider.mdx#setup) to find which one fits your +use-case. + + + + + + +Long-lived credentials are not compatible with MFA for administrative actions (MFA4A) +which is an additional security layer that protects Teleport in case of Identity Provider (IdP) compromise. + + + +## Prerequisites + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- [Terraform >= (=terraform.version=)+](https://learn.hashicorp.com/tutorials/terraform/install-cli) + + ```code + $ terraform version + # Terraform v(=terraform.version=) + ``` + +- (!docs/pages/includes/tctl.mdx!) + +## Step 1/3. Create Teleport credentials for Terraform + +Terraform needs a signed identity file from the Teleport cluster certificate authority to manage resources in the +cluster. You will create a local Teleport user for this purpose. + +1. Create a folder called `teleport-terraform` to hold temporary files: + + ```code + $ mkdir -p teleport-terraform + $ cd teleport-terraform + ``` + +1. Create a new file called `terraform.yaml` and open it in an editor. + +1. Configure settings for a local Teleport user and role by pasting the following content into the `terraform.yaml` file: + + ```yaml + kind: user + metadata: + name: terraform + spec: + roles: ['terraform-provider'] + version: v2 + ``` + (!docs/pages/includes/management/dynamic-resources/terraform-role.mdx!) + + These settings configure a user and role named `terraform` with the permissions + required to manage resources in your Teleport cluster. + +1. Create the `terraform` user and role by running the following command: + + ```code + $ tctl create terraform.yaml + ``` + + The `terraform` user can't sign in to get credentials, so you must have another user + **impersonate** the `terraform` account to request a certificate. + +1. Create a new file called `terraform-impersonator.yaml` and open it in an editor. + +1. Configure a role that enables your user to impersonate the Terraform user by pasting + the following content into the `terraform-impersonator.yaml` file: + + ```yaml + kind: role + version: v7 + metadata: + name: terraform-impersonator + spec: + allow: + # This impersonate role allows any user assigned to this role to impersonate + # and generate certificates for the user named "terraform" with a role also + # named "terraform". + impersonate: + users: ['terraform'] + roles: ['terraform'] + ``` + +1. Create the `terraform-impersonator` role by running the following command: + + ```code + $ tctl create terraform-impersonator.yaml + ``` + +1. (!docs/pages/includes/add-role-to-user.mdx role="terraform-impersonator"!) + +1. Request a signed identity file for the Terraform user by running the following command: + + ```code + $ tctl auth sign --user=terraform --out=terraform-identity + ``` + + After running this command, you have a `terraform-identity` file with credentials for the Terraform user. + +## Step 2/3. Prepare a Terraform configuration file + +To prepare a Terraform configuration file: + +1. Create a new file called `main.tf` and open it in an editor. +1. Define an example user and role using Terraform by pasting the following content into the `main.tf` file: + ```var + terraform { + required_providers { + teleport = { + source = "terraform.releases.teleport.dev/gravitational/teleport" + version = "~> (=teleport.major_version=).0" + } + } + } + + provider "teleport" { + addr = '' + identity_file_path = "terraform-identity" + } + + # We must create a test role, if we don't declare resources, Terraform won't try to + # connect to Teleport and we won't be able to validate the setup. + resource "teleport_role" "test" { + version = "v7" + metadata = { + name = "test" + description = "Dummy role to validate Terraform Provider setup" + labels = { + test = "yes" + } + } + + spec = {} + } + ``` + +## Step 3/3. Apply the configuration + +To apply the configuration: + +1. Check the contents of the `teleport-terraform` folder: + + ```code + $ ls + # main.tf terraform-identity terraform-impersonator.yaml terraform.yaml + ``` + +1. Initialize the working directory that contains Terraform configuration files by running the + following command: + + ```code + $ terraform init + Initializing the backend... + + Initializing provider plugins... + - Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ... + ``` + +1. Execute the Terraform plan defined in the configuration file by running the + following command: + + ```code + $ terraform apply + Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + + Terraform will perform the following actions: + + # teleport_role.test will be created + + resource "teleport_role" "test" { + + id = (known after apply) + + kind = (known after apply) + + metadata = { + + name = "test" + + namespace = (known after apply) + } + + spec = {} + + version = "v7" + } + + Plan: 1 to add, 0 to change, 0 to destroy. + ``` + +## Next steps + +- Explore the full list of supported [Terraform provider resources](../../../reference/terraform-provider.mdx). +- Learn [how to manage users and roles with IaC](../managing-resources/user-and-role.mdx) +- Read more about [impersonation](../../access-controls/guides/impersonation.mdx). diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-starter.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-starter.mdx index 8534f1d854282..31fa873f04166 100644 --- a/docs/pages/admin-guides/infrastructure-as-code/terraform-starter.mdx +++ b/docs/pages/admin-guides/infrastructure-as-code/terraform-starter.mdx @@ -9,10 +9,8 @@ Teleport resources to manage with Terraform in order to accomplish common Teleport setup tasks. You can use the example module as a starting point for managing a complete set of Teleport cluster resources. -The guides in the Terraform starter module assume that you have followed [Machine -ID with the Teleport Terraform Provider]( -../../enroll-resources/machine-id/access-guides/terraform.mdx) on your -workstation. +The guides in the Terraform starter module assume that you have [a working Terraform provider setup]( +./terraform-provider.mdx) on your workstation. ## Part One: Enroll resources diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-starter/rbac.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-starter/rbac.mdx index 867d2748f03b2..ab6e33bbda34f 100644 --- a/docs/pages/admin-guides/infrastructure-as-code/terraform-starter/rbac.mdx +++ b/docs/pages/admin-guides/infrastructure-as-code/terraform-starter/rbac.mdx @@ -268,7 +268,7 @@ do so, you can: - Import existing `teleport_user` resources and modify them to include the `dev_access` and `prod_access` roles (see the - [documentation](../terraform-provider.mdx#step-44-optional-import-existing-resources)). + [documentation](../managing-resources/import-existing-resources.mdx)). - Create a new `teleport_user` resource that includes the roles ([documentation](../managing-resources/user-and-role.mdx). diff --git a/docs/pages/enroll-resources/machine-id/access-guides.mdx b/docs/pages/enroll-resources/machine-id/access-guides.mdx index 26e6baf2ec50f..f192924b91a15 100644 --- a/docs/pages/enroll-resources/machine-id/access-guides.mdx +++ b/docs/pages/enroll-resources/machine-id/access-guides.mdx @@ -21,6 +21,6 @@ on how to do so. ## Specific Tools - [tctl](./access-guides/tctl.mdx): How to use Machine ID with `tctl` to manage your Teleport configuration. -- [Teleport Terraform](./access-guides/terraform.mdx): How to use Machine ID with the Teleport Terraform provider to manage your Teleport configuration as IaC. +- [Teleport Terraform provider](../../admin-guides/infrastructure-as-code/terraform-provider/dedicated-server.mdx): How to use Machine ID with the Teleport Terraform provider to manage your Teleport configuration as IaC. - [Ansible](./access-guides/ansible.mdx): How to use Machine ID with Ansible. - [SPIFFE](./workload-identity/getting-started.mdx): How to use Machine ID to issue SPIFFE certificates. diff --git a/docs/pages/enroll-resources/machine-id/deployment/circleci.mdx b/docs/pages/enroll-resources/machine-id/deployment/circleci.mdx index e8d14d29837ff..50fd3ccc351c7 100644 --- a/docs/pages/enroll-resources/machine-id/deployment/circleci.mdx +++ b/docs/pages/enroll-resources/machine-id/deployment/circleci.mdx @@ -16,51 +16,7 @@ joining method to eliminate the need for long-lived secrets. ## Step 1/5. Configure CircleCI -In order to configure the rules for which CircleCI workflows will be allowed to -connect to your Teleport cluster, you must determine the ID of your CircleCI -organization and create a CircleCI context. - -### Find your organization ID - -Open CircleCI and navigate to "Organization settings" from the navbar. -You should be presented with an interface titled "Overview" with a section -called "Organization ID". Note this value down and substitute `$ORGANIZATION_ID` -in configuration examples with this. - -### Create a context - -CircleCI has an organization-level concept called -**contexts**, which allow you to configure a series of secrets that should be -exposed to a workflow job. You can configure CircleCI to control which actors -are allowed to trigger jobs associated with a context. - -The contexts that a workflow job has been assigned are also encoded in the -identity token that CircleCI creates for the job. This makes them an ideal way -for Teleport to determine which CircleCI jobs should be granted access to the -Teleport cluster. - -In this example, you will create a CircleCI context named `teleport-access`. -You will then grant this context access to your Teleport cluster. - -To create the CircleCI context, open up "Organization settings" in CircleCI -and navigate to "Contexts". Click "Create Context" and provide `teleport-access` -as the name of the context you wish to create. You may substitute this value -for a string that makes more sense to your organization, but ensure in future -steps of this guide that you replace `teleport-access` with your value. - -Select the context you have just created. You will now be on a page that allows -you to configure the context. To determine the ID of the context -to use when configuring Teleport, locate the URL of the -context settings page, which should have a format similar to the following: - -```text -https://app.circleci.com/settings/organization/github/gravitational/contexts/00000000-0000-0000-0000-000000000000 -``` - -In this case, the context ID is: `00000000-0000-0000-0000-000000000000`. - -Note this value down and substitute `$CONTEXT_ID` in configuration examples -with this +(!docs/pages/includes/machine-id/recover-circle-ci-claims.mdx!) ## Step 2/5. Create the Machine ID bot @@ -73,7 +29,7 @@ cluster, you'll first need to create a join token. These tokens set out criteria by which the Auth Server decides whether or not to allow a bot or node to join. Create a file named `bot-token.yaml`, ensuring that you replace -`$ORGANIZATION_ID` and `$CONTEXT_ID` with the values from Step 1. + and with the values from Step 1. ```yaml kind: token @@ -85,11 +41,11 @@ spec: join_method: circleci bot_name: example circleci: - organization_id: $ORGANIZATION_ID + organization_id: # allow specifies the rules by which the Auth Server determines if `tbot` # should be allowed to join. allow: - - context_id: $CONTEXT_ID + - context_id: ``` Let's go over the token resource's fields in more detail: @@ -179,7 +135,7 @@ workflows: jobs: - write-run-log: context: - - teleport-access + - ``` `TELEPORT_ANONYMOUS_TELEMETRY` enables the submission of anonymous usage diff --git a/docs/pages/includes/machine-id/recover-circle-ci-claims.mdx b/docs/pages/includes/machine-id/recover-circle-ci-claims.mdx new file mode 100644 index 0000000000000..a3609620609c6 --- /dev/null +++ b/docs/pages/includes/machine-id/recover-circle-ci-claims.mdx @@ -0,0 +1,45 @@ +In order to configure the rules for which CircleCI workflows will be allowed to +connect to your Teleport cluster, you must determine the ID of your CircleCI +organization and create a CircleCI context. + +### Find your organization ID + +Open CircleCI and navigate to "Organization settings" from the navbar. +You should be presented with an interface titled "Overview" with a section +called "Organization ID". Note this value down and substitute +in configuration examples with this. + +### Create a context + +CircleCI has an organization-level concept called +**contexts**, which allow you to configure a series of secrets that should be +exposed to a workflow job. You can configure CircleCI to control which actors +are allowed to trigger jobs associated with a context. + +The contexts that a workflow job has been assigned are also encoded in the +identity token that CircleCI creates for the job. This makes them an ideal way +for Teleport to determine which CircleCI jobs should be granted access to the +Teleport cluster. + +In this example, you will create a CircleCI context named `teleport-access`. +You will then grant this context access to your Teleport cluster. + +To create the CircleCI context, open up "Organization settings" in CircleCI +and navigate to "Contexts". Click "Create Context" and provide +as the name of the context you wish to create. You may substitute this value +for a string that makes more sense to your organization, but ensure in future +steps of this guide that you replace with your value. + +Select the context you have just created. You will now be on a page that allows +you to configure the context. To determine the ID of the context +to use when configuring Teleport, locate the URL of the +context settings page, which should have a format similar to the following: + +```text +https://app.circleci.com/settings/organization/github/gravitational/contexts/00000000-0000-0000-0000-000000000000 +``` + +In this case, the context ID is: `00000000-0000-0000-0000-000000000000`. + +Note this value down and substitute in configuration examples +with this diff --git a/docs/pages/includes/management/dynamic-resources/terraform-role.mdx b/docs/pages/includes/management/dynamic-resources/terraform-role.mdx new file mode 100644 index 0000000000000..fa5233b1d2800 --- /dev/null +++ b/docs/pages/includes/management/dynamic-resources/terraform-role.mdx @@ -0,0 +1,43 @@ +Starting with 16.2, Teleport comes with a built-in role for the Terraform provider: `terraform-provider`. + +
+ On older version you will need to create the Terraform role yourself. + Write the following `role.yaml` manifest: + + ```yaml + kind: role + version: v7 + metadata: + name: terraform-provider + spec: + allow: + db_labels: + '*': '*' + app_labels: + '*': '*' + node_labels: + '*': '*' + rules: + - resources: + - app + - cluster_auth_preference + - cluster_networking_config + - db + - device + - github + - login_rule + - oidc + - okta_import_rule + - role + - saml + - session_recording_config + - token + - trusted_cluster + - user + - access_list + - node + verbs: ['list','create','read','update','delete'] + ``` + + Use `tctl create -f ./role.yaml` to create the role. +
diff --git a/docs/pages/reference/terraform-provider.mdx b/docs/pages/reference/terraform-provider.mdx index 8097b01491bb8..b04413e9454b4 100644 --- a/docs/pages/reference/terraform-provider.mdx +++ b/docs/pages/reference/terraform-provider.mdx @@ -78,7 +78,9 @@ provider "teleport" { ## Connection methods -{/* TODO(hugoShaka): Add native MachineID joining and tctl helpers methods here when they will get released */} +This section lists the different ways of passing credentials to the Terraform provider. +You can find which method fits your use case in +the [Teleport Terraform provider setup page](../admin-guides/infrastructure-as-code/terraform-provider.mdx) ### With an identity file @@ -88,13 +90,33 @@ the Terraform provider. The identity file can be obtained via several ways: +### Obtaining an identity file locally with `tctl` + +Since 16.2, you can use `tctl` and your local credentials to create a temporary bot and load its identity +in your shell's environment variables: + +```code +$ eval "$(tctl terraform env)" +🔑 Detecting if MFA is required +This is an admin-level action and requires MFA to complete +Tap any security key +Detected security key tap +⚙️ Creating temporary bot "tctl-terraform-env-82ab1a2e" and its token +🤖 Using the temporary bot to obtain certificates +🚀 Certificates obtained, you can now use Terraform in this terminal for 1h0m0s +``` + +You can find more information in +the ["Run the Terraform provider locally" guide](../admin-guides/infrastructure-as-code/terraform-provider/local.mdx) + #### Obtaining an identity file via `tbot` -Tbot relies on [MachineID](../enroll-resources/machine-id/introduction.mdx) to obtain and automatically renew short-lived credentials. -Such credentials are harder to exfiltrate, and you can control more precisely who has access to which roles -(e.g. you can allow only GitHub Actions pipelines targeting the `prod` environment to get certificates). +`tbot` relies on [MachineID](../enroll-resources/machine-id/introduction.mdx) to obtain and automatically renew +short-lived credentials. Such credentials are harder to exfiltrate, and you can control more precisely who has access to +which roles (e.g. you can allow only GitHub Actions pipelines targeting the `prod` environment to get certificates). -You can follow [the Terraform Provider guide](../admin-guides/infrastructure-as-code/terraform-provider.mdx) to achieve this setup. +You can follow [the Terraform Provider guide](../admin-guides/infrastructure-as-code/terraform-provider.mdx) to setup `tbot` +and have Terraform use its identity. #### Obtaining an identity file via `tctl auth sign` @@ -110,6 +132,18 @@ This auth method has the following limitations: On such clusters, Teleport will reject any long-lived certificate and require [an additional MFA challenge for administrative actions](../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx). +### With a token (native MachineID) + +Starting with 16.2, the Teleport Terraform provider can natively use MachineID (without `tbot`) to join a Teleport +cluster. The Terraform Provider will rely on its runtime (AWS, GCP, Kubernetes, CI/CD system) to prove its identity to +Teleport. + +You can use any [delegated join method](./join-methods.mdx#delegated-join-methods) by setting +both `join_method` and `join_token` in the provider configuration. + +This setup is described in more details in +the ["Run the Teleport Terraform provider in CI or Cloud" guide](../admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx). + ### With key, certificate, and CA certificate With this connection method, you must provide a TLS key, a TLS certificate, and the Teleport Auth Service TLS CA certificates. diff --git a/integrations/terraform/templates/index.md.tmpl b/integrations/terraform/templates/index.md.tmpl index 1451e9e77732c..cbf2c36eb98a8 100644 --- a/integrations/terraform/templates/index.md.tmpl +++ b/integrations/terraform/templates/index.md.tmpl @@ -35,19 +35,52 @@ is reserved by the generator for the catch-all resource template */} -{{tffile "./examples/provider/provider.tf" }} +```hcl +terraform { + required_providers { + teleport = { + source = "terraform.releases.teleport.dev/gravitational/teleport" + version = "~> 15.0" + } + } +} + +provider "teleport" { + # Update addr to point to Teleport Auth/Proxy + # addr = "auth.example.com:3025" + addr = "proxy.example.com:443" + identity_file_path = "terraform-identity/identity" +} +``` -{{tffile "./examples/provider/provider-cloud.tf" }} +```hcl +terraform { + required_providers { + teleport = { + source = "terraform.releases.teleport.dev/gravitational/teleport" + version = "~> 15.0" + } + } +} + +provider "teleport" { + # Update addr to point to your Teleport Enterprise (managed) tenant URL's host:port + addr = "mytenant.teleport.sh:443" + identity_file_path = "terraform-identity/identity" +} +``` ## Connection methods -{/* TODO(hugoShaka): Add native MachineID joining and tctl helpers methods here when they will get released */} +This section lists the different ways of passing credentials to the Terraform provider. +You can find which method fits your use case in +the [Teleport Terraform provider setup page](../admin-guides/infrastructure-as-code/terraform-provider.mdx) ### With an identity file @@ -57,13 +90,33 @@ the Terraform provider. The identity file can be obtained via several ways: +### Obtaining an identity file locally with `tctl` + +Since 16.2, you can use `tctl` and your local credentials to create a temporary bot and load its identity +in your shell's environment variables: + +```code +$ eval "$(tctl terraform env)" +🔑 Detecting if MFA is required +This is an admin-level action and requires MFA to complete +Tap any security key +Detected security key tap +⚙️ Creating temporary bot "tctl-terraform-env-82ab1a2e" and its token +🤖 Using the temporary bot to obtain certificates +🚀 Certificates obtained, you can now use Terraform in this terminal for 1h0m0s +``` + +You can find more information in +the ["Run the Terraform provider locally" guide](../admin-guides/infrastructure-as-code/terraform-provider/local.mdx) + #### Obtaining an identity file via `tbot` -Tbot relies on [MachineID](../enroll-resources/machine-id/introduction.mdx) to obtain and automatically renew short-lived credentials. -Such credentials are harder to exfiltrate, and you can control more precisely who has access to which roles -(e.g. you can allow only GitHub Actions pipelines targeting the `prod` environment to get certificates). +`tbot` relies on [MachineID](../enroll-resources/machine-id/introduction.mdx) to obtain and automatically renew +short-lived credentials. Such credentials are harder to exfiltrate, and you can control more precisely who has access to +which roles (e.g. you can allow only GitHub Actions pipelines targeting the `prod` environment to get certificates). -You can follow [the Terraform Provider guide](../admin-guides/infrastructure-as-code/terraform-provider.mdx) to achieve this setup. +You can follow [the Terraform Provider guide](../admin-guides/infrastructure-as-code/terraform-provider.mdx) to setup `tbot` +and have Terraform use its identity. #### Obtaining an identity file via `tctl auth sign` @@ -79,6 +132,18 @@ This auth method has the following limitations: On such clusters, Teleport will reject any long-lived certificate and require [an additional MFA challenge for administrative actions](../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx). +### With a token (native MachineID) + +Starting with 16.2, the Teleport Terraform provider can natively use MachineID (without `tbot`) to join a Teleport +cluster. The Terraform Provider will rely on its runtime (AWS, GCP, Kubernetes, CI/CD system) to prove its identity to +Teleport. + +You can use any [delegated join method](./join-methods.mdx#delegated-join-methods) by setting +both `join_method` and `join_token` in the provider configuration. + +This setup is described in more details in +the ["Run the Teleport Terraform provider in CI or Cloud" guide](../admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx). + ### With key, certificate, and CA certificate With this connection method, you must provide a TLS key, a TLS certificate, and the Teleport Auth Service TLS CA certificates.