diff --git a/docs/config.json b/docs/config.json index 63e0b54b2f9..051ca75289e 100644 --- a/docs/config.json +++ b/docs/config.json @@ -285,6 +285,21 @@ "destination": "/enroll-resources/auto-discovery/kubernetes-applications/reference/", "permanent": true }, + { + "source": "/enroll-resources/auto-discovery/kubernetes/aws/", + "destination": "/enroll-resources/auto-discovery/kubernetes/eks-discovery/", + "permanent": true + }, + { + "source": "/enroll-resources/auto-discovery/kubernetes/azure/", + "destination": "/enroll-resources/auto-discovery/kubernetes/aks-discovery/", + "permanent": true + }, + { + "source": "/enroll-resources/auto-discovery/kubernetes/google-cloud/", + "destination": "/enroll-resources/auto-discovery/kubernetes/gke-discovery/", + "permanent": true + }, { "source": "/reference/operator-resources/resources.teleport.dev_trustedclustersv2/", "destination": "/reference/infrastructure-as-code/operator-resources/resources-teleport-dev-trustedclustersv2/", diff --git a/docs/pages/enroll-resources/auto-discovery/auto-discovery.mdx b/docs/pages/enroll-resources/auto-discovery/auto-discovery.mdx index c967f3e35c6..a3e2649d086 100644 --- a/docs/pages/enroll-resources/auto-discovery/auto-discovery.mdx +++ b/docs/pages/enroll-resources/auto-discovery/auto-discovery.mdx @@ -95,17 +95,17 @@ tagLists={ [ { name: "AWS", - href: "./kubernetes/aws/", + href: "./kubernetes/eks-discovery/", icon: "aws", }, { name: "Azure", - href: "./kubernetes/azure/", + href: "./kubernetes/aks-discovery/", icon: "azure", }, { name: "Google Cloud", - href: "./kubernetes/google-cloud/", + href: "./kubernetes/gke-discovery/", icon: "googleCloud", }, ] diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/azure.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/aks-discovery.mdx similarity index 100% rename from docs/pages/enroll-resources/auto-discovery/kubernetes/azure.mdx rename to docs/pages/enroll-resources/auto-discovery/kubernetes/aks-discovery.mdx diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery-manual.mdx similarity index 97% rename from docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx rename to docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery-manual.mdx index 16ff99eef04..64b7bb9dc31 100644 --- a/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx +++ b/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery-manual.mdx @@ -1,7 +1,7 @@ --- -title: Teleport EKS Auto-Discovery -sidebar_label: Elastic Kubernetes Service -description: How to configure auto-discovery of AWS EKS clusters in Teleport. +title: Manual EKS Auto-Discovery Configuration +sidebar_label: Manual +description: How to configure Teleport EKS auto-discovery manually. tags: - how-to - zero-trust @@ -9,9 +9,8 @@ tags: - aws --- -EKS Auto-Discovery can automatically -discover any EKS cluster and enroll it in Teleport if its tags match the -configured labels. +This guide shows you how to manually configure Teleport and AWS to +automatically enroll EKS clusters in your Teleport cluster. (!docs/pages/includes/discovery/step-description.mdx serviceName="Kubernetes" resourceDesc="cluster" resourceKind="kube_cluster" !) diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery-terraform.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery-terraform.mdx new file mode 100644 index 00000000000..b0521673b72 --- /dev/null +++ b/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery-terraform.mdx @@ -0,0 +1,364 @@ +--- +title: Terraform EKS Auto-Discovery Configuration +sidebar_label: Terraform +description: How to configure Teleport EKS auto-discovery with Terraform +tags: + - how-to + - zero-trust + - infrastructure-identity + - aws +--- + +This guide shows you how to use Terraform to configure Teleport and AWS to +automatically enroll EKS clusters in your Teleport cluster. + +## How it works + +(!docs/pages/includes/discovery/step-description.mdx serviceName="Kubernetes" resourceDesc="cluster" resourceKind="kube_cluster" !) + +The [teleport-discovery-aws](../../../../reference/infrastructure-as-code/terraform-modules/teleport-discovery-aws/teleport-discovery-aws.mdx) +Terraform module creates the AWS IAM resources and the Teleport integration, +`discovery_config`, and provision token that configure the Discovery Service +to enroll EKS clusters. When the Discovery Service has the required IAM +permissions, it also provisions an EKS Access Entry for each discovered +cluster so the Kubernetes Service can forward traffic to it. + +## Prerequisites + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- An AWS account with IAM permissions to create roles, policies, and an OIDC + provider. See the next step for the full permissions Terraform needs. + +- [Terraform v(=terraform.version=)+](https://learn.hashicorp.com/tutorials/terraform/install-cli). + + ```code + $ terraform version + # Terraform v(=terraform.version=) + ``` + +- A host to run the Teleport Discovery and Kubernetes services. Teleport Cloud + runs the Discovery Service for you, but you still need to run your own + Kubernetes Service. See the [manual guide](eks-discovery-manual.mdx) for + service setup. + +- (!docs/pages/includes/tctl.mdx!) + +## Use the `teleport-discovery-aws` Terraform module + +### Step 1/5. Configure AWS Terraform provider + +Configure the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) +and AWS IAM permissions for Terraform to manage AWS resources. + +
+AWS IAM permissions required for AWS Terraform provider + +The AWS Terraform provider will need the following AWS IAM permissions to +manage AWS resources created by the `teleport-discovery-aws` module: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "TerraformIdentity", + "Effect": "Allow", + "Action": "sts:GetCallerIdentity", + "Resource": "*" + }, + { + "Sid": "ManageIamRole", + "Effect": "Allow", + "Action": [ + "iam:CreateRole", + "iam:DeleteRole", + "iam:GetRole", + "iam:ListInstanceProfilesForRole", + "iam:ListRolePolicies", + "iam:ListRoles", + "iam:ListRoleTags", + "iam:TagRole", + "iam:UntagRole", + "iam:UpdateAssumeRolePolicy" + ], + "Resource": "*" + }, + { + "Sid": "ManageIamPolicy", + "Effect": "Allow", + "Action": [ + "iam:CreatePolicy", + "iam:CreatePolicyVersion", + "iam:DeletePolicy", + "iam:DeletePolicyVersion", + "iam:GetPolicy", + "iam:GetPolicyVersion", + "iam:ListPolicies", + "iam:ListPolicyTags", + "iam:ListPolicyVersions", + "iam:TagPolicy", + "iam:UntagPolicy" + ], + "Resource": "*" + }, + { + "Sid": "ManageRolePolicyAttachments", + "Effect": "Allow", + "Action": [ + "iam:AttachRolePolicy", + "iam:DetachRolePolicy", + "iam:ListAttachedRolePolicies" + ], + "Resource": "*" + }, + { + "Sid": "ManageOidcProvider", + "Effect": "Allow", + "Action": [ + "iam:CreateOpenIDConnectProvider", + "iam:DeleteOpenIDConnectProvider", + "iam:GetOpenIDConnectProvider", + "iam:ListOpenIDConnectProviders", + "iam:TagOpenIDConnectProvider", + "iam:UntagOpenIDConnectProvider", + "iam:UpdateOpenIDConnectProviderThumbprint" + ], + "Resource": "*" + } + ] +} +``` + +
+ +### Step 2/5. Configure Teleport Terraform provider + +For a local quick start, log in with `tsh` and run `tctl terraform env` in +the same shell you use for `terraform` commands: + +```code +$ tsh login +$ eval "$(tctl terraform env)" +``` + +See the [Local Demo](../../../../zero-trust-access/infrastructure-as-code/terraform-provider/local.mdx) +guide for more detail on local setup. If you are running Terraform in CI, +Spacelift, or another remote environment, refer to [Using the Teleport +Terraform Provider](../../../../zero-trust-access/infrastructure-as-code/terraform-provider/terraform-provider.mdx) +for the appropriate guide. + +### Step 3/5. Configure the Terraform module inputs + +Add the `teleport-discovery-aws` module to your Terraform configuration. + + + + +```hcl +module "aws_discovery" { + source = "terraform.releases.teleport.dev/teleport/discovery/aws" + version = "~> (=cloud.major_version=).0" + + # Required inputs: + # Assign to your Teleport cluster's proxy public address in host:port form. + teleport_proxy_public_addr = "" + # teleport_discovery_group_name must match the discovery group name in your Discovery Service config file. + # Teleport Cloud clusters run the Discovery Service in the group name "cloud-discovery-group". + # Do not modify this input unless you intend to run your own Discovery Service. + teleport_discovery_group_name = "cloud-discovery-group" + + aws_matchers = [ + { + types = ["eks"] + # EKS discovery supports "*" to discover clusters across all enabled regions. + regions = ["*"] + # tags filter which EKS clusters are enrolled. The wildcard matches all tags. + tags = { "*" : ["*"] } + # Also enroll HTTP applications running inside discovered clusters. + kube_app_discovery = true + } + ] + + # Optional inputs: + # Apply the additional AWS tag "origin=example" to all AWS resources created by this module + apply_aws_tags = { origin = "example" } + # Apply the additional Teleport label "origin=example" to all Teleport resources created by this module + apply_teleport_resource_labels = { origin = "example" } +} +``` + + + +```hcl +module "aws_discovery" { + source = "terraform.releases.teleport.dev/teleport/discovery/aws" + version = "~> (=teleport.major_version=).0" + + # Required inputs: + # Edit this input to the host and port of the Teleport Proxy Service in your cluster + teleport_proxy_public_addr = "" + # Assign to the discovery group name in your Discovery Service config file. + teleport_discovery_group_name = "" + + aws_matchers = [ + { + types = ["eks"] + # EKS discovery supports "*" to discover clusters across all enabled regions. + regions = ["*"] + # tags filter which EKS clusters are enrolled. The wildcard matches all tags. + tags = { "*" : ["*"] } + # Also enroll HTTP applications running inside discovered clusters. + kube_app_discovery = true + } + ] + + # Optional inputs: + # Apply the additional AWS tag "origin=example" to all AWS resources created by this module + apply_aws_tags = { origin = "example" } + # Apply the additional Teleport label "origin=example" to all Teleport resources created by this module + apply_teleport_resource_labels = { origin = "example" } +} +``` + + + + +Add a Terraform output for the module so that Terraform will display its +outputs: + +```hcl +output "aws_discovery" { + value = module.aws_discovery +} +``` + +See the [teleport-discovery-aws +reference](../../../../reference/infrastructure-as-code/terraform-modules/teleport-discovery-aws/teleport-discovery-aws.mdx) +for a complete description of the module inputs and outputs. + +#### Granting access to discovered EKS clusters + +The IAM role created by this module includes permissions for the Discovery +Service to create and update EKS Access Entries. When the Discovery Service +finds a new EKS cluster, it automatically provisions an Access Entry so the +Teleport Kubernetes Service can forward traffic. + +By default, the Discovery Service grants access to its own IAM role. If your +Kubernetes Service runs with a different IAM role, add `setup_access_for_arn` +to the EKS matcher with that role's ARN: + +```hcl +aws_matchers = [ + { + types = ["eks"] + regions = ["*"] + tags = { "*" : ["*"] } + setup_access_for_arn = "arn:aws:iam::123456789012:role/teleport-kube-service" + } +] +``` + +### Step 4/5. Apply the Terraform module + +```code +$ terraform init +$ terraform apply +``` + +Terraform should plan to create the following resources: +- AWS IAM role for Teleport Discovery Service to assume +- AWS IAM policy that grants the AWS permissions necessary for Teleport to discover resources in AWS +- AWS IAM policy attachment to attach the IAM policy to the Discovery Service IAM role +- AWS OIDC Provider for Teleport Discovery Service to assume an IAM role using OIDC +- Teleport `discovery_config` cluster resource that configures Teleport for AWS resource discovery +- Teleport `integration` cluster resource for AWS OIDC +- Teleport `token` cluster resource that allows Teleport nodes to use AWS IAM credentials to join the cluster + +Review the Terraform plan and confirm the plan actions. + +After Terraform finishes applying the plan, it should display the module +outputs: + +``` +aws_discovery = { + "aws_oidc_provider_arn" = "arn:aws:iam::123456789012:oidc-provider/example.teleport.sh" + "teleport_discovery_config_name" = "discovery-aws-account-123456789012" + "teleport_discovery_service_iam_policy_arn" = "arn:aws:iam::123456789012:policy/teleport-discovery-" + "teleport_discovery_service_iam_role_arn" = "arn:aws:iam::123456789012:role/teleport-discovery-" + "teleport_integration_name" = "discovery-aws-account-123456789012" + "teleport_provision_token_name" = "discovery-aws-account-123456789012" +} +``` + +The AWS resources should have the following tags: +- `origin=example` +- `teleport.dev/cluster=` +- `teleport.dev/integration=discovery-aws-account-` +- `teleport.dev/iac-tool=terraform` + +The Teleport resources should have the following labels: +- `origin=example` +- `teleport.dev/iac-tool=terraform` + +### Step 5/5. Check discovery status + +After applying the Terraform module, the Teleport Discovery Service should +start to discover EKS clusters in your AWS account and enroll them in your +Teleport cluster as `kube_cluster` resources. + + + +It may take a few minutes for EKS clusters to be discovered and enrolled. + + + +Navigate to the Teleport Web UI and select `Zero Trust Access > Integrations`. +By default, the integration created by the `teleport-discovery-aws` Terraform +module is named `discovery-aws-account-`. + +Click on the integration for your AWS account to review the discovery status. + +The integration page provides an overview of how many EKS clusters have been +discovered and any issues encountered during the discovery process. + +## Updating module configuration + +The module inputs can be changed and re-applied to adjust the AWS discovery +integration. + +For example, if you had previously configured specific AWS regions, you can +switch to the wildcard to discover EKS clusters in all enabled regions: + +```diff +-regions = ["us-west-1"] ++regions = ["*"] +``` + +Apply Terraform again: + +```code +$ terraform apply +``` + +Review the Terraform plan before confirming the changes. + +After Terraform finishes applying its plan, the Discovery Service will pick up +the change to the dynamic `discovery_config` and begin to enroll EKS clusters +in the newly-configured regions. + +## Troubleshooting + +(!docs/pages/includes/discovery/discovery-service-troubleshooting.mdx resourceKind="Kubernetes cluster" tctlResource="kube_cluster" !) + +(!docs/pages/includes/discovery/kubernetes-service-troubleshooting.mdx!) + +## Next steps + +- Read the [teleport-discovery-aws module reference](../../../../reference/infrastructure-as-code/terraform-modules/teleport-discovery-aws/teleport-discovery-aws.mdx) + for a complete description of the module's inputs and outputs. +- Learn how Teleport can also [discover HTTP applications running inside your + Kubernetes clusters](../../kubernetes-applications/kubernetes-applications.mdx). +- Review the [auto-discovery labels + reference](../../reference/labels.mdx) for the cloud tags that Teleport + imports as Kubernetes cluster labels. diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery.mdx new file mode 100644 index 00000000000..c316384550f --- /dev/null +++ b/docs/pages/enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery.mdx @@ -0,0 +1,33 @@ +--- +title: Kubernetes Auto-Discovery for Amazon EKS +sidebar_label: Amazon EKS +description: How to configure Teleport to automatically enroll EKS clusters. +tags: + - how-to + - zero-trust + - infrastructure-identity + - aws +--- + +This guide shows you how to configure Teleport to automatically enroll EKS +clusters in your Teleport cluster. + +## How it works + +The Teleport Discovery Service queries the AWS API for EKS clusters that match +configured regions and tags, and creates a `kube_cluster` resource in Teleport +for each matching cluster. The Teleport Kubernetes Service watches those +resources and forwards user traffic to the underlying EKS clusters. + +## Choosing manual or Terraform EKS auto-discovery configuration + +In the manual EKS auto-discovery configuration process, you create the required +IAM policies, EKS cluster access, and Teleport configuration yourself. + +In the Terraform process, the [teleport-discovery-aws](../../../../reference/infrastructure-as-code/terraform-modules/teleport-discovery-aws/teleport-discovery-aws.mdx) +module creates the AWS and Teleport resources for you. + +## Guides + +- [Manual EKS Auto-Discovery Configuration](eks-discovery-manual.mdx) +- [Terraform EKS Auto-Discovery Configuration](eks-discovery-terraform.mdx) diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/google-cloud.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/gke-discovery.mdx similarity index 100% rename from docs/pages/enroll-resources/auto-discovery/kubernetes/google-cloud.mdx rename to docs/pages/enroll-resources/auto-discovery/kubernetes/gke-discovery.mdx diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/kubernetes.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/kubernetes.mdx index 0bedb0be774..cfca1ef14d4 100644 --- a/docs/pages/enroll-resources/auto-discovery/kubernetes/kubernetes.mdx +++ b/docs/pages/enroll-resources/auto-discovery/kubernetes/kubernetes.mdx @@ -17,9 +17,9 @@ minimal access permissions. ## Supported clouds -- [AWS](aws.mdx): Discovery for AWS EKS clusters. -- [Azure](azure.mdx): Discovery for Azure AKS clusters. -- [Google Cloud](google-cloud.mdx): Discovery for +- [AWS](eks-discovery/eks-discovery.mdx): Discovery for AWS EKS clusters. +- [Azure](aks-discovery.mdx): Discovery for Azure AKS clusters. +- [Google Cloud](gke-discovery.mdx): Discovery for Google Kubernetes Engine clusters. ## How Kubernetes Clusters Discovery works @@ -73,7 +73,9 @@ discovery_service: # eks - discovers and registers AWS EKS clusters # ec2 - discovers and registers AWS EC2 Machines - types: ["eks"] - # AWS regions to search for resources from + # AWS regions to search for resources from. Valid options are: + # '*' - discovers resources in all enabled regions (default). + # Any valid AWS region name, e.g. "us-east-1". regions: ["us-east-1", "us-west-1"] # AWS resource tags to match when registering resources # Optional section: Defaults to "*":"*" diff --git a/docs/pages/enroll-resources/auto-discovery/reference/labels.mdx b/docs/pages/enroll-resources/auto-discovery/reference/labels.mdx index b78110952ce..6a49178c296 100644 --- a/docs/pages/enroll-resources/auto-discovery/reference/labels.mdx +++ b/docs/pages/enroll-resources/auto-discovery/reference/labels.mdx @@ -45,7 +45,7 @@ See the AWS Databases auto-discovery [guide](../../../enroll-resources/auto-disc ### Kubernetes clusters -See the AWS EKS auto-discovery [guide](../../../enroll-resources/auto-discovery/kubernetes/aws.mdx). +See the AWS EKS auto-discovery [guide](../../../enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery.mdx). | Label | Description | |------------------------------------------------|-----------------------------------------------------------------------------------------------------------| @@ -97,7 +97,7 @@ See the Azure Databases auto-discovery [guide](../../database-access/enrollment/ ### Kubernetes clusters -See the Azure AKS auto-discovery [guide](../../../enroll-resources/auto-discovery/kubernetes/azure.mdx). +See the Azure AKS auto-discovery [guide](../../../enroll-resources/auto-discovery/kubernetes/aks-discovery.mdx). | Label | Description | |-------------------------------------------|-----------------------------------------------------------------------------------------------------------| @@ -125,7 +125,7 @@ See the GCP VM auto-discovery [guide](../../../enroll-resources/auto-discovery/s ### Kubernetes clusters -See the GCP GKE auto-discovery [guide](../../../enroll-resources/auto-discovery/kubernetes/google-cloud.mdx). +See the GCP GKE auto-discovery [guide](../../../enroll-resources/auto-discovery/kubernetes/gke-discovery.mdx). | Label | Description | |-------------------------------------------|-----------------------------------------------------------------------------------------------------------| diff --git a/docs/pages/enroll-resources/kubernetes-access/kubernetes-access.mdx b/docs/pages/enroll-resources/kubernetes-access/kubernetes-access.mdx index ff884038fec..ff7995e04a6 100644 --- a/docs/pages/enroll-resources/kubernetes-access/kubernetes-access.mdx +++ b/docs/pages/enroll-resources/kubernetes-access/kubernetes-access.mdx @@ -85,19 +85,19 @@ Log in with SSO and securely access enrolled Kubernetes clusters. Manage access title: "Azure Kubernetes Service (AKS) auto-discovery", description: "Automatically discover any AKS cluster and enroll it in Teleport.", iconComponent: azureSvg, - href: "../auto-discovery/kubernetes/azure/" + href: "../auto-discovery/kubernetes/aks-discovery/" }, { title: "Elastic Kubernetes Service (EKS) auto-discovery", description: "Automatically discover any EKS cluster and enroll it in Teleport", iconComponent: awsSvg, - href: "../auto-discovery/kubernetes/aws/" + href: "../auto-discovery/kubernetes/eks-discovery/" }, { title: "Google Kubernetes Engine (GKE) auto-discovery", description: "Automatically register your GKE clusters with Teleport", iconComponent: gcpSvg, - href: "../auto-discovery/kubernetes/google-cloud/" + href: "../auto-discovery/kubernetes/gke-discovery/" }, ]} /> diff --git a/docs/pages/installation/agents/amazon-ecs.mdx b/docs/pages/installation/agents/amazon-ecs.mdx index 315be5fcaac..3b0aebeafe0 100644 --- a/docs/pages/installation/agents/amazon-ecs.mdx +++ b/docs/pages/installation/agents/amazon-ecs.mdx @@ -266,5 +266,5 @@ Navigate to the [Amazon ECS console](https://console.aws.amazon.com/ecs/v2/clust ## Next steps Use this guide as a starting point for implementing Auto Discovery for AWS resources: -- [EKS clusters](../../enroll-resources/auto-discovery/kubernetes/aws.mdx) +- [EKS clusters](../../enroll-resources/auto-discovery/kubernetes/eks-discovery/eks-discovery.mdx) - [AWS databases](../../enroll-resources/database-access/enrollment/aws/aws.mdx)