gravitational Teleport Auto-Discovery
Connect Teleport to your cloud to automatically discover and enroll your resources. Use Terraform to create an OIDC integration in your cloud provider and configure the Teleport Discovery Service. Troubleshoot any issues getting your resources enrolled. Supports AWS EC2 instances, AWS EKS clusters, and Azure VMS.
Communicating
Open with one or two sentences stating which procedures will run and what each produces or checks. After that, address the user only to ask questions and to report each procedure's outcome or stop. Never report individual field derivations, commands run, or intermediate results.
Determine the cloud
Set CLOUD before anything else. Infer aws when the request names EC2, EKS, or an AWS
account. Infer azure when it names VMs, a subscription, a resource group, or a management group. If
the request implies neither, stop and ask the user which cloud. Do not run aws or az commands
and do not write Terraform until CLOUD is set.
Resolving fields
Resolve each field from the prompt first, then from its tool derivation, then from its
Default column. Treat a tool that is unavailable, ambiguous, or erroring as yielding
nothing. Where a procedure gathers fields, it lists them as | Field | Tool derivation | Default |.
In commands, $TSH and $TCTL stand for the tsh and tctl binaries, using the paths the
user gives or plain tsh and tctl otherwise.
When tsh or tctl fails for lack of a session, ask the user to run
$TSH login --proxy=<proxy_addr> in a separate terminal, then retry. Interactive logins
fail in the session, even with the ! prefix.
Asking
Each question states what the value controls in the final configuration, for example "Which AWS regions should discovery search for EC2 instances?". Make the default the first option and the other options concrete values. Write question text, option labels, and option descriptions in the user's voice, such as "Run it for me", because a bare I or you is ambiguous between you and the user. Free-form values arrive through the built-in Other option. Never ask a follow-up round to refine an answer. When an answer is unusable, state why and re-ask that single question.
AskUserQuestion takes at most 4 questions per call, so a round may span consecutive calls: group matcher-scope questions such as regions, tags, and subscriptions together, and logistics questions such as write location and apply choices together.
Procedures
Run the procedures the request asks for, in order: Setup, Apply, then Monitor. "Set up discovery" with no narrower scope runs all three.
Setup
Write, generate, configure, or extend the discovery Terraform. Gather these common fields, then
the cloud-specific fields in references/aws-setup.md for aws or references/azure-setup.md
for azure. Run the reference's version gate as soon as cluster_version resolves, before
asking the user anything. When cluster_version itself must be asked, run the gate on the
answer before writing. Collect every field that resolves to Ask, including write_location
when the prompt does not specify it, then ask for all of them in a single round with the
AskUserQuestion tool rather than one at a time. When Apply will run, include the two apply
questions from references/apply.md in the same round.
| Field | Tool derivation | Default |
|---|---|---|
proxy_addr |
$TSH status --format=json, active.profile_url with the https:// scheme stripped, such as example.teleport.sh:443 |
Ask |
cluster_version |
$TCTL status Version field, such as 18.8.0 |
Ask |
deployment |
cloud when proxy_addr's host ends in .teleport.sh, .cloud.gravitational.io, or .beams.sh, else self-hosted |
none |
discovery_group |
cloud: cloud-discovery-group. self-hosted: see Self-hosted discovery group |
Ask, per Self-hosted discovery group |
write_location |
none | Ask, with a new teleport-discovery/ directory as the default |
Self-hosted discovery group
Confirm a Discovery Service runs with $TCTL inventory list --services=discovery, and stop
when none does. The inventory output does not show groups, so collect the discovery_group
values from $TCTL get discovery_config --format=json and offer them as options. The
question states the value must match discovery_group in a running Discovery Service's
configuration.
Write location
Into a new project, write a fresh module in the write_location directory with versions.tf
and main.tf. Into an existing Terraform project, integrate following its structure. If the
project already declares the module "aws_discovery" or module "azure_discovery" block,
read it, pre-populate the gathered fields from its current values, and edit that block in
place.
Apply
Apply the Terraform to create the resources, with references/apply.md. Precede it with Setup
when the Terraform is not written yet.
Monitor and Troubleshoot
Check status, watch a sync, or diagnose why resources are not enrolling, with
references/monitor.md.