docs: add tctl and Terraform methods for creating Access Lists

docs/pages/identity-governance/access-lists/custom-access-list.mdx

@@ -2,7 +2,7 @@
 title: Creating an Access List with the Custom Form
 sidebar_label: Custom Access Lists
 sidebar_position: 4
-description: Use the Custom Form in the Teleport Web UI to create an Access List by directly assigning existing roles to members and owners.
+description: Creates an Access List by directly assigning existing roles to members and owners, using the Teleport Web UI, tctl, or Terraform.
 tags:
  - how-to
  - identity-governance
@@ -21,7 +21,7 @@ you pick from roles that already exist in the cluster.
 This guide will help you:
 
 - Decide when the Custom Form is the right fit
-- Create an Access List using the Custom Form in the Teleport Web UI
+- Create an Access List with the Teleport Web UI, `tctl`, or Terraform
 - Verify that members get access on login
 
 ## When to use this flow
@@ -42,20 +42,22 @@ request).
 
 ## Prerequisites
 
-- A running Teleport Enterprise cluster. If you don't have one yet,
-  [sign up](https://goteleport.com/signup) for a free trial.
+(!docs/pages/includes/edition-prereqs-tabs.mdx edition="Teleport Enterprise" optionalClientNote=", required only if creating the list with \`tctl\` or Terraform"!)
 
 (!docs/pages/identity-governance/access-lists/includes/preset-prerequisites.mdx!)
 
-## Step 1/3. Open the Custom Form
+## Step 1/2. Create the Access List
+
+Choose how to create the list.
+
+<Tabs queryString="method">
+<TabItem value="webui" label="Web UI">
 
 In the Teleport Web UI, hover over **Add New** from the sidebar menu then click
 **Access List**.
 
 Enter a name and optional description for the list, then click **Use Custom Form Instead**.
 
-## Step 2/3. Fill in the Access List
-
 The Custom Form is a single page split into three sections. Fill them out top
 to bottom, then click **Create Access List** at the bottom.
 
@@ -114,11 +116,139 @@ is the primary purpose of most Access Lists.
 
 ![Member Grants](../../../img/access-controls/access-lists/member-grants.png)
 
-## Step 3/3. Verify the access
-
-Log in as one of the members you added. The resources granted by the roles
-you selected should appear in the resource list and you should be able to
-connect to them.
+</TabItem>
+<TabItem value="tctl" label="tctl">
+
+(!docs/pages/identity-governance/access-lists/includes/tctl-acl-create-version.mdx!)
+
+The following command creates a list that grants the `support-engineer` role to
+`bob`, and lets `alice` own and review it. Substitute the usernames and role
+names with ones that exist in your cluster:
+
+```code
+$ tctl acl create \
+    --title "Production access for support engineers" \
+    --description "Grant access to production to engineers in the support rotation." \
+    --audit-frequency 6 \
+    --audit-day 1 \
+    --owners alice \
+    --owner-required-roles manager \
+    --members bob \
+    --member-required-roles engineer \
+    --member-grant-roles support-engineer
+```
+
+See [`tctl acl create`](../../reference/cli/tctl.mdx#tctl-acl-create) for the full
+list of flags, including the trait equivalent of each grant and eligibility flag above.
+
+(!docs/pages/identity-governance/access-lists/includes/tctl-flags-note.mdx!)
+
+</TabItem>
+<TabItem value="terraform" label="Terraform">
+
+`tctl acl create` accepts `--output terraform` as of `tctl` v19.0.0. On earlier
+versions of `tctl`, write the Terraform configuration by hand as described in
+[Creating Access Lists with IaC](../../configuration/resource-guides/access-list.mdx).
+The Custom Form does not generate Terraform; only the guided flows do.
+
+(!docs/pages/identity-governance/access-lists/includes/tctl-output-terraform-intro.mdx!)
+
+The following command generates a module for a list that grants the
+`support-engineer` role to `bob`, and lets `alice` own and review it. Substitute
+the usernames and role names with ones that exist in your cluster:
+
+```code
+$ tctl acl create \
+    --title "Production access for support engineers" \
+    --description "Grant access to production to engineers in the support rotation." \
+    --owners alice \
+    --owner-required-roles manager \
+    --members bob \
+    --member-required-roles engineer \
+    --member-grant-roles support-engineer \
+    --output terraform > access-list.tf
+```
+
+See [`tctl acl create`](../../reference/cli/tctl.mdx#tctl-acl-create) for the full
+list of flags, including the trait equivalent of each grant and eligibility flag above.
+
+The dry-run is a complete module: a provider block, the Access List itself, and
+one member resource per user you passed to `--members`. The provider's `addr`
+is filled in from the cluster `tctl` is talking to, so your output will be
+similar to the following:
+
+```hcl
+terraform {
+  required_providers {
+    teleport = {
+      source  = "terraform.releases.teleport.dev/gravitational/teleport"
+      version = "~> (=teleport.major_version=).0"
+    }
+  }
+}
+
+provider "teleport" {
+  addr = "teleport.example.com:443"
+}
+
+resource "teleport_access_list" "acl-0a1b2c3d-4e5f-6789-abcd-ef0123456789" {
+  header = {
+    kind    = "access_list"
+    version = "v1"
+    metadata = {
+      name = "0a1b2c3d-4e5f-6789-abcd-ef0123456789"
+    }
+  }
+
+  spec = {
+    description = "Grant access to production to engineers in the support rotation."
+    owners = [{
+      membership_kind = "1"
+      name            = "alice"
+    }]
+    membership_requires = {
+      roles = ["engineer"]
+    }
+    ownership_requires = {
+      roles = ["manager"]
+    }
+    grants = {
+      roles = ["support-engineer"]
+    }
+    title = "Production access for support engineers"
+    type  = "static"
+  }
+}
+
+resource "teleport_access_list_member" "acl-member-bob_86c6a0d4" {
+  depends_on = [teleport_access_list.acl-0a1b2c3d-4e5f-6789-abcd-ef0123456789]
+
+  header = {
+    kind    = "access_list_member"
+    version = "v1"
+    metadata = {
+      name = "bob"
+    }
+  }
+
+  spec = {
+    access_list     = "0a1b2c3d-4e5f-6789-abcd-ef0123456789"
+    name            = "bob"
+    membership_kind = "1"
+  }
+}
+```
+
+(!docs/pages/identity-governance/access-lists/includes/terraform-apply.mdx!)
+
+</TabItem>
+</Tabs>
+
+## Step 2/2. Verify the access
+
+Log in as one of the members you added. The resources granted by the roles you
+assigned should appear in the resource list and you should be able to connect to
+them.
 
 ## Next steps
 
@@ -128,5 +258,8 @@ connect to them.
   [Just-in-Time Access Guide](./jit-access-list.mdx).
 - Group members by inheriting access from other lists with
   [nested Access Lists](./nested-access-lists.mdx).
+- Manage the list from the command line after creating it — `tctl acl get`,
+  `tctl acl update`, `tctl acl users`, and `tctl acl rm` are documented in the
+  [`tctl` reference](../../reference/cli/tctl.mdx#tctl-acl-create).
 - Learn more about managing Access Lists as code with the
   [Terraform provider and Kubernetes operator](../../configuration/resource-guides/access-list.mdx).

docs/pages/identity-governance/access-lists/guide.mdx

@@ -9,6 +9,7 @@ tags:
 enterprise: Identity Governance
 page_type: how-to
 skills:
+  - teleport-acl-lifecycle
   - teleport-acl-review
 ---
 

docs/pages/identity-governance/access-lists/includes/editing-roles-warning.mdx

@@ -1,22 +1,25 @@
-<Admonition type="warning" title="Editing the generated roles">
-Avoid directly modifying the roles the guided flow creates for this Access
-List. Keep their names and their `teleport.internal/access-list-preset*` labels
-unchanged — the Web UI relies on both to recognize them as the roles generated
-for this Access List.
-To change what the list grants, update it through the Web UI Access List editor:
+<Admonition type="warning" title="Editing the supporting roles">
+However you created the list, keep the supporting roles' names and their
+`teleport.internal/access-list-preset*` labels unchanged. Both the Web UI Access
+List editor and `tctl acl update` rely on them to recognize which roles belong
+to this Access List.
 
-1. From the sidebar menu, click **Identity Governance** > **Access Lists**.
-2. Click on the target Access List.
-3. Click the **Access Definition** tab.
-4. Click **Edit Access**.
+To change what the list grants:
 
-If you created the list with Terraform produced by the Web UI editor, you can
-still use the web editor to update the Access List and copy the updated Terraform it
-generates.
+- **Web UI** — from the sidebar menu, click **Identity Governance** >
+  **Access Lists**, click the target Access List, open the **Access Definition**
+  tab, then click **Edit Access**.
+- **`tctl`** — rerun
+  [`tctl acl update`](../../../reference/cli/tctl.mdx#tctl-acl-update) with the
+  resource flags you want. It updates the supporting roles for you.
+- **Terraform** — rerun
+  [`tctl acl update`](../../../reference/cli/tctl.mdx#tctl-acl-update) with the
+  resource flags you want and `--output terraform` to regenerate the
+  configuration, then apply it.
 
-Editing the roles directly (via Terraform, `tctl`, or the role editor) may
-make the Access List editor in the Web UI unable to parse them (only a limited
-subset of role fields is supported by the editor) — at which point you can no
-longer use the Web UI editor to change the list's grants, and must update the
+Both tools support only a limited subset of role fields. If the roles end up
+outside that subset, neither can change the list's grants — the Web UI editor
+can no longer parse them, and `tctl acl update` rejects them rather than
+silently dropping the fields you added. From that point on you must manage the
 roles directly for the rest of the Access List's life.
 </Admonition>

docs/pages/identity-governance/access-lists/includes/tctl-acl-create-version.mdx

@@ -0,0 +1,2 @@
+`tctl acl create` was introduced in `tctl` v18.10.3. On earlier versions of
+`tctl`, use the Web UI.

docs/pages/identity-governance/access-lists/includes/tctl-flags-note.mdx

@@ -0,0 +1,3 @@
+Every list-valued flag takes a comma-separated string, for example
+`--members bob,carol`. Members can also be added after the fact with
+[`tctl acl users add`](../../../reference/cli/tctl.mdx#tctl-acl-users-add).

docs/pages/identity-governance/access-lists/includes/tctl-output-terraform-intro.mdx

@@ -0,0 +1,5 @@
+### Generate the configuration
+
+The `tctl acl create --output terraform` command will not create anything, but
+instead prints a Terraform module describing the Access List the other flags
+define, which you can write straight to a file.

docs/pages/identity-governance/access-lists/includes/terraform-apply.mdx

@@ -0,0 +1,43 @@
+Note the `type = "static"` field. Access Lists managed with Terraform must be
+static so that Terraform can own their membership, and static lists do not
+support periodic auditing. To learn the differences, see
+[Static versus default Access Lists](../../../configuration/resource-guides/access-list.mdx#static-versus-default-access-lists).
+
+### Apply the configuration
+
+Log in to your cluster, assigning <Var name="teleport.example.com:443" /> to your
+Teleport proxy address and <Var name="email@example.com" /> to your Teleport
+username:
+
+```code
+$ tsh login --proxy=<Var name="teleport.example.com:443" /> --user=<Var name="email@example.com" />
+```
+
+Generate temporary credentials for the Terraform provider:
+
+```code
+$ eval "$(tctl terraform env)"
+```
+
+Initialize Terraform, preview the changes, and apply them:
+
+```code
+$ terraform init
+$ terraform plan
+$ terraform apply
+```
+
+The Access List is created once `terraform apply` completes.
+
+<Admonition type="note">
+The steps above use `tctl terraform env` to issue short-lived credentials,
+which is convenient for trying things out locally. For remote environments
+such as CI/CD pipelines or cloud VMs, see the
+[Terraform provider documentation](../../../configuration/terraform-provider/terraform-provider.mdx)
+for guidance on setting up the provider.
+</Admonition>
+
+To write the configuration by hand instead of generating it, or for the full set
+of fields on the `teleport_access_list` and `teleport_access_list_member`
+resources, see
+[Creating Access Lists with IaC](../../../configuration/resource-guides/access-list.mdx).