Kubernetes Platform on AWS EKS

Minimal, production-ready Kubernetes platform with automated CI/CD pipeline.

Prerequisites

1. AWS CLI installed and configured with appropriate permissions
2. Terraform >= 1.0 installed
3. kubectl installed
4. Docker installed and running

AWS Credentials Setup

Required Environment Variables:

Before working with this repository, you must export your AWS credentials:

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_REGION="eu-west-3"  # or your preferred region

Important: These environment variables must be set in your current shell session. You can verify they are set with:

echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
echo $AWS_REGION

Required AWS Permissions: Your AWS user/role needs permissions for:

• EKS (Elastic Kubernetes Service)
• ECR (Elastic Container Registry)
• VPC and networking
• IAM roles and policies
• S3 (for Terraform state)
• DynamoDB (for Terraform state locking)

Architecture

• Infrastructure: AWS EKS cluster with VPC using Terraform modules
• Application: Go HTTPS server containerized and deployed to EKS
• CI/CD: GitHub Actions pipeline for automated deployment
• State Management: Terraform state stored in AWS S3 with DynamoDB locking

Quick Start

Step 1: Setup Backend Infrastructure

First, create the S3 backend and DynamoDB table:

cd terraform-backend
terraform init
terraform apply
cd ..

Step 2: Deploy Platform

make bootstrap

This single command will:

1. Initialize and apply Terraform infrastructure
2. Configure kubectl for EKS
3. Deploy the application

Manual Step-by-Step

# 1. Deploy infrastructure
make init
make plan
make apply

# 2. Deploy application
make deploy

Available Commands

make help                    # Show all available commands
make bootstrap              # Complete setup and deployment
make deploy                 # Deploy application to Kubernetes
make status                 # Show cluster and app status
make test                   # Test application locally
make test-k8s              # Test application in Kubernetes
make logs                   # Show application logs
make clean                  # Clean up local resources

Detailed Setup Guide

Step 1: AWS Setup

Configure AWS CLI

aws configure
# Enter your AWS Access Key ID, Secret Access Key, and region (eu-west-3)

Required AWS Permissions

Your AWS user/role needs permissions for:

• EKS (Elastic Kubernetes Service)
• ECR (Elastic Container Registry)
• VPC and networking
• IAM roles and policies
• S3 (for Terraform state)
• DynamoDB (for Terraform state locking)

Step 2: Terraform Backend Setup

Create S3 Backend and DynamoDB Table

cd terraform-backend
terraform init
terraform plan
terraform apply
cd ..

This creates:

• S3 bucket: k8s-platform-terraform-state
• DynamoDB table: terraform-state-lock

Step 3: Deploy Infrastructure

Initialize and Apply Terraform

make init
make plan
make apply

Expected Output:

• VPC with public/private subnets
• EKS cluster with managed node group
• ECR repository for container images
• IAM roles and policies

Step 4: Deploy Application

Configure kubectl and Deploy

make deploy

This will:

• Configure kubectl for EKS
• Deploy all Kubernetes manifests
• Wait for deployment rollout

Step 5: Verify Deployment

Check Status

make status

Test Application

make test-k8s

View Logs

make logs

GitHub Repository Setup

Required Secrets

Add these secrets to your GitHub repository:

1. AWS_ACCESS_KEY_ID: Your AWS access key
2. AWS_SECRET_ACCESS_KEY: Your AWS secret key
3. AWS_REGION: eu-west-3
4. ECR_REPOSITORY_URI: Output from terraform output ecr_repository_url

How to Add Secrets

1. Go to your GitHub repository
2. Click Settings → Secrets and variables → Actions
3. Click New repository secret
4. Add each secret with the exact names above

Test CI/CD Pipeline

Trigger Deployment

1. Push changes to the main branch
2. GitHub Actions will automatically:
   • Build the Docker image
   • Push to ECR
   • Deploy to EKS
   • Run smoke tests

Monitor Pipeline

1. Go to Actions tab in GitHub
2. Click on the latest workflow run
3. Monitor each step for success/failure

Troubleshooting

Common Issues

1. Terraform Backend Error

   # Ensure backend is properly configured
   cd terraform-backend && terraform apply
   cd .. && cd terraform && terraform init -reconfigure

2. EKS Connection Issues

   # Update kubeconfig
   make setup-kubectl
   
   # Check cluster status
   aws eks describe-cluster --name k8s-platform --region eu-west-3

3. Image Pull Errors

   # Check ECR repository
   aws ecr describe-repositories --region eu-west-3
   
   # Verify image exists
   aws ecr describe-images --repository-name jd-test-server --region eu-west-3

4. Pod Issues

   # Check pod logs
   make logs
   
   # Describe pod for events
   kubectl describe pod <pod-name>

Cleanup

Remove Application and Infrastructure

make destroy

Remove Backend Infrastructure

cd terraform-backend
terraform destroy
cd ..

Warning: This will delete the S3 bucket and DynamoDB table, potentially losing Terraform state if not backed up elsewhere.

Next Steps

1. Monitoring: Add Prometheus and Grafana
2. Logging: Implement centralized logging with ELK stack
3. Security: Enable pod security policies and network policies
4. Backup: Implement EKS cluster backup strategy
5. Multi-region: Extend to multiple AWS regions