📝 # AWS Kubeadm Simple Cluster Training

This is a simple (but effective) project that allows to quickly set-up a kubeadm cluster (single master) in AWS environment. It includes the possibility of creating the VPC, subnet, security groups and more for you.

You can place it as well in your existing VPC and create the subnet, or place it inside your existing subnet.

It is quite flexible. Enjoy it!

Report Bug · Request Feature

📚 Table of contents

• 📝 # AWS Kubeadm Simple Cluster Training
  • 📚 Table of contents
  • 💡 Details
    • Outcome architecture
    • Resources
  • 🚀 Installation and Execution
    • 🔧 Installation
      • Local environment
      • Docker
    • 💼 Usage
      • Locally
      • With Docker
    • 🛜 Connect to instances
  • 📍 Roadmap
  • 📎 Contributing
  • 📃 License
  • 👥 Contact

💡 Details

Outcome architecture

The outcome of the playbook is a single master kubeadm cluster configured with AWS infrastructure as shown:

• Public subnet

  • Represented by a blue outline within a red rectangle.

• Private subnet

  • Represented by a blue outline within a red rectangle, on the right side.
  • Contains several icons:
    • EC2 instances: 1 master and N number of workers (depending on instance count) that compound the Kubernetes cluster. Each instance with an iam profile applied.
    • A purple icon with a lock symbol, labeled "Client VPN endpoint", indicating a secure entry point for VPN connections.

• Route tables

  • Two identical icons located between the public and private subnets.
  • Represented by an orange circle with lines emanating from the center, symbolizing routing paths or connections.

• Overall Structure

  • The image depicts a network architecture with separate public and private subnets.
  • The public subnet is connected to the internet and has a routing mechanism to interface with the private subnet.
  • The private subnet hosts the core computing resources and is accessible via a client VPN endpoint for secure access.

Resources

The main resources for this project are located inside provisioner folder where the Ansible code is located.

Inside this folder we will find:

• aws:
  • ansible: containing the Ansible configuration, the different related playbooks (all started with main.yml) and the env_variables_aws.yaml containing the changeable configuration.
    • modules: those define the specific behavior for preparing the AWS related resources (Internet Gateway, Instances, Route Tables, Security Groups, Subnet and VPCs)
• filter_plugins: Global plugins that are used for simplification of some tasks.
• Dockerfile: for building the image to run the Ansible and Terraform dynamically generated project without having to install anything besides Docker.
• .dockerignore: To exclude some files from the image build for security and keeping it clean purposes.
• password_retriever.py: Utility for getting the password in clear text for the windows instance decrypting it using the private key for the instance.

Important

Do not forget to set the ANSIBLE_FILTER_PLUGINS environment variable to the absolute path where the custom_filters are located with the actual path of the project.

🚀 Installation and Execution

🔧 Installation

Caution

Remember to review the env variables. This playbook has direct support for several regions but do not cover all. Include your region and ami if missing in the list.

Local environment

1. Install Python.

sudo apt-get update && apt-get install -y python3 python3-pip

2. Install Ansible:

pip install ansible==9.4.0

3. Install Ansible collection for aws:

ansible-galaxy collection install amazon.aws

4. Install boto3 with pip.

pip3 install boto3 botocore

5. Install Terraform following Official instructions from Hashicorp documentation.

Tip

You can decide which version to install by checking PIP Ansible release history

Docker

You just have to build the Docker image!

docker build provisioner -f provisioner/Dockerfile -t cluster-provider:1.0 \
--build-arg UID=$(id -u) --build-arg GID=$(id -g) --build-arg USER=$(id -un) --build-arg GROUP=$(id -gn)

💼 Usage

Important

Do not forget to set at least your public IP in the rules of the security groups to be able to access using the SSH generated key after launching the playbook.

Locally

1. Set the required environment variables. If you do not have such, please check Amazon documentation on how to generate those here.

export AWS_REGION="eu-south-2"
export AWS_ACCESS_KEY_ID="REAL_VALUE_OF_AWS_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="REAL_VALUE_OF_AWS_SECRET_ACCESS_KEY"

2. Remember to change the Ansible env variables as your desired configuration.

3. Ensure to set the filter plugins env variable and make those available:

cp -r provisioner/filter_plugins ${HOME}
export ANSIBLE_FILTER_PLUGINS="${HOME}/filter_plugins"
export ANSIBLE_HOST_KEY_CHECKING=False

4. Run the playbook.

ansible-playbook provisioner/aws/main.yaml -vv

5. If successful, run the configuration playbook:

ansible-playbook aws/ansible/conf/main.yaml -i inventory.ini

With Docker

If you have built the image and adapted the Ansible env variables as your desired configuration, then you just need to execute this!

docker run --user $(id -u):$(id -g) -v $(pwd)/provisioner:/app  -e AWS_ACCESS_KEY_ID="" -e AWS_SECRET_ACCESS_KEY="" \
-e AWS_REGION="eu-west-2"   -e VERBOSITY="-vvv" -e ANSIBLE_FILTER_PLUGINS=/app/filter_plugins cluster-provider:1.0

Important

Do not forget to set the real values for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

🛜 Connect to instances

1. Obtain the ssh key for the instances in:

cd $(find $(pwd) -type d -name infra-provision*)/bsa-auto-infra/modules/key

Tip

If you have enabled the creation of client vpn, follow the next steps. Make sure to select your region first!

3. Navigate to Client VPNS

4. Click on Download client configuration

5. Insert the client certificates in the downloaded file. Check the illustration for the format.

terraform_outputs=$(find $(pwd) -type d -name infra-provision*)
cat ${terraform_outputs}/bsa-auto-infra/modules/vpn/pki_certs/client.crt
cat ${terraform_outputs}/bsa-auto-infra/modules/vpn/pki_certs/client.key

6. Launch a connection with ssh using the private ip and the hostname of the target destination.

📍 Roadmap

• Support for AWS
• Support flexibility in creating the Terraform through ansible.
• Creates: VPC, Subnet, Internet Gateway, Security Groups, SSH keys and instances linking all the objects as required.
• Include creation of client vpn endpoint with self-signed certificates (not recommended for production set up).
• Support for more regions.
• Included automatic configuration of the cluster.

See the open issues for a full list of proposed features (and known issues).

🔝 Back to top

📎 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated 💹.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch

   git checkout -b feature/AmazingFeature

3. Commit your Changes

   git commit -m 'Add some AmazingFeature

4. Push to the Branch

   git push origin feature/AmazingFeature

5. Open a Pull Request

🔝 Back to top

📃 License

Distributed under the Apache 2.0 License. See LICENSE for more information.

🔝 Back to top

👥 Contact

As we always state, our main purpose is keep learning, contributing to the community and finding ways to collaborate in interesting initiatives. Do not hesitate to contact us at [email protected]

If you are interested in our content creation, also check our social media accounts. We have all sorts of training resources, blogs, hackathons, write-ups and more! Do not skip it, you will like it 😏 😏 😏 👍

Don't forget to give the project a star if you liked it! Thanks again! 🌟 💛

🔝 Back to top