Add documentation for Teleport ECS/Fargate `db_service` installation via Teleport Discover

webvictim commented 1 year ago

Request

Add a section to the database service guides on Teleport Discover and how agents are deployed.

Details

Currently, adding an RDS database via the discover wizards in the Teleport 13.2.2+/14.0.0+ web UIs will take you through an OIDC provider configuration flow and then deploys a Teleport db_service on ECS using Fargate.

This is a really cool workflow and works great, but there are a number of issues:

It is not obvious:

that this flow exists
how exactly it works (e.g. how does Teleport determine which db_service will serve requests for a given database, and how you can configure that)
what exactly the wizard does
how you can see logs for the deployment
how you can troubleshoot problems with it
how you can change the service's configuration after deployment
how you should run multiple services connected to one cluster in different VPCs, for example dev vs staging vs production

How will we know this is resolved?

There will be a docs page explaining the items listed above!

Related Issues

Original tracking issue: https://github.com/gravitational/teleport/issues/25521 Implementation PRs:

GavinFrazar commented 2 months ago

I think this is a good idea and we should also include a "troubleshooting" section that can be used to troubleshoot the db service deployment in ECS.

Common issues such as:

task stuck in "Pending" state because it can't pull the teleport image (network issue, navigate to ECS task to see error)
task starts but never joins the cluster (network issue, check teleport process logs)
task starts, joins cluster, but can't reach a database (typically a network issue)

GavinFrazar commented 2 months ago

cc @greedy52 tracking the troubleshooting docs goal in this issue.

gravitational / teleport