하이브리드 노드 nodeadm 참조

하이브리드 노드 nodeadm 참조 (Hybrid nodes nodeadm reference)

Amazon EKS Hybrid Nodes CLI(nodeadm)는 하이브리드 노드 구성 요소의 설치, 구성, 등록, 제거를 단순화해요. 하이브리드 노드 부트스트랩을 자동화하기 위해 운영 체제 이미지에 nodeadm을 포함할 수 있어요. 자세한 내용은 하이브리드 노드용 운영 체제 준비하기를 참고하세요.

하이브리드 노드용 nodeadm 버전은 Amazon EC2 인스턴스를 Amazon EKS 클러스터의 노드로 부트스트래핑하는 데 사용되는 nodeadm 버전과 달라요. 적절한 nodeadm 버전에 대한 문서와 참조를 따르세요. 이 문서 페이지는 하이브리드 노드 nodeadm 버전을 위한 것이에요.

하이브리드 노드 nodeadm의 소스 코드는 https://github.com/aws/eks-hybrid GitHub 저장소에 게시돼 있어요.

중요

nodeadm은 root/sudo 권한이 있는 사용자로 실행해야 해요.

출처: 문서

본문

SSM 자격 증명 프로바이더에 필요한 nodeadm 버전

AWS Systems Manager(SSM)를 하이브리드 노드의 자격 증명 프로바이더로 사용한다면 새 설치와 업그레이드에 nodeadm 버전 1.0.19 이상을 사용해야 해요. 이전 버전의 nodeadm에는 오래된 SSM 서명 키가 포함되어 있으며 nodeadm install 및 nodeadm upgrade 중 다음 서명 확인 오류로 실패해요.

"msg":"Command failed","error":"failed to install ssm installer: validating ssm-setup-cli signature: Signature Verification Error: No matching signature"

이 오류를 해결하려면 nodeadm install 또는 nodeadm upgrade를 실행하기 전에 최신 버전의 nodeadm을 다운로드하세요.

`nodeadm` 다운로드

하이브리드 노드 버전의 nodeadm은 Amazon CloudFront가 앞단에 있는 Amazon S3에 호스팅돼요. 각 온프레미스 호스트에 nodeadm을 설치하려면 온프레미스 호스트에서 다음 명령을 실행할 수 있어요.

x86_64 호스트:

curl -OL 'https://hybrid-assets.eks.amazonaws.com/releases/latest/bin/linux/amd64/nodeadm'

ARM 호스트:

curl -OL 'https://hybrid-assets.eks.amazonaws.com/releases/latest/bin/linux/arm64/nodeadm'

각 호스트에서 다운로드한 바이너리에 실행 파일 권한을 추가해요.

chmod +x nodeadm

`nodeadm install`

nodeadm install 명령은 하이브리드 노드를 실행하고 Amazon EKS 클러스터에 조인하는 데 필요한 아티팩트와 종속성을 설치하는 데 사용돼요. nodeadm install 명령은 각 하이브리드 노드에서 개별적으로 실행하거나, 이미지 빌드 파이프라인 중에 실행해 운영 체제 이미지에 하이브리드 노드 종속성을 사전 설치할 수 있어요.

사용법

nodeadm install [KUBERNETES_VERSION] [flags]

위치 인수

(필수) KUBERNETES_VERSION – 설치할 EKS Kubernetes의 major.minor 버전. 예: 1.32

플래그

이름	필수	설명
`-p`, `--credential-provider`	TRUE	설치할 자격 증명 프로바이더. 지원 값은 `iam-ra` 및 `ssm`. 자세한 내용은 하이브리드 노드용 자격 증명 준비하기를 참고하세요.
`-s`, `--containerd-source`	FALSE	`containerd`의 소스. `nodeadm`은 OS 배포판, Docker 패키지에서 `containerd`를 설치하는 것과 `containerd` 설치 건너뛰기를 지원해요.
		`distro` – 기본값. `nodeadm`은 EKS Kubernetes 버전과 호환되는 노드 OS가 배포하는 최신 `containerd` 패키지를 설치해요. `distro`는 RHEL(Red Hat Enterprise Linux) 운영 체제에는 지원되는 값이 아니에요.
		`docker` – `nodeadm`은 EKS Kubernetes 버전과 호환되는 Docker가 빌드하고 배포하는 최신 `containerd` 패키지를 설치해요. `docker`는 Amazon Linux 2023에는 지원되는 값이 아니에요.
		`none` – `nodeadm`은 `containerd` 패키지를 설치하지 않아요. `nodeadm init`을 실행하기 전에 `containerd`를 수동으로 설치해야 해요.
`-r`, `--region`	FALSE	SSM에이전트 같은 아티팩트를 다운로드할 AWS 리전을 지정해요. 기본값은 `us-west-2`.
`-t`, `--timeout`	FALSE	최대 설치 명령 기간. 입력은 기간 형식을 따름. 예 `1h23m`. install 명령의 기본 다운로드 타임아웃은 20분으로 설정.
`-h`, `--help`	FALSE	사용 가능한 플래그, 하위 명령, 위치 값 매개변수가 있는 도움말 메시지를 표시.

예시

자격 증명 프로바이더로 AWS Systems Manager(SSM)를 사용해 Kubernetes 버전 1.32 설치:

nodeadm install 1.32 --credential-provider ssm

자격 증명 프로바이더로 AWS Systems Manager(SSM)를, containerd 소스로 Docker를 사용하고 다운로드 타임아웃 20분으로 Kubernetes 버전 1.32 설치:

nodeadm install 1.32 --credential-provider ssm --containerd-source docker --timeout 20m

자격 증명 프로바이더로 AWS IAM Roles Anywhere를 사용해 Kubernetes 버전 1.32 설치:

nodeadm install 1.32 --credential-provider iam-ra

`nodeadm config check`

nodeadm config check 명령은 제공된 노드 구성을 오류에 대해 검사해요. 이 명령은 하이브리드 노드 구성 파일의 정확성을 검증하고 확인하는 데 사용할 수 있어요.

사용법

nodeadm config check [flags]

플래그

이름	필수	설명
`-c`, `--config-source`	TRUE	nodeadm 구성의 소스. 하이브리드 노드의 경우 입력은 file scheme이 있는 URI를 따라야 해요.
`-h`, `--help`	FALSE	도움말 메시지 표시.

예시

nodeadm config check -c file://nodeConfig.yaml

`nodeadm init`

nodeadm init 명령은 하이브리드 노드를 시작하고 구성된 Amazon EKS 클러스터에 연결해요. nodeConfig.yaml 파일을 구성하는 방법은 SSM 하이브리드 활성화용 Node Config 또는 IAM Roles Anywhere용 Node Config를 참고하세요.

사용법

nodeadm init [flags]

플래그

이름	필수	설명
`-c`, `--config-source`	TRUE	`nodeadm` 구성의 소스. 하이브리드 노드의 경우 입력은 file scheme이 있는 URI를 따라야 해요.
`-s`, `--skip`	FALSE	건너뛸 `init` 단계(phase). 문제를 해결하는 데 도움이 되지 않는 한 단계를 건너뛰는 것은 권장되지 않아요.
		`install-validation`은 이전 install 명령이 성공적으로 실행되었는지 확인하는 것을 건너뜀.
		`cni-validation`은 노드에서 방화벽이 활성화된 경우 Cilium 또는 Calico CNI의 VXLAN 포트가 열려 있는지 확인하는 것을 건너뜀.
		`node-ip-validation`은 노드 IP가 원격 노드 네트워크의 CIDR 안에 속하는지 확인하는 것을 건너뜀.
`-h`, `--help`	FALSE	도움말 메시지 표시.

예시

nodeadm init -c file://nodeConfig.yaml

`nodeadm upgrade`

nodeadm upgrade 명령은 설치된 모든 아티팩트를 최신 버전으로 업그레이드하고, 업그레이드된 아티팩트를 구성하고 AWS의 EKS 클러스터에 조인하기 위해 노드를 부트스트랩해요. Upgrade는 노드에서 실행되는 워크로드에 중단을 일으키는 명령이에요. upgrade를 실행하기 전에 워크로드를 다른 노드로 이동하세요.

사용법

nodeadm upgrade [KUBERNETES_VERSION] [flags]

위치 인수

(필수) KUBERNETES_VERSION – 설치할 EKS Kubernetes의 major.minor 버전. 예: 1.32

플래그

이름	필수	설명
`-c`, `--config-source`	TRUE	`nodeadm` 구성의 소스. 하이브리드 노드의 경우 입력은 file scheme이 있는 URI를 따라야 해요.
`-t`, `--timeout`	FALSE	아티팩트 다운로드 타임아웃. 입력은 기간 형식을 따름. 예 1h23m. upgrade 명령의 기본 다운로드 타임아웃은 10분으로 설정.
`-s`, `--skip`	FALSE	건너뛸 upgrade 단계. 문제를 해결하는 데 도움이 되지 않는 한 단계를 건너뛰는 것은 권장되지 않아요.
		`pod-validation`은 데몬셋과 정적 Pod를 제외하고 노드에 실행 중인 Pod가 없는지 확인하는 것을 건너뜀.
		`node-validation`은 노드가 cordon되었는지 확인하는 것을 건너뜀.
		`init-validation`은 upgrade를 실행하기 전에 노드가 성공적으로 초기화되었는지 확인하는 것을 건너뜀.
		`containerd-major-version-upgrade`는 노드 업그레이드 중 containerd 메이저 버전 업그레이드를 방지함.
`-h`, `--help`	FALSE	도움말 메시지 표시.

예시

nodeadm upgrade 1.32 -c file://nodeConfig.yaml

nodeadm upgrade 1.32 -c file://nodeConfig.yaml --timeout 20m

`nodeadm uninstall`

nodeadm uninstall 명령은 nodeadm install 동안 nodeadm이 설치한 아티팩트(kubelet과 containerd 포함)를 중지하고 제거해요. uninstall 명령은 하이브리드 노드를 클러스터에서 drain하거나 삭제하지 않는다는 점에 유의하세요. drain 및 삭제 작업은 별도로 실행해야 해요. 자세한 내용은 하이브리드 노드 제거하기를 참고하세요. 기본적으로 nodeadm uninstall은 노드에 Pod가 남아 있으면 진행하지 않아요. 마찬가지로 nodeadm uninstall은 CNI 종속성이나 클러스터에서 실행하는 다른 Kubernetes 추가 기능의 종속성을 제거하지 않아요. 호스트에서 CNI 설치를 완전히 제거하려면 하이브리드 노드용 CNI 구성하기의 지침을 참고하세요. AWS SSM 하이브리드 활성화를 온프레미스 자격 증명 프로바이더로 사용한다면 nodeadm uninstall 명령은 호스트를 AWS SSM 관리형 인스턴스에서 등록 해제해요.

사용법

nodeadm uninstall [flags]

플래그

이름	필수	설명
`-s`, `--skip`	FALSE	건너뛸 uninstall 단계. 문제를 해결하는 데 도움이 되지 않는 한 단계를 건너뛰는 것은 권장되지 않아요.
		`pod-validation`은 데몬셋과 정적 Pod를 제외하고 노드에 실행 중인 Pod가 없는지 확인하는 것을 건너뜀.
		`node-validation`은 노드가 cordon되었는지 확인하는 것을 건너뜀.
		`init-validation`은 uninstall을 실행하기 전에 노드가 성공적으로 초기화되었는지 확인하는 것을 건너뜀.
`-h`, `--help`	FALSE	도움말 메시지 표시.
`-f`, `--force`	FALSE	Kubernetes와 CNI 구성 요소에서 남은 파일이 포함될 수 있는 추가 디렉터리를 강제로 삭제.
		경고 기본 Kubernetes 및 CNI 디렉터리(`/var/lib/cni`, `/etc/cni/net.d` 등)의 모든 내용이 삭제돼요. 이 위치에 자신의 데이터를 저장한다면 이 플래그를 사용하지 마세요.

nodeadm v1.0.9부터 ./nodeadm uninstall --skip node-validation,pod-validation --force 명령은 더 이상 /var/lib/kubelet 디렉터리를 삭제하지 않아요. 이는 Pod 볼륨과 마운트된 노드 파일 시스템을 포함할 수 있는 volume-subpath 디렉터리를 포함할 수 있기 때문이에요.

안전한 처리 팁

마운트된 경로를 삭제하면 실제 마운트된 노드 파일 시스템의 우발적 삭제로 이어질 수 있어요. /var/lib/kubelet 디렉터리를 수동으로 삭제하기 전에 모든 활성 마운트를 주의 깊게 검사하고 볼륨을 안전하게 언마운트해 데이터 손실을 방지하세요.

예시

nodeadm uninstall

nodeadm uninstall --skip node-validation,pod-validation

`nodeadm debug`

nodeadm debug 명령은 비정상적이거나 잘못 구성된 하이브리드 노드를 문제 해결하는 데 사용할 수 있어요. 다음 요구사항이 갖춰져 있는지 검증해요.

노드가 자격 증명을 얻기 위한 필수 AWS API에 네트워크 접근이 있는지,
노드가 구성된 Hybrid Nodes IAM 역할에 대한 AWS 자격 증명을 얻을 수 있는지,
노드가 EKS Kubernetes API 엔드포인트에 네트워크 접근이 있고 EKS Kubernetes API 엔드포인트 인증서가 유효한지,
노드가 EKS 클러스터로 인증할 수 있고, 클러스터에서 그 ID가 유효하며, 노드가 EKS 클러스터용으로 구성된 VPC를 통해 EKS 클러스터에 접근할 수 있는지.

오류가 발견되면 명령 출력이 문제 해결 단계를 제안해요. 일부 검증 단계는 하위 프로세스를 보여줘요. 실패하면 출력이 검증 오류 아래의 stderr 섹션에 표시돼요.

사용법

nodeadm debug [flags]

플래그

이름	필수	설명
`-c`, `--config-source`	TRUE	`nodeadm` 구성의 소스. 하이브리드 노드의 경우 입력은 file scheme이 있는 URI를 따라야 해요.
`--no-color`	FALSE	색상 출력 비활성화. 자동화에 유용.
`-h`, `--help`	FALSE	도움말 메시지 표시.

예시

nodeadm debug -c file://nodeConfig.yaml

Nodeadm 파일 위치

nodeadm install

nodeadm install을 실행할 때 다음 파일과 파일 위치가 구성돼요.

아티팩트	경로
IAM Roles Anywhere CLI	/usr/local/bin/aws_signing_helper
Kubelet 바이너리	/usr/bin/kubelet
Kubectl 바이너리	usr/local/bin/kubectl
ECR 자격 증명 프로바이더	/etc/eks/image-credential-provider/ecr-credential-provider
AWS IAM Authenticator	/usr/local/bin/aws-iam-authenticator
SSM Setup CLI	/opt/ssm/ssm-setup-cli
SSM Agent	Ubuntu - /snap/amazon-ssm-agent/current/amazon-ssm-agent / RHEL 및 AL2023 - /usr/bin/amazon-ssm-agent
Containerd	Ubuntu 및 AL2023 - /usr/bin/containerd / RHEL - /bin/containerd
Iptables	Ubuntu 및 AL2023 - /usr/sbin/iptables / RHEL - /sbin/iptables
CNI 플러그인	/opt/cni/bin
설치 아티팩트 추적기	/opt/nodeadm/tracker

nodeadm init

nodeadm init을 실행할 때 다음 파일과 파일 위치가 구성돼요.

이름	경로
Kubelet kubeconfig	/var/lib/kubelet/kubeconfig
Kubelet 구성	/etc/kubernetes/kubelet/config.json
Kubelet systemd 유닛	/etc/systemd/system/kubelet.service
이미지 자격 증명 프로바이더 구성	/etc/eks/image-credential-provider/config.json
Kubelet env 파일	/etc/eks/kubelet/environment
Kubelet 인증서	/etc/kubernetes/pki/ca.crt
Containerd 구성	/etc/containerd/config.toml
Containerd 커널 모듈 구성	/etc/modules-load.d/containerd.conf
AWS 구성 파일	/etc/aws/hybrid/config
AWS 자격 증명 파일 (자격 증명 파일 활성화 시)	/eks-hybrid/.aws/credentials
AWS signing helper 시스템 유닛	/etc/systemd/system/aws_signing_helper_update.service
Sysctl conf 파일	/etc/sysctl.d/99-nodeadm.conf
Ca-certificates	/etc/ssl/certs/ca-certificates.crt
Gpg 키 파일	/etc/apt/keyrings/docker.asc
Docker repo 소스 파일	/etc/apt/sources.list.d/docker.list

SSM 하이브리드 활성화용 Node Config

AWS SSM 하이브리드 활성화를 하이브리드 노드 자격 증명에 사용할 때의 nodeConfig.yaml 샘플은 다음과 같아요.

apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:             # Name of the EKS cluster
    region:           # AWS Region where the EKS cluster resides
  hybrid:
    ssm:
      activationCode: # SSM hybrid activation code
      activationId:   # SSM hybrid activation id

IAM Roles Anywhere용 Node Config

AWS IAM Roles Anywhere를 하이브리드 노드 자격 증명에 사용할 때의 nodeConfig.yaml 샘플은 다음과 같아요.

AWS IAM Roles Anywhere를 온프레미스 자격 증명 프로바이더로 사용할 때 nodeadm 구성에서 사용하는 nodeName은 Hybrid Nodes IAM 역할에 대해 범위를 지정한 권한과 일치해야 해요. 예를 들어 Hybrid Nodes IAM 역할의 권한이 역할 세션 이름이 호스트 인증서의 CN과 같은 경우에만 AWS IAM Roles Anywhere가 역할을 수임하도록 허용한다면, nodeadm 구성의 nodeName은 인증서의 CN과 같아야 해요. 사용하는 nodeName은 64자를 초과할 수 없어요. 자세한 내용은 하이브리드 노드용 자격 증명 준비하기를 참고하세요.

apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:              # Name of the EKS cluster
    region:            # AWS Region where the EKS cluster resides
  hybrid:
    iamRolesAnywhere:
      nodeName:        # Name of the node
      trustAnchorArn:  # ARN of the IAM Roles Anywhere trust anchor
      profileArn:      # ARN of the IAM Roles Anywhere profile
      roleArn:         # ARN of the Hybrid Nodes IAM role
      certificatePath: # Path to the certificate file to authenticate with the IAM Roles Anywhere trust anchor
      privateKeyPath:  # Path to the private key file for the certificate

kubelet 커스터마이징용 Node Config(선택 사항)

nodeadm 구성에서 kubelet 구성과 플래그를 전달할 수 있어요. 추가 노드 레이블 abc.example.com/test-label을 추가하고 kubelet 구성 shutdownGracePeriod를 30초로 설정하는 방법은 다음 예시를 참고하세요. kubelet 구성 옵션에 대한 자세한 내용은 Kubernetes 문서의 Kubelet Configuration (v1beta1) 참조를, kubelet 명령줄 플래그에 대한 자세한 내용은 Kubernetes 문서의 kubelet CLI 참조를 참고하세요.

apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:             # Name of the EKS cluster
    region:           # AWS Region where the EKS cluster resides
  kubelet:
    config:           # Map of kubelet config and values
       shutdownGracePeriod: 30s
    flags:            # List of kubelet flags
       - --node-labels=abc.example.com/test-label=true
  hybrid:
    ssm:
      activationCode: # SSM hybrid activation code
      activationId:   # SSM hybrid activation id

containerd 커스터마이징용 Node Config(선택 사항)

nodeadm 구성에서 커스텀 containerd 구성을 전달할 수 있어요. nodeadm의 containerd 구성은 인라인 TOML을 허용해요. containerd 콘텐츠 저장소에서 압축 해제된 이미지 레이어의 삭제를 비활성화하도록 containerd를 구성하는 예시는 아래를 참고하세요.

apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:             # Name of the EKS cluster
    region:           # AWS Region where the EKS cluster resides
  containerd:
    config: |         # Inline TOML containerd additional configuration
       [plugins."io.containerd.grpc.v1.cri".containerd]
       discard_unpacked_layers = false
  hybrid:
    ssm:
      activationCode: # SSM hybrid activation code
      activationId:   # SSM hybrid activation id

참고

Containerd 버전 1.x와 2.x는 다른 구성 형식을 사용해요. Containerd 1.x는 config version 2를, containerd 2.x는 config version 3을 사용해요. containerd 2.x는 config version 2와 하위 호환되지만, 최적의 성능을 위해 config version 3을 권장해요. containerd 버전은 containerd --version으로 확인하거나 nodeadm 설치 로그를 검토하세요. config 버전에 대한 자세한 내용은 https://containerd.io/releases/ 를 참고하세요.

또한 containerd 구성을 사용해 SELinux 지원을 활성화할 수 있어요. containerd에서 SELinux를 활성화하면 노드에 스케줄링된 Pod가 적절한 securityContext와 seLinuxOptions를 활성화했는지 확인하세요. 보안 컨텍스트 구성에 대한 자세한 내용은 Kubernetes 문서에서 확인할 수 있어요.

참고

Red Hat Enterprise Linux(RHEL) 8 및 RHEL 9는 호스트에서 SELinux를 기본적으로 활성화하고 strict로 설정해요. Amazon Linux 2023은 SELinux를 기본적으로 활성화하고 permissive 모드로 설정해요. 호스트에서 SELinux가 permissive 모드로 설정되면 containerd에서 활성화해도 요청을 차단하지 않지만, 호스트의 SELinux 구성에 따라 로그로 기록해요.

apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:             # Name of the EKS cluster
    region:           # AWS Region where the EKS cluster resides
  containerd:
    config: |         # Inline TOML containerd additional configuration
       [plugins."io.containerd.grpc.v1.cri"]
       enable_selinux = true
  hybrid:
    ssm:
      activationCode: # SSM hybrid activation code
      activationId:   # SSM hybrid activation id

더 알아보기 (Learn more)

공식 문서

하이브리드 노드 nodeadm 참조