Hybrid nodes nodeadm reference

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

The Amazon EKS Hybrid Nodes CLI (nodeadm) simplifies the installation, configuration, registration, and uninstallation of the hybrid nodes components. You can include nodeadm in your operating system images to automate hybrid node bootstrap, see Prepare operating system for hybrid nodes for more information.

The nodeadm version for hybrid nodes 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.

The source code for the hybrid nodes nodeadm is published in the https://github.com/aws/eks-hybrid GitHub repository.

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

nodeadm install

The nodeadm install command is used to install the artifacts and dependencies required to run and join hybrid nodes to an Amazon EKS cluster. The nodeadm 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.32

Flags

Examples

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

nodeadm install 1.32 --credential-provider ssm

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

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

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

nodeadm install 1.32 --credential-provider iam-ra

nodeadm config check

The nodeadm 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 -c file://nodeConfig.yaml

nodeadm init

The nodeadm init command starts and connects the hybrid node with the configured Amazon EKS cluster. See Node Config for SSM hybrid activations or Node Config for IAM Roles Anywhere for details of how to configure the nodeConfig.yaml file.

Usage

nodeadm init [flags]

Flags

Examples

nodeadm init -c file://nodeConfig.yaml

nodeadm 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.32

Flags

Examples

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

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

nodeadm 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 Remove hybrid nodes 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

nodeadm 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 -c file://nodeConfig.yaml

Nodeadm file locations

nodeadm install

When running nodeadm install, the following files and file locations are configured.

nodeadm init

When running nodeadm init, the following files and file locations are configured.

Node Config for 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

Node Config for 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

Node Config for customizing kubelet (Optional)

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

Node Config for customizing containerd (Optional)

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