Skip to content

NixOS 25.05 Kubernetes Worker Node

Updated: 2026, February 4th

  NixOS 25.05 EKS Worker

Connecting to the system

The default user is ec2-user. SSH keys are automatically configured from EC2 instance metadata when the instance is launched.

Important: Use ECDSA or Ed25519 SSH keys (RSA is deprecated in most modern Linux distributions).

To connect: 

ssh -i ~/.ssh/your-key ec2-user@<instance-ip>

Using the AMI

Launching an EKS Worker Node

  1. Launch an EC2 instance from the AMI
  2. Attach an IAM role with the following permissions:
  3. eks:DescribeCluster - to get cluster details
  4. Assume role permissions for kubelet authentication
  5. Configure security group to allow:
  6. SSH (port 22) from your IP
  7. Kubelet API (port 10250) from cluster CIDR
  8. NodePort range (30000-32767) from required sources
  9. Provide UserData to bootstrap the node:
#!/bin/bash
/etc/eks/bootstrap.sh my-cluster-name

Advanced Usage

With Custom Kubelet Arguments

#!/bin/bash
/etc/eks/bootstrap.sh my-cluster-name \
  --kubelet-extra-args "--node-labels=env=prod,team=backend --register-with-taints=key=value:NoSchedule"

With Node Labels and Taints

#!/bin/bash
/etc/eks/bootstrap.sh my-cluster-name \
  --kubelet-extra-args "--node-labels=epok.systems/nixos=true,instance-type=t3.medium --register-with-taints=dedicated=workload:NoSchedule"

The bootstrap script: - Retrieves cluster CA, API endpoint, and auth token from AWS - Configures kubelet with /var/lib/kubelet/config.json - Starts the kubelet service - Joins the node to the cluster

System Requirements

  • Instance Types: t3, t3a, t4g, m5, c5, m6i, c6i, etc. (HVM-compatible)
  • Minimum: t3.small (2 vCPU, 2 GB RAM) for testing
  • Recommended: t3.medium+ (2+ vCPU, 4+ GB RAM) for production
  • Security Group: Must allow SSH (22), Kubelet (10250), NodePorts (30000-32767)
  • VPC: Must have internet access or VPC endpoint for EKS API
  • IAM Role: Must have eks:DescribeCluster and sts:AssumeRole permissions

Upgrading to a new version

To upgrade the system to a new version (ex: 26.05), execute the following commands:

  1. # nix-channel --add https://nixos.org/channels/nixos-26.05 nixos

  2. # nixos-rebuild switch --upgrade

Troubleshooting

SSH Connection Issues

If you cannot connect via SSH:

  1. Check security group: Ensure port 22 is open from your IP
  2. Verify key pair: Ensure the correct SSH key is associated with the instance
  3. Check instance status: Instance must be in running state
  4. Wait for initialization: New instances may take a few minutes to be ready

Kubelet Not Starting

If kubelet fails to start after bootstrap:

  1. Check logs: 

    sudo journalctl -u kubelet -f

  2. Verify IAM role: Instance must have permissions to describe EKS cluster

  3. Check cluster name: Ensure the cluster name in UserData is correct
  4. Verify network: Instance must be able to reach EKS API endpoint

containerd Issues

If containerd fails to start:

  1. Check logs: 

    sudo journalctl -u containerd -f

  2. Verify service status: 

    sudo systemctl status containerd

  3. Check configuration: 

    sudo containerd config dump

Need Help?

If you need help, please refer to the official documentation.

For EKS-specific questions, see the AWS EKS Documentation.