coderain guide

Step-by-Step Guide to Installing Kubernetes on AWS

Kubernetes (K8s) has become the de facto standard for container orchestration, enabling teams to automate deployment, scaling, and management of containerized applications. When combined with Amazon Web Services (AWS)—a leading cloud provider with robust infrastructure—Kubernetes offers a scalable, reliable platform for running production workloads. AWS provides **Amazon Elastic Kubernetes Service (EKS)**, a managed Kubernetes service that simplifies deploying, managing, and scaling Kubernetes clusters. EKS eliminates the need to manually set up and maintain the Kubernetes control plane, allowing you to focus on your applications rather than infrastructure. In this guide, we’ll walk through installing Kubernetes on AWS using EKS, the most common and recommended approach. We’ll cover prerequisites, cluster setup, node configuration, deploying a sample app, and verification. By the end, you’ll have a fully functional Kubernetes cluster running on AWS.

Table of Contents

  1. Prerequisites
  2. Setting Up AWS CLI
  3. Choosing a Kubernetes Deployment Method on AWS
  4. Installing EKS with eksctl
  5. Configuring kubectl for EKS
  6. Creating Node Groups
  7. Deploying a Sample Application
  8. Verifying the Cluster
  9. Post-Installation Steps
  10. Cleanup
  11. Troubleshooting Common Issues
  12. References

Prerequisites

Before starting, ensure you have the following:

  • AWS Account: Sign up at aws.amazon.com. You’ll need administrative access to create resources.
  • IAM Permissions: Your AWS user must have permissions to create EKS clusters, EC2 instances, VPCs, and IAM roles. Attach policies like AdministratorAccess (for testing) or a custom policy with EKS-specific permissions.
  • AWS CLI: Install the AWS Command Line Interface (v2) to interact with AWS services.
  • kubectl: Install the Kubernetes command-line tool kubectl to manage the cluster. Ensure the version is compatible with your EKS cluster (e.g., kubectl v1.28 for EKS 1.28).
  • eksctl: Install eksctl, a CLI tool to simplify EKS cluster creation and management (recommended for beginners).
  • Operating System: Windows, macOS, or Linux (we’ll use Linux/macOS commands; adjust for Windows as needed).

Setting Up AWS CLI

  1. Install AWS CLI:

    • macOS: Use Homebrew: brew install awscli.
    • Linux: Use curl: 
      curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"  
unzip awscliv2.zip  
sudo ./aws/install
    • Windows: Download the AWS CLI installer and run it.

  2. Configure AWS CLI:
    Authenticate with your AWS account using access keys. Go to the AWS IAM Console, create an access key (under Users > Your User > Security Credentials), then run:

    aws configure

    Enter your AWS Access Key ID, AWS Secret Access Key, default region (e.g., us-west-2), and output format (e.g., json).

  3. Verify Setup:
    Run aws sts get-caller-identity to confirm authentication. You should see your account ID and user ARN.

Choosing a Kubernetes Deployment Method on AWS

AWS offers two primary ways to run Kubernetes:

1. Amazon EKS (Managed Kubernetes)

  • Control Plane: Managed by AWS (scalable, highly available, auto-updated).
  • Node Groups: EC2 instances or AWS Fargate (serverless) for running pods.
  • Pros: Low operational overhead, integrates with AWS services (CloudWatch, IAM, VPC).
  • Cons: Slightly higher cost than self-managed (pay for control plane).

2. Self-Managed Kubernetes

  • Tools: Use kops, kubeadm, or Terraform to manually provision control plane and nodes.
  • Pros: Full control over the cluster, lower cost (no EKS control plane fee).
  • Cons: Requires managing high availability, upgrades, and security for the control plane.

Recommendation: Start with EKS for simplicity. We’ll focus on EKS in this guide.

Installing EKS with eksctl

eksctl is the fastest way to create an EKS cluster. It automates VPC setup, IAM roles, and node group provisioning.

Step 1: Install eksctl

  • macOS: brew install eksctl.
  • Linux: 
    curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp  
sudo mv /tmp/eksctl /usr/local/bin
  • Windows: Use Chocolatey: choco install eksctl.

Verify installation: eksctl version.

Step 2: Create an EKS Cluster

You can create a cluster with a single command or a configuration file. We’ll use the command-line approach for simplicity.

Run the following to create a cluster with:

  • Name: my-eks-cluster
  • Region: us-west-2 (change to your preferred region)
  • Node group: 2 t3.medium instances (minimum for EKS)
  • Kubernetes version: 1.28 (check EKS versions for updates)
eksctl create cluster \  
  --name my-eks-cluster \  
  --region us-west-2 \  
  --nodegroup-name standard-workers \  
  --node-type t3.medium \  
  --nodes 2 \  
  --nodes-min 1 \  
  --nodes-max 3 \  
  --version 1.28

What Happens Next?

  • eksctl uses AWS CloudFormation to provision resources:
    • A VPC with public/private subnets, security groups, and IAM roles.
    • An EKS control plane (3 managed nodes across AWS Availability Zones).
    • A managed node group (EC2 instances) for running pods.
  • Duration: Cluster creation takes 10–15 minutes. Wait for the message: EKS cluster "my-eks-cluster" in "us-west-2" is ready.

Configuring kubectl for EKS

kubectl needs a kubeconfig file to connect to your EKS cluster. eksctl automatically updates kubeconfig during cluster creation, but verify with:

kubectl get nodes

If you see an error (e.g., “context not found”), manually update kubeconfig:

aws eks update-kubeconfig --name my-eks-cluster --region us-west-2

Now run kubectl get nodes again. You should see your 2 node instances:

NAME                                         STATUS   ROLES    AGE   VERSION  
ip-192-168-12-34.us-west-2.compute.internal   Ready    <none>   5m    v1.28.eks-abc123  
ip-192-168-56-78.us-west-2.compute.internal   Ready    <none>   5m    v1.28.eks-abc123

Creating Node Groups

Node groups are pools of EC2 instances that run your pods. The initial cluster creation includes a node group, but you may want to add more (e.g., for GPU workloads or different instance types).

Add a Managed Node Group with eksctl

Run this command to add a node group with t3.large instances:

eksctl create nodegroup \  
  --cluster my-eks-cluster \  
  --region us-west-2 \  
  --name high-memory-workers \  
  --node-type t3.large \  
  --nodes 1 \  
  --nodes-min 1 \  
  --nodes-max 2

Verify node groups:

eksctl get nodegroups --cluster my-eks-cluster --region us-west-2

Deploying a Sample Application

Let’s deploy a simple nginx app to test the cluster.

Step 1: Create a Deployment

Create a file named nginx-deployment.yaml with:

apiVersion: apps/v1  
kind: Deployment  
metadata:  
  name: nginx-deployment  
spec:  
  replicas: 2  
  selector:  
    matchLabels:  
      app: nginx  
  template:  
    metadata:  
      labels:  
        app: nginx  
    spec:  
      containers:  
      - name: nginx  
        image: nginx:1.23  
        ports:  
        - containerPort: 80

Apply the deployment:

kubectl apply -f nginx-deployment.yaml

Step 2: Verify Pods

Check if pods are running:

kubectl get pods

Output:

NAME                                READY   STATUS    RESTARTS   AGE  
nginx-deployment-7f96658b8c-2xqzv   1/1     Running   0          2m  
nginx-deployment-7f96658b8c-9k7p4   1/1     Running   0          2m

Step 3: Expose the App as a Service

To access nginx externally, expose the deployment with a LoadBalancer service:

kubectl expose deployment nginx-deployment --type=LoadBalancer --port=80 --name=nginx-service

Check the service:

kubectl get service nginx-service

Output (note the EXTERNAL-IP):

NAME            TYPE           CLUSTER-IP      EXTERNAL-IP       PORT(S)        AGE  
nginx-service   LoadBalancer   10.100.23.45    a1b2c3d4e5f6.us-west-2.elb.amazonaws.com   80:30080/TCP   1m

Step 4: Access the App

Open a browser and navigate to the EXTERNAL-IP (or run curl <EXTERNAL-IP>). You should see the nginx welcome page.

Verifying the Cluster

Use these commands to inspect cluster health:

  • Nodes: kubectl describe node <node-name> (check resources, labels, and conditions).
  • Pods: kubectl logs <pod-name> (view pod logs), kubectl exec -it <pod-name> -- /bin/bash (access pod shell).
  • Services: kubectl describe service nginx-service (check load balancer details).
  • Events: kubectl get events --sort-by='.lastTimestamp' (troubleshoot issues).

Post-Installation Steps

1. Monitor with CloudWatch

EKS integrates with Amazon CloudWatch for logging and monitoring. Enable Container Insights:

aws eks update-cluster-config \  
  --name my-eks-cluster \  
  --region us-west-2 \  
  --logging '{"clusterLogging":[{"types":["api","audit","authenticator","controllerManager","scheduler"],"enabled":true}]}'

View logs in the CloudWatch Console.

2. Secure with IAM Roles for Service Accounts (IRSA)

Restrict pod permissions using IRSA. Follow the EKS IRSA Guide to assign IAM roles to Kubernetes service accounts.

3. Enable VPC Flow Logs

Monitor network traffic in your EKS VPC. Go to the VPC Console, select your EKS VPC, and enable flow logs to CloudWatch.

Cleanup

To avoid AWS charges, delete the cluster when done:

eksctl delete cluster --name my-eks-cluster --region us-west-2

This removes the control plane, node groups, and associated resources (VPC, security groups, etc.).

Troubleshooting Common Issues

  • Cluster Creation Fails: Check CloudFormation logs (EKS uses CloudFormation stacks). Run eksctl utils describe-stacks --cluster my-eks-cluster to debug.
  • Nodes Not Joining: Ensure node groups have the correct IAM roles (AmazonEKSWorkerNodePolicy, AmazonEKS_CNI_Policy).
  • kubectl Connection Issues: Verify kubeconfig with cat ~/.kube/config and ensure AWS CLI is authenticated.

References

You now have a fully functional Kubernetes cluster on AWS! EKS simplifies scaling and managing containerized applications, letting you focus on building rather than infrastructure. For production, explore advanced features like Fargate (serverless nodes), auto-scaling, and network policies.