lightsail-k8s-installer is a shell script to simplifies the process of setting up a Kubernetes cluster on Amazon Lightsail. Not only it automates the creation of necessary resources using AWS CloudFormation, but it also automates the installation of Kubernetes packages. With just one simple command, your Kubernetes cluster should up and running in no time!

sh lightsail-k8s-installer.sh -i demo

By default it will create 3 Amazon Lightsail instances (1 control plane, 2 workers) and 1 Load Balancer. The load balancer will distribute the traffic to all worker nodes.

To destroy the cluster.

sh lightsail-k8s-installer.sh -d demo

You can also use CloudFormation console or AWS CLI to delete the stack.

Navigate:

• Requirements
• Installation
• Usage and Examples
  • Create cluster in specific region
  • Specify Availability Zones pool
  • Custom CIDR for Pod network
  • Lightsail instance plan
  • Dry run mode
  • Add new worker node
  • Environment variables
• FAQ
  • What OS is used in all nodes?
  • What network Pod add-on is used?
  • Is high availability control plane cluster supported?
  • How worker node is placed on each AZ?
  • How to delete worker node?
  • How sample app is configured?
  • How to delete sample app?
  • The installation is stuck, what should I do?
  • Is it safe to delete installation via CloudFormation console?
  • How do I skip SSH passphrase?
• Todo
• Changelog
• Contributing
• License

Things you need to run this script:

• Active AWS account and make sure it has permissions to create Lightsail and CloudFormation resources.
• AWS CLI v2
• SSH client
• Basic shell utilities such as awk, cat, cut, date, sed, tr, wc.
• jq

lightsail-k8s-installer has been tested using following shells.

• bash v4.2 (Linux)
• bash v5.2 (Windows via Git Bash)
• dash v0.5 (Linux)
• zsh v5.8 (Linux)
• zsh v5.9 (macOS)

Download the archive or clone the repository.

curl -o 'lightsail-k8s-installer.zip' -s -L https://github.com/rioastamal/lightsail-k8s-installer/archive/refs/heads/master.zip
unzip lightsail-k8s-installer.zip
cd lightsail-k8s-installer-master/

Running lightsail-k8s-installer with -h flag will gives you list of options and examples.

sh lightsail-k8s-installer.sh -h

Usage: lightsail-k8s-installer.sh [OPTIONS]

Where OPTIONS:
  -a AZs        specify list of Available Zones using AZs
  -c CIDR       specify pod network using CIDR
  -d ID         destroy installation id specified by ID
  -h            print this help and exit
  -i ID         specify installation id using ID
  -m            dry run mode, print CloudFormation template and exit
  -r REGION     specify region using REGION
  -v            print script version
  -w NUM        specify number of worker nodes using NUM
  -u            update the cluster by add new worker nodes

----------------------- lightsail-k8s-installer -----------------------

lightsail-k8s-installer is a command line interface to bootstrap Kubernetes 
cluster on Amazon Lightsail. 

lightsail-k8s-installer is free software licensed under MIT. Visit the project 
homepage at http://github.com/rioastamal/lightsail-k8s-installer.

To create Kubernetes cluster with 4 worker nodes you only need to specify installation id using -i and -w options.

sh lightsail-k8s-installer.sh -i demo -w 4

-----------------------------
lightsail-k8s-installer v1.0
-----------------------------
This process will create Kubernetes cluster on Amazon Lightsail.

CloudFormation stack: lk8s-demo
              Region: us-east-1
     AZs worker pool: us-east-1a us-east-1b us-east-1c 
           Resources: - 1 control plane node (plan: $5)
                      - 4 worker nodes (plan: $5)
                      - 1 load balancer (plan: $18)
      Estimated cost: $43.00/month or $0.06/hour

Press any key to continue: 

This may take several minutes, please wait...
To view detailed log, run following command on another terminal:
  tail -f /home/ec2-user/lightsail-k8s-installer/.out/us-east-1-lk8s-demo-20230124085932.log

[LK8S]: Checking existing stack 'lk8s-demo'
[LK8S]: Stack 'lk8s-demo' is not exists, good!
[LK8S]: Waiting stack 'lk8s-demo' to be ready..
...[cut]...

Command above will produces following resources:

To specify region you can use -r option or LK8S_REGION environment variable.

sh lightsail-k8s-installer.sh -i demo -r ap-southeast-1

By default lightsail-k8s-installer will put worker nodes on three availability zones. As an example if you specify us-east-1 as region and 3 worker nodes, it will spread accross us-east-1a, us-east-1b and us-east-1c.

You can override this by using -a options. Let say you want the worker nodes to be placed on us-east-1a and us-east-1f.

sh lightsail-k8s-installer.sh -i demo -r us-east-1 -a "us-east-1a us-east-1f"

If you have 3 worker nodes 2 will be on us-east-1a and 1 in us-east-1f and so on.

lightsail-k8s-installer utilise flannel for Pod network add-on. The default CIDR for the Pod network is 10.244.0.0/16. To specify different CIDR use -c option.

sh lightsail-k8s-installer.sh -i demo -c "10.100.0.0/16"

By default all nodes including the control plane is using $5 plan. To change this settings specify environment variables LK8S_CONTROL_PLANE_PLAN=[VALUE] and LK8S_WORKER_PLAN=[VALUE].

LK8S_CONTROL_PLANE_PLAN=20_usd \
LK8S_WORKER_PLAN=10_usd \
sh lightsail-k8s-installer.sh -i demo -r ap-southeast-1

Valid values: 3_5_usd, 5_usd, 10_usd, 20_usd, 40_usd, 80_usd, 160_usd.

To run the script in dry run mode, use -m option. It will print the CloudFormation template and then exit. This can be useful for inspecting the resources that will be created.

sh lightsail-k8s-installer.sh -i demo -r ap-southeast-1 -m

The dry run mode does not shows what commands that are going to be run on each nodes.

To add new worker simply use -u options. Following example will add 3 worker nodes ($10 plan) to the cluster. The workers will be placed sequentially on ap-southeast-1b and ap-southeast-1c only.

LK8S_WORKER_PLAN=10_usd \
sh lightsail-k8s-installer.sh -i demo -u -w 3 -a "ap-southeast-1b ap-southeast-1c"

All configuration for lightsail-k8s-installer are taken from environment variables. Here is a list of environment variables you can change.

Amazon Linux 2. Amazon Linux 2 uses yum as package manager similar with Fedora, CentOS and RHEL.

We use flannel. You're free to modify and change the network by yourself after cluster is up and running.

Not yet. But it is on the roadmap.

The worker node placed sequentially. For example if you specify 5 worker nodes on 2 AZs (us-east-1a and us-east-1b) here's the allocation.

There is no such functionality at the moment. It's still on the roadmap.

If you want to delete worker node you need to do it manually.

The sample app uses hashicorp/http-echo image which run on port 80. The installation script automatically adds a new label, node=[NODE_NAME] to each pod that has the label action=auto-label-node.

Then the script create new Kubernetes Service for each worker node and set the externalIPs to bind to Lightsail instance private IP. Each service has pod selector which is based on node name app=http-echo,node=[NODE_NAME].

By doing this Lightsail Load Balancer able to distribute traffic evenly to each worker node.

SSH into control plane node and run following command:

kubectl get services,deployments --no-headers -o name \
  -l cfstackname=[CLOUDFORMATION_STACKNAME] | xargs kubectl delete

Some browsers like Chrome use aggressive caching. I suggest to use command line tool such as cURL to do the testing.

See the log file at .out/[REGION]-[CLOUDFORMATION_STACK_NAME]-[TIME].log. If you did not find the issue then open CloudFormation console. Most of the time this is caused by CloudFormation failed to create a resource such as failed to create Amazon Lightsail Instance due permission issue or you do not have enough quota.

Yes it is totally safe. It will destroy all resources created by lightsail-k8s-installer.

lightsail-k8s-installer uses SSH to connect to node in Kubernetes to perform tasks. If your SSH key having a passphrase it may quite annoying to enter the passphrase multiple times during installation process.

One of the solution is by using ssh-agent and ssh-add. Before running the installation, issue command below.

eval $( ssh-agent )
ssh-add /path/to/your/ssh-private.key

• High availability control plane cluster
• Ability to delete worker node
• Kubernetes dashboard
• Custom tags for node
• Options to provide a container image and it's configuration
• Ability to choose OS for node

• Support for Windows (MINGW)
• Bug fixes:
  • Missing jq from the required tools
  • Wrong Lightsail SSH key pair name
  • Failed kubectl settings on control plane because of wrong interpretation of $HOME
• Improvements:
  • Add compatibility with dash shell
  • Add compatibility with zsh shell
  • Replace GNU's head with standard head

• Initial public release

Fork this repo and send me a PR. I am happy to review and merge it.

This project is licensed under MIT License.