mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-12 02:15:01 +00:00
Paul Gottschling
82289903fd
Fix issues that hinder AI agents that attempt to set up a demo cluster in order to follow other docs guides. - **Add resource guidelines to the Deploy Community guide:** An agent failed to follow many of our how-to guides because it ran all demo infrastructure resources on the same host as the Teleport cluster. This caused OOMs. Sizing guidance is based on the single-instance Terraform guide, `installation/self-hosted/deployments/aws-starter-cluster-terraform.mdx`. - **Edit the Community Edition guide to add further preventions against using self-signed certificates:** Agents see the Prerequisites requirement for DNS records as a blocker. If records don't exist, the agent doesn't try to create them. Instead, add a "Step" section with instructions to create DNS records. While an earlier change removed an existing "Step" section for creating records, this change includes commands in the section to reduce the context needed to follow the guide and give agents an easy course of action to reach for. (If it's not easy, they'll reach for self-signed certificates instead.) Also strengthen the Admonition against using self-signed certificates, which tends to be an AI agent's first choice. - **Mark the private CA alternative as advanced in the Deploy Community guide:** This way, it's not presented as equally viable for a demo environment, and agents won't be as tempted to follow it. - **Require a valid TLS certificate** in the partial we use in Prerequisites sections throughout our how-to guides, `edition-prereqs-tabs.mdx`. While agents tend to set up demo clusters successully, they often use self-signed certificates and fail to connect Teleport Agents to it, and for `tctl` commands, end up running the commands over a direct SSH connection to the Auth Service. Include a persistent reminder in how-to guides that we expect the Proxy Service to be reachable with a valid TLS certificate. - **Edit add-role-to-user.mdx:** Add a `TabItem` in this partial for non-interactive users, since agents had difficulty with `tsh login`.