Bottlerocket으로 하이브리드 노드 연결

Bottlerocket으로 하이브리드 노드 연결

Bottlerocket을 실행하는 하이브리드 노드를 Amazon EKS 클러스터에 연결하는 방법을 설명합니다.

출처: 문서

본문

이 주제는 Bottlerocket을 실행하는 하이브리드 노드를 Amazon EKS 클러스터에 연결하는 방법을 설명합니다. Bottlerocket은 AWS가 후원하고 지원하는 오픈 소스 Linux 배포판입니다. Bottlerocket은 컨테이너 워크로드 호스팅을 목적으로 설계되었습니다. Bottlerocket을 사용하면 컨테이너 인프라의 업데이트를 자동화하여 컨테이너화된 배포의 가용성을 높이고 운영 비용을 줄일 수 있습니다. Bottlerocket은 컨테이너를 실행하는 데 필요한 필수 소프트웨어만 포함하므로 자원 사용을 개선하고 보안 위협을 줄이며 관리 오버헤드를 낮춥니다.

EKS Hybrid Nodes에서 지원되는 것은 Bottlerocket 버전 v1.37.0 이상의 VMware 변형뿐입니다. Bottlerocket의 VMware 변형은 Kubernetes 버전 v1.28 이상에서 사용할 수 있습니다. 이러한 변형의 OS 이미지에는 kubelet, containerd, aws-iam-authenticator 및 EKS Hybrid Nodes의 기타 소프트웨어 사전 요구 사항이 포함됩니다. Bottlerocket 부트스트랩 및 admin 컨테이너의 base64 인코딩 사용자 데이터를 포함하는 Bottlerocket 설정 파일로 이러한 구성 요소를 구성할 수 있습니다. 이러한 설정을 구성하면 Bottlerocket이 하이브리드 노드 자격 증명 공급자를 사용하여 하이브리드 노드를 클러스터에 인증할 수 있습니다. 하이브리드 노드가 클러스터에 조인한 후 Amazon EKS 콘솔과 kubectl 같은 Kubernetes 호환 도구에 Not Ready 상태로 표시됩니다. 이 페이지의 단계를 완료한 후 하이브리드 노드에서 애플리케이션을 실행할 준비를 하려면 하이브리드 노드용 CNI 구성을 진행하세요.

사전 요구 사항

하이브리드 노드를 Amazon EKS 클러스터에 연결하기 전에 사전 요구 사항 단계를 완료했는지 확인하세요.

  • 온프레미스 환경에서 Amazon EKS 클러스터를 호스팅하는 AWS 리전으로의 네트워크 연결이 있습니다. 자세한 내용은 하이브리드 노드용 네트워킹 준비를 참조하세요.
  • Hybrid Nodes IAM 역할을 만들고 온프레미스 자격 증명 공급자(AWS Systems Manager 하이브리드 활성화 또는 AWS IAM Roles Anywhere)를 설정했습니다. 자세한 내용은 하이브리드 노드용 자격 증명 준비를 참조하세요.
  • 하이브리드 노드가 활성화된 Amazon EKS 클러스터를 만들었습니다. 자세한 내용은 하이브리드 노드가 있는 Amazon EKS 클러스터 생성을 참조하세요.
  • Hybrid Nodes IAM 역할을 Kubernetes RBAC(Role-Based Access Control) 권한과 연결했습니다. 자세한 내용은 하이브리드 노드용 클러스터 접근 준비를 참조하세요.

Step 1: Bottlerocket 설정 TOML 파일 생성

하이브리드 노드용 Bottlerocket을 구성하려면 필요한 구성이 포함된 settings.toml 파일을 만들어야 합니다. TOML 파일의 내용은 사용하는 자격 증명 공급자(SSM 또는 IAM Roles Anywhere)에 따라 다릅니다. 이 파일은 Bottlerocket 인스턴스를 프로비저닝할 때 사용자 데이터로 전달됩니다.

참고

아래 제공된 TOML 파일은 Bottlerocket VMWare 머신을 EKS 클러스터의 노드로 초기화하는 데 필요한 최소 설정만 나타냅니다. Bottlerocket은 여러 다른 사용 사례를 다루는 광범위한 설정을 제공하므로, 하이브리드 노드 초기화를 넘어선 추가 구성 옵션은 사용 중인 Bottlerocket 버전에 대한 모든 문서화된 설정의 포괄적인 목록에 대해 Bottlerocket 문서를 참조하세요(예: Bottlerocket 1.51.x에서 사용할 수 있는 모든 설정은 여기를 참조).

SSM

자격 증명 공급자로 AWS Systems Manager를 사용한다면 다음 내용으로 settings.toml 파일을 만듭니다.

[settings.kubernetes]
cluster-name = "<cluster-name>"
api-server = "<api-server>"
cluster-certificate = "<cluster-ca-bundle>"
hostname-override = "<hostname>"
provider-id = "eks-hybrid://<region>/<account-id>/<cluster-name>/<node-name>"
authentication-mode = "aws"
cloud-provider = "aws"
server-tls-bootstrap = true

[settings.network]
hostname = "<hostname>"

[settings.aws]
region = "<region>"

[settings.kubernetes.credential-providers.ecr-credential-provider]
enabled = true
cache-duration = "12h"
image-patterns = [
    "*.dkr.ecr.*.amazonaws.com",
    "*.dkr.ecr.*.amazonaws.com.cn",
    "*.dkr.ecr.*.amazonaws.eu",
    "*.dkr.ecr-fips.*.amazonaws.com",
    "*.dkr.ecr-fips.*.amazonaws.eu",
    "public.ecr.aws"
]

[settings.kubernetes.node-labels]
"eks.amazonaws.com/compute-type" = "hybrid"
"eks.amazonaws.com/hybrid-credential-provider" = "ssm"

[settings.host-containers.admin]
enabled = true
user-data = "<base64-admin-user-data>"

[settings.bootstrap-containers.eks-hybrid-setup]
mode = "always"
user-data = "<base64-bootstrap-user-data>"

[settings.host-containers.control]
enabled = true

자리 표시자를 다음 값으로 바꾸세요.

  • <cluster-name>: Amazon EKS 클러스터의 이름.
  • <api-server>: 클러스터의 API 서버 엔드포인트.
  • <cluster-ca-bundle>: 클러스터의 base64 인코딩 CA 번들.
  • <region>: 클러스터를 호스팅하는 AWS 리전(예: "us-east-1").
  • <hostname>: Bottlerocket 인스턴스의 호스트 이름으로, 노드 이름으로도 구성됩니다. 선택할 수 있는 고유한 값이면 되지만 Kubernetes 객체 명명 규칙을 따라야 합니다. 또한 사용하는 호스트 이름은 64자를 초과할 수 없습니다. 참고: SSM 공급자를 사용할 때 인스턴스가 SSM에 등록된 후 이 호스트 이름과 노드 이름은 관리 인스턴스 ID(예: mi-* ID)로 대체됩니다.
  • <base64-admin-user-data>: Bottlerocket admin 컨테이너 구성의 base64 인코딩 내용. admin 컨테이너를 활성화하면 SSH로 Bottlerocket 인스턴스에 연결하여 시스템 탐색 및 디버깅을 할 수 있습니다. 필수 설정은 아니지만 문제 해결을 쉽게 하기 위해 활성화할 것을 권장합니다. admin 컨테이너 인증에 대한 자세한 내용은 Bottlerocket admin container 문서를 참조하세요. admin 컨테이너는 다음과 같이 JSON 형식으로 SSH 사용자와 키를 입력받습니다.
{
  "user": "<ssh-user>",
  "ssh": {
    "authorized-keys": [
      "<ssh-public-key>"
    ]
  }
}
  • <base64-bootstrap-user-data>: Bottlerocket 부트스트랩 컨테이너 구성의 base64 인코딩 내용. 구성에 대한 자세한 내용은 Bottlerocket bootstrap container 문서를 참조하세요. 부트스트랩 컨테이너는 인스턴스를 AWS SSM Managed Instance로 등록하고 Amazon EKS 클러스터의 Kubernetes 노드로 조인하는 역할을 합니다. 부트스트랩 컨테이너에 전달되는 사용자 데이터는 이전에 만든 SSM 하이브리드 활성화 코드와 ID를 입력으로 받는 명령 호출의 형태를 취합니다.
eks-hybrid-ssm-setup --activation-id=<activation-id> --activation-code=<activation-code> --region=<region>

IAM Roles Anywhere

자격 증명 공급자로 AWS IAM Roles Anywhere를 사용한다면 다음 내용으로 settings.toml 파일을 만듭니다.

[settings.kubernetes]
cluster-name = "<cluster-name>"
api-server = "<api-server>"
cluster-certificate = "<cluster-ca-bundle>"
hostname-override = "<hostname>"
provider-id = "eks-hybrid://<region>/<account-id>/<cluster-name>/<node-name>"
authentication-mode = "aws"
cloud-provider = "aws"
server-tls-bootstrap = true

[settings.network]
hostname = "<hostname>"

[settings.aws]
region = "<region>"
config = "<base64-aws-config>"

[settings.kubernetes.credential-providers.ecr-credential-provider]
enabled = true
cache-duration = "12h"
image-patterns = [
    "*.dkr.ecr.*.amazonaws.com",
    "*.dkr.ecr.*.amazonaws.com.cn",
    "*.dkr.ecr.*.amazonaws.eu",
    "*.dkr.ecr-fips.*.amazonaws.com",
    "*.dkr.ecr-fips.*.amazonaws.eu",
    "public.ecr.aws"
]

[settings.kubernetes.node-labels]
"eks.amazonaws.com/compute-type" = "hybrid"
"eks.amazonaws.com/hybrid-credential-provider" = "iam-ra"

[settings.host-containers.admin]
enabled = true
user-data = "<base64-admin-user-data>"

[settings.bootstrap-containers.eks-hybrid-setup]
mode = "always"
user-data = "<base64-bootstrap-user-data>"

자리 표시자를 다음 값으로 바꾸세요.

  • <cluster-name>: Amazon EKS 클러스터의 이름.
  • <api-server>: 클러스터의 API 서버 엔드포인트.
  • <cluster-ca-bundle>: 클러스터의 base64 인코딩 CA 번들.
  • <region>: 클러스터를 호스팅하는 AWS 리전(예: "us-east-1").
  • <hostname>: Bottlerocket 인스턴스의 호스트 이름으로, 노드 이름으로도 구성됩니다. 선택할 수 있는 고유한 값이면 되지만 Kubernetes 객체 명명 규칙을 따라야 합니다. 또한 사용하는 호스트 이름은 64자를 초과할 수 없습니다. 참고: IAM-RA 공급자를 사용할 때 "sts:RoleSessionName": "${aws:PrincipalTag/x509Subject/CN}" 자원 조건으로 Hybrid Nodes IAM 역할의 신뢰 정책을 구성했다면 노드 이름은 호스트의 인증서 CN과 일치해야 합니다.
  • <base64-aws-config>: AWS 구성 파일의 base64 인코딩 내용. 파일 내용은 다음과 같아야 합니다.
[default]
credential_process = aws_signing_helper credential-process --certificate /root/.aws/node.crt --private-key /root/.aws/node.key --profile-arn <profile-arn> --role-arn <role-arn> --trust-anchor-arn <trust-anchor-arn> --role-session-name <role-session-name>
  • <base64-admin-user-data>: Bottlerocket admin 컨테이너 구성의 base64 인코딩 내용. admin 컨테이너를 활성화하면 SSH로 Bottlerocket 인스턴스에 연결하여 시스템 탐색 및 디버깅을 할 수 있습니다. 필수 설정은 아니지만 문제 해결을 쉽게 하기 위해 활성화할 것을 권장합니다. admin 컨테이너 인증에 대한 자세한 내용은 Bottlerocket admin container 문서를 참조하세요. admin 컨테이너는 다음과 같이 JSON 형식으로 SSH 사용자와 키를 입력받습니다.
{
  "user": "<ssh-user>",
  "ssh": {
    "authorized-keys": [
      "<ssh-public-key>"
    ]
  }
}
  • <base64-bootstrap-user-data>: Bottlerocket 부트스트랩 컨테이너 구성의 base64 인코딩 내용. 구성에 대한 자세한 내용은 Bottlerocket bootstrap container 문서를 참조하세요. 부트스트랩 컨테이너는 인스턴스에 IAM Roles Anywhere 호스트 인증서와 인증서 개인 키 파일을 만드는 역할을 합니다. 그런 다음 이 파일들을 aws_signing_helper가 사용하여 Amazon EKS 클러스터 인증용 임시 자격 증명을 얻습니다. 부트스트랩 컨테이너에 전달되는 사용자 데이터는 이전에 만든 인증서와 개인 키의 내용을 입력으로 받는 명령 호출의 형태를 취합니다.
eks-hybrid-iam-ra-setup --certificate=<certificate> --key=<private-key>

Step 2: 사용자 데이터로 Bottlerocket vSphere VM 프로비저닝

TOML 파일을 만든 후 vSphere VM 생성 중 사용자 데이터로 전달합니다. 사용자 데이터는 VM이 처음 전원이 켜지기 전에 구성되어야 한다는 점을 기억하세요. 따라서 인스턴스를 만들 때 제공하거나, VM을 미리 만드려면 VM이 사용자 데이터를 구성할 때까지 poweredOff 상태여야 합니다. 예를 들어 govc CLI를 사용한다면:

VM을 처음 만들 때:

govc vm.create \
  -on=true \
  -c=2 \
  -m=4096 \
  -net.adapter=<adapter> \
  -net=<network> \
  -e guestinfo.userdata.encoding="base64" \
  -e guestinfo.userdata="$(base64 -w0 settings.toml)" \
  -template=<bottlerocket-template> \
  <vm-name>

기존 VM의 사용자 데이터 업데이트:

govc vm.create \
    -on=false \
    -c=2 \
    -m=4096 \
    -net.adapter=<adapter> \
    -net=<network> \
    -template=<bottlerocket-template> \
    <vm-name>

govc vm.change \
    -vm <vm-name> \
    -e guestinfo.userdata="$(base64 -w0 settings.toml)" \
    -e guestinfo.userdata.encoding="base64"

govc vm.power -on

위 섹션에서 -e guestinfo.userdata.encoding="base64" 옵션은 사용자 데이터가 base64 인코딩되었음을 지정합니다. -e guestinfo.userdata 옵션은 settings.toml 파일의 base64 인코딩 내용을 Bottlerocket 인스턴스에 사용자 데이터로 전달합니다. Bottlerocket OVA 템플릿과 네트워킹 세부 정보 등 자리 표시자를 특정 값으로 바꾸세요.

Step 3: 하이브리드 노드 연결 확인

Bottlerocket 인스턴스가 시작된 후 Amazon EKS 클러스터에 조인을 시도합니다. 클러스터의 Compute 탭으로 이동하거나 다음 명령을 실행하여 연결을 확인할 수 있습니다.

kubectl get nodes

중요

노드는 Not Ready 상태가 되며, 이는 예상된 동작이고 하이브리드 노드에서 실행되는 CNI가 없기 때문입니다. 노드가 클러스터에 조인하지 않았다면 하이브리드 노드 문제 해결을 참조하세요.

Step 4: 하이브리드 노드용 CNI 구성

하이브리드 노드가 애플리케이션을 실행할 준비를 하려면 하이브리드 노드용 CNI 구성의 단계를 계속하세요.

더 알아보기 (Learn more)