Organize the Infrastructure as Code section (#45509)

Backports #45269 - Rename misleadingly named pages related to managing Login Rules with IaC tools. - Organize guides into thematic subdirectories. Currently, the Infrastructure as Code section includes all guides on one level, which makes it difficult to navigate.
gravitational · Aug 15, 2024 · 9f2227f · 9f2227f
1 parent 4378bdd
commit 9f2227f
Show file tree

Hide file tree

Showing 18 changed files with 63 additions and 52 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -920,7 +920,7 @@ access start time up to a week in advance.
 
 The Teleport Terraform provider and Kubernetes operator now support declaring
 agentless OpenSSH and OpenSSH EC2 ICE servers. You can follow [this
-guide](docs/pages/admin-guides/infrastructure-as-code/agentless-ssh-servers.mdx)
+guide](docs/pages/admin-guides/infrastructure-as-code/managing-resources/agentless-ssh-servers.mdx)
 to register OpenSSH agents with infrastructure as code.
 
 Setting up EC2 ICE automatic discovery with IaC will come in a future update.
@@ -1300,8 +1300,7 @@ When deployed with the `teleport-cluster` chart, the operator now runs in a
 separate pod. This ensures that Teleport's availability won't be impacted if the
 operator becomes unready.
 
-See [the Standalone Operator
-guide](docs/pages/admin-guides/infrastructure-as-code/teleport-operator-standalone.mdx)
+See [the Standalone Operator guide](docs/pages/admin-guides/infrastructure-as-code/teleport-operator/teleport-operator-standalone.mdx)
 for installation instructions.
 
 #### Roles v6 and v7 support for Kubernetes Operator

diff --git a/docs/config.json b/docs/config.json
@@ -1930,7 +1930,7 @@
     },
     {
       "source": "/access-controls/login-rules/kubernetes/",
-      "destination": "/admin-guides/infrastructure-as-code/kubernetes/",
+      "destination": "/admin-guides/infrastructure-as-code/managing-resources/login-rules-operator/",
       "permanent": true
     },
     {
@@ -1940,7 +1940,7 @@
     },
     {
       "source": "/access-controls/login-rules/terraform/",
-      "destination": "/admin-guides/infrastructure-as-code/terraform/",
+      "destination": "/admin-guides/infrastructure-as-code/managing-resources/login-rules-terraform/",
       "permanent": true
     },
     {
@@ -2430,22 +2430,22 @@
     },
     {
       "source": "/management/dynamic-resources/access-list/",
-      "destination": "/admin-guides/infrastructure-as-code/access-list/",
+      "destination": "/admin-guides/infrastructure-as-code/managing-resources/access-list/",
       "permanent": true
     },
     {
       "source": "/management/dynamic-resources/agentless-ssh-servers/",
-      "destination": "/admin-guides/infrastructure-as-code/agentless-ssh-servers/",
+      "destination": "/admin-guides/infrastructure-as-code/managing-resources/agentless-ssh-servers/",
       "permanent": true
     },
     {
       "source": "/management/dynamic-resources/teleport-operator-helm/",
-      "destination": "/admin-guides/infrastructure-as-code/teleport-operator-helm/",
+      "destination": "/admin-guides/infrastructure-as-code/teleport-operator/teleport-operator-helm/",
       "permanent": true
     },
     {
       "source": "/management/dynamic-resources/teleport-operator-standalone/",
-      "destination": "/admin-guides/infrastructure-as-code/teleport-operator-standalone/",
+      "destination": "/admin-guides/infrastructure-as-code/teleport-operator/teleport-operator-standalone/",
       "permanent": true
     },
     {
@@ -2460,7 +2460,7 @@
     },
     {
       "source": "/management/dynamic-resources/user-and-role/",
-      "destination": "/admin-guides/infrastructure-as-code/user-and-role/",
+      "destination": "/admin-guides/infrastructure-as-code/managing-resources/user-and-role/",
       "permanent": true
     },
     {

diff --git a/docs/pages/admin-guides/deploy-a-cluster/migrate-to-cloud.mdx b/docs/pages/admin-guides/deploy-a-cluster/migrate-to-cloud.mdx
@@ -35,7 +35,7 @@ Enterprise cluster:
   `tctl` to manage dynamic resources, but it is also possible to use [Teleport
   Terraform provider](../infrastructure-as-code/terraform-provider.mdx) and
   [Kubernetes
-  operator](../infrastructure-as-code/teleport-operator-standalone.mdx), in
+  operator](../infrastructure-as-code/teleport-operator/teleport-operator-standalone.mdx), in
   addition to custom scripts that use the [Teleport API](../api/api.mdx)
   to manage the Teleport Auth Service backend.
 - An account with no trusted clusters enrolled. Trusted clusters are not

diff --git a/docs/pages/admin-guides/infrastructure-as-code.mdx b/docs/pages/admin-guides/infrastructure-as-code.mdx
@@ -64,9 +64,9 @@ infrastructure-as-code and GitOps approaches.
 
 You can get started with `tctl`, the Terraform Provider, and the Kubernetes
 Operator by following: 
-- the ["Managing Users and Roles with IaC" guide](infrastructure-as-code/user-and-role.mdx)
-- the ["Creating Access Lists with IaC" guide](infrastructure-as-code/access-list.mdx)
-- the ["Registering Agentless OpenSSH Servers with IaC" guide](infrastructure-as-code/agentless-ssh-servers.mdx)
+- the ["Managing Users and Roles with IaC" guide](infrastructure-as-code/managing-resources/user-and-role.mdx)
+- the ["Creating Access Lists with IaC" guide](infrastructure-as-code/managing-resources/access-list.mdx)
+- the ["Registering Agentless OpenSSH Servers with IaC" guide](infrastructure-as-code/managing-resources/agentless-ssh-servers.mdx)
 
 For more information on Teleport roles, including the `internal.logins`
 trait we use in these example roles, see the [Teleport Access

diff --git a/...es/infrastructure-as-code/access-list.mdx → ...s-code/managing-resources/access-list.mdx b/...es/infrastructure-as-code/access-list.mdx → ...s-code/managing-resources/access-list.mdx
@@ -269,7 +269,7 @@ Login as `alice` in the web UI, open the management panel and select the
 "Access Lists" tab. Your Access List should be displayed, open it, choose "Enroll
 members" and add `bob`.
 
-![Screenshot of the web UI showing the Access List and the "Enroll Member" button](../../../img/management/access-list-web-ui.png)
+![Screenshot of the web UI showing the Access List and the "Enroll Member" button](../../../../img/management/access-list-web-ui.png)
 
 </TabItem>
 <TabItem label="CLI">
@@ -297,4 +297,4 @@ Members of support-engineers:
 ## Next steps
 
 You can see all supported Access List fields
-[in the Access List reference](../../reference/access-controls/access-lists.mdx).
+[in the Access List reference](../../../reference/access-controls/access-lists.mdx).
diff --git a/...ructure-as-code/agentless-ssh-servers.mdx → ...aging-resources/agentless-ssh-servers.mdx b/...ructure-as-code/agentless-ssh-servers.mdx → ...aging-resources/agentless-ssh-servers.mdx
@@ -26,8 +26,8 @@ To follow this guide, you must have:
 <TabItem label="Kubernetes Operator">
 
 A running operator by following either:
-- [the guide to enable the operator in the `teleport-cluster` Helm chart](./teleport-operator-helm.mdx).
-- [the guide to setup a standalone operator](./teleport-operator-standalone.mdx).
+- [the guide to enable the operator in the `teleport-cluster` Helm chart](../teleport-operator/teleport-operator-helm.mdx).
+- [the guide to setup a standalone operator](../teleport-operator/teleport-operator-standalone.mdx).
 
 You must also set the namespace in which you deployed the operator as this is
 the namespace where you will deploy the CustomResources:
@@ -43,7 +43,7 @@ $ export OPERATOR_NAMESPACE="teleport-iac"
 </TabItem>
 <TabItem label="Terraform">
 
-A functional Teleport Terraform provider by following [the Terraform provider guide](./terraform-provider.mdx).
+A functional Teleport Terraform provider by following [the Terraform provider guide](../terraform-provider.mdx).
 
 </TabItem>
 </Tabs>
@@ -54,7 +54,7 @@ A functional Teleport Terraform provider by following [the Terraform provider gu
 <Admonition type="tip">
   If you want to add a private SSH server (e.g. behind a NAT, in a private
   network, protected by a firewall blocking inbound traffic, ...) you can
-  [install a Teleport agent](../../enroll-resources/server-access/getting-started.mdx). The
+  [install a Teleport agent](../../../enroll-resources/server-access/getting-started.mdx). The
   Teleport agent opens a tunnel to the Teleport Proxy Service, allowing any user
   to connect to it by going through the Proxy Service.
 </Admonition>
@@ -70,7 +70,7 @@ You must also choose a set of labels for the server. Those labels can be used to
 describe the server and control which users can access the server. They can be
 dynamically changed later, without having to reconfigure openSSH.
 
-See the [Access Controls for Servers](../../enroll-resources/server-access/rbac.mdx) page for
+See the [Access Controls for Servers](../../../enroll-resources/server-access/rbac.mdx) page for
 more details about labels and how to control access to your servers.
 
 In the rest of this guide, the labels will be:
@@ -283,9 +283,9 @@ infrastructure and tooling (you can configure the SSH CA in the VM image, use
 custom startup scripts, provision servers with Ansible, ...).
 
 A step-by-step manual setup is described
-in [the OpenSSH manual installation guide](../../enroll-resources/server-access/openssh/openssh-manual-install.mdx)
+in [the OpenSSH manual installation guide](../../../enroll-resources/server-access/openssh/openssh-manual-install.mdx)
 starting with the Step 2.
 
 ## Next steps
 
-- [Setup RBAC](../../enroll-resources/server-access/rbac.mdx) to control which user can SSH on which server.
+- [Setup RBAC](../../../enroll-resources/server-access/rbac.mdx) to control which user can SSH on which server.
diff --git a/...des/infrastructure-as-code/kubernetes.mdx → ...naging-resources/login-rules-operator.mdx b/...des/infrastructure-as-code/kubernetes.mdx → ...naging-resources/login-rules-operator.mdx
@@ -39,7 +39,7 @@ This guide is applicable if you self-host Teleport in Kubernetes using the
 
   </Admonition>
 
-- Follow the [Teleport operator guides](teleport-operator.mdx)
+- Follow the [Teleport operator guides](../teleport-operator.mdx)
   to install the Teleport Operator in your Kubernetes cluster.
   Make sure to follow the Enterprise instructions if you're deploying the
   operator as part of the `teleport-cluster` chart.
@@ -246,7 +246,7 @@ logins:
 
 ## Next Steps
 
-- Read the [Teleport Operator Guide](teleport-operator.mdx) to
+- Read the [Teleport Operator Guide](../teleport-operator.mdx) to
   learn more about the Teleport Operator.
-- Read the [Login Rules reference](../../reference/access-controls/login-rules.mdx) to learn mode about the
+- Read the [Login Rules reference](../../../reference/access-controls/login-rules.mdx) to learn mode about the
   Login Rule expression syntax.
diff --git a/...ides/infrastructure-as-code/terraform.mdx → ...aging-resources/login-rules-terraform.mdx b/...ides/infrastructure-as-code/terraform.mdx → ...aging-resources/login-rules-terraform.mdx
@@ -27,7 +27,7 @@ For simplicity, this guide will configure the Terraform provider to use your
 current logged-in user's Teleport credentials obtained from `tsh login`.
 
 <Admonition type="note">
-The [Terraform provider guide](terraform-provider.mdx)
+The [Terraform provider guide](../terraform-provider.mdx)
 includes instructions for configuring a dedicated `terraform` user and role,
 which is a better option when running Terraform in a non-interactive
 environment.
@@ -152,7 +152,7 @@ logins:
 
 ## Next Steps
 
-- Read the [Terraform Guide](terraform-provider.mdx) to
+- Read the [Terraform Guide](../terraform-provider.mdx) to
   learn more about configuring the Terraform provider.
-- Read the [Login Rules reference](../../reference/access-controls/login-rules.mdx) to learn mode about the
+- Read the [Login Rules reference](../../../reference/access-controls/login-rules.mdx) to learn mode about the
   Login Rule expression syntax.
diff --git a/...s/admin-guides/infrastructure-as-code/managing-resources/managing-resources.mdx b/...s/admin-guides/infrastructure-as-code/managing-resources/managing-resources.mdx
@@ -0,0 +1,10 @@
+---
+title: "Managing Resources with Infrastructure as Code"
+description: Provides instructions on managing specific dynamic resources with tctl and the Teleport Terraform provider and Kubernetes operator.
+layout: tocless-doc
+---
+
+Read the guides in this section for instructions on managing specific dynamic
+resources with tctl and the Teleport Terraform provider and Kubernetes operator.
+
+(!toc!)
diff --git a/.../infrastructure-as-code/user-and-role.mdx → ...code/managing-resources/user-and-role.mdx b/.../infrastructure-as-code/user-and-role.mdx → ...code/managing-resources/user-and-role.mdx
@@ -27,8 +27,8 @@ To follow this guide, you must have:
 <TabItem label="Kubernetes Operator">
 
 A running operator by following either:
-- [the guide to enable the operator in the `teleport-cluster` Helm chart](./teleport-operator-helm.mdx).
-- [the guide to setup a standalone operator](./teleport-operator-standalone.mdx).
+- [the guide to enable the operator in the `teleport-cluster` Helm chart](../teleport-operator/teleport-operator-helm.mdx).
+- [the guide to setup a standalone operator](../teleport-operator/teleport-operator-standalone.mdx).
 
 You must also set the namespace in which you deployed the operator as this is
 the namespace where you will deploy the CustomResources:
@@ -44,7 +44,7 @@ $ export OPERATOR_NAMESPACE="teleport-iac"
 </TabItem>
 <TabItem label="Terraform">
 
-A functional Teleport Terraform provider by following [the Terraform provider guide](./terraform-provider.mdx).
+A functional Teleport Terraform provider by following [the Terraform provider guide](../terraform-provider.mdx).
 
 </TabItem>
 </Tabs>
@@ -192,7 +192,7 @@ We will create 2 users:
   Users created from manifests are local users, as opposed to users coming from
   an external SAML/OIDC/GitHub Identity Provider (IdP).
 
-  See [the user type reference](../../reference/user-types.mdx) for more details.
+  See [the user type reference](../../../reference/user-types.mdx) for more details.
 </Admonition>
 
 <Tabs>
@@ -367,7 +367,7 @@ created and granted the correct roles.
 If you have UI access, connect to your Teleport cluster Web UI, open the
 management panel, and select the "Users" tab.
 
-![Screenshot of the web UI listing alice and bob users](../../../img/management/check-users-web-ui.png)
+![Screenshot of the web UI listing alice and bob users](../../../../img/management/check-users-web-ui.png)
 
 Two new users `alice` and `bob` should be present.
 
@@ -480,13 +480,13 @@ resource "teleport_user" "bob" {
 - Allow users with the `manager` role to grant access to production servers to
   some `engineers` via Access Lists. Manager will need to justify and review
   granted access periodically.
-  See [the AccessList documentation](../access-controls/access-lists.mdx) for
+  See [the AccessList documentation](../../access-controls/access-lists.mdx) for
   a high-level explanation of the feature,
   and [the AccessList IaC guide](access-list.mdx) for a step by step IaC
   AccessList setup.
 - Allow users with the `engineer` role to request temporary access to
   production, and have users with the `manager` role validate the requests.
-  See [the Access Requests documentation](../access-controls/access-requests.mdx)
+  See [the Access Requests documentation](../../access-controls/access-requests.mdx)
 - You can see all supported fields in the references
-  of [the user resource](../../reference/resources.mdx#user)
-  and [the role resource](../../reference/resources.mdx#role).
+  of [the user resource](../../../reference/resources.mdx)
+  and [the role resource](../../../reference/resources.mdx).
diff --git a/docs/pages/admin-guides/infrastructure-as-code/teleport-operator.mdx b/docs/pages/admin-guides/infrastructure-as-code/teleport-operator.mdx
@@ -40,10 +40,10 @@ Currently supported Teleport resources are:
 ### Setting up the operator
 
 If you are self-hosting Teleport using the `teleport-cluster` Helm chart,
-follow [the guide for Helm-deployed clusters](./teleport-operator-helm.mdx).
+follow [the guide for Helm-deployed clusters](teleport-operator/teleport-operator-helm.mdx).
 
 If you are hosting Teleport out of Kubernetes (Teleport Cloud, Terraform, ...),
-follow [the standalone operator guide](./teleport-operator-standalone.mdx).
+follow [the standalone operator guide](teleport-operator/teleport-operator-standalone.mdx).
 
 ### Control reconciliation with annotations
 
@@ -78,5 +78,5 @@ Possible values are `"true"` or `"false"` (those are strings, as Booleans are no
 
 ## Next steps
 
-- Follow the ["Managing users and roles with IaC" guide](./user-and-role.mdx).
+- Follow the ["Managing users and roles with IaC" guide](managing-resources/user-and-role.mdx).
 - Check out [access controls documentation](../access-controls/access-controls.mdx).
diff --git a/...ucture-as-code/teleport-operator-helm.mdx → ...eport-operator/teleport-operator-helm.mdx b/...ucture-as-code/teleport-operator-helm.mdx → ...eport-operator/teleport-operator-helm.mdx
@@ -98,13 +98,13 @@ $ kubectl get pods -n <Var name="teleport-cluster"/>
 
 ## Next steps
 
-Follow [the user and role IaC guide](./user-and-role.mdx) to use your newly
+Follow [the user and role IaC guide](../managing-resources/user-and-role.mdx) to use your newly
 deployed Teleport Kubernetes Operator to create Teleport users and grant them
 roles.
 
-Helm Chart parameters are documented in the [`teleport-cluster` Helm chart reference](../../reference/helm-reference/teleport-cluster.mdx).
+Helm Chart parameters are documented in the [`teleport-cluster` Helm chart reference](../../../reference/helm-reference/teleport-cluster.mdx).
 
-See the [Helm Deployment guides](../deploy-a-cluster/helm-deployments.mdx) detailing specific setups like running Teleport on AWS or GCP.
+See the [Helm Deployment guides](../../deploy-a-cluster/helm-deployments.mdx) detailing specific setups like running Teleport on AWS or GCP.
 
 ## Troubleshooting
 

diff --git a/...-as-code/teleport-operator-standalone.mdx → ...operator/teleport-operator-standalone.mdx b/...-as-code/teleport-operator-standalone.mdx → ...operator/teleport-operator-standalone.mdx
@@ -130,11 +130,11 @@ At this point, you can configure and run the operator:
 
 ## Next steps
 
-Follow [the user and role IaC guide](./user-and-role.mdx) to use your newly
+Follow [the user and role IaC guide](../managing-resources/user-and-role.mdx) to use your newly
 deployed Teleport Kubernetes Operator to create Teleport users and grant them
 roles.
 
-Helm Chart parameters are documented in the [`teleport-operator` Helm chart reference](../../reference/helm-reference/teleport-operator.mdx).
+Helm Chart parameters are documented in the [`teleport-operator` Helm chart reference](../../../reference/helm-reference/teleport-operator.mdx).
 
 ## Troubleshooting
 

diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider.mdx
@@ -12,7 +12,7 @@ machines and services, rather than users. This tutorial will show you how to use
 a local Machine ID bot to try it out.
 
 For instructions on managing users and roles via Terraform, read
-the ["Managing users and roles with IaC" guide](./user-and-role.mdx).
+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
@@ -282,7 +282,7 @@ cluster configuration matches your expectations.
 
 ## Next steps
 
-- Follow [the user and role IaC guide](./user-and-role.mdx) to use the Terraform
+- 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).

diff --git a/docs/pages/enroll-resources/server-access/openssh/openssh-manual-install.mdx b/docs/pages/enroll-resources/server-access/openssh/openssh-manual-install.mdx
@@ -113,7 +113,7 @@ $ tctl create openssh-node-resource.yaml
 <Admonition type="note">
   This step can be done with Infrastructure-as-Code (IaC) tools (tctl,
   Terraform, or Kubernetes Operator). This is described [in the OpenSSH server
-  IaC guide](../../../admin-guides/infrastructure-as-code/agentless-ssh-servers.mdx).
+  IaC guide](../../../admin-guides/infrastructure-as-code/managing-resources/agentless-ssh-servers.mdx).
 </Admonition>
 
 ## Step 2/5. Configure `sshd` to trust the Teleport CA

diff --git a/docs/pages/reference/helm-reference/teleport-operator.mdx b/docs/pages/reference/helm-reference/teleport-operator.mdx
@@ -6,7 +6,7 @@ description: Values that can be set using the teleport-operator Helm chart
 The `teleport-operator` Helm chart deploys the Teleport Kubernetes Operator.
 When deployed via the chart, the operator can join Teleport clusters living in
 Kubernetes or remote ones (such as Teleport Cloud).
-See the [Kubernetes Operator for remote Teleport clusters guide](../../admin-guides/infrastructure-as-code/teleport-operator-standalone.mdx)
+See the [Kubernetes Operator for remote Teleport clusters guide](../../admin-guides/infrastructure-as-code/teleport-operator/teleport-operator-standalone.mdx)
 for more details.
 
 You can

diff --git a/docs/pages/reference/terraform-provider.mdx b/docs/pages/reference/terraform-provider.mdx
@@ -16,7 +16,8 @@ It lists all the supported resources and their fields.
 To get started with the Terraform provider, you must start with [the installation
 guide](../admin-guides/infrastructure-as-code/terraform-provider.mdx).
 Once you got a working provider, we recommend you to follow the
-["Managing users and roles with IaC"](../admin-guides/infrastructure-as-code/user-and-role.mdx) guide.
+["Managing users and roles with
+IaC"](../admin-guides/infrastructure-as-code/managing-resources/user-and-role.mdx) guide.
 </Admonition>
 
 The provider exposes Teleport resources both as Terraform data-sources and Terraform resources.

diff --git a/integrations/terraform/templates/index.md.tmpl b/integrations/terraform/templates/index.md.tmpl
@@ -16,7 +16,8 @@ It lists all the supported resources and their fields.
 To get started with the Terraform provider, you must start with [the installation
 guide](../admin-guides/infrastructure-as-code/terraform-provider.mdx).
 Once you got a working provider, we recommend you to follow the
-["Managing users and roles with IaC"](../admin-guides/infrastructure-as-code/user-and-role.mdx) guide.
+["Managing users and roles with
+IaC"](../admin-guides/infrastructure-as-code/managing-resources/user-and-role.mdx) guide.
 </Admonition>
 
 The provider exposes Teleport resources both as Terraform data-sources and Terraform resources.