**이 페이지 개선에 도움 주기**
이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다.
# 하이브리드 노드 `nodeadm` 참조
Amazon EKS Hybrid Nodes CLI(`nodeadm`)는 하이브리드 노드 구성 요소의 설치, 구성, 등록 및 제거를 간소화합니다. 운영 체제 이미지에 `nodeadm`을 포함하여 하이브리드 노드 부트스트랩을 자동화할 수 있습니다. 자세한 내용은 [하이브리드 노드용 운영 체제 준비](hybrid-nodes-os.md) 섹션을 참조하세요.
하이브리드 노드용 `nodeadm` 버전은 Amazon EC2 인스턴스를 Amazon EKS 클러스터의 노드로 부트스트랩하는 데 사용되는 `nodeadm` 버전과 다릅니다. 적절한 `nodeadm` 버전의 설명서 및 참조를 따릅니다. 이 설명서 페이지는 하이브리드 노드 `nodeadm` 버전용입니다.
하이브리드 노드 `nodeadm`의 소스 코드는 https://github.com/aws/eks-hybrid GitHub 리포지토리에 게시됩니다.
**중요**
root/sudo 권한이 있는 사용자와 함께 `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`)
**Flags**
| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `-p`,
`--credential-provider` | TRUE | 설치할 자격 증명 공급자입니다. 지원되는 값은 `iam-ra` 및 `ssm`입니다. 자세한 정보는 [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md)을 참조하세요. |
| `-s`,
`--containerd-source` | FALSE | `containerd` 소스입니다. `nodeadm`은 OS distro, Docker 패키지에서 `containerd` 설치 또는 `containerd` 설치 건너뛰기를 지원합니다.
**값**
`distro` - 기본값입니다. `nodeadm`은 노드 OS(EKS Kubernetes 버전과 호환됨)에서 배포한 `containerd` 패키지를 설치합니다. `distro`는 Red Hat Enterprise Linux(RHEL) 운영 체제에서 지원되지 않는 값입니다.
`docker` - `nodeadm`은 Docker에서 빌드 및 배포한 최신 `containerd` 패키지를 설치합니다. `docker`는 Amazon Linux 2023에서 지원되지 않는 값입니다.
`none`-`nodeadm`은 `containerd` 패키지를 설치하지 않습니다. `nodeadm init`를 실행하기 전에 `containerd`를 수동으로 설치해야 합니다. |
| `-r`,
`--region` | FALSE | SSM 에이전트와 같은 아티팩트를 다운로드할 AWS 리전을 지정합니다. 기본값은 `us-west-2`입니다. |
| `-t`,
`--timeout` | FALSE | 최대 설치 명령 기간입니다. 입력은 기간 형식을 따릅니다. 예: `1h23m`. 설치 명령의 기본 다운로드 제한 시간은 20분으로 설정됩니다. |
| `-h`, `--help` | FALSE | 사용 가능한 플래그, 하위 명령, 위치 값 파라미터가 포함된 도움말 메시지가 표시됩니다. |
**예제**
AWS Systems Manager(SSM)를 자격 증명 공급자로 사용하여 Kubernetes 버전 `1.32` 설치
```
nodeadm install 1.32 --credential-provider ssm
```
AWS Systems Manager(SSM)를 자격 증명 공급자로, Docker를 Containered 소스로 사용하여 Kubernetes 버전 `1.32`을 설치하고 다운로드 제한 시간은 20분입니다.
```
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]
```
**Flags**
| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `-c`,
`--config-source` | TRUE | nodeadm 구성 소스입니다. 하이브리드 노드의 경우 입력은 파일 체계의 URI를 따라야 합니다. |
| `-h`, `--help` | FALSE | 사용 가능한 플래그, 하위 명령, 위치 값 파라미터가 포함된 도움말 메시지가 표시됩니다. |
**예제**
```
nodeadm config check -c file://nodeConfig.yaml
```
## `nodeadm init`
`nodeadm init` 명령은 하이브리드 노드를 시작하고 구성된 Amazon EKS 클러스터와 연결합니다. `nodeConfig.yaml` 파일을 구성하는 방법에 대한 자세한 내용은 [SSM 하이브리드 활성화를 위한 노드 구성](#hybrid-nodes-node-config-ssm) 또는 [IAM Roles Anywhere를 위한 노드 구성](#hybrid-nodes-node-config-iamra) 섹션을 참조하세요.
**사용량**
```
nodeadm init [flags]
```
**Flags**
| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `-c`,
`--config-source` | TRUE | `nodeadm` 구성 소스입니다. 하이브리드 노드의 경우 입력은 파일 체계의 URI를 따라야 합니다. |
| `-s`,
`--skip` | FALSE | 건너뛸 `init`의 단계입니다. 문제 해결에 도움이 되지 않는 한 단계를 건너뛰는 것은 권장되지 않습니다.
**값**
`install-validation`은 진행 중인 설치 명령이 성공적으로 실행되었는지 확인하는 단계를 건너뜁니다.
`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 클러스터에 조인합니다. 업그레이드는 노드에서 실행되는 워크로드에 대한 중단 명령입니다. 업그레이드를 실행하기 전에 워크로드를 다른 노드로 이동하세요.
**사용량**
```
nodeadm upgrade [KUBERNETES_VERSION] [flags]
```
**위치 인수**
(필수) `KUBERNETES_VERSION` 설치할 EKS Kubernetes의 major.minor 버전(예: `1.32`)
**Flags**
| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `-c`,
`--config-source` | TRUE | `nodeadm` 구성 소스입니다. 하이브리드 노드의 경우 입력은 파일 체계의 URI를 따라야 합니다. |
| `-t`,
`--timeout` | FALSE | 아티팩트 다운로드 제한 시간입니다. 입력은 기간 형식을 따릅니다. 예를 들면 1h23m입니다. 업그레이드 명령의 기본 다운로드 제한 시간은 10분으로 설정됩니다. |
| `-s`,
`--skip` | FALSE | 건너뛸 업그레이드 단계입니다. 문제 해결에 도움이 되지 않는 한 단계를 건너뛰는 것은 권장되지 않습니다.
**값**
`pod-validation`은 대몬 세트 및 정적 포드를 제외하고 노드에서 모든 포드가 실행 중인지 확인하는 단계를 건너뜁니다.
`node-validation`은 노드가 차단되었는지 확인하는 단계를 건너뜁니다.
`init-validation`은 업그레이드를 실행하기 전에 노드가 성공적으로 초기화되었는지 확인하는 단계를 건너뜁니다.
`containerd-major-version-upgrade`는 노드 업그레이드 중에 Containered 메이저 버전 업그레이드를 방지합니다. |
| `-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` 명령은 kubelet 및 Containered를 포함하여 `nodeadm install` 중에 아티팩트 `nodeadm` 설치를 중지하고 제거합니다. 제거 명령은 클러스터에서 하이브리드 노드를 드레이닝하거나 삭제하지 않습니다. 드레이닝 및 삭제 작업을 별도로 실행해야 합니다. 자세한 내용은 [하이브리드 노드 제거](hybrid-nodes-remove.md) 섹션을 참조하세요. 노드에 포드가 남아 있는 경우 기본적으로 `nodeadm uninstall`이 진행되지 않습니다. 마찬가지로 `nodeadm uninstall`은 CNI 종속성 또는 클러스터에서 실행하는 다른 Kubernetes 추가 기능의 종속성을 제거하지 않습니다. 호스트에서 CNI 설치를 완전히 제거하려면 [하이브리드 노드에 대한 CNI 구성](hybrid-nodes-cni.md)의 지침을 참조하세요. 온프레미스 자격 증명 공급자로 AWS SSM 하이브리드 활성화를 사용하는 경우 `nodeadm uninstall` 명령은 호스트를 AWS SSM 관리형 인스턴스로 등록 취소합니다.
**사용량**
```
nodeadm uninstall [flags]
```
**Flags**
| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `-s`,
`--skip` | FALSE | 건너뛸 제거 단계입니다. 문제 해결에 도움이 되지 않는 한 단계를 건너뛰는 것은 권장되지 않습니다.
**값**
`pod-validation`은 대몬 세트 및 정적 포드를 제외하고 노드에서 모든 포드가 실행 중인지 확인하는 단계를 건너뜁니다.
`node-validation`은 노드가 차단되었는지 확인하는 단계를 건너뜁니다.
`init-validation`은 제거를 실행하기 전에 노드가 성공적으로 초기화되었는지 확인하는 단계를 건너뜁니다. |
| `-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` 디렉터리가 삭제되지 않습니다. 탑재된 노드 파일 시스템을 포함하는 포드 볼륨 및 볼륨 하위 경로 디렉터리가 포함될 수 있기 때문입니다.
**안전한 처리 관련 팁**
- 탑재된 경로를 삭제하면 실제 탑재된 노드 파일 시스템이 실수로 삭제될 수 있습니다. `/var/lib/kubelet` 디렉터리를 수동으로 삭제하기 전에 모든 활성 탑재를 주의하여 검사하고 볼륨 탑재를 안전하게 해제하여 데이터 손실을 방지합니다. |
**예제**
```
nodeadm uninstall
```
```
nodeadm uninstall --skip node-validation,pod-validation
```
## `nodeadm debug`
`nodeadm debug` 명령을 사용하여 비정상이거나 잘못 구성된 하이브리드 노드 문제를 해결할 수 있습니다. 다음 요구 사항이 있는지 확인합니다.
+ 노드는 자격 증명을 얻는 데 필요한 AWS API에 대한 네트워크 액세스 권한이 있습니다.
+ 노드는 구성된 하이브리드 노드 IAM 역할에 대한 AWS 자격 증명을 가져올 수 있습니다.
+ 노드에는 EKS Kubernetes API 엔드포인트에 대한 네트워크 액세스 권한과 EKS Kubernetes API 엔드포인트 인증서의 유효성이 있습니다.
+ 노드는 EKS 클러스터로 인증할 수 있고, 클러스터의 자격 증명이 유효하며, 노드가 EKS 클러스터에 대해 구성된 VPC를 통해 EKS 클러스터에 액세스할 수 있는지 확인할 수 있습니다.
오류가 발견되면 명령의 출력에서 문제 해결 단계를 제안합니다. 특정 검증 단계는 하위 프로세스를 보여줍니다. 이러한 오류가 발생하면 출력이 검증 오류 아래의 stderr 섹션에 표시됩니다.
**사용량**
```
nodeadm debug [flags]
```
**Flags**
| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `-c`, `--config-source` | TRUE | `nodeadm` 구성 소스입니다. 하이브리드 노드의 경우 입력은 파일 체계의 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 인증자 | /usr/local/bin/aws-iam-authenticator |
| SSM 설정 CLI | /opt/ssm/ssm-setup-cli |
| SSM 에이전트 | Ubuntu - /snap/amazon-ssm-agent/current/amazon-ssm-agent
RHEL 및 AL2023 - /usr/bin/amazon-ssm-agent |
| Containered | 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 |
| Containered 구성 | /etc/containerd/config.toml |
| Containered 커널 모듈 구성 | /etc/modules-load.d/containerd.conf |
| AWS Config 파일 | /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 리포지토리 소스 파일 | /etc/apt/sources.list.d/docker.list |
## SSM 하이브리드 활성화를 위한 노드 구성
다음은 하이브리드 노드 자격 증명에 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를 위한 노드 구성
다음은 하이브리드 노드 자격 증명을 위한 AWS IAM Roles Anywhere의 샘플 `nodeConfig.yaml`입니다.
AWS IAM Roles Anywhere를 온프레미스 자격 증명 공급자로 사용하는 경우 `nodeadm` 구성에서 사용하는 `nodeName`은 하이브리드 노드 IAM 역할에 대해 범위가 지정된 권한과 일치해야 합니다. 예를 들어 하이브리드 노드 IAM 역할에 대한 권한이 역할 세션 이름이 호스트 인증서의 CN과 같을 때만 AWS IAM Roles Anywhere가 역할을 수임하도록 허용하는 경우 `nodeadm` 구성의 `nodeName`은 인증서의 CN과 동일해야 합니다. 사용하는 `nodeName`은 64자를 초과할 수 없습니다. 자세한 내용은 [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md) 섹션을 참조하세요.
```
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 사용자 지정을 위한 노드 구성(선택 사항)
`nodeadm` 구성에서 kubelet 구성 및 플래그를 전달할 수 있습니다. `shutdownGracePeriod`를 30초로 설정하기 위해 노드 레이블 `abc.amazonaws.com/test-label` 및 구성을 추가하는 방법은 아래 예제를 참조하세요.
```
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.company.com/test-label=true
hybrid:
ssm:
activationCode: # SSM hybrid activation code
activationId: # SSM hybrid activation id
```
## Containered 사용자 지정을 위한 노드 구성(선택 사항)
`nodeadm` 구성에서 사용자 지정 Containered 구성을 전달할 수 있습니다. `nodeadm`에 대한 Containered 구성은 인라인 TOML을 허용합니다. Containered 콘텐츠 스토어에서 압축되지 않은 이미지 계층의 삭제를 비활성화하도록 Containered를 구성하는 방법은 아래 예제를 참조하세요.
```
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
```
**참고**
Containered 버전 1.x 및 2.x는 여러 구성 형식을 사용합니다. Containerd 1.x는 구성 버전 2를 사용하는 반면, Containered 2.x는 구성 버전 3을 사용합니다. Containered 2.x는 구성 버전 2와 이전 버전과의 호환성을 유지하지만 최적의 성능을 위해 구성 버전 3이 권장됩니다. `containerd --version`을 사용하여 Containered 버전을 확인하거나 `nodeadm` 설치 로그를 검토합니다. 구성 버전 관리에 대한 자세한 내용은 https://containerd.io/releases/를 참조하세요.
Containered 구성을 사용하여 SELinux 지원을 활성화할 수도 있습니다. Containered에서 SELinux를 활성화한 경우 노드에 예약된 포드에 적절한 securityContext 및 seLinuxOptions가 활성화되어 있는지 확인합니다. 보안 컨텍스트 구성에 대한 자세한 내용은 [Kubernetes 설명서](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/)에서 확인할 수 있습니다.
**참고**
Red Hat Enterprise Linux(RHEL) 8 및 RHEL 9는 SELinux가 기본적으로 활성화하고 호스트에서 엄격으로 설정됩니다. Amazon Linux 2023는 SELinux가 기본적으로 활성화되고 허용 모드로 설정됩니다. SELinux가 호스트에서 허용 모드로 설정된 경우 Containered에서 활성화하면 요청이 차단되지 않고 호스트의 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
```