Docs: add DiscoveryConfig as an alternative method for configuring server discovery

build.assets/tooling/cmd/resource-ref-generator/config.yaml

@@ -1,5 +1,6 @@
 source: "../../../../api"
 destination: "../../../../docs/pages/reference/infrastructure-as-code/teleport-resources"
+examples_directory: "./resource_examples"
 
 # Please alphabetize the resource list by type name.
 resources:

build.assets/tooling/cmd/resource-ref-generator/reference/reference.go

@@ -37,8 +37,9 @@ type pageContent struct {
 // resourceSection represents a top-level section of the resource reference
 // dedicated to a dynamic resource.
 type resourceSection struct {
-	Version string
-	Kind    string
+	Version         string
+	Kind            string
+	ResourceExample string
 	resource.ReferenceEntry
 }
 
@@ -77,6 +78,8 @@ type GeneratorConfig struct {
 	// Directory where the generator writes reference pages.
 	DestinationDirectory string   `yaml:"destination"`
 	CamelCaseExceptions  []string `yaml:"camel_case_exceptions"`
+	// Directory where example YAML files are located.
+	ExamplesDirectory string `yaml:"examples_directory"`
 }
 
 type GenerationError struct {
@@ -133,6 +136,11 @@ func Generate(conf GeneratorConfig, tmpl *template.Template) error {
 		pc.Resource.Kind = r.KindValue
 		pc.Resource.Version = r.VersionValue
 
+		resourceExampleLocation := filepath.Join(conf.ExamplesDirectory, r.KindValue+".yaml")
+		if exampleBytes, err := os.ReadFile(resourceExampleLocation); err == nil {
+			pc.Resource.ResourceExample = string(exampleBytes)
+		}
+
 		filename := strings.ReplaceAll(strings.ToLower(pc.Resource.SectionName), " ", "-")
 		docpath := filepath.Join(conf.DestinationDirectory, filename+".mdx")
 		doc, err := os.Create(docpath)

build.assets/tooling/cmd/resource-ref-generator/reference/reference.tmpl

@@ -13,19 +13,26 @@ sidebar_label: {{ .Resource.SectionName }}
 
 {{ .Resource.Description }}
 
+{{- if gt (len .Resource.ResourceExample) 0 }}
+
+Example definition:
+```yaml
+{{ .Resource.ResourceExample }}
+```
+{{- end }}
+
+## Top-level fields
+
 Example:
 
 ```yaml
 {{ .Resource.YAMLExample -}}
 ```
-
-{{- if gt (len .Resource.Fields) 0 }}
 |Field Name|Description|Type|
 |---|---|---|
 {{ range .Resource.Fields -}}
 |{{.Name}}|{{.Description}}|{{.Type}}|
-{{ end }} 
-{{- end }}
+{{ end }}
 
 {{- range .Fields }}
 ## {{ .SectionName }}

build.assets/tooling/cmd/resource-ref-generator/resource_examples/discovery_config.yaml

@@ -0,0 +1,197 @@
+kind: discovery_config
+version: v1
+metadata:
+  name: my-discovery-config
+spec:
+  # discovery_group is used to group discovered resources into different
+  # sets. This is required when you have multiple Teleport Discovery services
+  # running. It prevents discovered services from colliding in Teleport when
+  # managing discovered resources.
+  # If two Discovery Services match the same resources, they must be in the
+  # same discovery group.
+  # If two Discovery Services match different resources, they must be in
+  # different discovery groups.
+  #
+  # It is also used to watch DiscoveryConfig resources.
+  # The Discovery Configs that have a matching discovery_group will be added to
+  # this Discovery Service matchers.
+  discovery_group: "disc-group"
+  # Matchers for discovering AWS-hosted resources.
+  aws:
+    # AWS resource types to discover and register with your Teleport cluster.
+    # Valid options are:
+    # 'ec2' - Amazon EC2 instances.
+    # 'eks' - Amazon EKS clusters.
+    # 'rds' - Amazon RDS and Aurora databases.
+    # 'rdsproxy' - Amazon RDS Proxy databases.
+    # 'redshift' - Amazon Redshift databases.
+    # 'redshift-serverless' - Amazon Redshift Serverless databases.
+    # 'elasticache' - Amazon ElastiCache Redis and Valkey databases.
+    # 'elasticache-serverless' - Amazon ElastiCache Serverless Redis or Valkey databases.
+    # 'memorydb' - Amazon MemoryDB databases.
+    # 'opensearch' - Amazon OpenSearch Redis databases.
+    # 'docdb' - Amazon DocumentDB databases.
+  - types: ["ec2"]
+    # AWS regions to search for resources from
+    regions: ["us-east-1","us-west-1"]
+    # Optional AWS resource tags to match when registering resources
+    # Defaults to a wildcard selector that matches any resource: "*":"*"
+    tags:
+      "*": "*"
+    # Optional AWS role that the Discovery Service will assume to discover
+    # and register AWS-hosted databases and EKS clusters.
+    assume_role:
+      role_arn: "arn:aws:iam::123456789012:role/example-role-name"
+      # AWS role name that the Discovery Service will assume to discover resources in other accounts
+      # Only required when using discovering accounts under an organization.
+      role_name: "example-role-name"
+      # Optional AWS external ID that the Discovery Service will use to assume
+      # a role in an external AWS account.
+      external_id: "example-external-id"
+    # Organization sections enables AWS organization account discovery.
+    # Only applicable for EC2 discovery.
+    organization:
+      # Organization ID used for discovering accounts in the AWS organization.
+      organization_id: "o-exampleorgid"
+      # Filters for matching on AWS Organizational Units (OUs).
+      organizational_units:
+        # Include is a list of AWS Organizational Unit IDs and children OUs to include.
+        # Accounts that belong to these OUs, and their children, will be included.
+        # Only exact matches or wildcard (*) are supported.
+        # Required.
+        include_ous: ["*"]
+        # Exclude is a list of AWS Organizational Unit IDs and children OUs to exclude.
+        # Accounts that belong to these OUs, and their children, will be excluded, even if they were included.
+        # Only exact matches are supported.
+        # Optional. If empty, no OUs are excluded.
+        exclude_ous: []
+    # Optional section: install is used to provide parameters to the installer script.
+    # Only applicable for EC2 discovery.
+    install:
+      # The token to use when joining the cluster
+      join_token: "iam-join-token"
+      # The method to use when joining the cluster
+      join_method: "iam"
+      # script_name is the name of the Teleport install script to use.
+      # Optional, defaults to: "default-installer".
+      script_name: "default-installer"
+      # Optional: adds a suffix to teleport installation, allowing for multiple agent installations.
+      # Requires managed updates to be enabled.
+      # Supported characters are alphanumeric characters and `-`.
+      suffix: "<suffix>"
+      # Optional: when using managed updates, set the update group of the installation.
+      # Supported characters are alphanumeric characters and `-`.
+      update_group: "<update-group>"
+      # Optional: proxy settings for the install script.
+      # Sets the http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY, no_proxy, and NO_PROXY
+      # environment variables for the install script.
+      http_proxy_settings:
+        https_proxy: http://172.31.5.130:3128
+        http_proxy: http://172.31.5.130:3128
+        no_proxy: my-local-domain
+    # Optional section: ssm is used to configure which AWS SSM document to use
+    # If the ssm section isnt provided the below defaults are used.
+    ssm:
+      # document_name is the name of the SSM document that should be
+      # executed when installing teleport on matching nodes
+      # Can be set to "AWS-RunShellScript" which is a pre-defined SSM Document,
+      # removing the need to create a custom SSM Document in each region.
+      # Optional, defaults to: "TeleportDiscoveryInstaller".
+      document_name: "AWS-RunShellScript"
+    # Optional role for which the Discovery Service should create the EKS access entry.
+    # If not set, the Discovery Service will attempt to create the access
+    # entry using its own identity.
+    # If used, the role must match the role configured for a Teleport Kubernetes Service.
+    setup_access_for_arn: arn:aws:iam::123456789012:role/kube-service-role
+  # Matchers for discovering Azure-hosted resources.
+  azure:
+    # Azure resource types. Valid options are:
+    # 'aks' - discovers and registers Azure AKS Kubernetes Clusters.
+    # 'vm' - discovers and registers Azure virtual machines.
+    # 'mysql' - discovers and registers Azure MySQL databases.
+    # 'postgres' - discovers and registers Azure PostgreSQL databases.
+    # 'redis' - discovers and registers Azure Cache for Redis databases.
+    # 'sqlserver' - discovers and registers Azure SQL Server databases.
+  - types: ["aks"]
+    # Azure regions to search for resources from. Valid options are:
+    # '*' - discovers resources in all regions (default).
+    # Any valid Azure region name. List all valid regions using the Azure "az" cli: `az account list-locations -o table`
+    regions: ["eastus", "westus"]
+    # Azure subscription IDs to search resources from. Valid options are:
+    # '*' - discovers resources in all subscriptions (default).
+    # Any subscription_id: `az account subscription list -o table`
+    subscriptions: ["11111111-2222-3333-4444-555555555555"]
+    # Azure resource groups to search resources from. Valid options are:
+    # '*' - discovers resources in all resource groups within configured subscription(s) (default).
+    # Any resource_groups: `az group list -o table`
+    resource_groups: ["group1", "group2"]
+    # Optional section: install is used to provide parameters to the Teleport installation in Azure VMs.
+    # Only applicable for VM discovery.
+    install_params:
+      # The token to use when joining the cluster
+      join_token: "iam-join-token"
+      # The method to use when joining the cluster
+      join_method: "azure"
+      # script_name is the name of the Teleport install script to use.
+      # Optional, defaults to: "default-installer".
+      script_name: "default-installer"
+      # Optional: adds a suffix to teleport installation, allowing for multiple agent installations.
+      # Requires managed updates to be enabled.
+      # Supported characters are alphanumeric characters and `-`.
+      suffix: "<suffix>"
+      # Optional: when using managed updates, set the update group of the installation.
+      # Supported characters are alphanumeric characters and `-`.
+      update_group: "<update-group>"
+      # Optional: proxy settings for the install script.
+      # Sets the http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY, no_proxy, and NO_PROXY
+      # environment variables for the install script.
+      http_proxy_settings:
+        https_proxy: http://172.31.5.130:3128
+        http_proxy: http://172.31.5.130:3128
+        no_proxy: my-local-domain
+    # Azure resource tag filters used to match resources.
+    tags:
+      "*": "*"
+  # Matchers for discovering GCP-hosted resources.
+  gcp:
+    # GCP resource types. Valid options are:
+    # 'gke' - discovers and registers GKE Kubernetes clusters.
+    # 'gce' - discovers and registers GCP compute instances.
+    - types: ["gce"]
+      # IDs of GCP projects to search for resources from.
+      project_ids: ["project-id"]
+      # GCP locations to search for resources from. Valid options are:
+      # '*' - discovers resources in all locations.
+      # Any valid GCP region (e.g. "us-west1").
+      # Any valid GCP zone (e.g. "us-west1-b").
+      locations: ["us-east2", "us-west1-b"]
+      # Email addresses of service accounts that instances can join with.
+      # If empty, any service account is allowed.
+      service_accounts: []
+      # Optional section: install is used to provide parameters to the Teleport installation in Google Cloud VMs.
+      # Only applicable for VM discovery.
+      install_params:
+        # The token to use when joining the cluster
+        join_token: "gcp-join-token"
+        # The method to use when joining the cluster
+        join_method: "gcp"
+        # script_name is the name of the Teleport install script to use.
+        # Optional, defaults to: "default-installer".
+        script_name: "default-installer"
+        # Optional: adds a suffix to teleport installation, allowing for multiple agent installations.
+        # Requires managed updates to be enabled.
+        # Supported characters are alphanumeric characters and `-`.
+        suffix: "<suffix>"
+        # Optional: when using managed updates, set the update group of the installation.
+        # Supported characters are alphanumeric characters and `-`.
+        update_group: "<update-group>"
+        # Optional: proxy settings for the install script.
+        # Sets the http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY, no_proxy, and NO_PROXY
+        # environment variables for the install script.
+        http_proxy_settings:
+          https_proxy: http://172.31.5.130:3128
+          http_proxy: http://172.31.5.130:3128
+          no_proxy: my-local-domain
+      # GCP resource label filters used to match resources.
+      labels:
+        "*": "*"

docs/pages/enroll-resources/auto-discovery/servers/azure-discovery.mdx

@@ -239,18 +239,19 @@ $ tctl tokens add --type=discovery
 Save the generated token in `/tmp/token` on the virtual machine that will run
 the Discovery Service.
 
-In order to enable Azure instance discovery the `discovery_service.azure` section
-of `teleport.yaml` must include at least one entry:
-
 (!docs/pages/includes/discovery/discovery-group.mdx!)
 
+Assign <Var name="teleport.example.com:443" /> to the host and port of the Teleport Proxy Service in your cluster,
+and <Var name="azure-prod" /> to a name that identifies a group of resources that you will enroll:
+
 ```yaml
+# teleport.yaml
 version: v3
 teleport:
   join_params:
     token_name: "/tmp/token"
     method: token
-  proxy_server: "teleport.example.com:443"
+  proxy_server: "<Var name="teleport.example.com:443" />"
 auth_service:
   enabled: false
 proxy_service:
@@ -259,27 +260,87 @@ ssh_service:
   enabled: false
 discovery_service:
   enabled: true
-  discovery_group: "azure-prod"
-  azure:
-    - types: ["vm"]
-      subscriptions: ["<subscription>"]
-      resource_groups: ["<resource-group>"]
-      regions: ["<region>"]
-      tags:
-        "env": "prod" # Match virtual machines where tag:env=prod
-      install:
-        azure:
-          # Optional: If the VMs to discover have more than one managed
-          # identity assigned to them, set the client ID here to the client
-          # ID of the identity created in step 3.
-          client_id: "<client-id>"
+  discovery_group: <Var name="azure-prod" />
 ```
 
-- Edit the `teleport.auth_servers` key to match your Auth Service or Proxy Service's URI
-  and port.
-- Adjust the keys under `discovery_service.azure` to match your Azure environment,
-  specifically the regions and tags you want to associate with the Discovery
-  Service.
+Create a matcher for the resources you want to enroll.
+
+<Admonition type="tip">
+Dynamic configuration uses Discovery Configs which can be managed using Terraform.
+See the [Terraform `discovery_config` reference](../../../reference/infrastructure-as-code/terraform-provider/resources/discovery_config.mdx) for more information.
+
+Static configuration while simpler at first, has less flexibility because enrollment changes require edits to `teleport.yaml` and the restart of the Discovery Service.
+</Admonition>
+
+<Tabs>
+<TabItem label="Dynamic configuration (recommended)">
+  Create a Discovery Config resource, that has the same discovery group you configured earlier, to enable Azure VM discovery.
+
+  Create a file named `discovery-azure-prod.yaml` with the following content:
+  ```yaml
+  kind: discovery_config
+  version: v1
+  metadata:
+    name: example-discovery-config
+  spec:
+    discovery_group: <Var name="azure-prod" />
+    azure:
+      - types: ["vm"]
+        subscriptions: ["<subscription>"]
+        resource_groups: ["<resource-group>"]
+        regions: ["<region>"]
+        tags:
+          "env": "prod" # Match virtual machines where tag:env=prod
+        install:
+          azure:
+            # Optional: If the VMs to discover have more than one managed
+            # identity assigned to them, set the client ID here to the client
+            # ID of the identity created in step 3.
+            client_id: "<client-id>"
+  ```
+  Adjust the keys under `spec.azure` to match your Azure environment,
+  specifically the resource groups, regions and tags you want to associate with the Discovery Service.
+
+  Create the Discovery Config by running the following command:
+  ```code
+  $ tctl create -f discovery-azure-prod.yaml
+  ```
+
+  Matching instances will be added to the Teleport cluster automatically.
+
+  You can update the Discovery Config at any time, and the service will automatically re-apply the changes.
+</TabItem>
+
+<TabItem label="Static configuration">
+  In order to enable Azure VM discovery the `discovery_service.azure` section
+  of `teleport.yaml` must include at least one entry:
+
+  ```yaml
+  # teleport.yaml
+  # ...
+  discovery_service:
+    enabled: true
+    discovery_group: <Var name="azure-prod" />
+    azure:
+      - types: ["vm"]
+        subscriptions: ["<subscription>"]
+        resource_groups: ["<resource-group>"]
+        regions: ["<region>"]
+        tags:
+          "env": "prod" # Match virtual machines where tag:env=prod
+        install:
+          azure:
+            # Optional: If the VMs to discover have more than one managed
+            # identity assigned to them, set the client ID here to the client
+            # ID of the identity created in step 3.
+            client_id: "<client-id>"
+  ```
+
+  Adjust the keys under `discovery_service.azure` to match your Azure environment, 
+  specifically the regions and tags you want to associate with the Discovery Service.
+</TabItem>
+
+</Tabs>
 
 ## Auto-discovery labels