企业官网建设流程全解析

• 网络安全
• 认证鉴权
• 运维
• 后端

Teleport 在 Teleport Cloud 环境中通过 AWS OIDC Integration 自动发现并接入（Auto Discovery / Auto Enrollment）Amazon EKS 集群时，要求目标集群必须可以被公网访问，否则无法部署 Teleport Kubernetes Agent。本指南围绕用户任务（UserTask）描述文档eks-missing-endpoint-public-access（原文见 lib/usertasks/descriptions/eks-missing-endpoint-public-access.md），结合仓库源码讲解该问题的触发条件、底层判定逻辑、在 Teleport 界面中的呈现方式，以及完整的修复步骤。读完本文，你将能准确识别这一报错、定位其产生原因，并通过 AWS 控制台或命令行快速恢复 EKS 集群的自动接入。

问题定义：EKS 集群必须公网可达才能部署 Agent

该用户任务的标题与说明非常简洁，核心就一句话：

The EKS Cluster must be publicly accessible in order for Teleport to deploy the Teleport Kubernetes Agent.You can enable the public endpoint by accessing the Manage Endpoint Access.

其含义是：Teleport 在将 EKS 集群纳入管理时，需要在集群内安装 Teleport Kubernetes Agent（以 Helm Chart / StatefulSet 形式运行）。如果 EKS 集群的 API Server 端点仅配置为私网（Private endpoint）而关闭了公网端点（Public endpoint），并且 Teleport 部署在 Teleport Cloud 环境中，那么 Teleport 将无法访问集群 API，从而无法安装并部署 Agent，自动接入即告失败。

在仓库中，这个问题的类型标识（IssueType）被定义为字符串常量：

// AutoDiscoverEKSIssueMissingEndpoingPublicAccess is used to identify clusters that failed to auto-enroll // because they don't have a public endpoint and this Teleport Cluster is running in Teleport Cloud. AutoDiscoverEKSIssueMissingEndpoingPublicAccess = "eks-missing-endpoint-public-access"

见 api/types/usertasks/object.go。注意两点：一是该问题仅与 Teleport Cloud 环境相关；二是它隶属于 EKS 自动发现/接入（Auto Discover EKS）用户任务的五个已知问题类型之一（完整列表见同一文件DiscoverEKSIssueTypes，包括eks-status-not-active、eks-missing-endpoint-public-access、eks-authentication-mode-unsupported、eks-cluster-unreachable、eks-agent-not-connecting）。

触发场景：EKS 自动发现与自动接入的完整链路

该问题出现在 Teleport 的AWS 自动发现（Auto Discovery）流程中。整体链路为：

1. 用户配置AWS OIDC Integration（api/proto/teleport/integration/v1/awsoidc_service.proto），用于授予 Teleport 访问 AWS 资源的权限；
2. Teleport 调用ListEKSClusters列出某个 Region 下的 EKS 集群，并附带集群的详细属性；
3. Teleport 调用EnrollEKSClusters对每个符合条件的集群执行自动接入（安装 Teleport Kube Agent）；
4. 某个集群接入失败时，结果中携带IssueType字段，用于区分失败类别，见 api/proto/teleport/integration/v1/awsoidc_service.proto 中EnrollEKSClusterResult的定义：

   IssueTypecontains the UserTask's issue type for well-known errors. Example of allowed values:eks-status-not-active、eks-missing-endpoint-public-access、eks-authentication-mode-unsupported、eks-cluster-unreachable、eks-agent-not-connecting。

在列表阶段，Teleport 已经从 AWS 的DescribeCluster结果中读取了 VPC 配置信息。EndpointPublicAccess字段在 lib/integrations/awsoidc/eks_list_clusters.go 中定义如下：

// EndpointPublicAccess indicates whether the Cluster's VPC Config has its endpoint as a public address. // For Teleport Cloud, this is required to access the cluster and proceed with the installation. EndpointPublicAccess bool

该字段由cluster.ResourcesVpcConfig.EndpointPublicAccess直接映射而来，是后续判定eks-missing-endpoint-public-access的关键数据来源。

源码级成因：enrollEKSCluster 中的判定逻辑

自动接入单个集群的核心实现位于 lib/integrations/awsoidc/eks_enroll_clusters.go 的enrollEKSCluster函数。该函数按顺序执行一系列前置检查，任何一步不满足都会直接返回对应的 IssueType 与错误信息：

1. DescribeCluster：调用 AWS EKS API 获取集群详情，失败则直接报错；
2. 状态检查：集群Status必须为ACTIVE，否则返回eks-status-not-active；
3. 公网端点检查（本文主题）：

   // We can't discover private EKS clusters for cloud clients, since we know that auth server is running in our VPC. if req.IsCloud && !eksCluster.ResourcesVpcConfig.EndpointPublicAccess { return "", usertasks.AutoDiscoverEKSIssueMissingEndpoingPublicAccess, trace.AccessDenied("can't enroll %q because it is not accessible from Teleport Cloud, please enable endpoint public access in your EKS cluster and try again.", clusterName) }

   这里有两个必要条件同时成立才会触发该问题：req.IsCloud为true（即 Teleport 运行在 Teleport Cloud，其 Auth Server 位于 Teleport 自己的 VPC 内），并且集群 VPC 配置中EndpointPublicAccess为false。此时 Teleport 无法从自己的网络访问集群 API，Agent 自然无法部署。返回给用户的错误信息原文为：

   can't enroll "EKS3" because it is not accessible from Teleport Cloud, please enable endpoint public access in your EKS cluster and try again.

4. 认证模式检查：集群AccessConfig.AuthenticationMode必须是API或API_AND_CONFIG_MAP，否则返回eks-authentication-mode-unsupported（CONFIG_MAP模式下 API 不可用，Teleport 无法安装 Helm Chart）；
5. Access Entry 关联：为接入主体创建/关联访问条目并授予策略；
6. 安装 Agent：通过 Helm 安装 Teleport Kube Agent，若 Agent 后续无法连接 Teleport 则表现为eks-agent-not-connecting。

由此可见，eks-missing-endpoint-public-access是整个接入流程中发生在较早阶段的一个可提前避免的问题：它不属于 Agent 运行时的瞬时故障，而是集群网络配置不满足接入前提的确定性失败。

问题在 Teleport 中的呈现：UserTask 用户任务机制

当自动接入失败时，Teleport 会生成一个UserTask（用户任务），把失败的集群与上述 IssueType 关联起来，并在 Web UI 中向管理员展示问题描述与修复指引。这一机制的实现细节如下：

描述文档的加载方式

所有已知问题类型的说明都存放在 lib/usertasks/descriptions/ 目录下，以<issue-type>.md命名（本文主题即eks-missing-endpoint-public-access.md）。这些 Markdown 文件通过//go:embed编译进二进制，见 lib/usertasks/descriptions.go：

//go:embed descriptions/*.md var descriptionsFS embed.FS func loadIssueTitleDescription(issueType string) (string, string) { filename := fmt.Sprintf("descriptions/%s.md", issueType) bs, err := descriptionsFS.ReadFile(filename) ... title := documentParts[0] if !strings.HasPrefix(title, "# ") { return "", "" } title = title[2:] description := strings.TrimSpace(documentParts[1]) return title, description }

即：文档第一行（以#开头）被解析为问题标题，其余部分被解析为问题说明与修复步骤。DescriptionForDiscoverEKSIssue等导出函数（见 lib/usertasks/descriptions.go）供上层调用，将标题和描述渲染到 Web UI 中。

控制台直达链接的富化（URL 增强）

为了让管理员能够一键进入 AWS 控制台修复问题，lib/usertasks/urls.go中的EKSClustersWithURLs会根据 IssueType 为每个失败集群附加对应的 AWS 控制台 URL，见 lib/usertasks/urls.go：

// ManageEndpointAccessURL is the URL to open the EKS in Amazon Web Console, in the Manage Endpoint Access page. // Present when issue is of type eks-cluster-unreachable and eks-missing-endpoint-public-access. // Format: https://console.aws.amazon.com/eks/home?region=<region>#/clusters/<cluster-name>/manage-endpoint-access ManageEndpointAccessURL string `json:"manageEndpointAccessUrl,omitempty"`

URL 的拼接逻辑在 lib/usertasks/urls.go：当 IssueType 为eks-missing-endpoint-public-access（或eks-cluster-unreachable）时，会在集群基础 URL 上追加/manage-endpoint-access片段，从而直接定位到 AWS EKS 控制台的Manage Endpoint Access页面——这与原文档指引的修复入口完全一致：

case usertasksapi.AutoDiscoverEKSIssueClusterUnreachable, usertasksapi.AutoDiscoverEKSIssueMissingEndpoingPublicAccess: clusterBaseURL.Fragment = clusterBaseURL.Fragment + "/manage-endpoint-access" ret.ManageEndpointAccessURL = clusterBaseURL.String()

此外每个集群还会附带ResourceURL（指向 EKS 控制台的集群详情页），方便管理员先确认集群状态再决定如何修复。

修复步骤：开启 EKS 集群的公网端点

根据原文档指引，修复方式是访问 EKS 控制台的 Manage Endpoint Access 页面并启用公网端点。具体操作如下。

方式一：AWS 控制台（对应原文档指引）

1. 打开 AWS 管理控制台，进入Amazon EKS；
2. 在左侧选择集群，点击目标集群（即 UserTask 中报错的集群）；
3. 进入Networking（网络）或Manage endpoint access（管理端点访问）页面（该页面即ManageEndpointAccessURL指向的地址）；
4. 在Endpoint access配置中，将Public endpoint（公网端点）设为Enabled；
5. 保存配置。AWS 会更新集群的ResourcesVpcConfig，将EndpointPublicAccess置为true；
6. 返回 Teleport，等待下一次自动接入重试，或手动重新发起对目标集群的接入。

方式二：AWS CLI（等价的命令行操作）

对于偏好命令行或需要批量处理的管理员，可以使用 AWS CLI 的update-cluster-config更新集群 VPC 配置，将endpointPublicAccess设置为true：

aws eks update-cluster-config \ --region <region> \ --name <cluster-name> \ --resources-vpc-config endpointPublicAccess=true

说明：endpointPublicAccess字段与仓库源码中读取的cluster.ResourcesVpcConfig.EndpointPublicAccess一一对应（见 lib/integrations/awsoidc/eks_list_clusters.go），即 Teleport 正是通过该字段判断集群是否公网可达。修改完成后，集群 VPC 配置变更会被 AWS 异步应用，可在控制台或通过aws eks describe-cluster --name <cluster-name>确认。

修复后的确认

• 在 AWS 侧确认集群状态为ACTIVE，且 Networking 中公网端点已启用；
• 在 Teleport 侧，确认对应 UserTask 状态更新或消失，目标集群出现在 Kubernetes 资源列表中；
• 若仍然失败，可结合其他 IssueType（如eks-cluster-unreachable、eks-agent-not-connecting）进一步排查网络连通性与 Agent 连接问题。

安全权衡与相关问题区分

安全注意事项

启用公网端点意味着 EKS API Server 将暴露在公网，需要权衡安全性。建议在开启公网端点的同时，通过 AWS 的Public access CIDRs（公网访问 CIDR 白名单）将可访问的源 IP 范围限制在必要的最小集合内（如公司出口 IP 或 Teleport Cloud 相关网段），避免 API Server 对全网开放。若企业安全策略禁止任何公网暴露，则应评估自建（非 Cloud）Teleport 部署方案，或通过 VPC Peering / PrivateLink 等网络方案打通网络后再接入。

与 eks-cluster-unreachable 的区分

仓库代码明确区分了两个语义相近的问题类型，见 api/types/usertasks/object.go：

• eks-missing-endpoint-public-access：仅在Teleport Cloud场景触发（req.IsCloud == true），是"集群配置不满足公网可达前提"的确定性判定，无需实际建连即可报出；
• eks-cluster-unreachable：用于Teleport 无法访问集群 API的场景，适用于非 Cloud（自建）部署或其他网络不通的情况（如安全组、VPC 路由、IAM 权限等导致的连通性失败）。

两者在 URL 富化时都会附加ManageEndpointAccessURL，因为修复路径通常一致（开放公网端点或调整网络）。排查时先确认部署形态：Teleport Cloud 环境优先检查公网端点；自建环境优先检查网络连通性。

测试与验证

仓库为这一判定逻辑提供了完整的单元测试，见 lib/integrations/awsoidc/eks_enroll_clusters_test.go。测试构造了一个EndpointPublicAccess: false的集群（EKS3），断言自动接入返回的错误信息与 IssueType 完全匹配：

require.EqualError(t, err, `can't enroll "EKS3" because it is not accessible from Teleport Cloud, please enable endpoint public access in your EKS cluster and try again.`) require.Equal(t, "eks-missing-endpoint-public-access", response.Results[0].IssueType)

同文件还覆盖了EndpointPublicAccess: true时正常继续执行后续接入流程的场景，以及eks-status-not-active、eks-authentication-mode-unsupported等其他问题类型，共同保证了enrollEKSCluster前置检查顺序与错误分类的正确性。相关 URL 富化逻辑也有对应的测试（见 lib/usertasks/urls_test.go），验证ManageEndpointAccessURL生成格式为https://console.aws.amazon.com/eks/home?region=<region>#/clusters/<cluster-name>/manage-endpoint-access。

小结

eks-missing-endpoint-public-access是 Teleport Cloud 在 EKS 自动接入场景下的一个网络前置条件检查问题：只要目标集群未开启公网端点，Teleport 便无法部署 Kubernetes Agent，并会以 UserTask 形式在 Web UI 中提示管理员通过Manage Endpoint Access页面启用公网端点。本文从 lib/integrations/awsoidc/eks_enroll_clusters.go 的判定源码、lib/usertasks/descriptions.go 的描述加载机制到 lib/usertasks/urls.go 的直达链接富化，完整还原了该问题的产生、呈现与修复闭环。遇到此类报错时，按"控制台/CLI 开启公网端点 → 确认集群 ACTIVE → 重试接入"的顺序操作即可解决；若属自建 Teleport 部署，则应按eks-cluster-unreachable的网络连通性方向排查。

• 网络安全
• 认证鉴权
• 运维
• 后端