{"id":22341348,"url":"https://github.com/aws/eks-hybrid","last_synced_at":"2025-07-30T01:31:52.596Z","repository":{"id":265966198,"uuid":"801051598","full_name":"aws/eks-hybrid","owner":"aws","description":"Use your on-premises and edge infrastructure as nodes in EKS clusters with EKS Hybrid Nodes","archived":false,"fork":false,"pushed_at":"2025-07-25T00:24:22.000Z","size":9719,"stargazers_count":49,"open_issues_count":20,"forks_count":22,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-25T03:31:06.744Z","etag":null,"topics":["aws","cli","eks","hybrid","hybrid-cloud","kubernetes","kubernetes-deployment"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/eks/hybrid-nodes/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-15T13:53:28.000Z","updated_at":"2025-07-24T22:45:19.000Z","dependencies_parsed_at":"2025-01-08T18:25:25.341Z","dependency_job_id":"bd5ac001-deef-4e57-839a-5aa7fa577a78","html_url":"https://github.com/aws/eks-hybrid","commit_stats":null,"previous_names":["aws/eks-hybrid"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/aws/eks-hybrid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Feks-hybrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Feks-hybrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Feks-hybrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Feks-hybrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/eks-hybrid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Feks-hybrid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267792658,"owners_count":24144929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cli","eks","hybrid","hybrid-cloud","kubernetes","kubernetes-deployment"],"created_at":"2024-12-04T08:06:31.984Z","updated_at":"2025-07-30T01:31:52.071Z","avatar_url":"https://github.com/aws.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Amazon EKS Hybrid Nodes\nWith [EKS Hybrid Nodes](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-overview.html), you can use your on-premises and edge infrastructure as nodes in EKS clusters. The EKS Hybrid Nodes CLI (nodeadm) used for hybrid nodes lifecycle management differs from the nodeadm version used for bootstrapping EC2 instances as nodes in EKS clusters. You should not use the hybrid nodes nodeadm version for nodes running on EC2 instances. This repository is for the hybrid nodes nodeadm version. For the nodeadm version for EC2 instances, see the EKS AMI [GitHub repository](https://github.com/awslabs/amazon-eks-ami) and [documentation](https://awslabs.github.io/amazon-eks-ami/nodeadm/). \n\n## nodeadm\n\nYou can run nodeadm on each on-premises host to simplify the installation, configuration, registration, and uninstall of the hybrid nodes components. You can alternatively include nodeadm in your operating system images to automate hybrid node bootstrap (see [Packer examples](example/packer) for more information).\n\n**See [Hybrid Nodes nodeadm reference](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-nodeadm.html) in the EKS User Guide for the full nodeadm usage reference. This readme contains example commands only.**\n\n---\n\n### Usage\n\n#### Download nodeadm\n\nTo install nodeadm on each on-premises host, you can run the following command from your on-premises hosts.\n\nFor x86_64 hosts:\n\n```sh\ncurl -OL 'https://hybrid-assets.eks.amazonaws.com/releases/latest/bin/linux/amd64/nodeadm'\n```\n\nFor ARM hosts\n\n```sh\ncurl -OL 'https://hybrid-assets.eks.amazonaws.com/releases/latest/bin/linux/arm64/nodeadm'\n```\n\nAdd executable file permission to the downloaded binary on each host. You must run nodeadm with a user that has root/sudo privileges.\n\n```sh\nchmod +x nodeadm\n```\n\n#### nodeadm install\n\nThe `install` command is used to install the artifacts and dependencies required to run and join hybrid nodes to an 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. You must run nodeadm with a user that has root/sudo privileges.\n\nInstall Kubernetes version 1.31 with AWS Systems Manager (SSM) as the credential provider\n```sh\nnodeadm install 1.31 --credential-provider ssm \n```\nInstall Kubernetes version 1.31 with AWS Systems Manager (SSM) as the credential provider with a download timeout of 30 minutes.\n```sh\nnodeadm install 1.31 --credential-provider ssm --timeout 30m\n```\nInstall Kubernetes version 1.31 with AWS IAM Roles Anywhere as the credential provider\n```sh\nnodeadm install 1.31 --credential-provider iam-ra\n```\n\n#### nodeadm init\nThe `nodeadm init` command starts and connects hybrid nodes with the configured Amazon EKS cluster.\n\n```\nnodeadm init --config-source file://nodeConfig.yaml\n```\n\n#### nodeadm upgrade\nThe `nodeadm upgrade` command shuts down the existing older Kubernetes components running on the hybrid node, uninstalls the existing older Kubernetes components, installs the new target Kubernetes components, and starts the new target Kubernetes components. It is strongly recommend to upgrade one node at a time to minimize impact to applications running on the hybrid nodes. The duration of this process depends on your network bandwidth and latency.\n\nSee [Upgrade hybrid nodes](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-upgrade.html) in the EKS User Guide for detailed information and guidance on hybrid nodes upgrades.\n\nUpgrade to Kubernetes version 1.31\n```sh\nnodeadm upgrade 1.31 --config-source file://nodeConfig.yaml\n```\nUpgrade to Kubernetes version `1.31` with a download timeout of 30 minutes.\n```sh\nnodeadm upgrade 1.31 --config-source file://nodeConfig.yaml --timeout 30m\n```\n\n#### nodeadm uninstall\nThe `nodeadm uninstall` command stops and removes the artifacts nodeadm installs during `nodeadm install`, including the kubelet and containerd. Note, the `nodeadm 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](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-delete.html) in the EKS User Guide for more information. \n\nUninstall nodeadm-installed components\n```sh\nnodeadm uninstall\n```\nUninstall nodeadm-installed components and skip node and pod validations\n```sh\nnodeadm uninstall --skip node-validation,pod-validation\n```\n\n---\n\n### Configuration\n\nSample `nodeConfig.yaml` when using AWS SSM hybrid activations for hybrid nodes credentials\n\n```yaml\napiVersion: node.eks.aws/v1alpha1\nkind: NodeConfig\nspec:\n  cluster:\n    name:             # Name of the EKS cluster\n    region:           # AWS Region where the EKS cluster resides\n  hybrid:\n    ssm:\n      activationCode: # SSM hybrid activation code\n      activationId:   # SSM hybrid activation id\n```\n\nSample `nodeConfig.yaml` for AWS IAM Roles Anywhere for hybrid nodes credentials.\n\n```yaml\napiVersion: node.eks.aws/v1alpha1\nkind: NodeConfig\nspec:\n  cluster:\n    name:              # Name of the EKS cluster\n    region:            # AWS Region where the EKS cluster resides\n  hybrid:\n    iamRolesAnywhere:\n      nodeName:          # Name of the node\n      trustAnchorArn:  # ARN of the IAM Roles Anywhere trust anchor\n      profileArn:      # ARN of the IAM Roles Anywhere profile\n      roleArn:         # ARN of the Hybrid Nodes IAM role\n      certificatePath: # Path to the certificate file to authenticate with the IAM Roles Anywhere trust anchor\n      privateKeyPath:  # Path to the private key file for the certificate\n```\n\n**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.\n\n```yaml\napiVersion: node.eks.aws/v1alpha1\nkind: NodeConfig\nspec:\n  cluster:\n    name:             # Name of the EKS cluster\n    region:           # AWS Region where the EKS cluster resides\n  kubelet:\n    config:           # Map of kubelet config and values\n       shutdownGracePeriod: 30s\n    flags:            # List of kubelet flags\n       - --node-labels=abc.company.com/test-label=true\n  hybrid:\n    ssm:\n      activationCode: # SSM hybrid activation code\n      activationId:   # SSM hybrid activation id\n```\n\n**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. \n\n```yaml\napiVersion: node.eks.aws/v1alpha1\nkind: NodeConfig\nspec:\n  cluster:\n    name:             # Name of the EKS cluster\n    region:           # AWS Region where the EKS cluster resides\n  containerd:\n    config: |         # Inline TOML containerd additional configuration\n       [plugins.\"io.containerd.grpc.v1.cri\".containerd]\n       discard_unpacked_layers = false\n  hybrid:\n    ssm:\n      activationCode: # SSM hybrid activation code\n      activationId:   # SSM hybrid activation id\n```\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Feks-hybrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Feks-hybrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Feks-hybrid/lists"}