From d70f984b072aa0500d3feb107411262db7e5efad Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 4 Dec 2025 08:41:40 -0500 Subject: [PATCH] Generate a reference for discovery_config See #61931 Edit the resource reference generator config to support the `discovery_config` resource and generate a reference guide to the resource's fields. Also perform some minor cleanup of the resource reference generator config file. Note that, in order to add the `Metadata` field to the reference, this change fixes a bug in which it only adds reference entries based on the fields of a given declaration, not the fields included in any embedded struct fields of the declaration. As part off this work, clarify function names, renaming `handleEmbeddedStructFields` to `allFieldsForDecl` and `getRawTypes` to `typeForDecl`. Also remove a list of possible function declarations that the generator used in an earlier iteration but no longer uses. --- .../cmd/resource-ref-generator/config.yaml | 20 +- .../resource/resource.go | 26 +- .../resource/resource_test.go | 79 +++ .../teleport-resources/discovery-config.mdx | 521 ++++++++++++++++++ 4 files changed, 622 insertions(+), 24 deletions(-) create mode 100644 docs/pages/reference/infrastructure-as-code/teleport-resources/discovery-config.mdx diff --git a/build.assets/tooling/cmd/resource-ref-generator/config.yaml b/build.assets/tooling/cmd/resource-ref-generator/config.yaml index bec10e418e460..86795daffef87 100644 --- a/build.assets/tooling/cmd/resource-ref-generator/config.yaml +++ b/build.assets/tooling/cmd/resource-ref-generator/config.yaml @@ -1,16 +1,22 @@ source: "../../../../api" destination: "../../../../docs/pages/reference/infrastructure-as-code/teleport-resources" + +# Please alphabetize the resource list by type name. resources: - - type: "InstallerV1" + - type: DiscoveryConfig + package: discoveryconfig + yaml_kind: discovery_config + yaml_version: v1 + - type: InstallerV1 package: types - yaml_kind: "installer" - yaml_version: "v1" + yaml_kind: installer + yaml_version: v1 - type: OIDCConnectorV3 package: types - yaml_kind: "oidc" - yaml_version: "v3" + yaml_kind: oidc + yaml_version: v3 - type: SAMLConnectorV2 package: types - yaml_kind: "saml" - yaml_version: "v2" + yaml_kind: saml + yaml_version: v2 diff --git a/build.assets/tooling/cmd/resource-ref-generator/resource/resource.go b/build.assets/tooling/cmd/resource-ref-generator/resource/resource.go index 6f9df67127e6a..491575c455f84 100644 --- a/build.assets/tooling/cmd/resource-ref-generator/resource/resource.go +++ b/build.assets/tooling/cmd/resource-ref-generator/resource/resource.go @@ -82,7 +82,6 @@ func NewSourceData(rootPath string) (SourceData, error) { // information about dynamic resource fields, which we can look up by // package and declaration name. typeDecls := make(map[PackageInfo]DeclarationInfo) - possibleFuncDecls := []DeclarationInfo{} // Load each file in the source directory individually. Not using // packages.Load here since the resulting []*Package does not expose @@ -128,15 +127,8 @@ func NewSourceData(rootPath string) (SourceData, error) { // - Type declarations pn := NamedImports(file) for _, decl := range file.Decls { - di := DeclarationInfo{ - Decl: decl, - FilePath: relDeclPath, - PackageName: file.Name.Name, - NamedImports: pn, - } l, ok := decl.(*ast.GenDecl) if !ok { - possibleFuncDecls = append(possibleFuncDecls, di) continue } if len(l.Specs) != 1 { @@ -390,10 +382,10 @@ func (e NotAGenDeclError) Error() string { return "the declaration is not a GenDecl" } -// getRawTypes returns a representation of the type spec of decl to use for +// typeForDecl returns a representation of the type spec of decl to use for // further processing. Returns an error if there is either no type spec or more // than one. -func getRawTypes(decl DeclarationInfo, allDecls map[PackageInfo]DeclarationInfo) (rawType, error) { +func typeForDecl(decl DeclarationInfo, allDecls map[PackageInfo]DeclarationInfo) (rawType, error) { gendecl, ok := decl.Decl.(*ast.GenDecl) if !ok { return rawType{}, NotAGenDeclError{} @@ -734,12 +726,12 @@ func printableDescription(description, ident string) string { return result } -// handleEmbeddedStructFields finds embedded structs within fld and recursively +// allFieldsForDecl finds embedded structs within fld and recursively // processes the fields of those structs as though the fields belonged to the // containing struct. Uses decl and allDecls to look up fields within the base // structs. Returns a modified slice of fields that include all non-embedded // fields within fld. -func handleEmbeddedStructFields(decl DeclarationInfo, fld []rawField, allDecls map[PackageInfo]DeclarationInfo) ([]rawField, error) { +func allFieldsForDecl(decl DeclarationInfo, fld []rawField, allDecls map[PackageInfo]DeclarationInfo) ([]rawField, error) { fieldsToProcess := []rawField{} for _, l := range fld { // Not an embedded struct field, so append it to the final @@ -787,14 +779,14 @@ func handleEmbeddedStructFields(decl DeclarationInfo, fld []rawField, allDecls m c.name, ) } - e, err := getRawTypes(d, allDecls) + e, err := typeForDecl(d, allDecls) if err != nil && !errors.As(err, &NotAGenDeclError{}) { return nil, err } // The embedded struct field may have its own embedded struct // fields. - nf, err := handleEmbeddedStructFields(decl, e.fields, allDecls) + nf, err := allFieldsForDecl(decl, e.fields, allDecls) if err != nil { return nil, err } @@ -827,12 +819,12 @@ func NamedImports(file *ast.File) map[string]string { // ReferenceDataFromDeclaration gets data for the reference by examining decl. // Looks up decl's fields in allDecls and methods in allMethods. func ReferenceDataFromDeclaration(decl DeclarationInfo, allDecls map[PackageInfo]DeclarationInfo) (map[PackageInfo]ReferenceEntry, error) { - rs, err := getRawTypes(decl, allDecls) + rs, err := typeForDecl(decl, allDecls) if err != nil { return nil, err } - fieldsToProcess, err := handleEmbeddedStructFields(decl, rs.fields, allDecls) + fieldsToProcess, err := allFieldsForDecl(decl, rs.fields, allDecls) if err != nil { return nil, err } @@ -872,7 +864,7 @@ func ReferenceDataFromDeclaration(decl DeclarationInfo, allDecls map[PackageInfo // For any fields within decl that have a custom type, look up the // declaration for that type and create a separate reference entry for // it. - for _, f := range rs.fields { + for _, f := range fieldsToProcess { // Don't make separate reference entries for embedded structs // since they are part of the containing struct for the purposes // of unmarshaling YAML. diff --git a/build.assets/tooling/cmd/resource-ref-generator/resource/resource_test.go b/build.assets/tooling/cmd/resource-ref-generator/resource/resource_test.go index cf3b2633e82e4..21b41d8949a3a 100644 --- a/build.assets/tooling/cmd/resource-ref-generator/resource/resource_test.go +++ b/build.assets/tooling/cmd/resource-ref-generator/resource/resource_test.go @@ -708,6 +708,85 @@ type Metadata struct { YAMLExample: `alias: "string" name: "string" active: true +`, + }, + }, + }, + { + description: "embedded struct with struct field", + declInfo: PackageInfo{ + DeclName: "MyResource", + PackageName: "mypkg", + }, + source: `package mypkg +// MyResource is a resource declared for testing. +type MyResource struct{ + // Alias is another name to call the resource. + Alias string BACKTICKjson:"alias"BACKTICK + types.Header +} +`, + declSources: []string{ + `package types +type Header struct { + // Metadata is the resource metadata + Metadata Metadata BACKTICKjson:"metadata"BACKTICK +} + +// Metadata describes information about a dynamic resource. Every dynamic +// resource in Teleport has a metadata object. +type Metadata struct { + // Name is the name of the resource. + Name string BACKTICKprotobuf:"bytes,1,opt,name=Name,proto3" json:"name"BACKTICK + // Active indicates whether the resource is currently in use. + Active bool BACKTICKjson:"active"BACKTICK +}`, + }, + expected: map[PackageInfo]ReferenceEntry{ + PackageInfo{ + DeclName: "MyResource", + PackageName: "mypkg", + }: { + SectionName: "My Resource", + Description: "A resource declared for testing.", + SourcePath: "src/myfile.go", + Fields: []Field{ + { + Name: "alias", + Description: "Another name to call the resource.", + Type: "string", + }, + { + Name: "metadata", + Description: "The resource metadata", + Type: "[Metadata](#metadata)", + }, + }, + YAMLExample: `alias: "string" +metadata: # [...] +`, + }, + PackageInfo{ + DeclName: "Metadata", + PackageName: "types", + }: { + SectionName: "Metadata", + SourcePath: "src/myfile0.go", + Description: "Describes information about a dynamic resource. Every dynamic resource in Teleport has a metadata object.", + Fields: []Field{ + { + Name: "active", + Description: "Indicates whether the resource is currently in use.", + Type: "Boolean", + }, + { + Name: "name", + Description: "The name of the resource.", + Type: "string", + }, + }, + YAMLExample: `name: "string" +active: true `, }, }, diff --git a/docs/pages/reference/infrastructure-as-code/teleport-resources/discovery-config.mdx b/docs/pages/reference/infrastructure-as-code/teleport-resources/discovery-config.mdx new file mode 100644 index 0000000000000..36b623ac02423 --- /dev/null +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/discovery-config.mdx @@ -0,0 +1,521 @@ +--- +title: Discovery Config Reference +description: Provides a reference of fields within the Discovery Config resource, which you can manage with tctl. +sidebar_label: Discovery Config +--- +{/* vale 3rd-party-products.former-names = NO */} +{/* vale messaging.capitalization = NO */} +{/* Automatically generated from: types/discoveryconfig/discoveryconfig.go */} +{/* DO NOT EDIT */} + +**Kind**: `discovery_config`
+**Version**: `v1` + +Describes extra discovery matchers that are added to DiscoveryServices that share the same Discovery Group. + +Example: + +```yaml +kind: "string" +sub_kind: "string" +version: "string" +metadata: # [...] +spec: # [...] +status: # [...] +``` +|Field Name|Description|Type| +|---|---|---| +|kind|A resource kind.|string| +|metadata|Metadata for the resource.|[Metadata](#metadata)| +|spec|The specification for the discovery config.|[Spec](#spec)| +|status|The status for the discovery config.|[Status](#status)| +|sub_kind|An optional resource sub kind, used in some resources.|string| +|version|The resource version.|string| + +## AWS Matcher + +Matches AWS EC2 instances and AWS Databases + + +Example: + +```yaml +types: + - "string" + - "string" + - "string" +regions: + - "string" + - "string" + - "string" +assume_role: # [...] +tags: # [...] +install: # [...] +ssm: # [...] +integration: "string" +kube_app_discovery: true +setup_access_for_arn: "string" +organization: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|assume_role|ARN is the AWS role to assume for database discovery.|[Assume Role](#assume-role)| +|install|Sets the join method when installing on discovered EC2 nodes|[Installer Params](#installer-params)| +|integration|The integration name used to generate credentials to interact with AWS APIs. Environment credentials will not be used when this value is set.|string| +|kube_app_discovery|Controls whether Kubernetes App Discovery will be enabled for agents running on discovered clusters, currently only affects AWS EKS discovery in integration mode.|Boolean| +|organization|An AWS Organization matcher for discovering resources accross multiple accounts under an Organization.|[AWS Organization Matcher](#aws-organization-matcher)| +|regions|AWS regions to query for databases.|[]string| +|setup_access_for_arn|The role that the Discovery Service should create EKS Access Entries for. This value should match the IAM identity that Teleport Kubernetes Service uses. If this value is empty, the Discovery Service will attempt to set up access for its own identity (self).|string| +|ssm|Provides options to use when sending a document command to an EC2 node|[AWSSSM](#awsssm)| +|tags|AWS resource Tags to match.|[Labels](#labels)| +|types|AWS database types to match, "ec2", "rds", "redshift", "elasticache", or "memorydb".|[]string| + +## AWS Organization Matcher + +Specifies an Organization and rules for discovering accounts under that organization. + + +Example: + +```yaml +organization_id: "string" +organizational_units: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|organization_id|The AWS Organization ID to match against. Required.|string| +|organizational_units|Contains rules for matchings AWS accounts based on their Organizational Units.|[AWS Organization Units Matcher](#aws-organization-units-matcher)| + +## AWS Organization Units Matcher + +Contains rules for matching accounts under an Organization. Accounts that belong to an excluded Organizational Unit, and its children, will be excluded even if they were included. + + +Example: + +```yaml +include: + - "string" + - "string" + - "string" +exclude: + - "string" + - "string" + - "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|exclude|A list of AWS Organizational Unit IDs to exclude. Only exact matches or wildcard (*) are supported. If empty, no Organizational Units are excluded by default.|[]string| +|include|A list of AWS Organizational Unit IDs to match. Only exact matches or wildcard (*) are supported. If empty, all Organizational Units are included by default.|[]string| + +## AWSSSM + +Provides options to use when executing SSM documents + + +Example: + +```yaml +document_name: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|document_name|The name of the document to use when executing an SSM command|string| + +## Access Graph AWS Sync + +A configuration for AWS Access Graph service poll service. + + +Example: + +```yaml +regions: + - "string" + - "string" + - "string" +assume_role: # [...] +integration: "string" +cloud_trail_logs: # [...] +eks_audit_logs: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|assume_role|ARN is the AWS role to assume for database discovery.|[Assume Role](#assume-role)| +|cloud_trail_logs|Configuration settings for collecting AWS CloudTrail logs via an SQS queue.|[Access Graph AWS Sync Cloud Trail Logs](#access-graph-aws-sync-cloud-trail-logs)| +|eks_audit_logs||[Access Graph AWS Sync EKS Audit Logs](#access-graph-aws-sync-eks-audit-logs)| +|integration|The integration name used to generate credentials to interact with AWS APIs.|string| +|regions|AWS regions to import resources from.|[]string| + +## Access Graph AWS Sync Cloud Trail Logs + +Defines settings for ingesting AWS CloudTrail logs by polling an SQS queue that receives notifications about new log files. + + +Example: + +```yaml +region: "string" +sqs_queue: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|region|The AWS region of the SQS queue for CloudTrail notifications, ex.: "us-east-2".|string| +|sqs_queue|The name or URL for CloudTrail log events, ex.: "demo-cloudtrail-queue".|string| + +## Access Graph AWS Sync EKS Audit Logs + +Defines the settings for ingesting Kubernetes apiserver audit logs from EKS clusters. + + +Example: + +```yaml +tags: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|tags|The tags of EKS clusters for which apiserver audit logs should be fetched.|[Labels](#labels)| + +## Access Graph Azure Sync + +A configuration for Azure Access Graph service poll service. + + +Example: + +```yaml +subscription_id: "string" +integration: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|integration|The integration name used to generate credentials to interact with AWS APIs.|string| +|subscription_id|Is the ID of the Azure subscription to sync resources from|string| + +## Access Graph Sync + +A configuration for Access Graph service. + + +Example: + +```yaml +aws: + - # [...] + - # [...] + - # [...] +poll_interval: # See description +azure: + - # [...] + - # [...] + - # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|aws|A configuration for AWS Access Graph service poll service.|[][Access Graph AWS Sync](#access-graph-aws-sync)| +|azure|A configuration for Azure Access Graph service poll service.|[][Access Graph Azure Sync](#access-graph-azure-sync)| +|poll_interval|The frequency at which to poll for resources|| + +## Assume Role + +Provides a role ARN and ExternalID to assume an AWS role when interacting with AWS resources. + + +Example: + +```yaml +role_arn: "string" +external_id: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|external_id|The external ID used to assume a role in another account.|string| +|role_arn|The fully specified AWS IAM role ARN.|string| + +## Azure Installer Params + +The set of Azure-specific installation parameters. + + +Example: + +```yaml +client_id: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|client_id|The client ID of the managed identity discovered nodes should use to join the cluster.|string| + +## Azure Matcher + +Matches Azure resources. It defines which resource types, filters and some configuration params. + + +Example: + +```yaml +subscriptions: + - "string" + - "string" + - "string" +resource_groups: + - "string" + - "string" + - "string" +types: + - "string" + - "string" + - "string" +regions: + - "string" + - "string" + - "string" +tags: # [...] +install_params: # [...] +integration: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|install_params|Sets the join method when installing on discovered Azure nodes.|[Installer Params](#installer-params)| +|integration|The integration name used to generate credentials to interact with Azure APIs. Environment credentials will not be used when this value is set.|string| +|regions|Azure locations to match for databases.|[]string| +|resource_groups|Azure resource groups to query for resources.|[]string| +|subscriptions|Azure subscriptions to query for resources.|[]string| +|tags|Azure tags on resources to match.|[Labels](#labels)| +|types|Azure types to match: "mysql", "postgres", "aks", "vm"|[]string| + +## GCP Matcher + +Matches GCP resources. + + +Example: + +```yaml +types: + - "string" + - "string" + - "string" +locations: + - "string" + - "string" + - "string" +tags: # [...] +project_ids: + - "string" + - "string" + - "string" +service_accounts: + - "string" + - "string" + - "string" +install_params: # [...] +labels: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|install_params|Sets the join method when installing on discovered GCP nodes.|[Installer Params](#installer-params)| +|labels|GCP labels to match.|[Labels](#labels)| +|locations|GKE locations to search resources for.|[]string| +|project_ids|The GCP project ID where the resources are deployed.|[]string| +|service_accounts|The emails of service accounts attached to VMs.|[]string| +|tags|Obsolete and only exists for backwards compatibility. Use Labels instead.|[Labels](#labels)| +|types|GKE resource types to match: "gke", "vm".|[]string| + +## HTTP Proxy Settings + +Defines HTTP proxy settings for making HTTP and HTTPS requests. + + +Example: + +```yaml +http_proxy: "string" +https_proxy: "string" +no_proxy: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|http_proxy|The URL for the HTTP proxy to use when making requests. When applied, this will set the HTTP_PROXY environment variable.|string| +|https_proxy|The URL for the HTTPS Proxy to use when making requests. When applied, this will set the HTTPS_PROXY environment variable.|string| +|no_proxy|A comma separated list of URLs that will be excluded from proxying. When applied, this will set the NO_PROXY environment variable.|string| + +## Install Param Enroll Mode + +The mode used to enroll the node into the cluster. + + +## Installer Params + +InstallParams sets join method to use on discovered nodes + + +Example: + +```yaml +join_method: # [...] +join_token: "string" +script_name: "string" +install_teleport: true +sshd_config: "string" +proxy_addr: "string" +azure: # [...] +enroll_mode: # [...] +suffix: "string" +update_group: "string" +http_proxy_settings: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|azure|The set of Azure-specific installation parameters.|[Azure Installer Params](#azure-installer-params)| +|enroll_mode|Indicates the enrollment mode to be used when adding a node. Valid values: 0: uses eice for EC2 matchers which use an integration and script for all the other methods 1: uses script mode 2: uses eice mode (deprecated)|[Install Param Enroll Mode](#install-param-enroll-mode)| +|http_proxy_settings|Defines HTTP proxy settings for making HTTP requests. When set, this will set the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables before running the installation.|[HTTP Proxy Settings](#http-proxy-settings)| +|install_teleport|Disables agentless discovery|Boolean| +|join_method|The method to use when joining the cluster|[Join Method](#join-method)| +|join_token|The token to use when joining the cluster|string| +|proxy_addr|The address of the proxy the discovered node should use to connect to the cluster.|string| +|script_name|The name of the teleport installer script resource for the cloud instance to execute|string| +|sshd_config|Provides the path to write sshd configuration changes|string| +|suffix|Indicates the installation suffix for the teleport installation. Set this value if you want multiple installations of Teleport. See --install-suffix flag in teleport-update program. Note: only supported for Amazon EC2. Suffix name can only contain alphanumeric characters and hyphens.|string| +|update_group|Indicates the update group for the teleport installation. This value is used to group installations in order to update them in batches. See --group flag in teleport-update program. Note: only supported for Amazon EC2. Group name can only contain alphanumeric characters and hyphens.|string| + +## Join Method + +The method used for new nodes to join the cluster. + + +## Kubernetes Matcher + +Matches Kubernetes services. + + +Example: + +```yaml +types: + - "string" + - "string" + - "string" +namespaces: + - "string" + - "string" + - "string" +labels: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|labels|Kubernetes services labels to match.|[Labels](#labels)| +|namespaces|Kubernetes namespaces in which to discover services|[]string| +|types|Kubernetes services types to match. Currently only 'app' is supported.|[]string| + +## Labels + +A wrapper around map that can marshal and unmarshal itself from scalar and list values + + +## Metadata + +Resource metadata + + +Example: + +```yaml +name: "string" +description: "string" +labels: + "string": "string" + "string": "string" + "string": "string" +expires: # See description +revision: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|description|Object description|string| +|expires|A global expiry time header can be set on any resource in the system.|| +|labels|A set of labels|map[string]string| +|name|An object name|string| +|revision|An opaque identifier which tracks the versions of a resource over time. Clients should ignore and not alter its value but must return the revision in any updates of a resource.|string| + +## Spec + +The specification for a discovery config. + + +Example: + +```yaml +discovery_group: "string" +aws: + - # [...] + - # [...] + - # [...] +azure: + - # [...] + - # [...] + - # [...] +gcp: + - # [...] + - # [...] + - # [...] +kube: + - # [...] + - # [...] + - # [...] +access_graph: # [...] +``` + +|Field Name|Description|Type| +|---|---|---| +|access_graph|The configuration for the Access Graph Cloud sync.|[Access Graph Sync](#access-graph-sync)| +|aws|A list of matchers for the supported resources in AWS.|[][AWS Matcher](#aws-matcher)| +|azure|A list of matchers for the supported resources in Azure.|[][Azure Matcher](#azure-matcher)| +|discovery_group|The Discovery Group for the current DiscoveryConfig. DiscoveryServices should include all the matchers if the DiscoveryGroup matches with their own group.|string| +|gcp|A list of matchers for the supported resources in GCP.|[][GCP Matcher](#gcp-matcher)| +|kube|A list of matchers for the supported resources in Kubernetes.|[][Kubernetes Matcher](#kubernetes-matcher)| + +## Status + +Holds dynamic information about the discovery configuration running status such as errors, state and count of the resources. + + +Example: + +```yaml +state: "string" +error_message: "string" +discovered_resources: 1 +last_sync_time: # See description +integration_discovered_resources: + "string": # See description + "string": # See description + "string": # See description +``` + +|Field Name|Description|Type| +|---|---|---| +|discovered_resources|Holds the count of the discovered resources in the previous iteration.|number| +|error_message|Holds the error message when state is DISCOVERY_CONFIG_STATE_ERROR.|string| +|integration_discovered_resources|Maps an integration to a summary of resources that were found using that integration.|map[string]| +|last_sync_time|The timestamp when the Discovery Config was last sync.|| +|state|The current state of the discovery config.|string| +