Hybrid nodes nodeadm reference

The Amazon EKS Hybrid Nodes CLI (nodeadm) used for hybrid nodes lifecycle management differs from the nodeadm version used for bootstrapping Amazon EC2 instances as nodes in Amazon EKS clusters. Follow the documentation and references for the appropriate nodeadm version. This documentation page is for the hybrid nodes nodeadm version and the hybrid nodes nodeadm version is available in the eks-hybrid repository on GitHub. See the nodeadm - Amazon EKS AMI documentation for the nodeadm version used for Amazon EC2 instances.

Download nodeadm

The hybrid nodes version of nodeadm is hosted in Amazon S3 fronted by Amazon CloudFront. To install nodeadm on each on-premises host, you can run the following command from your on-premises hosts.

For x86_64 hosts:

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

For ARM hosts

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

Add executable file permission to the downloaded binary on each host.

chmod +x nodeadm

Commands

Install

The install command is used to install the artifacts and dependencies required to run and join hybrid nodes to an Amazon EKS cluster. The install command can be run individually on each hybrid node or can be run during image build pipelines to preinstall the hybrid nodes dependencies in operating system images.

Usage

nodeadm install [KUBERNETES_VERSION] [flags]

Positional Arguments

(Required) KUBERNETES_VERSION The major.minor version of EKS Kubernetes to install, for example 1.31

Flags

Examples

Install Kubernetes version 1.31 with AWS Systems Manager (SSM) as the credential provider

nodeadm install 1.31 --credential-provider ssm

Install Kubernetes version 1.31 with AWS Systems Manager (SSM) as the credential provider, Docker as the containerd source, with a download timeout of 20 minutes.

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

Install Kubernetes version 1.31 with AWS IAM Roles Anywhere as the credential provider

nodeadm install 1.31 --credential-provider iam-ra

Files installed

Config check

The config check command checks the provided node configuration for errors. This command can be used to verify and validate the correctness of a hybrid node configuration file.

Usage

nodeadm config check [flags]

Flags

Examples

nodeadm config check --config-source file:///root/nodeConfig.yaml

Init

The init command starts and connects the hybrid node with the configured Amazon EKS cluster.

Usage

nodeadm init [flags]

Flags

Examples

nodeadm init --config-source file://root/nodeConfig.yaml

Files installed

Upgrade

The nodeadm upgrade command upgrades all the installed artifacts to the latest version and bootstraps the node to configure the upgraded artifacts and join the EKS cluster on AWS. Upgrade is a disruptive command to the workloads running on the node. Please move your workloads to another node before running upgrade.

Usage

nodeadm upgrade [KUBERNETES_VERSION] [flags]

Positional Arguments

(Required) KUBERNETES_VERSION The major.minor version of EKS Kubernetes to install, for example 1.31

Flags

Examples

nodeadm upgrade 1.31 --config-source file:///root/nodeConfig.yaml

nodeadm upgrade 1.31 --config-source file:///root/nodeConfig.yaml --timeout 20m

Uninstall

The nodeadm uninstall command stops and removes the artifacts nodeadm installs during nodeadm install, including the kubelet and containerd. Note, the uninstall command does not drain or delete your hybrid nodes from your cluster. You must run the drain and delete operations separately, see Delete hybrid nodes from your EKS cluster for more information. By default, nodeadm uninstall will not proceed if there are pods remaining on the node. Similarly, nodeadm uninstall does not remove CNI dependencies or dependencies of other Kubernetes add-ons you run on your cluster. To fully remove the CNI installation from your host, see the instructions at Configure a CNI for hybrid nodes. If you are using AWS SSM hybrid activations as your on-premises credentials provider, the nodeadm uninstall command deregisters your hosts as AWS SSM managed instances.

Usage

nodeadm uninstall [flags]

Flags

Examples

nodeadm uninstall

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

Debug

The nodeadm debug command can be used to troubleshoot unhealthy or misconfigured hybrid nodes. It validates the following requirements are in-place.

If errors are found, the command’s output suggests troubleshooting steps. Certain validation steps show child processes. If these fail, the output is showed in a stderr section under the validation error.

Usage

nodeadm debug [flags]

Flags

Examples

nodeadm debug --config-source file://nodeConfig.yaml

Node Config API Reference

AWS SSM hybrid activations

The following is a sample nodeConfig.yaml when using AWS SSM hybrid activations for hybrid nodes credentials.

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

AWS IAM Roles Anywhere

The following is a sample nodeConfig.yaml for AWS IAM Roles Anywhere for hybrid nodes credentials.

When using AWS IAM Roles Anywhere as your on-premises credentials provider, the nodeName you use in your nodeadm configuration must align with the permissions you scoped for your Hybrid Nodes IAM role. For example, if your permissions for the Hybrid Nodes IAM role only allow AWS IAM Roles Anywhere to assume the role when the role session name is equal to the CN of the host certificate, then the nodeName in your nodeadm configuration must be the same as the CN of your certificates. The nodeName that you use can’t be longer than 64 characters. For more information, see Prepare credentials for hybrid nodes.

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

(Optional) Kubelet configuration

You can pass kubelet configuration and flags in your nodeadm configuration. See the example below for how to add an additional node label abc.amazonaws.com/test-label and config for setting shutdownGracePeriod to 30 seconds.

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

(Optional) Containerd configuration

You can pass custom containerd configuration in your nodeadm configuration. The containerd configuration for nodeadm accepts in-line TOML. See the example below for how to configure containerd to disable deletion of unpacked image layers in the containerd content store.

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

You can also use the containerd configuration to enable SELinux support. With SELinux enabled on containerd, ensure pods scheduled on the node have the proper securityContext and seLinuxOptions enabled. More information on configuring a security context can be found on the Kubernetes documentation.

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