From 260be7a2004e463f926eab67252a958758e73382 Mon Sep 17 00:00:00 2001 From: Tiago Silva Date: Tue, 28 May 2024 20:58:37 +0100 Subject: [PATCH 1/7] docs: document EKS Auto discovery self-bootstrap This PR documents EKS auto-discovery self bootstrap using AccessEntries to gain access to the cluster. Signed-off-by: Tiago Silva --- docs/pages/auto-discovery/kubernetes.mdx | 46 +++++++- docs/pages/auto-discovery/kubernetes/aws.mdx | 105 ++++++++++++++----- 2 files changed, 126 insertions(+), 25 deletions(-) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index 939cad20e6931..6f2c8459fd74e 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -80,6 +80,17 @@ discovery_service: # Optional section: Defaults to "*":"*" tags: "env": "prod" + # AWS role to assume when discovering resources in the AWS Account. + # This value is an optional AWS role ARN to assume when polling EKS clusters + assume_role_arn: arn:aws:iam::123456789012:role/iam-discovery-role + # External Id is an optional value that should be set when accessing + # your AWS account from a 3rd party access (delegate access). + external_id: 123456789 + # Specifies the role for which the Discovery Service should create the EKS Access Entry. + # This is an optional parameter. 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 the 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: @@ -136,7 +147,40 @@ kubernetes_service: resources: - labels: "*": "*" # can be configured to limit the clusters to watched by this service. + aws: + # AWS role to assume when accessing EKS clusters in the AWS Account. + # This value is an optional AWS role ARN to assume when forwarding requests + # to EKS clusters. + assume_role_arn: arn:aws:iam::123456789012:role/iam-discovery-role + # External Id is an optional value that should be set when accessing + # your AWS account from a 3rd party access (delegate access). + external_id: 123456789 ``` + +When configuring the `kubernetes_service.resources` parameter, the Teleport +Kubernetes Service is set to monitor EKS clusters that are discovered by +the Teleport Discovery Service. The monitoring process involves a label +matching mechanism to identify and manage the EKS clusters. + +1. **Discovery and Label Matching**: + - The Discovery Service identifies available EKS clusters within the AWS environment. + - The Teleport Kubernetes Service checks the labels of these discovered EKS clusters + against the labels specified in the `kubernetes_service.resources[].labels` configuration. + - The labels in the `kubernetes_service.resources[].labels` array serve as selectors. + +2. **Role Selection**: + - The first selector in the array that matches the labels of an EKS cluster determines + the role that the Kubernetes Service will assume. + - This role is essential for the Teleport Kubernetes Service to retrieve necessary cluster details from the AWS API. + - If no match is found, the Kubernetes Service defaults to its own identity. + +3. **Interaction with AWS and Kubernetes API**: + - Once a match is found and a role is assumed, the Teleport Kubernetes Service uses + this role to access the AWS API. + - It retrieves detailed information about the EKS cluster, such as configuration and status. + - Subsequently, the Teleport Kubernetes Service forwards requests to the Kubernetes + API, enabling seamless interaction with the cluster. + Both services — Discovery and Kubernetes — can be configured in the same -Teleport process or separate processes. +Teleport process or separate processes. \ No newline at end of file diff --git a/docs/pages/auto-discovery/kubernetes/aws.mdx b/docs/pages/auto-discovery/kubernetes/aws.mdx index 4e5e5e9ce3ce2..ca309289c0d60 100644 --- a/docs/pages/auto-discovery/kubernetes/aws.mdx +++ b/docs/pages/auto-discovery/kubernetes/aws.mdx @@ -14,32 +14,16 @@ configured labels. (!docs/pages/includes/edition-prereqs-tabs.mdx!) - 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. -## 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 -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`. - -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. - -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. +Starting with Teleport v15.3.8, the Discovery Service can self-bootstrap +access to EKS clusters by automatically creating and managing Access Entries +for each discovered cluster. This contrasts with earlier versions of EKS +Auto-Discovery, where agents could not access a cluster without having +pre-existing access configured. @@ -56,8 +40,12 @@ describe EKS clusters: { "Effect": "Allow", "Action": [ - "eks:DescribeCluster", - "eks:ListClusters" + "eks:DescribeCluster", + "eks:ListClusters", + "eks:DescribeAccessEntry", + "eks:CreateAccessEntry", + "eks:DeleteAccessEntry", + "eks:AssociateAccessPolicy" ], "Resource": "" } @@ -69,6 +57,13 @@ Update `Resource` entries to match your AWS account's EKS resources, which have ## Step 2/3. Configure EKS cluster authorization + +If you are running Teleport Discovery v15.3.8 or later and the IAM role +used by the Discovery Service has the necessary permissions to create and +update Access Entries, you can skip this section. The service can self-bootstrap +the required permissions automatically. + + 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 @@ -149,6 +144,28 @@ subjects: ### IAM mapping + + + +Create an EKS Access Entry to link the +to the Kubernetes Group `teleport` we created in the previous step. + +```shell +$ aws eks create-access-entry \ + --cluster-name \ + --region \ + --principal-arn \ + --kubernetes-groups teleport + +{ + ... +} +``` + + + + + 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. @@ -164,6 +181,8 @@ data: rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role username: teleport ``` + + At this point, the Teleport IAM role already has the minimum permissions to forward requests to the cluster. @@ -203,6 +222,41 @@ service means granting administrator-level permissions on the Kubernetes cluster To follow least privilege principle we do not recommend using this method in production. + + + + + +Create an EKS Access Entry and Access Policy to link the +to the cluster wide policy `arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy` (equivalent of `cluster-admin` `ClusterRole`). + +```shell +$ aws eks create-access-entry \ + --cluster-name \ + --region \ + --principal-arn + +{ + ... +} + +$ aws eks associate-access-policy \ + --cluster-name \ + --region \ + --principal-arn + --policy-arn "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy" \ + --access-scope type=cluster + +{ + ... +} + +``` + + + + + 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`. @@ -220,6 +274,9 @@ data: 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. @@ -229,7 +286,7 @@ 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` +`Cloudformation`, you can use them to automatically configure the `aws-auth` `Configmap` or Access Entry and create the `ClusterRole` and `ClusterRoleBinding` resources during cluster provisioning. From 1e933eb74246d7e088ccc3aa0f4e4de9110d4c32 Mon Sep 17 00:00:00 2001 From: Tiago Silva Date: Tue, 28 May 2024 21:34:58 +0100 Subject: [PATCH 2/7] Update kubernetes.mdx Co-authored-by: Steven Martin --- docs/pages/auto-discovery/kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index 6f2c8459fd74e..73079efb419fe 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -85,7 +85,7 @@ discovery_service: assume_role_arn: arn:aws:iam::123456789012:role/iam-discovery-role # External Id is an optional value that should be set when accessing # your AWS account from a 3rd party access (delegate access). - external_id: 123456789 + external_id: "example-external-id" # Specifies the role for which the Discovery Service should create the EKS Access Entry. # This is an optional parameter. If not set, the Discovery Service will attempt to create # the access entry using its own identity. From e484d043be032038c05717cab9e31b259160ead2 Mon Sep 17 00:00:00 2001 From: Tiago Silva Date: Tue, 28 May 2024 21:35:06 +0100 Subject: [PATCH 3/7] Update kubernetes.mdx Co-authored-by: Steven Martin --- docs/pages/auto-discovery/kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index 73079efb419fe..316315c7eab00 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -154,7 +154,7 @@ kubernetes_service: assume_role_arn: arn:aws:iam::123456789012:role/iam-discovery-role # External Id is an optional value that should be set when accessing # your AWS account from a 3rd party access (delegate access). - external_id: 123456789 + external_id: "example-external-id" ``` From a8a17b421f76e55e706e6f9aca7020473c2e1511 Mon Sep 17 00:00:00 2001 From: Tiago Silva Date: Wed, 29 May 2024 09:27:26 +0100 Subject: [PATCH 4/7] fix lint --- docs/pages/auto-discovery/kubernetes.mdx | 28 +++++++++++------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index 316315c7eab00..179148664c76e 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -164,23 +164,21 @@ the Teleport Discovery Service. The monitoring process involves a label matching mechanism to identify and manage the EKS clusters. 1. **Discovery and Label Matching**: - - The Discovery Service identifies available EKS clusters within the AWS environment. - - The Teleport Kubernetes Service checks the labels of these discovered EKS clusters - against the labels specified in the `kubernetes_service.resources[].labels` configuration. - - The labels in the `kubernetes_service.resources[].labels` array serve as selectors. - + - The Discovery Service identifies available EKS clusters within the AWS environment. + - The Teleport Kubernetes Service checks the labels of these discovered EKS clusters + against the labels specified in the `kubernetes_service.resources[].labels` configuration. + - The labels in the `kubernetes_service.resources[].labels` array serve as selectors. 2. **Role Selection**: - - The first selector in the array that matches the labels of an EKS cluster determines - the role that the Kubernetes Service will assume. - - This role is essential for the Teleport Kubernetes Service to retrieve necessary cluster details from the AWS API. - - If no match is found, the Kubernetes Service defaults to its own identity. - + - The first selector in the array that matches the labels of an EKS cluster determines + the role that the Kubernetes Service will assume. + - This role is essential for the Teleport Kubernetes Service to retrieve necessary cluster details from the AWS API. + - If no match is found, the Kubernetes Service defaults to its own identity. 3. **Interaction with AWS and Kubernetes API**: - - Once a match is found and a role is assumed, the Teleport Kubernetes Service uses - this role to access the AWS API. - - It retrieves detailed information about the EKS cluster, such as configuration and status. - - Subsequently, the Teleport Kubernetes Service forwards requests to the Kubernetes - API, enabling seamless interaction with the cluster. + - Once a match is found and a role is assumed, the Teleport Kubernetes Service uses + this role to access the AWS API. + - It retrieves detailed information about the EKS cluster, such as configuration and status. + - Subsequently, the Teleport Kubernetes Service forwards requests to the Kubernetes + API, enabling seamless interaction with the cluster. Both services — Discovery and Kubernetes — can be configured in the same Teleport process or separate processes. \ No newline at end of file From d86ce52d70fff1228ac322c39d8b947d74d68d23 Mon Sep 17 00:00:00 2001 From: Tiago Silva Date: Wed, 29 May 2024 09:41:19 +0100 Subject: [PATCH 5/7] add how it works section --- docs/pages/auto-discovery/kubernetes.mdx | 2 +- docs/pages/auto-discovery/kubernetes/aws.mdx | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index 179148664c76e..aaeb90025a5d3 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -178,7 +178,7 @@ matching mechanism to identify and manage the EKS clusters. this role to access the AWS API. - It retrieves detailed information about the EKS cluster, such as configuration and status. - Subsequently, the Teleport Kubernetes Service forwards requests to the Kubernetes - API, enabling seamless interaction with the cluster. + API, enabling interaction with the cluster. Both services — Discovery and Kubernetes — can be configured in the same Teleport process or separate processes. \ No newline at end of file diff --git a/docs/pages/auto-discovery/kubernetes/aws.mdx b/docs/pages/auto-discovery/kubernetes/aws.mdx index ca309289c0d60..209495b8d6113 100644 --- a/docs/pages/auto-discovery/kubernetes/aws.mdx +++ b/docs/pages/auto-discovery/kubernetes/aws.mdx @@ -9,6 +9,18 @@ configured labels. (!docs/pages/includes/discovery/step-description.mdx!) +## How it works + +The Teleport Discovery Service scans configured cloud providers, including AWS, +for Kubernetes clusters that match specified filtering labels, creating dynamic +resources within Teleport for any new clusters identified. The Teleport Kubernetes +Service monitors these dynamic resources, forwarding requests to the corresponding +Kubernetes clusters. Both services require access to the AWS API to perform their +functions. + +Additionally, the Kubernetes Service needs direct access to the target clusters +and the necessary permissions to forward requests. + ## Prerequisites (!docs/pages/includes/edition-prereqs-tabs.mdx!) From 9a6fc206559934244909d3d4618875bd7852d4a9 Mon Sep 17 00:00:00 2001 From: Tiago Silva Date: Wed, 29 May 2024 23:17:49 +0100 Subject: [PATCH 6/7] handle code review --- docs/pages/auto-discovery/kubernetes.mdx | 11 +++++------ docs/pages/auto-discovery/kubernetes/aws.mdx | 14 +++++++------- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index aaeb90025a5d3..707c324f4a179 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -1,7 +1,6 @@ --- title: Kubernetes Clusters Discovery description: Detailed guides for configuring Kubernetes Clusters Discovery. -layout: tocless-doc --- Kubernetes Clusters Discovery allows Kubernetes clusters @@ -83,10 +82,10 @@ discovery_service: # AWS role to assume when discovering resources in the AWS Account. # This value is an optional AWS role ARN to assume when polling EKS clusters assume_role_arn: arn:aws:iam::123456789012:role/iam-discovery-role - # External Id is an optional value that should be set when accessing - # your AWS account from a 3rd party access (delegate access). + # External ID is an optional value that should be set when accessing + # your AWS account from a third-party service (delegated access). external_id: "example-external-id" - # Specifies the role for which the Discovery Service should create the EKS Access Entry. + # Specifies the role for which the Discovery Service should create the EKS access entry. # This is an optional parameter. 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 the Kubernetes Service. @@ -152,8 +151,8 @@ kubernetes_service: # This value is an optional AWS role ARN to assume when forwarding requests # to EKS clusters. assume_role_arn: arn:aws:iam::123456789012:role/iam-discovery-role - # External Id is an optional value that should be set when accessing - # your AWS account from a 3rd party access (delegate access). + # External ID is an optional value that should be set when accessing + # your AWS account from a third-party service (delegated access). external_id: "example-external-id" ``` diff --git a/docs/pages/auto-discovery/kubernetes/aws.mdx b/docs/pages/auto-discovery/kubernetes/aws.mdx index 209495b8d6113..14cb1b0c6550b 100644 --- a/docs/pages/auto-discovery/kubernetes/aws.mdx +++ b/docs/pages/auto-discovery/kubernetes/aws.mdx @@ -11,12 +11,12 @@ configured labels. ## How it works -The Teleport Discovery Service scans configured cloud providers, including AWS, +The Teleport Discovery Service scans configured cloud providers, including AWS, for Kubernetes clusters that match specified filtering labels, creating dynamic resources within Teleport for any new clusters identified. The Teleport Kubernetes Service monitors these dynamic resources, forwarding requests to the corresponding Kubernetes clusters. Both services require access to the AWS API to perform their -functions. +functions. Additionally, the Kubernetes Service needs direct access to the target clusters and the necessary permissions to forward requests. @@ -157,9 +157,9 @@ subjects: ### IAM mapping - + -Create an EKS Access Entry to link the +Create an EKS access entry to link the to the Kubernetes Group `teleport` we created in the previous step. ```shell @@ -237,9 +237,9 @@ To follow least privilege principle we do not recommend using this method in pro - + -Create an EKS Access Entry and Access Policy to link the +Create an EKS access entry and Access Policy to link the to the cluster wide policy `arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy` (equivalent of `cluster-admin` `ClusterRole`). ```shell @@ -298,7 +298,7 @@ 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` or Access Entry +`Cloudformation`, you can use them to automatically configure the `aws-auth` `Configmap` or access entry and create the `ClusterRole` and `ClusterRoleBinding` resources during cluster provisioning. From 3dc08ddfecce2e1e9a1589c9a81baa2a82755d2a Mon Sep 17 00:00:00 2001 From: Tiago Silva Date: Thu, 30 May 2024 22:10:10 +0100 Subject: [PATCH 7/7] Update kubernetes.mdx Co-authored-by: Paul Gottschling --- docs/pages/auto-discovery/kubernetes.mdx | 32 ++++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/pages/auto-discovery/kubernetes.mdx b/docs/pages/auto-discovery/kubernetes.mdx index 707c324f4a179..94e7130cb68a4 100644 --- a/docs/pages/auto-discovery/kubernetes.mdx +++ b/docs/pages/auto-discovery/kubernetes.mdx @@ -162,22 +162,22 @@ Kubernetes Service is set to monitor EKS clusters that are discovered by the Teleport Discovery Service. The monitoring process involves a label matching mechanism to identify and manage the EKS clusters. -1. **Discovery and Label Matching**: - - The Discovery Service identifies available EKS clusters within the AWS environment. - - The Teleport Kubernetes Service checks the labels of these discovered EKS clusters - against the labels specified in the `kubernetes_service.resources[].labels` configuration. - - The labels in the `kubernetes_service.resources[].labels` array serve as selectors. -2. **Role Selection**: - - The first selector in the array that matches the labels of an EKS cluster determines - the role that the Kubernetes Service will assume. - - This role is essential for the Teleport Kubernetes Service to retrieve necessary cluster details from the AWS API. - - If no match is found, the Kubernetes Service defaults to its own identity. -3. **Interaction with AWS and Kubernetes API**: - - Once a match is found and a role is assumed, the Teleport Kubernetes Service uses - this role to access the AWS API. - - It retrieves detailed information about the EKS cluster, such as configuration and status. - - Subsequently, the Teleport Kubernetes Service forwards requests to the Kubernetes - API, enabling interaction with the cluster. +1. **Discovery and Label Matching:** The Discovery Service identifies available + EKS clusters within the AWS environment. The Teleport Kubernetes Service + checks the labels of these clusters against the labels specified in the + `kubernetes_service.resources[].labels` configuration, which is the + **selector array**. +1. **Role Selection:** The first selector in the array that matches the labels + of an EKS cluster determines the role that the Kubernetes Service will + assume. This role is essential for the Teleport Kubernetes Service to + retrieve necessary cluster details from the AWS API. If no match is found, + the Kubernetes Service defaults to its own identity. +1. **Interaction with AWS and Kubernetes APIs:** Once a match is found and a + role is assumed, the Teleport Kubernetes Service uses this role to access the + AWS API. It retrieves information about the EKS cluster, such as + configuration and status. Subsequently, the Teleport Kubernetes Service + forwards requests to the Kubernetes API, enabling interaction with the + cluster. Both services — Discovery and Kubernetes — can be configured in the same Teleport process or separate processes. \ No newline at end of file