search

gravitational / teleport

The easiest, and most secure way to access and protect all of your infrastructure.
https://goteleport.com
GNU Affero General Public License v3.0
17.37k stars 1.74k forks source link

Remove static/dynamic config branching in agent how-to guides #38931

Open ptgott opened 6 months ago

ptgott commented 6 months ago

Applies To

Multiple pages. See "Details".

Details

Some how-to guides for setting up Teleport agents include tab items that show users how to perform the same task with both dynamic resources and static agent configs. How-to guides should only provide guidance on a specific procedure, not all possible variations of the procedure, since otherwise a how-to guide can get to complex for users to follow.

For agent-related guides, we should show either configuration using dynamic resources or a static config file, then use the "Next steps" section to indicate that you can do both. We can also modify the Prerequisites sections of these guides to indicate that thes guide will show one several ways of doing things.

Here are guides/partials that include "static" and "dynamic" within a Tabs component:

$ find docs/pages -name "*.mdx" -exec awk '
/^<Tabs/{t=1}
t==1 && /^<\/Tabs/{t=0}
t==1 && /[dD]ynamic/{d=1}
t==1 && /[sS]tatic/{s=1}
END{if (s==1 && d==1) print FILENAME }' {} \;
docs/pages/database-access/guides/oracle-self-hosted.mdx
docs/pages/database-access/guides/aws-cross-account.mdx
docs/pages/access-controls/device-trust/device-management.mdx
docs/pages/access-controls/device-trust/enforcing-device-trust.mdx
docs/pages/access-controls/guides/per-session-mfa.mdx
docs/pages/access-controls/guides/webauthn.mdx
docs/pages/access-controls/guides/passwordless.mdx
docs/pages/access-controls/guides/mfa-for-admin-actions.mdx
docs/pages/access-controls/sso.mdx
docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx
docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx
docs/pages/includes/database-access/auto-user-provisioning/db-definition-self-hosted.mdx
docs/pages/includes/database-access/aws-troubleshooting-max-policy-size.mdx
docs/pages/includes/enterprise/oidcauthentication.mdx
docs/pages/includes/enterprise/samlauthentication.mdx
docs/pages/reference/authentication.mdx
docs/pages/application-access/guides/connecting-apps.mdx
docs/pages/application-access/cloud-apis/google-cloud.mdx
docs/pages/application-access/cloud-apis/azure.mdx

How will we know this is resolved?

The find command above returns no relevant output, with the pages shown above edited to include only one configuration example.

Related Issues

ptgott commented 6 months ago

Here are the pages that include the relevant partials (there's one partial in this list, and it's shared between two guides):

$ find docs/pages/includes -name "*.mdx" -exec awk '
/^<Tabs/{t=1}
t==1 && /^<\/Tabs/{t=0}
t==1 && /[dD]ynamic/{d=1}
t==1 && /[sS]tatic/{s=1}
END{if (s==1 && d==1) print FILENAME }' {} \; | xargs -I{} grep -Rl '{}' docs/pages
docs/pages/database-access/auto-user-provisioning/postgres.mdx
docs/pages/database-access/auto-user-provisioning/mariadb.mdx
docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx
docs/pages/database-access/auto-user-provisioning/mysql.mdx
docs/pages/database-access/auto-user-provisioning/mongodb.mdx
docs/pages/database-access/guides/postgres-redshift.mdx
docs/pages/database-access/guides/rds.mdx
docs/pages/includes/database-access/rds-proxy.mdx
docs/pages/access-controls/sso/gitlab.mdx
docs/pages/access-controls/sso/google-workspace.mdx
docs/pages/access-controls/sso/oidc.mdx
docs/pages/access-controls/sso/adfs.mdx
docs/pages/access-controls/sso/one-login.mdx
docs/pages/access-controls/sso/azuread.mdx
docs/pages/access-controls/sso/okta.mdx