Document how to import resources into Terraform #39701
Conversation
|
The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with |
|
The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with |
ptgott
added
no-changelog
|
🤖 Vercel preview here: https://docs-3cwbak7kk-goteleport.vercel.app/docs/ver/preview |
docs/config.json
Outdated
| { | ||
| "title": "Terraform Provider", | ||
| "slug": "/management/dynamic-resources/terraform-provider/" | ||
| } | ||
| }, | ||
| { | ||
| "title": "Import Teleport Resources into Terraform", | ||
| "slug": "/management/dynamic-resources/import-terraform-resources/" | ||
| } |
There was a problem hiding this comment.
It's not related to this PR per-se, but I've always found our terraform provider documentation to be buried and non-discoverable. Whenever I go to search something terraform-provider-related, I always get confused where I should look (is it managing cluster? deploying agents? reference?), and can never find what I'm looking for "organically" and end up just using search.
What do think about elevating all Terraform Provider relevant documentation to its own top-level section in the left nav bar? In fact, I would probably want to do the same for Kube Operator later. I think we had both of them at the top level long time ago but then they got buried during some docs restructuring.
There was a problem hiding this comment.
In the past, these guides were in docs/pages/management/guides, which was kind of a catch-all section with no explicit theme.
In the current docs, we put guides related to dynamic resources in /management/dynamic-resources. Reference guides are mostly but not always in "Reference", and guides related to deploying agents are in /agents. Since the "Deploy Agents with Terraform" guide has to do with agents, and not dynamic resources, I put it in the /agents section.
I can see how this would be confusing if you're looking for all content related to Terraform. In general, the docs are inconsistent in where they store reference information, so I'm not sure of a good solution for the reference guide without taking more time to look at this.
On my 4k monitor at the default zoom, the left sidebar already extends past the bottom of the viewport—I'm also not sure if we can accommodate more sidebar sections, but it might be worth looking into. Would it make sense to promote the "Dynamic Resources" docs to a top-level section that includes content for the Kubernetes operator and Terraform provider?
There was a problem hiding this comment.
I can't for the life of me navigate around the docs hierarchy myself. I'll typically just ask AI bot for pointers rather than hunting the menus. I'd really appreciate if you could simply cmd-f to find strings in there... But deeper items are permanently hidden, and the folded parts of the menu are not searched.
ptgott
force-pushed
the
paul.gottschling/9720-import
branch
from
5983b17
to
7015838
Compare
|
🤖 Vercel preview here: https://docs-i7lunvcri-goteleport.vercel.app/docs/ver/preview |
ptgott
force-pushed
the
paul.gottschling/9720-import
branch
from
7015838
to
3f3a9db
Compare
|
🤖 Vercel preview here: https://docs-qnmtjfek8-goteleport.vercel.app/docs/ver/preview |
docs/pages/management/dynamic-resources/import-terraform-resources.mdx
Outdated
Show resolved
Hide resolved
docs/pages/management/dynamic-resources/import-terraform-resources.mdx
Outdated
Show resolved
Hide resolved
ptgott
force-pushed
the
paul.gottschling/9720-import
branch
from
9ef14c8
to
469f492
Compare
|
🤖 Vercel preview here: https://docs-euen0ze50-goteleport.vercel.app/docs/ver/preview |
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.
- 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
ptgott
force-pushed
the
paul.gottschling/9720-import
branch
from
469f492
to
a533da7
Compare
|
🤖 Vercel preview here: https://docs-452fn4heg-goteleport.vercel.app/docs/ver/preview |
|
@Tener @r0mant Friendly ping if you have a moment for a second round of feedback. The change only modifies a single file now (the getting started guide to the Teleport Terraform provider), so while information architecture of our Terraform content is still something we need to improve, I would argue that it's less relevant to this specific PR. |
Co-authored-by: Roman Tkachenko <[email protected]>
|
🤖 Vercel preview here: https://docs-gdfc0lt9b-goteleport.vercel.app/docs/ver/preview |
Closes #9720
Add a guide to importing Teleport resources into Terraform. While it is mostly straightforward to add an
importblock, 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:
-fflag intctl create: This way a user doesn't accidentally override an existingterraformroletbotdata directory in an unprivileged path in the working directory of the setup script. This way, we don't need to giveteleportownership of the default Machine ID output directory.identityin theterraform-identitydirectory.