NixOS 25.05 Kubernetes Worker Node¶

Updated: 2026, February 4th

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¶

Launch an EC2 instance from the AMI
Attach an IAM role with the following permissions:
eks:DescribeCluster - to get cluster details
Assume role permissions for kubelet authentication
Configure security group to allow:
SSH (port 22) from your IP
Kubelet API (port 10250) from cluster CIDR
NodePort range (30000-32767) from required sources
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:

# nix-channel --add https://nixos.org/channels/nixos-26.05 nixos
# nixos-rebuild switch --upgrade

Troubleshooting¶

SSH Connection Issues¶

If you cannot connect via SSH:

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

Kubelet Not Starting¶

If kubelet fails to start after bootstrap:

Check logs:
```
sudo journalctl -u kubelet -f
```
Verify IAM role: Instance must have permissions to describe EKS cluster
Check cluster name: Ensure the cluster name in UserData is correct
Verify network: Instance must be able to reach EKS API endpoint

containerd Issues¶

If containerd fails to start:

Check logs:
```
sudo journalctl -u containerd -f
```
Verify service status:
```
sudo systemctl status containerd
```
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.