diff --git a/README.md b/README.md index d8f577c..7c971d7 100755 --- a/README.md +++ b/README.md @@ -9,7 +9,9 @@ Before you begin, ensure you have the following prerequisites installed and conf - AWS CLI - Terraform - Ansible -- Ansible module : [ansible.posix](https://galaxy.ansible.com/ui/repo/published/ansible/posix/) +- Ansible module : + - [ansible.posix](https://galaxy.ansible.com/ui/repo/published/ansible/posix/) + - [community.docker](https://docs.ansible.com/ansible/latest/collections/community/docker/docker_compose_module.html) - Git (if cloning the repository) - An AWS account with the necessary permissions - A configured [AWS Key Pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html) diff --git a/ansible/README.md b/ansible/README.md new file mode 100644 index 0000000..6f384fe --- /dev/null +++ b/ansible/README.md @@ -0,0 +1,109 @@ +# README for Ansible Playbook: ContainerLab Installation + +This README provides detailed information about the Ansible playbook designed for setting up and configuring ContainerLab, along with Docker, Tailscale, and additional system tools on Ubuntu hosts. + +## Overview + +The playbook is structured to run a series of tasks including setting the hostname, installing required system packages, configuring Docker and Tailscale repositories, and installing ContainerLab. It ensures that necessary directories are created, and relevant permissions are set up for a seamless user experience. + +## Key Features + +- **Hostname Configuration**: Sets the system hostname to `ContainerLab`. +- **System Packages**: Installs essential packages such as `curl`, `git`, `python3-pip`, and several others necessary for running ContainerLab and associated tools. +- **Docker Setup**: Adds Docker's official GPG key and repository, installs Docker and Docker Compose, and adds the executing user to the Docker group. +- **Tailscale VPN**: Configures the Tailscale repository and installs it for creating secure networks. +- **ContainerLab Installation**: Sets up the ContainerLab repository, installs ContainerLab, and ensures necessary directories and user configurations are in place. +- **Project and Data Management**: Clones a specified GitHub repository, synchronizes local directories, and manages network images within the target system. + +## Installation Steps + +1. **Prepare your inventory**: Ensure your Ansible inventory file is updated with the hostnames or IP addresses of the target machines. +2. **Clone the playbook**: Download or clone this playbook repository to your control machine. +3. **Configure variables**: Review and update the `clab_vars.yml` file with necessary values like `tailscale_auth_key`, and `repo_git_url` (or `local_dir_path`). +4. **Run the playbook**: Execute the playbook with the following command: + + ```bash + ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook \ + -u admin \ + -i ../ansible/inventory \ + --private-key AWS_KEY_LOCATION \ + ../ansible/install_containerlab.yml + ``` + +## Important Variables + +- `tailscale_auth_key`: Authentication key for setting up Tailscale. +- `repo_git_url`: URL of the Git repository to be cloned. +- `local_dir_path`: Local directory path for synchronization with the remote machine. + +## Directory Structure + +- `/opt/containerlab`: Main directory for ContainerLab configurations and projects. +- `/opt/edgeshark`: Directory for EdgeShark configurations, including a Docker Compose file pulled from its repository. + +## Usage + +After successful installation, ContainerLab and associated tools will be configured and ready to use. You can manage your ContainerLab environments and use Tailscale to connect your labs securely. + +## Support + +For issues related to the playbook, review the error logs generated during playbook execution or refer to the official documentation of each component (Docker, Tailscale, ContainerLab) installed by this playbook. + +## Detailed Task Explanations + +1. **Set hostname to ContainerLab** + - Sets the system hostname to `ContainerLab` to ensure a specific, predictable hostname for network configuration. + +2. **Install required system packages** + - Installs essential packages for running ContainerLab and tools, ensuring the system has necessary dependencies like `curl`, `python3-pip`, etc. + +3. **Add Docker GPG apt Key** + - Adds Docker's official GPG key to ensure the authenticity of the Docker packages from the official repository. + +4. **Add Docker Repository** + - Adds the Docker repository to apt sources to enable installation of the latest Docker versions. + +5. **Update apt and install Docker** + - Updates the apt package index and installs Docker and Docker Compose, necessary for container management. + +6. **Add the current user to the Docker group** + - Adds the ansible user to the Docker group to allow running Docker commands without sudo privileges. + +7. **Add Tailscale GPG apt Key** + - Adds the GPG key for Tailscale to verify the authenticity of the packages. + +8. **Add Tailscale Repository** + - Configures apt to use the Tailscale repository for secure VPN connections. + +9. **Update apt and install Tailscale** + - Installs Tailscale for creating secure networks between devices. + +10. **Run Tailscale CLI command** + - Automatically connects the machine to the Tailscale network using an authorization key. + +11. **Add ContainerLab Repository** + - Adds the official ContainerLab repository for installation of ContainerLab. + +12. **Update apt and install ContainerLab** + - Installs ContainerLab, essential for working with network topologies in a lab environment. + +13. **Ensure /opt/containerlab directory exists** + - Creates and sets permissions for the ContainerLab project directory. + +14. **Ensure user 'admin' exists** + - Ensures there is an `admin` user with adequate permissions for Docker and ContainerLab management. + +15. **Ensure the /opt/edgeshark directory exists** + - Creates a directory for EdgeShark deployments, part of the network monitoring or edge computing setups. + +16. **Download the edgeshark docker-compose.yaml file** + - Pulls a Docker Compose file for EdgeShark, facilitating its deployment. + +17. **Clone specified GitHub repository to /opt/containerlab** + - Clones a repository to the ContainerLab directory for managing project files. + +18. **Synchronize local directory to VM** + - Mirrors local developments to the remote machine, ensuring consistency. + +19. **Copy network images to remote /tmp directory** + - Prepares network images for use in simulations, aiding in topology experiments. diff --git a/ansible/install_containerlab.yml b/ansible/install_containerlab.yml index 830daf2..8f1aaad 100755 --- a/ansible/install_containerlab.yml +++ b/ansible/install_containerlab.yml @@ -36,9 +36,11 @@ repo: deb https://download.docker.com/linux/ubuntu focal stable state: present - - name: Update apt and install docker-ce + - name: Update apt and install docker ansible.builtin.apt: - name: docker-ce + pkg: + - docker + - docker-compose update_cache: true - name: Add the current user to the docker group @@ -97,6 +99,18 @@ shell: /bin/bash become: true + - name: Ensure the /opt/edgeshark directory exists + ansible.builtin.file: + path: /opt/edgeshark + state: directory + mode: '0755' + + - name: Download the edgeshark docker-compose.yaml file + ansible.builtin.get_url: + url: https://github.com/siemens/edgeshark/raw/main/deployments/wget/docker-compose.yaml + dest: "/opt/edgeshark/docker-compose.yaml" + mode: '0644' + - name: Clone specified GitHub repository to /opt/containerlab ansible.builtin.git: repo: "{{ repo_git_url }}" diff --git a/terraform/README.md b/terraform/README.md new file mode 100644 index 0000000..290d2ef --- /dev/null +++ b/terraform/README.md @@ -0,0 +1,91 @@ +# Terraform Deployment + +This directory contains the Terraform configuration files for deploying an AWS EC2 instance with ContainerLab. + +## Prerequisites + +- Terraform installed on your local machine +- AWS CLI configured with your credentials +- An AWS account with the necessary permissions + +## Configuration + +1. **Set AWS Credentials and Variables** + + Rename the `terraform.tfvars.sample` to `terraform.tfvars` and update the following variables with your own values: + + ```tfvars + AWS_ACCESS_KEY = "your_access_key" + AWS_SECRET_KEY = "your_secret_key" + AWS_KEY_NAME = "your_key_pair_name" + AWS_KEY_LOCATION = "path_to_your_private_key" + ``` + + **Important** : Never commit `terraform.tfvars` to version control as it contains sensitive information. + +2. **Customize Terraform Variables** + + You can customize the deployment by modifying the Terraform variables in `variables.tf`. + +## Action made by the EC2.tf file + +1. **AWS Provider Configuration**: It sets up the AWS provider with the region, access key, and secret key specified in the Terraform variables. + + ```tf + provider "aws" { + region = var.AWS_REGION + access_key = var.AWS_ACCESS_KEY + secret_key = var.AWS_SECRET_KEY + } + ``` + +2. **Security Group Creation**: It creates a new AWS security group named `netlab_sg`. This security group allows all outbound traffic and only inbound SSH (port 22) traffic from the IP address specified in the `AWS_LOCAL_IP` variable. + + ```tf + resource "aws_security_group" "netlab_sg" { + ... + } + ``` + +3. **EC2 Instance Creation**: It creates a new AWS EC2 instance with the specified AMI, instance type, and key pair. The instance is associated with the `netlab_sg` security group. The instance is tagged with the name "ContainerLab". + + ```tf + resource "aws_instance" "containerlab_host" { + ... + } + ``` + +4. **Root Block Device Configuration**: It configures the root block device of the EC2 instance with a volume size of 128 GB, a volume type of `gp2`, encryption disabled, and deletion on termination enabled. + + ```tf + root_block_device { + ... + } + ``` + +5. **Local Provisioners**: It uses two local provisioners to perform actions on the local machine after the EC2 instance is created: + + - The first provisioner writes the public IP address of the newly created EC2 instance to the `../ansible/inventory` file. + + ```tf + provisioner "local-exec" { + command = "echo ${aws_instance.containerlab_host.public_ip} > ../ansible/inventory" + } + ``` + + - The second provisioner waits for 20 seconds and then runs the Ansible playbook `install_containerlab.yml` using the `ansible-playbook` command. The playbook is run against the new EC2 instance. + + ```tf + provisioner "local-exec" { + command = <