在使用 EC2 实例存储配置的 AWS Outposts 上部署 Amazon EKS 本地集群

本主题提供了有关在使用 EC2 实例存储配置的 AWS Outpost 上部署 Amazon EKS 本地集群的说明。

注意

如果您的 Outpost 是使用 Amazon EBS 而不是 EC2 实例存储配置的，则本主题中描述的架构不适用于您的 Outpost。使用 EBS 配置的 Outposts 将继续使用现有的本地集群实现。有关更多信息，请参阅在 AWS Outposts 上部署 Amazon EKS 集群。

如果您有兴趣使用更新后的本地集群架构在 EBS 支持的 Outpost 上创建本地集群，请联系您的 AWS 客户团队。

重要

本地集群仅支持 Outpost 机架。单个本地集群可跨构成单个逻辑 Outpost 的多个物理 Outpost 机架运行。单个本地集群不能跨多个逻辑 Outpost 运行。
Kubernetes 控制面板在您的 Outpost 上的 AWS 托管式服务账户中运行。您无法访问控制面板实例或在 Amazon EC2 控制台中查看这些实例，也无法在这些实例上运行工作负载。
控制面板采用外部 etcd 拓扑结构，在 6 个 EC2 实例（3 etcd + 3 个 API 服务器）上运行。有关容量要求，请参阅为使用 EC2 实例存储配置的 AWS Outposts 上的 Amazon EKS 本地集群选择实例类型和置放。
适用于 Kubernetes 的 Amazon VPC CNI 插件、kube-proxy 和 CoreDNS 会自动安装到本地集群上。有关已验证附加组件的完整列表，请参阅适用于使用 EC2 实例存储配置的 AWS Outposts 上的本地集群的 Amazon EKS 附加组件。
Amazon EKS 会定期备份 etcd。如果 etcd 失去法定数量（quorum），Amazon EKS 会从最近的快照中恢复集群状态。

先决条件

一个使用 EC2 实例存储配置，且具有足够虚拟化容量用于控制面板实例的现有 Outpost 机架。请参阅为使用 EC2 实例存储配置的 AWS Outposts 上的 Amazon EKS 本地集群选择实例类型和置放。
满足为使用 EC2 实例存储配置的 AWS Outposts 上的 Amazon EKS 本地集群创建 VPC 和子网中所述要求的 VPC 和子网。
计算机或 AWS CloudShell 上安装了 kubectl 命令行工具。该版本可以与集群的 Kubernetes 版本相同，或者最多早于或晚于该版本一个次要版本。要安装或升级 kubectl，请参阅设置 kubectl 和 eksctl。
您的设备或 AWS CloudShell 上安装并配置了 2.35.3 或更高版本的 AWS CLI。要查看当前版本，请使用 aws --version。要进行安装或升级，请参阅安装 AWS CLI。
具有创建和描述 Amazon EKS 集群的权限的 IAM 主体（用户或角色）。有关更多信息，请参阅在 Outpost 上创建本地 Kubernetes 集群和列出或描述所有集群。
附加了以下 AWS 托管式策略的集群的 IAM 角色：AmazonEKSClusterPolicy 和 AmazonEKSServicePolicy。角色信任策略必须允许 eks.amazonaws.com 服务主体代入该角色。

注意

创建本地集群后，创建该集群的 IAM 主体将作为具有 system:masters 权限的管理员永久添加到 Kubernetes RBAC 授权表中。确保永远不要删除该主体。

创建本地集群

您可以使用 AWS 管理控制台、AWS CLI、Amazon EKS API 或 AWS CloudFormation 创建本地集群。

创建本地集群时，应注意以下方面：

您必须传递 Outpost 所在可用区中的子网。如果您传递多个可用区中的子网，则请求将会失败。
必须将 endpointPrivateAccess 设置为 true。此外也可以启用 endpointPublicAccess。
必须传递 outpostConfig 的值，包括 outpostArns、controlPlaneInstanceType 和 etcdInstanceType。您也可以指定置放配置。请参阅为使用 EC2 实例存储配置的 AWS Outposts 上的 Amazon EKS 本地集群选择实例类型和置放。

AWS CLI


aws eks create-cluster \
  --name my-cluster \
  --role-arn arn:aws:iam::111122223333:role/myEKSClusterRole \
  --kubernetes-version 1.36 \
  --resources-vpc-config subnetIds=subnet-ExampleID1,endpointPrivateAccess=true,endpointPublicAccess=true \
  --logging '{"clusterLogging":[{"types":["api","audit","authenticator","controllerManager","scheduler"],"enabled":true}]}' \
  --access-config authenticationMode=API_AND_CONFIG_MAP,bootstrapClusterCreatorAdminPermissions=true \
  --outpost-config outpostArns=arn:aws:outposts:region-code:111122223333:outpost/op-uniqueid,controlPlaneInstanceType=m5.large,controlPlanePlacement={spreadLevel=host},etcdInstanceType=m5.large,etcdPlacement={spreadLevel=host}

AWS 管理控制台

打开 Amazon EKS 控制台。
选择创建集群。
对于 Kubernetes 控制面板位置，请选择 AWS Outposts。
配置以下内容：
- 名称：集群的名称。
- Kubernetes 版本：要使用的版本。
- 集群服务角色：具有 AmazonEKSClusterPolicy 和 AmazonEKSServicePolicy 的 IAM 角色。
- Outpost ID：要部署到的逻辑 Outpost。
- 控制面板实例类型：Kubernetes API 服务器、调度器和控制器管理器的实例类型。
- etcd 实例类型：etcd 的实例类型。
- 分布级别：将 host 还是 rack 用于控制面板和 etcd 置放。
配置联网：VPC、子网、安全组。启用私有端点访问权限。
配置可观测性：控制面板日志。
审核和创建

`CreateCluster` API


{
    "name": "my-cluster",
    "roleArn": "arn:aws:iam::111122223333:role/myEKSClusterRole",
    "version": "1.36",
    "resourcesVpcConfig": {
        "subnetIds": ["subnet-ExampleID1"],
        "endpointPublicAccess": true,
        "endpointPrivateAccess": true
    },
    "logging": {
        "clusterLogging": [{
            "types": ["api", "audit", "authenticator", "controllerManager", "scheduler"],
            "enabled": true
        }]
    },
    "accessConfig": {
        "authenticationMode": "API_AND_CONFIG_MAP",
        "bootstrapClusterCreatorAdminPermissions": true
    },
    "outpostConfig": {
        "outpostArns": ["arn:aws:outposts:region-code:111122223333:outpost/op-uniqueid"],
        "controlPlaneInstanceType": "m5.large",
        "controlPlanePlacement": {
            "spreadLevel": "host"
        },
        "etcdInstanceType": "m5.large",
        "etcdPlacement": {
            "spreadLevel": "host"
        }
    }
}

在使用 EC2 实例存储配置的 Outposts 上创建本地集群时，必须使用 controlPlaneInstanceType 和 etcdInstanceType 参数。controlPlanePlacement 和 etcdPlacement 参数可选。如果未指定这两个参数，则不会应用任何置放分布策略。

注意

outpostConfig 是一种仅限创建属性。要更改控制面板实例类型、etcd 实例类型、置放或 Outpost，必须创建新的集群。

连接到集群

配置 kubectl 以与集群通信：


aws eks update-kubeconfig --region region-code --name my-cluster

注意

如果集群是使用低于 2.35.3 的 AWS CLI 版本创建的，则必须更新 kubeconfig 以在 exec 参数中指定 --cluster-name（而不是 --cluster-id）

集群的 Kubernetes API 服务器端点在 Amazon Route 53 中托管。该端点会解析为 Amazon EKS 在您的子网中创建的跨账户弹性网络接口（ENI）的私有 IP 地址。这些 ENI 具有固定私有 IP 地址，在整个集群生命周期中都不会更改。

在创建集群时，Amazon EKS 将在您指定的子网中创建 3 个弹性网络接口。这些网络接口可实现集群和 VPC 之间的通信。每个网络接口的描述中都有 Amazon EKS cluster-name 文字。

部署 Worker 节点

使用自行管理的节点组将 Worker 节点部署到本地集群。

在您的 Outpost 上部署 Worker 节点 AWS CloudFormation 模板或创建单独的 EC2 实例。


curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2025-11-24/amazon-eks-outpost-nodegroup.yaml

向节点实例角色授予对集群的访问权限。为节点的 IAM 角色创建一个访问条目：
```
aws eks create-access-entry \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::111122223333:role/myNodeRole \
  --type EC2_LINUX
```
如果您使用 aws-auth ConfigMap 进行身份验证，则也可将该节点实例角色添加到 ConfigMap 中。请参阅向 IAM 用户和角色授予对 Kubernetes API 的访问权限。
验证节点是否处于 Ready 状态：
```
kubectl get nodes
```

内部资源

创建本地集群时，Amazon EKS 会自动在 kube-system 命名空间中安装以下附加组件的自行管理版本：coredns、kube-proxy 和 aws-node（VPC CNI）。您也可以选择通过 Amazon EKS 附加组件 API 安装这些附加组件的托管式版本。有关更多信息，请参阅适用于使用 EC2 实例存储配置的 AWS Outposts 上的本地集群的 Amazon EKS 附加组件。

Amazon EKS 还会在您的子网中创建跨账户弹性网络接口（ENI），用于集群 VPC 通信。请勿删除这些网络接口。如果跨账户 ENI 被删除或其 IP 地址更改，则必须手动更新每个节点和每个使用静态 IP 访问的管理员。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

运行本地集群（EC2 实例存储）

创建 VPC 和子网（EC2 实例存储）