Document how to import resources into Terraform (#39701)

* Document how to import resources into Terraform Closes #9720 Add a guide to importing Teleport resources into Terraform. While it is mostly straightforward to add an `import` block, determining the ID to use for each resource requires some planning, since the ID depends on the resource type. This change also edits the Terraform provider guide, since testing out this guide was required to test out the resource import workflow: - Minor style and readability tweaks. - Remove the `-f` flag in `tctl create`: This way a user doesn't accidentally override an existing `terraform` role - Add a `tbot` data directory in an unprivileged path in the working directory of the setup script. This way, we don't need to give `teleport` ownership of the default Machine ID output directory. - Fix identity file paths. These should point to a file called `identity` in the `terraform-identity` directory. - Edit the "Next steps" section to point to the resource import guide. * 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 * Update docs/pages/management/dynamic-resources/terraform-provider.mdx Co-authored-by: Roman Tkachenko <[email protected]> --------- Co-authored-by: Roman Tkachenko <[email protected]>
gravitational · Apr 8, 2024 · b32cbd7 · b32cbd7
1 parent e9fd157
commit b32cbd7
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 18 deletions.
diff --git a/docs/config.json b/docs/config.json
@@ -659,7 +659,7 @@
               "slug": "/management/dynamic-resources/teleport-operator-standalone/"
             },
             {
-              "title": "Terraform Provider",
+              "title": "Set up the Terraform Provider",
               "slug": "/management/dynamic-resources/terraform-provider/"
             }
           ]

diff --git a/docs/pages/management/dynamic-resources/terraform-provider.mdx b/docs/pages/management/dynamic-resources/terraform-provider.mdx
@@ -1,10 +1,10 @@
 ---
-title: Terraform Provider
+title: Set up the Teleport Terraform Provider
 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
+This guide demonstrates how to set up the Terraform provider for Teleport on
 Linux and macOS.
 
 Terraform is intended to be used with Machine ID, Teleport's feature for providing identities to
@@ -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:
@@ -43,11 +46,10 @@ authority to manage resources in the cluster. To prepare credentials using a loc
    $ cd teleport-terraform
    ```
 
-1. Create a new file called `terraform.yaml` and open it in an editor.
-
-1. Terraform needs a role giving it permission to manage our Cluster's resources. The bot will
-   create identity certificates that have this role. Configure the necessary role by pasting
-   the following content into a `terraform_role.yaml` file:
+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
@@ -90,13 +92,14 @@ authority to manage resources in the cluster. To prepare credentials using a loc
 1. Create the `terraform` role by running the following command:
 
    ```code
-   $ tctl create -f terraform_role.yaml
+   $ tctl create terraform_role.yaml
    role 'terraform' has been created
    ```
 
-1. We're going to create two scripts that will let us 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:
+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
@@ -117,14 +120,21 @@ authority to manage resources in the cluster. To prepare credentials using a loc
    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 -rf ./terraform-identity
+   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.
@@ -137,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:
 
@@ -159,7 +169,7 @@ To prepare a Terraform configuration file:
    </TabItem>
    </Tabs>
 
-## Step 3/3. Validate the configuration
+## Step 3/4. Validate the configuration
 
 To apply the configuration:
 
@@ -193,9 +203,88 @@ 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 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](./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](../../machine-id/access-guides/terraform.mdx).
+- Explore the full list of supported [Terraform provider
+  resources](../../reference/terraform-provider.mdx).
+- See how to use Machine ID with Terraform in
+  [production](../../machine-id/access-guides/terraform.mdx).