diff --git a/build.assets/tooling/cmd/resource-ref-generator/config.yaml b/build.assets/tooling/cmd/resource-ref-generator/config.yaml index 3affda5bdd9ea..4740dae572322 100644 --- a/build.assets/tooling/cmd/resource-ref-generator/config.yaml +++ b/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: diff --git a/build.assets/tooling/cmd/resource-ref-generator/reference/reference.go b/build.assets/tooling/cmd/resource-ref-generator/reference/reference.go index 7a1f312a2eda7..c2a230f1b1835 100644 --- a/build.assets/tooling/cmd/resource-ref-generator/reference/reference.go +++ b/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) diff --git a/build.assets/tooling/cmd/resource-ref-generator/reference/reference.tmpl b/build.assets/tooling/cmd/resource-ref-generator/reference/reference.tmpl index 36e3eff4fb73c..57b17fb6954f9 100644 --- a/build.assets/tooling/cmd/resource-ref-generator/reference/reference.tmpl +++ b/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 }} diff --git a/build.assets/tooling/cmd/resource-ref-generator/resource_examples/discovery_config.yaml b/build.assets/tooling/cmd/resource-ref-generator/resource_examples/discovery_config.yaml new file mode 100644 index 0000000000000..c04e432a8452e --- /dev/null +++ b/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: "" + # Optional: when using managed updates, set the update group of the installation. + # Supported characters are alphanumeric characters and `-`. + 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: "" + # Optional: when using managed updates, set the update group of the installation. + # Supported characters are alphanumeric characters and `-`. + 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: "" + # Optional: when using managed updates, set the update group of the installation. + # Supported characters are alphanumeric characters and `-`. + 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: + "*": "*" diff --git a/docs/pages/enroll-resources/auto-discovery/servers/azure-discovery.mdx b/docs/pages/enroll-resources/auto-discovery/servers/azure-discovery.mdx index fca90b846138f..39e0590d00d4b 100644 --- a/docs/pages/enroll-resources/auto-discovery/servers/azure-discovery.mdx +++ b/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 to the host and port of the Teleport Proxy Service in your cluster, +and 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: "" 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: [""] - resource_groups: [""] - regions: [""] - 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: "" + discovery_group: ``` -- 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. + + +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. + + + + + 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: + azure: + - types: ["vm"] + subscriptions: [""] + resource_groups: [""] + regions: [""] + 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: "" + ``` + 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. + + + + 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: + azure: + - types: ["vm"] + subscriptions: [""] + resource_groups: [""] + regions: [""] + 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: "" + ``` + + 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. + + + ## Auto-discovery labels diff --git a/docs/pages/enroll-resources/auto-discovery/servers/gcp-discovery.mdx b/docs/pages/enroll-resources/auto-discovery/servers/gcp-discovery.mdx index 256b1329cf6ac..86f3988d2ad39 100644 --- a/docs/pages/enroll-resources/auto-discovery/servers/gcp-discovery.mdx +++ b/docs/pages/enroll-resources/auto-discovery/servers/gcp-discovery.mdx @@ -241,18 +241,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 GCP instance discovery the `discovery_service.gcp` section -of `teleport.yaml` must include at least one entry: - (!docs/pages/includes/discovery/discovery-group.mdx!) +Assign to the host and port of the Teleport Proxy Service in your cluster, +and 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: ":443" + proxy_server: "" auth_service: enabled: false proxy_service: @@ -261,30 +262,88 @@ ssh_service: enabled: false discovery_service: enabled: true - discovery_group: "gcp-prod" - gcp: - - types: ["gce"] - # The IDs of GCP projects that VMs can join from. - project_ids: [] - # (Optional) The locations that VMs can join from. Note: both regions and - # zones are accepted. - locations: [] - # (Optional) The email addresses of service accounts that VMs can join - # with. - service_accounts: [] - # (Optional) Labels that joining VMs must have. - labels: - "env": "prod" # Match virtual machines where label:env=prod - install: - public_proxy_addr: ":443" + discovery_group: ``` -- Edit the `teleport.auth_server` or `teleport.proxy_server` key to match your Auth Service or Proxy Service's domain name - and port, respectively. -- Adjust the keys under `discovery_service.gcp` to match your GCP environment, +Create a matcher for the resources you want to enroll. + + +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. + + + + + Create a Discovery Config resource, that has the same discovery group you configured earlier, to enable GCP VM discovery. + + Create a file named `discovery-gcp-prod.yaml` with the following content: + ```yaml + kind: discovery_config + version: v1 + metadata: + name: example-discovery-config + spec: + discovery_group: + gcp: + - types: ["gce"] + # The IDs of GCP projects that VMs can join from. + project_ids: [] + # (Optional) The locations that VMs can join from. Note: both regions and + # zones are accepted. + locations: [] + # (Optional) The email addresses of service accounts that VMs can join + # with. + service_accounts: [] + # (Optional) Labels that joining VMs must have. + labels: + "env": "prod" # Match virtual machines where label:env=prod + ``` + Adjust the keys under `spec.gcp` to match your GCP environment, + specifically the project IDs, locations, service accounts and labels you want to associate with the Discovery Service. + + Create the Discovery Config by running the following command: + ```code + $ tctl create -f discovery-gcp-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. + + + + In order to enable GCP VM discovery the `discovery_service.gcp` section + of `teleport.yaml` must include at least one entry: + + ```yaml + # teleport.yaml + # ... + discovery_service: + enabled: true + discovery_group: + gcp: + - types: ["gce"] + # The IDs of GCP projects that VMs can join from. + project_ids: [] + # (Optional) The locations that VMs can join from. Note: both regions and + # zones are accepted. + locations: [] + # (Optional) The email addresses of service accounts that VMs can join + # with. + service_accounts: [] + # (Optional) Labels that joining VMs must have. + labels: + "env": "prod" # Match virtual machines where label:env=prod + ``` + Adjust the keys under `discovery_service.gcp` to match your GCP environment, specifically the projects, locations, service accounts, and tags you want to associate with the Discovery Service. + + + ### GCP credentials The Teleport Discovery Service must have the credentials of the diff --git a/docs/pages/includes/auto-discovery/ec2-config.mdx b/docs/pages/includes/auto-discovery/ec2-config.mdx index 586f0f9ad98ab..7bbdb1045ad93 100644 --- a/docs/pages/includes/auto-discovery/ec2-config.mdx +++ b/docs/pages/includes/auto-discovery/ec2-config.mdx @@ -9,13 +9,10 @@ $ tctl tokens add --type=discovery Save the generated token in `/tmp/token` on the Node (EC2 instance) that will run the Discovery Service. -In order to enable EC2 instance discovery the `discovery_service.aws` section -of `teleport.yaml` must include at least one entry: - (!docs/pages/includes/discovery/discovery-group.mdx!) -Assign to the host and port of the -Teleport Proxy Service in your cluster: +Assign to the host and port of the Teleport Proxy Service in your cluster, +and to a name that identifies a group of resources that you will enroll: ```yaml # teleport.yaml @@ -33,22 +30,80 @@ ssh_service: enabled: false discovery_service: enabled: true - discovery_group: "aws-prod" - aws: - - types: ["ec2"] - regions: ["us-east-1","us-west-1"] - ssm: - document_name: "AWS-RunShellScript" - install: + discovery_group: +``` + +Create a matcher for the resources you want to enroll. + + +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. + + + + + Create a Discovery Config resource, that has the same discovery group you configured earlier, to enable EC2 instance discovery. + + Create a file named `discovery-aws-prod.yaml` with the following content: + ```yaml + kind: discovery_config + version: v1 + metadata: + name: example-discovery-config + spec: + discovery_group: + aws: + - types: ["ec2"] + regions: ["us-east-1", "us-west-1"] + ssm: + document_name: "AWS-RunShellScript" + install: join_params: token_name: aws-discovery-iam-token method: iam - tags: - "env": "prod" # Match EC2 instances where tag:env=prod -``` + tags: + "env": "prod" # Match EC2 instances where tag:env=prod + ``` + Adjust the keys under `spec.aws` to match your EC2 environment, + specifically the 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-aws-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. + + + + In order to enable EC2 instance discovery the `discovery_service.aws` section + of `teleport.yaml` must include at least one entry: + + ```yaml + # teleport.yaml + # ... + discovery_service: + enabled: true + discovery_group: + aws: + - types: ["ec2"] + regions: ["us-east-1","us-west-1"] + ssm: + document_name: "AWS-RunShellScript" + install: + join_params: + token_name: aws-discovery-iam-token + method: iam + tags: + "env": "prod" # Match EC2 instances where tag:env=prod + ``` + + Adjust the keys under `discovery_service.aws` to match your EC2 environment, + specifically the regions and tags you want to associate with the Discovery Service. + -- Edit the `teleport.proxy_server` key to match your Proxy Service's URI - and port. -- Adjust the keys under `discovery_service.aws` to match your EC2 environment, - specifically the regions and tags you want to associate with the Discovery - Service. + diff --git a/docs/pages/includes/auto-discovery/ec2-cross-account-config.mdx b/docs/pages/includes/auto-discovery/ec2-cross-account-config.mdx index 94a2a1a7a77a2..d58889950f565 100644 --- a/docs/pages/includes/auto-discovery/ec2-cross-account-config.mdx +++ b/docs/pages/includes/auto-discovery/ec2-cross-account-config.mdx @@ -1,3 +1,40 @@ + + +Edit the Discovery Config created previously to add an entry to the `spec.aws` section, +assigning to the ARN of the IAM role to assume and + to an optional external ID: + +```yaml +kind: discovery_config +# ... +spec: + aws: + - types: ["ec2"] + ssm: + document_name: "AWS-RunShellScript" + # Add new entry after existing entries + - types: ["ec2"] + regions: ["us-east-1","us-west-1"] + install: + join_params: + token_name: aws-discovery-iam-token + method: iam + ssm: + document_name: "AWS-RunShellScript" + tags: + "env": "prod" # Match EC2 instances where tag:env=prod + assume_role: + role_arn: "" + external_id: "" + - types: ["ec2"] + ssm: + document_name: "AWS-RunShellScript" + # Add a new entry for each account. + # ... +``` + + + Add an entry to the `discovery_service.aws` section of your `teleport.yaml` file, assigning to the ARN of the IAM role to assume and to an optional external ID: @@ -30,4 +67,6 @@ discovery_service: document_name: "AWS-RunShellScript" # Add a new entry for each account. # ... -``` \ No newline at end of file +``` + + \ No newline at end of file diff --git a/docs/pages/includes/auto-discovery/server-advanced-config.mdx b/docs/pages/includes/auto-discovery/server-advanced-config.mdx index 76962af9503b2..faa3275c31e7d 100644 --- a/docs/pages/includes/auto-discovery/server-advanced-config.mdx +++ b/docs/pages/includes/auto-discovery/server-advanced-config.mdx @@ -7,7 +7,20 @@ This section covers configuration options for discovering and enrolling servers. When using blue-green deployments or other multiple clusters setups, you might want to access your instances from different clusters. Teleport supports installing and running multiple agents on the same instance, using a suffixed installation which allows you to isolate each installation. + + +To configure the Discovery Service to use a suffixed installation, edit the Discovery Config and set the `spec.aws.install.suffix` key: +```yaml +kind: discovery_config +# ... +spec: + {{ matcher }}: + - install: + suffix: "blue-cluster" +``` + + To configure the Discovery Service to use a suffixed installation, specify the `install.suffix` key in your Discovery Service configuration: ```yaml @@ -20,6 +33,8 @@ discovery_service: - install: suffix: "blue-cluster" ``` + + Requires [agent managed updates](../../upgrading/agent-managed-updates/agent-managed-updates.mdx) to be enabled. @@ -27,6 +42,21 @@ Requires [agent managed updates](../../upgrading/agent-managed-updates/agent-man If you are using Teleport [Agent managed updates](../../upgrading/agent-managed-updates/agent-managed-updates.mdx), you can configure the update group so that you can control which instances get updated together. + + +To set the update group, edit the Discovery Config and set the `spec.aws.install.update_group` key: + +```yaml +kind: discovery_config +# ... +spec: + {{ matcher }}: + - install: + update_group: "update-group-1" +``` + + + To set the update group, specify the `install.update_group` key in your Discovery Service configuration: ```yaml @@ -40,10 +70,31 @@ discovery_service: update_group: "update-group-1" ``` + + + ### Configure HTTP Proxy during installation For instances which require a proxy to access the installation files, you can configure HTTP Proxy settings in the Discovery Service. + + +To set the HTTP proxy settings, edit the Discovery Config and set the `spec.aws.install.http_proxy_settings` key: + +```yaml +kind: discovery_config +# ... +spec: + {{ matcher }}: + - install: + http_proxy_settings: + https_proxy: http://172.31.5.130:3128 + http_proxy: http://172.31.5.130:3128 + no_proxy: my-local-domain +``` + + + You must set the `install.http_proxy_settings` key in your configuration: ```yaml @@ -58,4 +109,6 @@ discovery_service: https_proxy: http://172.31.5.130:3128 http_proxy: http://172.31.5.130:3128 no_proxy: my-local-domain -``` \ No newline at end of file +``` + + \ No newline at end of file diff --git a/docs/pages/includes/discovery/discovery-config.yaml b/docs/pages/includes/discovery/discovery-config.yaml index 85cb4e9e41649..2d0776c1c23b3 100644 --- a/docs/pages/includes/discovery/discovery-config.yaml +++ b/docs/pages/includes/discovery/discovery-config.yaml @@ -8,6 +8,10 @@ discovery_service: # 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" # poll_interval is the cadence at which the discovery server will run each of its # discovery cycles. The default is 5m. diff --git a/docs/pages/includes/server-access/custom-installer-aws-dynamic.yaml b/docs/pages/includes/server-access/custom-installer-aws-dynamic.yaml new file mode 100644 index 0000000000000..d1282fd765e7a --- /dev/null +++ b/docs/pages/includes/server-access/custom-installer-aws-dynamic.yaml @@ -0,0 +1,20 @@ +kind: discovery_config +# ... +spec: + aws: + - types: ["ec2"] + tags: + - "env": "prod" + regions: ["us-west1", "us-east1"] + install: + script_name: "default-installer" + ssm: + document_name: "AWS-RunShellScript" + - types: ["ec2"] + tags: + - "env": "devel" + regions: ["us-west1", "us-east1"] + install: + script_name: "devel-installer" + ssm: + document_name: "AWS-RunShellScript" diff --git a/docs/pages/includes/server-access/custom-installer-azure-dynamic.yaml b/docs/pages/includes/server-access/custom-installer-azure-dynamic.yaml new file mode 100644 index 0000000000000..048ce60c5860f --- /dev/null +++ b/docs/pages/includes/server-access/custom-installer-azure-dynamic.yaml @@ -0,0 +1,14 @@ +kind: discovery_config +# ... +spec: + azure: + - types: ["vm"] + tags: + - "env": "prod" + install: # optional section when default-installer is used. + script_name: "default-installer" + - types: ["vm"] + tags: + - "env": "devel" + install: + script_name: "devel-installer" diff --git a/docs/pages/includes/server-access/custom-installer-gcp-dynamic.yaml b/docs/pages/includes/server-access/custom-installer-gcp-dynamic.yaml new file mode 100644 index 0000000000000..6f302f1cbccfe --- /dev/null +++ b/docs/pages/includes/server-access/custom-installer-gcp-dynamic.yaml @@ -0,0 +1,14 @@ +kind: discovery_config +# ... +spec: + gcp: + - types: ["gce"] + tags: + - "env": "prod" + install: # optional section when default-installer is used. + script_name: "default-installer" + - types: ["gce"] + tags: + - "env": "devel" + install: + script_name: "devel-installer" diff --git a/docs/pages/includes/server-access/custom-installer.mdx b/docs/pages/includes/server-access/custom-installer.mdx index b842c0c2c479e..9abbb9570e789 100644 --- a/docs/pages/includes/server-access/custom-installer.mdx +++ b/docs/pages/includes/server-access/custom-installer.mdx @@ -36,12 +36,22 @@ After making the desired changes to the default installer, save and close the file in your text editor. Multiple `installer` resources can exist and be specified in the -`{{ matcher }}.install.script_name` section of a `discovery_service.{{ matcher }}` list item in -`teleport.yaml`: +`{{ matcher }}.install.script_name` section: + + +Edit the Discovery Config to specify a custom installer script: +```yaml +(!docs/pages/includes/server-access/custom-installer-{{ matcher }}-dynamic.yaml!) +``` + + +Edit the `teleport.yaml` configuration to specify a custom installer script: ```yaml (!docs/pages/includes/server-access/custom-installer-{{ matcher }}.yaml!) ``` + + --- diff --git a/docs/pages/reference/deployment/config.mdx b/docs/pages/reference/deployment/config.mdx index 914cf92f4ef1f..09c6bd3efa709 100644 --- a/docs/pages/reference/deployment/config.mdx +++ b/docs/pages/reference/deployment/config.mdx @@ -195,6 +195,12 @@ These settings apply to the Teleport Database Service: ### Discovery Service +Discovery Service watches your cloud environment and automatically enrolls supported resources into Teleport. + +Instead of using the cloud matchers (i.e. `discovery_service.aws`, `discovery_service.gcp` and `discovery_service.azure`) to specify which resources to enroll, +you can create Discovery Configs via [`tctl`](../infrastructure-as-code/teleport-resources/discovery-config.mdx) or [Terraform](../infrastructure-as-code/terraform-provider/resources/discovery_config.mdx). +The Discovery Service loads all the Discovery Configs that have the same `discovery_group`. + These settings apply to the Teleport Discovery Service: ```yaml diff --git a/docs/pages/reference/infrastructure-as-code/teleport-resources/app-v3.mdx b/docs/pages/reference/infrastructure-as-code/teleport-resources/app-v3.mdx index edca321856eaf..64db326302e6b 100644 --- a/docs/pages/reference/infrastructure-as-code/teleport-resources/app-v3.mdx +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/app-v3.mdx @@ -13,6 +13,8 @@ sidebar_label: App V3 Represents an app resource. +## Top-level fields + Example: ```yaml 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 index ef045e75241c9..771be881cbac5 100644 --- a/docs/pages/reference/infrastructure-as-code/teleport-resources/discovery-config.mdx +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/discovery-config.mdx @@ -13,6 +13,210 @@ sidebar_label: Discovery Config Describes extra discovery matchers that are added to DiscoveryServices that share the same Discovery Group. +Example definition: +```yaml +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: "" + # Optional: when using managed updates, set the update group of the installation. + # Supported characters are alphanumeric characters and `-`. + 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: "" + # Optional: when using managed updates, set the update group of the installation. + # Supported characters are alphanumeric characters and `-`. + 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: "" + # Optional: when using managed updates, set the update group of the installation. + # Supported characters are alphanumeric characters and `-`. + 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: + "*": "*" + +``` + +## Top-level fields + Example: ```yaml diff --git a/docs/pages/reference/infrastructure-as-code/teleport-resources/installer-v1.mdx b/docs/pages/reference/infrastructure-as-code/teleport-resources/installer-v1.mdx index 94f2280dad77c..8a8e324e41a95 100644 --- a/docs/pages/reference/infrastructure-as-code/teleport-resources/installer-v1.mdx +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/installer-v1.mdx @@ -13,6 +13,8 @@ sidebar_label: Installer V1 Represents an installer script resource. Used to provide a script to install teleport on discovered nodes. +## Top-level fields + Example: ```yaml diff --git a/docs/pages/reference/infrastructure-as-code/teleport-resources/oidc-connector-v3.mdx b/docs/pages/reference/infrastructure-as-code/teleport-resources/oidc-connector-v3.mdx index 8b184646e9909..f3072b929f054 100644 --- a/docs/pages/reference/infrastructure-as-code/teleport-resources/oidc-connector-v3.mdx +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/oidc-connector-v3.mdx @@ -13,6 +13,8 @@ sidebar_label: OIDC Connector V3 Represents an OIDC connector. +## Top-level fields + Example: ```yaml diff --git a/docs/pages/reference/infrastructure-as-code/teleport-resources/saml-connector-v2.mdx b/docs/pages/reference/infrastructure-as-code/teleport-resources/saml-connector-v2.mdx index cd7180c957b90..e46fda3a12529 100644 --- a/docs/pages/reference/infrastructure-as-code/teleport-resources/saml-connector-v2.mdx +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/saml-connector-v2.mdx @@ -13,6 +13,8 @@ sidebar_label: SAML Connector V2 Represents a SAML connector. +## Top-level fields + Example: ```yaml diff --git a/docs/pages/reference/infrastructure-as-code/teleport-resources/saml-idpservice-provider-v1.mdx b/docs/pages/reference/infrastructure-as-code/teleport-resources/saml-idpservice-provider-v1.mdx new file mode 100644 index 0000000000000..a6f04df209776 --- /dev/null +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/saml-idpservice-provider-v1.mdx @@ -0,0 +1,112 @@ +--- +title: SAML IdPService Provider V1 Reference +description: Provides a reference of fields within the SAML IdPService Provider V1 resource, which you can manage with tctl. +sidebar_label: SAML IdPService Provider V1 +--- +{/* vale 3rd-party-products.former-names = NO */} +{/* vale messaging.capitalization = NO */} +{/* Automatically generated from: types/types.pb.go */} +{/* DO NOT EDIT */} + +**Kind**: `saml_idp_service_provider`
+**Version**: `v1` + +The representation of a SAML IdP service provider. + +## Top-level fields + +Example: + +```yaml +kind: "string" +sub_kind: "string" +version: "string" +metadata: # [...] +spec: # [...] +``` +|Field Name|Description|Type| +|---|---|---| +|kind|A resource kind|string| +|metadata|Resource metadata|[Metadata](#metadata)| +|spec|The SAML IdP service provider spec.|[SAML IdPService Provider Spec V1](#saml-idpservice-provider-spec-v1)| +|sub_kind|An optional resource sub kind, used in some resources|string| +|version|The API version used to create the resource. It must be specified. Based on this version, Teleport will apply different defaults on resource creation or deletion. It must be an integer prefixed by "v". For example: `v1`|string| + +## 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| + +## SAML Attribute Mapping + +Represents SAML service provider requested attribute name, format and its values. + + +Example: + +```yaml +name: "string" +name_format: "string" +value: "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|name|Name is an attribute name.|string| +|name_format|Name_format is an attribute name format.|string| +|value|Value is an attribute value definable with predicate expression.|string| + +## SAML IdPService Provider Spec V1 + +The SAMLIdPServiceProviderV1 resource spec. + + +Example: + +```yaml +entity_descriptor: "string" +entity_id: "string" +acs_url: "string" +attribute_mapping: + - # [...] + - # [...] + - # [...] +preset: "string" +relay_state: "string" +launch_urls: + - "string" + - "string" + - "string" +``` + +|Field Name|Description|Type| +|---|---|---| +|acs_url|The endpoint where SAML authentication response will be redirected.|string| +|attribute_mapping|Used to map service provider requested attributes to username, role and traits in Teleport.|[][SAML Attribute Mapping](#saml-attribute-mapping)| +|entity_descriptor|The entity descriptor for the service provider|string| +|entity_id|The entity ID for the entity descriptor. If entity descriptor is provided, this value is checked that it matches the entity ID in the entity descriptor at upsert time to avoid having to parse the XML blob in the entity descriptor every time we need to use this resource.|string| +|launch_urls|Used to configure custom landing URLs for service provider. It is useful in the following scenarios: 1. If a service provider does not support IdP initiated authentication, launch url can be configured to launch users directly into the service provider authentication endpoint. 2. If a service provider does support IdP initiated authentication, it can be useful if that service provider acts as a master authentication service provider for internal services. In such case, Teleport administrator can configure launch URL, that lets user pick a specific internal service URL from the Log In tile in the UI, which would take them to that particular service for authentication instead of directly launching to the master service provider. Each launch URL value must be an HTTPs endpoint.|[]string| +|preset|Used to define service provider profile that will have a custom behavior processed by Teleport.|string| +|relay_state|Used to add custom value in the SAML response as a relay_state HTTP parameter. The value can contain service provider specific redirect URL, static state token etc. The value is only applied in the IdP initiated SSO flow.|string| + diff --git a/docs/pages/reference/infrastructure-as-code/teleport-resources/teleport-resources.mdx b/docs/pages/reference/infrastructure-as-code/teleport-resources/teleport-resources.mdx index 5a62a3ccdc7cb..88ec7f7be6585 100644 --- a/docs/pages/reference/infrastructure-as-code/teleport-resources/teleport-resources.mdx +++ b/docs/pages/reference/infrastructure-as-code/teleport-resources/teleport-resources.mdx @@ -69,4 +69,4 @@ Here's the list of resources currently exposed via [`tctl`](../../cli/tctl.mdx): | [inference_model](inference-model.mdx) | Session summarization AI model configuration | | [inference_secret](inference-secret.mdx) | Session summarization AI provider secret (API key) | | [inference_policy](inference-policy.mdx)| Matches sessions to inference models using session kind and other metadata | - +| [discovery_config](discovery-config.mdx)| Auto discovery configurations |