**帮助改进此页面** 

要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。

# 混合节点 `nodeadm` 参考
<a name="hybrid-nodes-nodeadm"></a>

Amazon EKS 混合节点功能 CLI (`nodeadm`) 简化了混合节点组件的安装、配置、注册和卸载。您可以将 `nodeadm` 包含在操作系统映像中以自动执行混合节点引导过程，有关更多信息，请参阅[为混合节点准备操作系统](hybrid-nodes-os.md)。

用于混合节点的 `nodeadm` 版本，与用于引导 Amazon EC2 实例以作为 Amazon EKS 集群中节点的 `nodeadm` 版本不同。请按照相应 `nodeadm` 版本的文档和参考进行操作。此文档页面适用于混合节点 `nodeadm` 版本。

https://github.com/aws/eks-hybrid GitHub 存储库发布了混合节点 `nodeadm` 的源代码。

**重要**  
您必须使用具有 root/sudo 权限的用户运行 `nodeadm`。

## 下载 `nodeadm`
<a name="_download_nodeadm"></a>

`nodeadm` 的混合节点版本在 Amazon S3 中托管，由 Amazon CloudFront 分发。要在每台本地主机上安装 `nodeadm`，您可以在本地主机上运行以下命令。

 **x86\$164 主机：**

```
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`
<a name="_nodeadm_install"></a>

`nodeadm install` 命令用于安装运行和将混合节点加入 Amazon EKS 集群所需的构件和依赖项。`nodeadm install` 命令可以在每个混合节点上单独运行，也可以在映像生成管道期间运行，以便在操作系统映像中预装混合节点依赖项。

 **用法** 

```
nodeadm install [KUBERNETES_VERSION] [flags]
```

 **定位参数** 

（必需）`KUBERNETES_VERSION` 要安装的 EKS Kubernetes 的主要.次要版本，例如 `1.32` 

 **Flags** 


| 名称 | 必需 | 说明 | 
| --- | --- | --- | 
|   `-p`,  `--credential-provider`   |  TRUE  |  要安装的凭证提供者。支持的值为 `iam-ra` 和 `ssm`。请参阅[准备用于混合节点的凭证](hybrid-nodes-creds.md)了解更多信息。  | 
|   `-s`,  `--containerd-source`   |  FALSE  |  `containerd` 的来源。`nodeadm` 支持从操作系统发行版、Docker 软件包安装 `containerd` 以及跳过 `containerd` 安装。  **值**   `distro`：此为默认值。`nodeadm` 会安装由节点操作系统分发的、与 EKS Kubernetes 版本兼容的最新 `containerd` 软件包。`distro` 并非 Red Hat Enterprise Linux（RHEL）操作系统的有效值。  `docker`：`nodeadm` 会安装由 Docker 编译并分发的、与 EKS Kubernetes 版本兼容的最新 `containerd` 软件包。`docker` 并非 Amazon Linux 2023 的有效值。  `none`：`nodeadm` 不会安装 `containerd` 软件包。您必须首先手动安装 `containerd`，然后再运行 `nodeadm init`。  | 
|   `-r`,  `--region`   |  FALSE  |  指定用于下载 SSM Agent 等构件的 Amazon 区域。默认值为 `us-west-2`。  | 
|   `-t`,  `--timeout`   |  FALSE  |  安装命令的最大持续时间。输入遵循持续时间格式。例如 `1h23m`。安装命令的默认下载超时设置为 20 分钟。  | 
|   `-h`, `--help`   |  FALSE  |  显示带有可用标志、子命令和位置值参数的帮助消息。  | 

 **示例** 

安装 Kubernetes 版本 `1.32`，并将 Amazon Systems Manager（SSM）作为凭证提供者

```
nodeadm install 1.32 --credential-provider ssm
```

安装 Kubernetes 版本 `1.32`，并将 Amazon Systems Manager（SSM）作为凭证提供者，将 Docker 作为 containerd 源，下载超时设置为 20 分钟。

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

安装 Kubernetes 版本 `1.32`，并将 Amazon IAM Roles Anywhere 作为凭证提供者

```
nodeadm install 1.32 --credential-provider iam-ra
```

## `nodeadm config check`
<a name="_nodeadm_config_check"></a>

`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`
<a name="_nodeadm_init"></a>

`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 端口是否已打开  如果节点 IP 在远程节点网络的 CIDR 范围内，`node-ip-validation` 将会跳过检查。  | 
|   `-h`, `--help`   |  FALSE  |  显示带有可用标志、子命令和位置值参数的帮助消息。  | 

 **示例** 

```
nodeadm init -c file://nodeConfig.yaml
```

## `nodeadm upgrade`
<a name="_nodeadm_upgrade"></a>

`nodeadm upgrade` 命令会将所有已安装的构件升级到最新版本，启动节点以配置升级后的构件并加入 Amazon 上的 EKS 集群。对于在节点上运行的工作负载，升级是一个中断性命令。在运行升级之前，请将您的工作负载转移至其他节点。

 **用法** 

```
nodeadm upgrade [KUBERNETES_VERSION] [flags]
```

 **定位参数** 

（必需）`KUBERNETES_VERSION` 要安装的 EKS Kubernetes 的主要.次要版本，例如 `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` 可避免在节点升级期间对 containerd 执行大版本升级操作。  | 
|   `-h`, `--help`   |  FALSE  |  显示带有可用标志、子命令和位置值参数的帮助消息。  | 

 **示例** 

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

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

## `nodeadm uninstall`
<a name="_nodeadm_uninstall"></a>

`nodeadm uninstall` 命令会停止并移除在 `nodeadm install` 期间安装的构件 `nodeadm`，包括 kubelet 和 containerd。请注意，卸载命令不会从集群中清空或删除混合节点。您必须分别运行清空和删除操作，有关更多信息，请参阅[移除混合节点](hybrid-nodes-remove.md)。默认情况下，如果节点上还有容器组，则 `nodeadm uninstall` 不会执行。同样，`nodeadm uninstall` 也不会移除 CNI 依赖项或您在集群上运行的其他 Kubernetes 附加组件的依赖项。要从主机上完全移除 CNI 安装，请参阅[为混合节点配置 CNI](hybrid-nodes-cni.md) 中的说明。如果将 Amazon SSM 混合激活作为本地凭证提供者，则 `nodeadm uninstall` 命令将从 Amazon SSM 托管式实例中注销您的主机。

 **用法** 

```
nodeadm uninstall [flags]
```

 **Flags** 


| 名称 | 必需 | 说明 | 
| --- | --- | --- | 
|   `-s`,  `--skip`   |  FALSE  |  要跳过的卸载阶段。除非有助于解决问题，否则不建议跳过任何阶段。  **值**   `pod-validation` 会跳过检查除进程守护程序集和静态容器组外，是否节点上的所有容器组都在运行。  `node-validation` 会跳过检查节点是否已被封锁。  `init-validation` 会跳过检查节点在运行卸载之前是否已成功初始化。  | 
|   `-h`,  `--help`   |  FALSE  |  显示带有可用标志、子命令和位置值参数的帮助消息。  | 
|   `-f`,  `--force`   |  FALSE  |  强制删除可能包含 Kubernetes 和 CNI 组件中剩余文件的其他目录。  **WARNING**  此操作将删除默认 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`
<a name="_nodeadm_debug"></a>

`nodeadm debug` 命令可用于对运行不正常或配置有错误的混合节点进行故障排除。此命令可以验证以下要求是否已经满足。
+ 该节点具有必需 Amazon API 的网络访问权限以获取凭证，
+ 该节点能够获取所配置混合节点 IAM 角色的 Amazon 凭证，
+ 该节点具有对 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 文件位置
<a name="_nodeadm_file_locations"></a>

### nodeadm 安装
<a name="_nodeadm_install_2"></a>

运行 `nodeadm install` 时，将配置以下文件和文件位置。


| Artifact | 路径 | 
| --- | --- | 
|  IAM Roles Anywhere CLI  |  /usr/local/bin/aws\$1signing\$1helper  | 
|  Kubelet 二进制包  |  /usr/bin/kubelet  | 
|  Kubectl 二进制包  |  usr/local/bin/kubectl  | 
|  ECR 凭证提供者  |  /etc/eks/image-credential-provider/ecr-credential-provider  | 
|   Amazon IAM 身份验证器  |  /usr/local/bin/aws-iam-authenticator  | 
|  SSM 安装 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
<a name="_nodeadm_init_2"></a>

运行 `nodeadm init` 时，将配置以下文件和文件位置。


| 名称 | 路径 | 
| --- | --- | 
|  Kubelet kubeconfig  |  /var/lib/kubelet/kubelet/kubecconfig  | 
|  Kubelet config  |  /etc/kubernetes/kubelet/config.json  | 
|  Kubelet systemd 单元  |  /etc/systemd/system/kubelet.service  | 
|  映像凭证提供者配置  |  /etc/eks/image-credential-provider/config.json  | 
|  Kubelet 环境文件  |  /etc/eks/kubelet/environment  | 
|  Kubelet 证书  |  /etc/kubernetes/pki/ca.crt  | 
|  Containerd 配置  |  /etc/containerd/config.toml  | 
|  Containerd 内核模块配置  |  /etc/modules-load.d/containerd.conf  | 
|   Amazon 配置文件  |  /etc/aws/hybrid/config  | 
|   Amazon 凭证文件（如果启用了凭证文件）  |  /eks-hybrid/.aws/credentials  | 
|   Amazon 签名助手系统单元  |  /etc/systemd/system/aws\$1signing\$1helper\$1update.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 混合激活的节点配置
<a name="hybrid-nodes-node-config-ssm"></a>

以下是将 Amazon SSM 混合激活作为混合节点凭证的示例 `nodeConfig.yaml`。

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

## IAM Roles Anywhere 的节点配置
<a name="hybrid-nodes-node-config-iamra"></a>

以下是将 Amazon IAM Roles Anywhere 作为混合节点凭证的示例 `nodeConfig.yaml`。

如果将 Amazon IAM Roles Anywhere 作为本地凭证提供者，您在 `nodeadm` 配置中使用的 `nodeName` 必须与您为混合节点 IAM 角色设定的权限范围一致。例如，假设混合节点 IAM 角色的权限仅允许 Amazon IAM Roles Anywhere 在角色会话名称等于主机证书的 CN 时代入该角色，则 `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:            # Amazon 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 的节点配置（可选）
<a name="hybrid-nodes-nodeadm-kubelet"></a>

您可以在 `nodeadm` 配置中传递 kubelet 配置和标志。有关如何添加额外节点标签 `abc.amazonaws.com/test-label` 和配置，以将 `shutdownGracePeriod` 设置为 30 秒的信息，请参阅以下示例。

```
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:             # Name of the EKS cluster
    region:           # Amazon 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
```

## 自定义 containerd 的节点配置（可选）
<a name="_node_config_for_customizing_containerd_optional"></a>

您可以在 `nodeadm` 配置中传递自定义 containerd 配置。`nodeadm` containerd 配置接受内联 TOML。要了解如何配置 containerd 以禁用删除 containerd 内容存储中未打包的映像层，请参阅以下示例。

```
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:             # Name of the EKS cluster
    region:           # Amazon 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 使用配置版本 2，而 containerd 2.x 使用配置版本 3。虽然 containerd 2.x 对配置版本 2 仍保持向下兼容，但为实现最优性能，建议使用配置版本 3。您可通过 `containerd --version` 命令查看 containerd 版本，也可查阅 `nodeadm` 安装日志。有关配置版本控制的更多详细信息，请参阅 https://containerd.io/releases/

您还可以使用 containerd 配置来实现 SELinux 支持。在 containerd 上启用 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 设置为宽容模式时，在 containerd 上启用此功能不会阻止请求，但会根据主机上的 SELinux 配置记录请求。

```
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name:             # Name of the EKS cluster
    region:           # Amazon 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
```