diff --git a/docs/pages/includes/discovery/discovery-config.yaml b/docs/pages/includes/discovery/discovery-config.yaml index 6228ba9de6039..3e024dde762ab 100644 --- a/docs/pages/includes/discovery/discovery-config.yaml +++ b/docs/pages/includes/discovery/discovery-config.yaml @@ -1,5 +1,11 @@ discovery_service: enabled: "yes" + # discovery_group is used to group discovered resources into different + # sets. This is useful when you have multiple Teleport Discovery services + # running in the same cluster but polling different cloud providers or cloud + # accounts. It prevents discovered services from colliding in Teleport when + # managing discovered resources. + discovery_group: "disc-group" aws: # AWS resource types. Valid options are: # ec2 - discovers and registers AWS EC2 instances @@ -11,7 +17,7 @@ discovery_service: # Optional section: Defaults to "*":"*" tags: "*": "*" - # Optional section: install is used to provide parameters to the AWS SSM document. + # Optional section: install is used to provide parameters to the AWS SSM document. # If the install section isn't provided, the below defaults are used. # Only applicable for EC2 discovery. install: diff --git a/docs/pages/kubernetes-access/discovery.mdx b/docs/pages/kubernetes-access/discovery.mdx index 208538d804aa8..79f448aed1a97 100644 --- a/docs/pages/kubernetes-access/discovery.mdx +++ b/docs/pages/kubernetes-access/discovery.mdx @@ -4,10 +4,10 @@ description: Detailed guides for configuring Kubernetes Auto-Discovery. layout: tocless-doc --- -Kubernetes Auto-Discovery allows Kubernetes clusters -hosted on cloud providers to be discovered and enrolled automatically. +Kubernetes Auto-Discovery allows Kubernetes clusters +hosted on cloud providers to be discovered and enrolled automatically. -While discovering a new Kubernetes cluster, Teleport does not install any component +While discovering a new Kubernetes cluster, Teleport does not install any component on the cluster. Instead, it requires direct access to the cluster's API and minimal access permissions. @@ -24,43 +24,51 @@ Kubernetes Auto-Discovery consists of two steps: ### Polling cloud APIs -The Teleport Discovery Service is responsible for scanning the configured cloud -providers and identifying if any Kubernetes clusters match a set of filtering labels. -When the process identifies a new Kubernetes cluster, it creates a dynamic -resource within Teleport. This resource includes information imported from the +The Teleport Discovery Service is responsible for scanning the configured cloud +providers and identifying if any Kubernetes clusters match a set of filtering labels. +When the process identifies a new Kubernetes cluster, it creates a dynamic +resource within Teleport. This resource includes information imported from the cloud provider such as: -- *Name*: Cluster name +- *Name*: Cluster name - *Labels* - Cluster tags. - Cluster location. - Identification of which cloud account the cluster belongs to — AWS Account ID / Azure Subscription ID. -You can import the cluster under a different name into Teleport's registry. +You can import the cluster under a different name into Teleport's registry. To achieve this, you must attach the following tag to the resources — EKS and AKS — in your cloud provider: - - ***key***: `teleport.dev/kubernetes-name` - - ***value***: desired name + - ***key***: `teleport.dev/kubernetes-name` + - ***value***: desired name -The Discovery Service will check if the cluster includes the tag and use its value +The Discovery Service will check if the cluster includes the tag and use its value as the resource name in Teleport. -You should use this feature whenever there are clusters in different regions/cloud providers +You should use this feature whenever there are clusters in different regions/cloud providers with the same name to prevent them from colliding in Teleport. -In addition to detecting new Kubernetes clusters, the Discovery Service also removes -— from Teleport's registry — the Kubernetes clusters that have been deleted or whose tags +In addition to detecting new Kubernetes clusters, the Discovery Service also removes +— from Teleport's registry — the Kubernetes clusters that have been deleted or whose tags no longer meet the filtering labels. -The following snippet describes the different configuration options for the Discovery Service +(!docs/pages/kubernetes-access/discovery/includes/discovery-group.mdx!) + +The following snippet describes the different configuration options for the Discovery Service and their default values. ```yaml # This section configures the Discovery Service discovery_service: enabled: "yes" + # discovery_group is used to group discovered resources into different + # sets. This is useful when you have multiple Teleport Discovery services + # running in the same cluster but polling different cloud providers or cloud + # accounts. It prevents discovered services from colliding in Teleport when + # managing discovered resources. + discovery_group: "prod" aws: # AWS resource types. Valid options are: # eks - discovers and registers AWS EKS clusters @@ -97,12 +105,12 @@ discovery_service: ### Forwarding requests to the Kubernetes Cluster -The Teleport Kubernetes Service is responsible for monitoring the dynamic resources created or +The Teleport Kubernetes Service is responsible for monitoring the dynamic resources created or updated by the Discovery Service and forwarding requests to the Kubernetes clusters they represent. -To work correctly, it requires direct access to the target Kubernetes clusters and +To work correctly, it requires direct access to the target Kubernetes clusters and permissions to forward requests. -To turn on dynamic resource monitoring in the Kubernetes Service, you must configure +To turn on dynamic resource monitoring in the Kubernetes Service, you must configure the `kubernetes_service.resources` section as shown in the following snippet: ```yaml @@ -115,5 +123,5 @@ kubernetes_service: "*": "*" # can be configured to limit the clusters to watched by this service. ``` -Both services — Discovery and Kubernetes — can be configured in the same -Teleport process or separate processes. +Both services — Discovery and Kubernetes — can be configured in the same +Teleport process or separate processes. diff --git a/docs/pages/kubernetes-access/discovery/aws.mdx b/docs/pages/kubernetes-access/discovery/aws.mdx index 0e963dbb0fa3f..cf1ba301116ba 100644 --- a/docs/pages/kubernetes-access/discovery/aws.mdx +++ b/docs/pages/kubernetes-access/discovery/aws.mdx @@ -3,9 +3,9 @@ title: Teleport EKS Auto-Discovery (Preview) description: How to configure auto-discovery of AWS EKS clusters in Teleport. --- -EKS Auto-Discovery can automatically -discover any EKS cluster and enroll it in Teleport if its tags match the -configured labels. +EKS Auto-Discovery can automatically +discover any EKS cluster and enroll it in Teleport if its tags match the +configured labels. (!docs/pages/kubernetes-access/discovery/includes/step-description.mdx!) @@ -16,28 +16,28 @@ configured labels. - An AWS account with permissions to create and attach IAM policies. - An AWS account with `system:masters` RBAC access to EKS clusters. - A host to run the Teleport Discovery and Kubernetes services. -- One or more EKS clusters running. +- One or more EKS clusters running. ## Known limitations -Due to the authorization method that AWS has chosen for EKS clusters, it is not -possible for the Teleport process to configure the necessary permissions to forward +Due to the authorization method that AWS has chosen for EKS clusters, it is not +possible for the Teleport process to configure the necessary permissions to forward requests to EKS clusters. This limitation exists because the authorization method on EKS clusters requires that the IAM role - -used for authentication - exists in the -[`aws-auth`](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) `ConfigMap`. +used for authentication - exists in the +[`aws-auth`](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) `ConfigMap`. -In this `ConfigMap`, IAM roles are mapped to Kubernetes RBAC users or groups that are then -used by Kubernetes RBAC to grant access permissions. If the mapping does not exist, it results in +In this `ConfigMap`, IAM roles are mapped to Kubernetes RBAC users or groups that are then +used by Kubernetes RBAC to grant access permissions. If the mapping does not exist, it results in unauthorized requests. Therefore, Teleport cannot edit the `ConfigMap` without first having access to the cluster. -If Teleport is not running with the same IAM identity that creates all clusters, -please ensure you configure the required permissions as described in Step 2. +If Teleport is not running with the same IAM identity that creates all clusters, +please ensure you configure the required permissions as described in Step 2. -The AWS EKS team is working on a feature request to introduce an external API to manage access to the cluster without manually editing the Configmap ([aws/containers-roadmap#185](https://github.com/aws/containers-roadmap/issues/185)). +The AWS EKS team is working on a feature request to introduce an external API to manage access to the cluster without manually editing the Configmap ([aws/containers-roadmap#185](https://github.com/aws/containers-roadmap/issues/185)). Hopefully, once the feature is available, Teleport can leverage it to configure its access to the cluster. @@ -46,7 +46,7 @@ Hopefully, once the feature is available, Teleport can leverage it to configure ## Step 1/3. Set up AWS IAM credentials For Teleport to discover EKS clusters, the instance -running the Discovery Service requires an IAM policy that allows Teleport to list and +running the Discovery Service requires an IAM policy that allows Teleport to list and describe EKS clusters: ```js @@ -62,39 +62,39 @@ describe EKS clusters: "Resource": "*" } ] -} +} ``` ## Step 2/3. Configure EKS cluster authorization -When the Kubernetes Service uses an IAM role that is different from the one that -creates the clusters, you need to configure the mapping between the Teleport IAM -Role and the Kubernetes RBAC permissions by editing the `aws-auth` `Configmap` on -each of the discovered clusters. +When the Kubernetes Service uses an IAM role that is different from the one that +creates the clusters, you need to configure the mapping between the Teleport IAM +Role and the Kubernetes RBAC permissions by editing the `aws-auth` `Configmap` on +each of the discovered clusters. -To forward requests to the Kubernetes cluster, the Teleport Kubernetes Service -requires cluster-wide permissions to `Impersonate` RBAC users and groups, to -create `SelfSubjectAccessReviews` and `SelfSubjectRulesReviews`, and, finally, +To forward requests to the Kubernetes cluster, the Teleport Kubernetes Service +requires cluster-wide permissions to `Impersonate` RBAC users and groups, to +create `SelfSubjectAccessReviews` and `SelfSubjectRulesReviews`, and, finally, read access to `Pods`. -If your Kubernetes cluster does not have an RBAC group with the required -permissions, you can create the `ClusterRole`, `ClusterRoleBinding`, and the -mapping by following the Creating RBAC group guide. -If your cluster already has an RBAC group that satisfies the required permissions, -you can reuse it and map it into the IAM Role used by the Teleport Kubernetes -Service. For simplicity, it is also possible to map the Teleport IAM role onto -a built-in Kubernetes RBAC group like `system:masters`, but not recommended in +If your Kubernetes cluster does not have an RBAC group with the required +permissions, you can create the `ClusterRole`, `ClusterRoleBinding`, and the +mapping by following the Creating RBAC group guide. +If your cluster already has an RBAC group that satisfies the required permissions, +you can reuse it and map it into the IAM Role used by the Teleport Kubernetes +Service. For simplicity, it is also possible to map the Teleport IAM role onto +a built-in Kubernetes RBAC group like `system:masters`, but not recommended in production. -Connect to your target cluster with your credentials and create the following +Connect to your target cluster with your credentials and create the following resources using `kubectl`. ### ClusterRole -Create the `ClusterRole` RBAC definition with the required permissions for Teleport +Create the `ClusterRole` RBAC definition with the required permissions for Teleport Kubernetes Service to forward requests to the cluster. ```yaml @@ -147,9 +147,9 @@ subjects: ### IAM mapping -Finally, edit the `configmap/aws-auth` in the `kube-system` namespace and append -the following to `mapRoles`. Replace `{teleport_aws_iam_role}` with the -appropriate IAM role that Teleport Kubernetes Service will use. +Finally, edit the `configmap/aws-auth` in the `kube-system` namespace and append +the following to `mapRoles`. Replace `{teleport_aws_iam_role}` with the +appropriate IAM role that Teleport Kubernetes Service will use. This step will link the Teleport IAM role into the Kubernetes RBAC group `teleport`, allowing Teleport Kubernetes Service to forward requests into the cluster. @@ -163,15 +163,15 @@ data: username: teleport ``` -At this point, the Teleport IAM role already has the minimum permissions -to forward requests to the cluster. +At this point, the Teleport IAM role already has the minimum permissions +to forward requests to the cluster. -To associate the Teleport IAM role with an existing Kubernetes RBAC group, -edit the `configmap/aws-auth` in the `kube-system` namespace and append -the following to `mapRoles`. +To associate the Teleport IAM role with an existing Kubernetes RBAC group, +edit the `configmap/aws-auth` in the `kube-system` namespace and append +the following to `mapRoles`. ```yaml apiVersion: v1 @@ -184,26 +184,26 @@ data: username: teleport ``` -Please replace `{teleport_aws_iam_role}` with the appropriate IAM role that -Teleport Kubernetes Service is using and `{rbac_group}` with the existing Kubernetes +Please replace `{teleport_aws_iam_role}` with the appropriate IAM role that +Teleport Kubernetes Service is using and `{rbac_group}` with the existing Kubernetes RBAC Group that satisfies the required permissions. -At this point, the Teleport IAM role already has the minimum permissions -to forward requests to the cluster. +At this point, the Teleport IAM role already has the minimum permissions +to forward requests to the cluster. -Granting the `system:masters` group to the IAM role associated with the Teleport -service means granting administrator-level permissions on the Kubernetes cluster. +Granting the `system:masters` group to the IAM role associated with the Teleport +service means granting administrator-level permissions on the Kubernetes cluster. To follow least privilege principle we do not recommend using this method in production. -To associate the Teleport IAM role with the `system:masters` RBAC group, -edit the `configmap/aws-auth` in the `kube-system` namespace and append -the following to `mapRoles`. +To associate the Teleport IAM role with the `system:masters` RBAC group, +edit the `configmap/aws-auth` in the `kube-system` namespace and append +the following to `mapRoles`. ```yaml apiVersion: v1 @@ -216,18 +216,18 @@ data: username: teleport ``` -Please replace `{teleport_aws_iam_role}` with the appropriate IAM role that +Please replace `{teleport_aws_iam_role}` with the appropriate IAM role that Teleport Kubernetes Service is using. -At this point, the Teleport IAM role already has the minimum permissions -to forward requests to the cluster. +At this point, the Teleport IAM role already has the minimum permissions +to forward requests to the cluster. -If you provision your EKS clusters using tools such as `terraform`, `eksctl` or -`Cloudformation`, you can use them to automatically configure the `aws-auth` `Configmap` +If you provision your EKS clusters using tools such as `terraform`, `eksctl` or +`Cloudformation`, you can use them to automatically configure the `aws-auth` `Configmap` and create the `ClusterRole` and `ClusterRoleBinding` resources during cluster provisioning. @@ -235,9 +235,9 @@ and create the `ClusterRole` and `ClusterRoleBinding` resources during cluster p ### Get a join token -Teleport EKS Auto-Discovery requires a valid Teleport auth token for the Discovery and -Kubernetes services to join the cluster. Generate one by running the following -command against your Teleport Auth Service and save it in `/tmp/token` on the +Teleport EKS Auto-Discovery requires a valid Teleport auth token for the Discovery and +Kubernetes services to join the cluster. Generate one by running the following +command against your Teleport Auth Service and save it in `/tmp/token` on the machine that will run Kubernetes Auto-Discovery: ```code @@ -246,11 +246,13 @@ $ tctl tokens add --type=discovery,kube ### Configure the Teleport Kubernetes and Discovery Services -Enabling EKS Auto-Discovery requires that the `discovery_service.aws` section -include at least one entry and that `discovery_service.aws.types` include `eks`. -It also requires configuring the `kubernetes_service.resources.tags` to use the same -labels configured at `discovery_service.aws.tags` or a subset of them to make -the Kubernetes Service listen to the dynamic resources created by the Discovery +(!docs/pages/kubernetes-access/discovery/includes/discovery-group.mdx!) + +Enabling EKS Auto-Discovery requires that the `discovery_service.aws` section +include at least one entry and that `discovery_service.aws.types` include `eks`. +It also requires configuring the `kubernetes_service.resources.tags` to use the same +labels configured at `discovery_service.aws.tags` or a subset of them to make +the Kubernetes Service listen to the dynamic resources created by the Discovery Service. ```yaml @@ -269,6 +271,7 @@ ssh_service: enabled: off discovery_service: enabled: "yes" + discovery_group: "aws-prod" aws: - types: ["eks"] regions: ["*"] diff --git a/docs/pages/kubernetes-access/discovery/azure.mdx b/docs/pages/kubernetes-access/discovery/azure.mdx index 9f5727b6c8c0d..6a99294312cfc 100644 --- a/docs/pages/kubernetes-access/discovery/azure.mdx +++ b/docs/pages/kubernetes-access/discovery/azure.mdx @@ -3,9 +3,9 @@ title: Teleport AKS Auto-Discovery (Preview) description: Auto-Discovery of AKS clusters in Azure cloud. --- -AKS Auto-Discovery can automatically -discover any AKS cluster and enroll it in Teleport if its tags match the -configured labels. +AKS Auto-Discovery can automatically +discover any AKS cluster and enroll it in Teleport if its tags match the +configured labels. (!docs/pages/kubernetes-access/discovery/includes/step-description.mdx!) @@ -14,32 +14,32 @@ configured labels. (!docs/pages/includes/edition-prereqs-tabs.mdx!) - An Azure identity with permissions to create and attach AD Groups. -- One or more AKS clusters running. +- One or more AKS clusters running. - Access to AKS clusters. - A host to run the Teleport Discovery and Kubernetes services. ## Step 1/2. Set up Azure Identity with the required permissions -Depending on each cluster's authentication and authorization settings, Azure -uses a different way to configure the necessary permissions for Teleport to forward +Depending on each cluster's authentication and authorization settings, Azure +uses a different way to configure the necessary permissions for Teleport to forward requests to the server. -Check the authentication modes used on your clusters and choose one or more -permissions scenarios. In some configurations, Teleport has the ability to -automatically configure the access to the cluster if you include the necessary +Check the authentication modes used on your clusters and choose one or more +permissions scenarios. In some configurations, Teleport has the ability to +automatically configure the access to the cluster if you include the necessary permissions to do so. -In this scenario, the Teleport's authentication happens through Active Directory, -and the permissions required to access the Kubernetes cluster are associated with -the roles assigned to its identity. +In this scenario, the Teleport's authentication happens through Active Directory, +and the permissions required to access the Kubernetes cluster are associated with +the roles assigned to its identity. -This mode allows you to grant permissions to multiple Kubernetes clusters without +This mode allows you to grant permissions to multiple Kubernetes clusters without requiring specific settings for each one of them. -To grant access to the AKS clusters running with this setting, create an AD role +To grant access to the AKS clusters running with this setting, create an AD role with the following content and assign it to the identity that the Teleport process will use. ```json @@ -66,31 +66,31 @@ with the following content and assign it to the identity that the Teleport proce } ``` -Replace the `{subscription_id}` with the desired Subscription ID or a wildcard if +Replace the `{subscription_id}` with the desired Subscription ID or a wildcard if you want to guarantee permissions on all subscriptions. -When using Azure AD authentication with Kubernetes RBAC mode, Azure is responsible -for user authentication using AD credentials, but permissions management is Kubernetes' +When using Azure AD authentication with Kubernetes RBAC mode, Azure is responsible +for user authentication using AD credentials, but permissions management is Kubernetes' RBAC responsibility. -Therefore, for Teleport to work correctly, you must create the Kubernetes `ClusterRole` -and `ClusterRoleBinding` resources on each discovered cluster. -The `ClusterRoleBinding` must bind the `ClusterRole` to one of the AD groups +Therefore, for Teleport to work correctly, you must create the Kubernetes `ClusterRole` +and `ClusterRoleBinding` resources on each discovered cluster. +The `ClusterRoleBinding` must bind the `ClusterRole` to one of the AD groups configured in the Teleport identity. -Teleport can automatically create the `ClusterRole` and `ClusterRoleBinding` resources +Teleport can automatically create the `ClusterRole` and `ClusterRoleBinding` resources in the following cases: - Teleport's AD identity has permissions that allow access to the static [cluster administrator credentials](https://learn.microsoft.com/en-us/rest/api/aks/managed-clusters/list-cluster-admin-credentials) (local accounts). - Teleport's AD identity belongs to the cluster's administrator group. -- Teleport's AD identity has permissions to create `ClusterRole` and `ClusterRoleBinding` on the +- Teleport's AD identity has permissions to create `ClusterRole` and `ClusterRoleBinding` on the cluster and permissions to execute [remote commands](https://learn.microsoft.com/en-us/rest/api/aks/managed-clusters/run-command). -In either of the specified cases, Teleport will be able to create the `ClusterRole` and bind -it to the first AD group it belongs. To make this possible, associate the +In either of the specified cases, Teleport will be able to create the `ClusterRole` and bind +it to the first AD group it belongs. To make this possible, associate the following permissions with Teleport's identity. ```json @@ -115,17 +115,17 @@ following permissions with Teleport's identity. In all other cases, you must manually set up the required access as described in the guide below. -
-Connect to every cluster to enroll with admin permissions and create the following resources +Connect to every cluster to enroll with admin permissions and create the following resources using `kubectl`. ### ClusterRole -Create the `ClusterRole` RBAC definition with the required permissions for Teleport +Create the `ClusterRole` RBAC definition with the required permissions for Teleport Kubernetes Service to forward requests to the cluster. ```yaml @@ -183,8 +183,8 @@ associated with Teleport identity. - In this case, Teleport will use the user credentials generated during the - provisioning phase of the cluster. + In this case, Teleport will use the user credentials generated during the + provisioning phase of the cluster. ```json { @@ -208,22 +208,24 @@ associated with Teleport identity. ## Step 2/2. Configure Teleport to discover AKS clusters -Teleport AKS Auto-Discovery requires a valid auth token for the Discovery and -Kubernetes services to join the cluster. Generate one by running the following -command against your Teleport Auth Service and save it in `/tmp/token` on the +Teleport AKS Auto-Discovery requires a valid auth token for the Discovery and +Kubernetes services to join the cluster. Generate one by running the following +command against your Teleport Auth Service and save it in `/tmp/token` on the machine that will run Kubernetes Auto-Discovery: ```code $ tctl tokens add --type=discovery,kube ``` -Enabling AKS Auto-Discovery requires that the `discovery_service.azure` section -include at least one entry and that `discovery_service.azure.types` include `aks`. -It also requires configuring the `kubernetes_service.resources.tags` to use the same -labels configured at `discovery_service.azure.tags` or a subset of them to make -the Kubernetes Service listen to the dynamic resources created by the Discovery +Enabling AKS Auto-Discovery requires that the `discovery_service.azure` section +include at least one entry and that `discovery_service.azure.types` include `aks`. +It also requires configuring the `kubernetes_service.resources.tags` to use the same +labels configured at `discovery_service.azure.tags` or a subset of them to make +the Kubernetes Service listen to the dynamic resources created by the Discovery Service. +(!docs/pages/kubernetes-access/discovery/includes/discovery-group.mdx!) + ```yaml version: v2 teleport: @@ -240,6 +242,7 @@ ssh_service: enabled: off discovery_service: enabled: "yes" + discovery_group: "aks-prod" azure: - types: ["aks"] regions: ["*"] diff --git a/docs/pages/kubernetes-access/discovery/google-cloud.mdx b/docs/pages/kubernetes-access/discovery/google-cloud.mdx index a397504d02084..505b78edd76ad 100644 --- a/docs/pages/kubernetes-access/discovery/google-cloud.mdx +++ b/docs/pages/kubernetes-access/discovery/google-cloud.mdx @@ -7,7 +7,7 @@ The Teleport Discovery Service can automatically register your Google Kubernetes Engine (GKE) clusters with Teleport. With Teleport Kubernetes Auto-Discovery, you can configure the Teleport Kubernetes Service and Discovery Service once, then create GKE clusters without needing to register them with Teleport after -each creation. +each creation. In this guide, we will show you how to get started with Teleport Kubernetes Auto-Discovery for GKE. @@ -69,7 +69,7 @@ $ gcloud iam roles create GKEKubernetesAutoDisc \ ### Create an IAM role for the Kubernetes Service The Teleport Kubernetes Service needs Google Cloud IAM permissions in order to -forward user traffic to your GKE clusters. +forward user traffic to your GKE clusters. Create a file called `GKEAccessManager.yaml` with the following content: @@ -250,11 +250,11 @@ $ gcloud iam service-accounts keys create kube-service-credentials.json \ ``` Move `discovery-service-credentials.json` to the host running the Teleport -Discovery Service at the path `/var/lib/teleport/google-cloud-credentials.json`. +Discovery Service at the path `/var/lib/teleport/google-cloud-credentials.json`. Move `kubernetes-service-credentials.json` to the host running the Teleport Kubernetes Service at the path -`/var/lib/teleport/google-cloud-credentials.json`. +`/var/lib/teleport/google-cloud-credentials.json`. We will use these credentials files when running this services later in this guide. @@ -277,7 +277,7 @@ Discovery Service: (!docs/pages/includes/install-linux.mdx!) -### Create a join token +### Create a join token The Teleport Discovery Service and Kubernetes Service require an authentication token in order to to join the cluster. Generate one by running the following @@ -311,7 +311,7 @@ $ tctl tokens add --type=kube --format=text Copy each token (e.g., `(=presets.tokens.second=)` and `(=presets.tokens.third=)` above) and save it in `/tmp/token` on the machine -that will run the appropriate service. +that will run the appropriate service.
@@ -320,6 +320,8 @@ that will run the appropriate service. On the host running the Kubernetes Service and Discovery Service, create a Teleport configuration file with the following content at `/etc/teleport.yaml`: +(!docs/pages/kubernetes-access/discovery/includes/discovery-group.mdx!) + ```yaml version: v3 teleport: @@ -335,6 +337,7 @@ ssh_service: enabled: off discovery_service: enabled: "yes" + discovery_group: "gke-myproject" gcp: - types: ["gke"] locations: ["*"] @@ -404,7 +407,7 @@ discovery_service: Edit this configuration for your environment as explained below. -#### `proxy_server` +#### `proxy_server` Replace `teleport.example.com:443` with the host and port of your Teleport Proxy Service (e.g., `mytenant.teleport.sh:443` for a Teleport Cloud tenant). @@ -419,7 +422,7 @@ have declared a single matcher. Each matcher searches for clusters that match *all* properties of the matcher, i.e., that belong to the specified locations and projects and have the specified tags. The Discovery Service registers GKE clusters that match *any* -configured matcher. +configured matcher. This means that if you declare the following two matchers, the Discovery Service will register clusters in project `myproj-dev` running in `us-east1`, as well as @@ -457,19 +460,19 @@ wildcard character (`*`). Each matcher's `locations` field contains an array of Google Cloud region or zone names that the matcher will search for GKE clusters. The wildcard -character, `*`, configures the matcher to search all locations. +character, `*`, configures the matcher to search all locations. #### `discovery_service.gcp[0].tags` Like `locations`, `tags` consists of a map where each key is a string that represents the key of a tag, and each value is either a single string or an -array of strings, representing one tag value or a list of tag values. +array of strings, representing one tag value or a list of tag values. A wildcard key or value matches any tag key or value in your Google Cloud account. If you include another value, the matcher will match all GKE clusters -with the provided tag. +with the provided tag. -### Start the Kubernetes Service and Discovery Service +### Start the Kubernetes Service and Discovery Service On the host where you will run the Kubernetes Service, execute the following command, depending on: @@ -478,7 +481,7 @@ command, depending on: - Whether you are running the Discovery and Kubernetes Service on Google Cloud or another platform - @@ -505,12 +508,12 @@ $ sudo systemctl start teleport When you installed Teleport via package manager, the installation process created a configuration for the init system `systemd` to run Teleport as a -daemon. +daemon. This service reads environment variables from a file at the path `/etc/default/teleport`. Teleport's built-in Google Cloud client reads the credentials file at the location given by the `GOOGLE_APPLICATION_CREDENTIALS` -variable. +variable. Ensure that `/etc/default/teleport` has the following content: @@ -539,7 +542,7 @@ $ sudo systemctl enable teleport This service reads environment variables from a file at the path `/etc/default/teleport`. Teleport's built-in Google Cloud client reads the credentials file at the location given by the `GOOGLE_APPLICATION_CREDENTIALS` -variable. +variable. Ensure that `/etc/default/teleport` has the following content: @@ -616,9 +619,9 @@ user has access to. The list should now include your GKE cluster: ```code $ tsh kube ls -Kube Cluster Name Labels Selected -------------------- -------------------------------------------------------------------------------------------------------- -------- -mycluster-gke location=us-east1 project-id=myproject teleport.dev/cloud=GCP teleport.dev/origin=cloud +Kube Cluster Name Labels Selected +------------------- -------------------------------------------------------------------------------------------------------- -------- +mycluster-gke location=us-east1 project-id=myproject teleport.dev/cloud=GCP teleport.dev/origin=cloud ``` Log in to your cluster, replacing `mycluster-gke` with the name of a cluster diff --git a/docs/pages/kubernetes-access/discovery/includes/discovery-group.mdx b/docs/pages/kubernetes-access/discovery/includes/discovery-group.mdx new file mode 100644 index 0000000000000..da3b6a9954a38 --- /dev/null +++ b/docs/pages/kubernetes-access/discovery/includes/discovery-group.mdx @@ -0,0 +1,22 @@ + +Discovery Service exposes a configuration parameter - `discovery_service.discovery_group` - +that allows you to group discovered resources into different sets. This parameter +is used to prevent Discovery Agents watching different sets of cloud resources +from colliding against each other and deleting resources created by another services. + +When running multiple Discovery Services, you must ensure that each service is configured +with the same `discovery_group` value if they are watching the same cloud resources +or a different value if they are watching different cloud resources. + +It is possible to run a mix of configurations in the same Teleport cluster meaning +that some Discovery Services can be configured to watch the same cloud resources +while others watch different resources. As an example, a 4-agent high availability +configuration analyzing data from two different cloud accounts would run with +the following configuration. + +- 2 Discovery Services configured with `discovery_group: "prod"` polling data +from Production account. +- 2 Discovery Services configured with `discovery_group: "staging"` polling data +from Staging account. + + \ No newline at end of file