From a533da7645794b75b6a4c0c2c1d4286b546e0e3c Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 28 Mar 2024 17:56:04 -0400 Subject: [PATCH] Respond to Tener feedback - Edit the "Terraform Provider" guide title to describe the purpose of the guide more explicitly, distinguishing it from the new guide. - Describe general rules for finding the ID of a resource, rather than using a comprehensive table. - Incorporate the import instructions into the setup guide. This way, we don't need to clarify the relationship between two guides, which wasn't entirely clear at the outset. - Add a more explicit benefit statement for importing resources. - Use the `-v` flag in `rm` commands --- docs/config.json | 8 +- docs/pages/management/dynamic-resources.mdx | 3 - .../import-terraform-resources.mdx | 108 ------------------ .../dynamic-resources/terraform-provider.mdx | 95 +++++++++++++-- 4 files changed, 88 insertions(+), 126 deletions(-) delete mode 100644 docs/pages/management/dynamic-resources/import-terraform-resources.mdx diff --git a/docs/config.json b/docs/config.json index 2984410054b7..e2889b073300 100644 --- a/docs/config.json +++ b/docs/config.json @@ -659,13 +659,9 @@ "slug": "/management/dynamic-resources/teleport-operator-standalone/" }, { - "title": "Terraform Provider", + "title": "Set up the Terraform Provider", "slug": "/management/dynamic-resources/terraform-provider/" - }, - { - "title": "Import Teleport Resources into Terraform", - "slug": "/management/dynamic-resources/import-terraform-resources/" - } + } ] }, { diff --git a/docs/pages/management/dynamic-resources.mdx b/docs/pages/management/dynamic-resources.mdx index d9141b9d902c..b4d9d7fa6241 100644 --- a/docs/pages/management/dynamic-resources.mdx +++ b/docs/pages/management/dynamic-resources.mdx @@ -120,9 +120,6 @@ resource "teleport_role" "developer" { [Get started with the Terraform provider](./dynamic-resources/terraform-provider.mdx). -[Import Teleport resources](./dynamic-resources/import-terraform-resources.mdx) -that you have already created as Terraform resources. - ### Teleport Kubernetes Operator The Teleport Kubernetes Operator lets you apply Teleport resources as Kubernetes diff --git a/docs/pages/management/dynamic-resources/import-terraform-resources.mdx b/docs/pages/management/dynamic-resources/import-terraform-resources.mdx deleted file mode 100644 index e9411adeedf5..000000000000 --- a/docs/pages/management/dynamic-resources/import-terraform-resources.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Import Teleport Resources into Terraform -description: Describes how to import existing Teleport resources using the Teleport Terraform provider ---- - -If you want to use Terraform to manage Teleport dynamic resources, but have -already created resources with a tool like `tctl`, you can automatically -generate Terraform configuration for them. This guide shows you import Teleport -resource into your Terraform project. - -## Prerequisites - -- The Teleport Terraform provider. Read the [Terraform provider getting started - guide](./terraform-provider.mdx) for how to set up Terraform to manage - Teleport dynamic resources. This guide assumes that you have set up a root - Terraform module for Teleport on your workstation and started `tbot` to to - retrieve credentials for the provider. - -- Terraform version `v1.5.0` or above. - -## Import a Teleport resource into Terraform - -To generate Terraform configuration by importing an existing Teleport resource: - -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 - } - ``` - -1. Retrieve the ID of the resource. The method to use depends on the resource - type. See the [table below](#resource-ids) for how to obtain an ID for each - resource. The ID is either the value of another field within the resource or - a constant value such as `auth_preference`. - - 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" - } - ``` - -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. - -## Resource IDs - -The Teleport Terraform provider uses two possible methods to -define the ID of a resource: - -- Using another field within the resource, such as `metadata.name` or - `metadata.id` -- Using a constant value such as `cluster_networking_config` - -The following table indicates how the Teleport Terraform provider defines the ID -of each available Teleport resource: - -| Resource | How to obtain the ID | -|---------------------------------------|-------------------------------------| -| `teleport_app` | Use `metadata.name` | -| `teleport_auth_preference` | Always `auth_preference` | -| `teleport_cluster_maintenance_config` | Always `cluster_maintenance_config` | -| `teleport_cluster_networking_config` | Always `cluster_networking_config` | -| `teleport_database` | Use `metadata.name` | -| `teleport_github_connector` | Use `metadata.name` | -| `teleport_oidc_connector` | Use `metadata.name` | -| `teleport_saml_connector` | Use `metadata.name` | -| `teleport_provision_token` | Use `metadata.id` | -| `teleport_role` | Use `metadata.name` | -| `teleport_session_recording_config` | Always `session_recording_config` | -| `teleport_trusted_cluster` | Use `metadata.name` | -| `teleport_user` | Use `metadata.name` | -| `teleport_login_rule` | Use `metadata.name` | -| `teleport_device_trust` | Use `metadata.name` | -| `teleport_okta_import_rule` | Use `metadata.name` | -| `teleport_access_list` | Use `metadata.name` | - -## Next steps - -Read the [Terraform provider reference](../../reference/terraform-provider.mdx) -for a comprehensive description of Teleport resources that you can manage with -Terraform. diff --git a/docs/pages/management/dynamic-resources/terraform-provider.mdx b/docs/pages/management/dynamic-resources/terraform-provider.mdx index 6cdbd84250c0..e54775cb05b6 100644 --- a/docs/pages/management/dynamic-resources/terraform-provider.mdx +++ b/docs/pages/management/dynamic-resources/terraform-provider.mdx @@ -1,5 +1,5 @@ --- -title: Terraform Provider +title: Set up the Teleport Terraform Provider description: How to manage dynamic resources using the Teleport Terraform provider. videoBanner: YgNHD4SS8dg --- @@ -29,9 +29,12 @@ and Machine ID](../../machine-id/deployment/spacelift.mdx). # Terraform v(=terraform.version=) ``` + To import existing Teleport resources as Terraform resources, you must have + Terraform version `v1.5.0` or above. + - (!docs/pages/includes/tctl.mdx!) -## Step 1/3. Create Teleport credentials for Terraform +## 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: @@ -130,8 +133,8 @@ paste in the following content: #! /usr/bin/env bash tctl bots rm terraform-test - rm -rf ./terraform-identity - rm -rf ./tbot-data + 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. @@ -144,7 +147,7 @@ paste in the following content: $ ./create_and_run_terraform_bot.sh ``` -## Step 2/3. Prepare a Terraform configuration file +## Step 2/4. Prepare a Terraform configuration file To prepare a Terraform configuration file: @@ -166,7 +169,7 @@ To prepare a Terraform configuration file: -## Step 3/3. Validate the configuration +## Step 3/4. Validate the configuration To apply the configuration: @@ -200,11 +203,85 @@ To apply the configuration: 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 othe 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 -- If you have already created Teleport resources with another tool, such as - `tctl`, learn how to [import Teleport resources into - Terraform](./import-terraform-resources.mdx). - 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