EC2 인스턴스 스토어로 구성된 AWS Outposts에 Amazon EKS 로컬 클러스터 배포하기

이 주제에서는 EC2 인스턴스 스토어로 구성된 AWS Outpost에 로컬 Amazon EKS 클러스터를 배포하는 방법에 대한 지침을 제공합니다.

참고: Outpost가 EC2 인스턴스 스토어 대신 Amazon EBS로 구성된 경우 이 주제에서 설명하는 아키텍처는 Outpost에서 사용할 수 없어요. EBS로 구성된 Outposts는 기존 로컬 클러스터 구현을 계속 사용합니다. 자세한 내용은 AWS Outposts에 Amazon EKS 클러스터 배포를 참고하세요.

업데이트된 로컬 클러스터 아키텍처를 사용해 EBS 지원 Outpost에 로컬 클러스터를 만드는 데 관심이 있다면 AWS 계정 팀에 문의하세요.

중요: 로컬 클러스터는 Outpost 랙만 지원합니다. 단일 로컬 클러스터는 단일 논리적 Outpost를 구성하는 여러 물리적 Outpost 랙에 걸쳐 실행될 수 있어요. 단일 로컬 클러스터는 여러 논리적 Outposts에 걸쳐 실행될 수 없습니다.

출처: 문서

본문

Kubernetes 제어 플레인은 Outpost의 AWS 관리형 서비스 계정에서 실행됩니다. 제어 플레인 인스턴스에 액세스하거나, Amazon EC2 콘솔에서 보거나, 그 위에서 워크로드를 실행할 수 없어요.

제어 플레인은 외부 etcd 토폴로지의 6개 EC2 인스턴스(etcd 3개 + API 서버 3개)에서 실행됩니다. 용량 요구 사항은 EC2 인스턴스 스토어로 구성된 AWS Outposts의 Amazon EKS 로컬 클러스터용 인스턴스 유형 및 배치 선택을 참고하세요.

Kubernetes용 Amazon VPC CNI 플러그인, kube-proxy, CoreDNS는 로컬 클러스터에 자동으로 설치됩니다. 검증된 애드온의 전체 목록은 EC2 인스턴스 스토어로 구성된 AWS Outposts 로컬 클러스터용 Amazon EKS 애드온을 참고하세요.

Amazon EKS는 주기적으로 etcd를 백업합니다. etcd가 쿼럼을 잃으면 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에 AWS CLI 버전 2.35.3 이상이 설치되고 구성되어 있어야 합니다. 현재 버전을 확인하려면 aws --version을 사용하세요. 설치하거나 업그레이드하려면 AWS CLI 설치를 참고하세요.
Amazon EKS 클러스터를 생성하고 설명할 수 있는 권한이 있는 IAM 보안 주체(사용자 또는 역할). 자세한 내용은 Outpost에 로컬 Kubernetes 클러스터 생성 및 모든 클러스터 나열 또는 설명을 참고하세요.
다음 AWS 관리형 정책이 연결된 클러스터용 IAM 역할: AmazonEKSClusterPolicy 및 AmazonEKSServicePolicy. 역할 신뢰 정책은 eks.amazonaws.com 서비스 보안 주체가 역할을 수임할 수 있도록 허용해야 해요.

참고: 로컬 클러스터를 생성하면 클러스터를 생성한 IAM 보안 주체가 system:masters 권한의 관리자로 Kubernetes RBAC 권한 부여 테이블에 영구적으로 추가됩니다. 이 보안 주체를 절대 삭제하지 마세요.

로컬 클러스터 생성

AWS Management Console, 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 Management Console

Amazon EKS 콘솔을 엽니다.
클러스터 생성(Create cluster)을 선택합니다.
Kubernetes control plane location에서 AWS Outposts를 선택합니다.
다음을 구성합니다.
- Name — 클러스터 이름입니다.
- Kubernetes version — 사용할 버전.
- Cluster service role — AmazonEKSClusterPolicy 및 AmazonEKSServicePolicy가 있는 IAM 역할.
- Outpost ID — 배포할 논리적 Outpost.
- Control plane instance type — Kubernetes API 서버, 스케줄러, 컨트롤러 매니저용 인스턴스 유형.
- etcd instance type — etcd용 인스턴스 유형.
- Spread level — 제어 플레인 및 etcd 배치용 host 또는 rack.
네트워킹 구성: 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는 생성 전용(create-only) 속성입니다. 제어 플레인 인스턴스 유형, etcd 인스턴스 유형, 배치 또는 Outpost를 변경하려면 새 클러스터를 만들어야 합니다.

클러스터에 연결

kubectl이 클러스터와 통신하도록 구성합니다.

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

참고: 2.35.3 미만의 AWS CLI 버전으로 클러스터를 생성했다면 exec 인수에 --cluster-id(대신 --cluster-name)를 지정하도록 kubeconfig를 업데이트해야 합니다.

클러스터의 Kubernetes API 서버 엔드포인트는 Amazon Route 53에 호스팅됩니다. 엔드포인트는 Amazon EKS가 서브넷에 생성하는 교차 계정 탄력적 네트워크 인터페이스(ENI)의 프라이빗 IP 주소로 확인됩니다. 이러한 ENI는 클러스터 수명 주기 동안 변경되지 않는 고정 프라이빗 IP 주소를 가져요.

클러스터를 생성하면 Amazon EKS가 지정한 서브넷에 3개의 탄력적 네트워크 인터페이스를 생성합니다. 이러한 네트워크 인터페이스는 클러스터와 VPC 간의 통신을 가능하게 해요. 각 네트워크 인터페이스의 설명에는 Amazon EKS cluster-name 텍스트가 있습니다.

워커 노드 배포

자체 관리형 노드 그룹을 사용해 로컬 클러스터에 워커 노드를 배포합니다.

워커 노드 AWS CloudFormation 템플릿을 배포하거나 Outpost에 개별 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는 클러스터-VPC 통신을 위해 서브넷에 교차 계정 탄력적 네트워크 인터페이스(ENI)도 생성합니다. 이러한 네트워크 인터페이스를 삭제하지 마세요. 교차 계정 ENI가 삭제되거나 IP 주소가 변경되면 정적 IP 기반 액세스를 사용하는 모든 노드와 모든 관리자를 수동으로 업데이트해야 해요.

더 알아보기 (Learn more)

공식 문서

EC2 인스턴스 스토어로 구성된 AWS Outposts에 Amazon EKS 로컬 클러스터 배포하기