From 5215938949a5b3da0d84bd90cabef9f7194392fa Mon Sep 17 00:00:00 2001 From: Nils Hoffmann <3309580+nilshoffmann@users.noreply.github.com> Date: Wed, 21 Jan 2026 15:12:05 +0000 Subject: [PATCH 1/8] Starting new tutorial for Ansible OpenStack IaC on the de.NBI Cloud --- _data/tutorial_groups.yml | 3 +- .../ansible_openstack_services/tutorial.md | 29 +++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 _tutorials/ansible_openstack_services/tutorial.md diff --git a/_data/tutorial_groups.yml b/_data/tutorial_groups.yml index efa6b73..efaadd9 100644 --- a/_data/tutorial_groups.yml +++ b/_data/tutorial_groups.yml @@ -4,10 +4,11 @@ - unix-course - title: Cloud computing - description: Tutorials focused on ... + description: Introduction to cloud computing concepts and hands-on tutorials tutorials: - simpleVMWorkshop - bibigrid + - ansible_webservices_denbi_cloud - title: Machine Learning on Cloud infrastructure description: Tutorials focused on ... diff --git a/_tutorials/ansible_openstack_services/tutorial.md b/_tutorials/ansible_openstack_services/tutorial.md new file mode 100644 index 0000000..d2d3fc7 --- /dev/null +++ b/_tutorials/ansible_openstack_services/tutorial.md @@ -0,0 +1,29 @@ +--- +layout: tutorial_hands_on + +title: Using Ansible to Deploy and Operate (Web)Services on the de.NBI Cloud +description: This tutorial teaches you how to use Ansible to deploy and manage (web)services on the de.NBI Cloud OpenStack infrastructure. It introduces you to the basics of Ansible and guides you through writing infrastructure-as-code to automate the deployment and operation of your services, using Docker and optionally Docker Swarm. +slug: ansible_webservices_denbi_cloud +time_estimation: 1H +questions: + - Which questions are addressed by the tutorial? +objectives: + - Learn to access and use the de.NBI Cloud OpenStack API with Ansible + - Learn how to Write infrastructure-as-code using Ansible to deploy your (web)service + - Learn how to set up additional +key_points: +- The take-home messages +- They will appear at the end of the tutorial +version: 0.1 +life_cycle: alpha +contributions: + authorship: + - Nils Hoffmann + - author 2 + editing: + funding: +--- + +## Motivation + + From 02a5fa46ecca23dc10060042144a0788737553e5 Mon Sep 17 00:00:00 2001 From: Nils Hoffmann <3309580+nilshoffmann@users.noreply.github.com> Date: Wed, 4 Feb 2026 12:26:03 +0000 Subject: [PATCH 2/8] First commit for Ansible, OpenStack, Swarm service project. --- _data/tutorial_groups.yml | 11 +- .../resources/openstack.yml | 190 ++++++++++++ .../ansible_openstack_services/tutorial.md | 284 +++++++++++++++++- 3 files changed, 476 insertions(+), 9 deletions(-) create mode 100644 _tutorials/ansible_openstack_services/resources/openstack.yml diff --git a/_data/tutorial_groups.yml b/_data/tutorial_groups.yml index efaadd9..5fd40a5 100644 --- a/_data/tutorial_groups.yml +++ b/_data/tutorial_groups.yml @@ -1,17 +1,16 @@ - title: Unix - description: Our Core Curriculum consists of the lessons in the table below. + description: Tutorials focused on basic Unix / Linux commands and shell usage. tutorials: - unix-course - title: Cloud computing - description: Introduction to cloud computing concepts and hands-on tutorials + description: Tutorials focused on using the de.NBI Cloud infrastructure and project types. tutorials: - simpleVMWorkshop - bibigrid - - ansible_webservices_denbi_cloud - title: Machine Learning on Cloud infrastructure - description: Tutorials focused on ... + description: Tutorials focused on setting up machine learning toolkits and applications on cloud infrastructure. tutorials: - ml-fastapi - ml-streamlit @@ -23,12 +22,12 @@ - panbench - title: Basic Data Management in the de.NBI Cloud - description: Tutorial focused on ... + description: Tutorial focused on data management best practices and tools in the de.NBI Cloud. tutorials: - DM_in_the_deNBI_cloud - title: Metagenomics - description: Tutorials focused on dealing with metagenomics seqeuncing data + description: Tutorials focused on handling of metagenomics sequencing data. tutorials: - basicsAmpliconQC diff --git a/_tutorials/ansible_openstack_services/resources/openstack.yml b/_tutorials/ansible_openstack_services/resources/openstack.yml new file mode 100644 index 0000000..3cbb697 --- /dev/null +++ b/_tutorials/ansible_openstack_services/resources/openstack.yml @@ -0,0 +1,190 @@ +my: + ansible_host: "129.70.51.190" + openstack_cloud: "myproject-prod" + openstack_project: "myproject" + openstack_site: "Bielefeld" + ssh: + key: + #the keyname in openstack under Compute/Key Pairs + name: "myproject-key" + public: "/Users/username/.ssh/id_rsa.pub" + network: + name: "myproject-network" + subnet: + name: "ingress-network" + cidr: "192.168.1.0/24" + gateway_ip: "192.168.1.1" + security_group: + name: "myproject-security-group" + rules: + - protocol: tcp + port_range_min: 80 + port_range_max: 80 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 443 + port_range_max: 443 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 22 + port_range_max: 22 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 50 + port_range_max: 50 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 53 + port_range_max: 53 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 111 + port_range_max: 111 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 111 + port_range_max: 111 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 2049 + port_range_max: 2049 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 2049 + port_range_max: 2049 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 2377 + port_range_max: 2377 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 5353 + port_range_max: 5353 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 7946 + port_range_max: 7946 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 7946 + port_range_max: 7946 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 4789 + port_range_max: 4789 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 9001 + port_range_max: 9001 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 33333 + port_range_max: 33333 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 33333 + port_range_max: 33333 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + router: + name: "myproject-router" + network: "external" + vms: + gateway: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI small" + description: "Gateway Server" + host_groups: + - "gateway" + - "k8s_cluster" + - "masters" + - "swarmmanager" + - "swarmseed" + - "swarm" + - "nfsclient" + - "all" + rke2_type: "server" + # external ip to access project gateway + floating_ip: "129.70.51.247" + count: 1 + swarm: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI medium + ephemeral" + description: "Ephemeral fast local storage" + host_groups: + - "k8s_cluster" + - "masters" + - "swarmmanager" + - "swarm" + - "nfsclient" + - "swarmephemeral" + - "all" + rke2_type: "server" + count: 4 + swarmhighmem: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI highmem medium" + description: "High Mem Instances" + host_groups: + - "k8s_cluster" + - "workers" + - "swarm" + - "swarmworker" + - "swarmhighmem" + - "nfsclient" + - "all" + rke2_type: "agent" + count: 2 + nfsserver: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI small" + description: "NFS Server" + host_groups: + - "nfsserver" + - "all" + count: 1 + gpuserver: + image: "Ubuntu 22.04 LTS (2024-11-22)" + flavor: "de.NBI 2 GPU L4 medium + ephemeral" + description: "GPU Server" + host_groups: + - "workers" + - "swarm" + - "swarmworker" + - "nfsclient" + - "gpu" + - "all" + count: 1 diff --git a/_tutorials/ansible_openstack_services/tutorial.md b/_tutorials/ansible_openstack_services/tutorial.md index d2d3fc7..fb56329 100644 --- a/_tutorials/ansible_openstack_services/tutorial.md +++ b/_tutorials/ansible_openstack_services/tutorial.md @@ -14,16 +14,294 @@ objectives: key_points: - The take-home messages - They will appear at the end of the tutorial -version: 0.1 +version: main life_cycle: alpha contributions: authorship: - Nils Hoffmann - - author 2 editing: funding: --- -## Motivation +# Tutorial: Setting up a Docker Swarm Project with Ansible on OpenStack (de.NBI Cloud, Bielefeld) + +## Introduction + +This tutorial provides a step-by-step guide to setting up a Docker Swarm project using Ansible for automation and OpenStack integration on the de.NBI Cloud site in Bielefeld. The process involves preparing your local environment, configuring OpenStack resources, setting up Ansible, and deploying infrastructure and services. + +> ## Prerequisites +> This tutorial assumes a familiarity with the following concepts: +> - [Linux command line and SSH]( {% link _tutorials/unix-course/main/tutorial.md %} ) +> - [Basic knowledge of Ansible and YAML syntax](https://training.galaxyproject.org/training-material/topics/admin/tutorials/ansible/tutorial.html) +> - [Familiarity with OpenStack concepts (projects, flavors, networks)](https://cloud.denbi.de/wiki/Concept/basics/) +> - [Basic understanding of Docker and containerization](https://carpentries-incubator.github.io/docker-introduction/index.html) +> +> This tutorial is designed for advanced users who are comfortable with command-line tools, automation and who want to deploy and expose their own (bioinformatics) services to outside users. In order to follow along, you will **should** have an active OpenStack project on the de.NBI Cloud platform. If you do not have an account, please register at [de.NBI Cloud](https://cloud.denbi.de/) and apply for a project. +> Most steps in this tutorial can be adapted to other OpenStack providers with minor modifications. +> +{: .details} + +Note: This tutorial is generalized from the LipidCompass deployment playbooks. Docker Swarm setup is optional and can be skipped if not required for your project. + +## Concepts Covered + +- ssh key management and secure access +- OpenStack project and resource configuration +- Ansible basics and role-based architecture +- OpenStack resource management with Ansible +- Docker Swarm setup and service deployment +- Infrastructure-as-code principles + +## Prerequisites + +### Local Machine Setup + +Ensure the following software is installed on your local machine: + +- Ansible >= 2.16 +- Python >= 3.8 +- OpenStack SDK >= 4.0.0 + +Install the required Python packages in a virtual environment: + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip3 install -r requirements-pip.txt +``` + +Install necessary Ansible collections: + +```bash +ansible-galaxy collection install ansible.posix community.general openstack.cloud community.docker +``` + +### SSH Key Setup + +Generate or use an existing SSH key pair for secure connections: + +```bash +# Generate a new key pair (optional) +ssh-keygen -t rsa -b 4096 -C "your_email@example.com" +``` + +Refer to [de.NBI Cloud SSH setup guide](https://cloud.denbi.de/wiki/quickstart/#ssh-setup) for detailed instructions. + +## OpenStack Preparations + +### Create a New Project + +1. Access your OpenStack project dashboard. +2. Create a new project or select an existing one with appropriate permissions. +3. Ensure required VM flavors are available (check `group_vars/openstack.yml` for specifics). +4. Create a router named `-router` if it doesn't exist (under Network > Routers). + +### Configure OpenStack Credentials + +1. Go to Identity > Application Credentials. +2. Create new application credentials and save the secret securely. +3. Download the `clouds.yaml` file from API Access > Download OpenStack RC-File. +4. Place or append it to `~/.config/openstack/clouds.yaml`. +5. Edit the file to configure your cloud: + +```yaml +clouds: + -prod: + auth: + auth_url: https://openstack.cebitec.uni-bielefeld.de:5000 + application_credential_id: "your-application-credential-id" + application_credential_secret: "your-secret" + region_name: "Bielefeld" + interface: "public" + identity_api_version: 3 + auth_type: "v3applicationcredential" +``` + +## Ansible Configuration + +### Prepare Ansible Config + +1. Copy the template configuration: + +```bash +cp ansible.cfg.tmpl ansible.cfg +chmod go-rwx ansible.cfg +``` + +2. Review and adapt `ansible.cfg` as needed. + +### Update OpenStack Deployment Variables + +Edit `group_vars/openstack.yml` to set your SSH key path and other variables: + +```yaml +my: + openstack_cloud: "openstack" + openstack_project: "YourProjectName" + ssh: + key: + name: "YOUR_USER_NAME" + public: "/home/YOUR_USER_NAME/.ssh/ID_OF_YOUR_PUBLIC_KEY.pub" +``` + +### Configure SSH Access + +Add the following to your `~/.ssh/config` file: + +```bash +Host + HostName FLOATING_IP_OF_YOUR_JUMPHOST + IdentityFile ~/.ssh/ID_OF_YOUR_PRIVATE_KEY + User ubuntu + Port 22 + ForwardAgent yes + AddKeysToAgent yes + UserKnownHostsFile /dev/null + StrictHostKeyChecking no + +# Internal network subnet +Host 192.168.1.* + User ubuntu + IdentityFile ~/.ssh/ID_OF_YOUR_PRIVATE_KEY + Port 22 + ProxyJump +``` + +### Prepare Secrets + +1. Copy the secrets template: + +```bash +cp secrets.tmpl group_vars/all/secrets +``` + +2. Edit the secrets file with your passwords and sensitive data. +3. Encrypt the secrets file: + +```bash +ansible-vault encrypt group_vars/all/secrets +``` + +4. Set up the vault password file: + +```bash +mkdir -p ~/. +chmod -R go-rwx ~/. +chmod -R g+s ~/. +echo "your_vault_password" > ~/./vault.pwd +chmod o-rwx ~/./vault.pwd +``` + +## Deployment Configuration and Topology + +The main deployment configuration is located in `group_vars/openstack.yml`. This file defines the infrastructure topology, including VM flavors, network settings, and firewall rules. Adjust these settings to fit your project's requirements. + +> ## Customization of Deployment Configuration +> Please note that the provided configurations are examples and should be tailored to your specific needs and to the OpenStack quotas and available flavors in your project. +> The flavors defined in the example are based on the de.NBI Cloud OpenStack environment at the Bielefeld cloud site. +> +{: .details} + + + +## Bootstrapping the Infrastructure + +Run the bootstrap playbooks to set up the basic infrastructure: + +```bash +export ANSIBLE_CONFIG=ansible.bi.cfg +ansible-playbook bootstrap-openstack.yml +ansible-playbook bootstrap.yml +``` + +This process may take some time. The playbooks will create VMs, networks, and other necessary resources in your OpenStack project. + +## Service Configuration and Deployment + +Separation of concerns and DRY (Don't Repeat Yourself) are important design principles in software engineering and IT operations. For infrastructure-as-code, this means separating the configuration of different services into distinct roles and configurations, maintaining clear responsibilities. Ultimately, we want to avoid monolithic playbooks that handle everything in one place and instead have modular, reusable components, which can be granularly composed to form the desired infrastructure. + +To realize this requirement, Ansible supports you with the 'role' abstraction. + +### Introduction to Ansible Roles + +Ansible roles are self-contained units of configuration that can be shared and reused across different playbooks. Each role contains tasks, variables, files, templates, and handlers related to a specific functionality. Roles are defined in a directory structure below the 'roles' folder with specific subdirectories for each component. + +A helpful guide on creating Ansible roles can be found [here](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html). + +Roles can be understood as modular components that encapsulate specific configurations or functionalities, typically of a service, but also of cross-cutting functionalities. They help in organizing playbooks and promoting code reuse, following the DRY (Don't Repeat Yourself) principle. + +1. Create a custom ansible role for your application by creating a new directory in the `roles/` folder. + +The directory structure for a role with the name 'your_service_role' should look like this: + +```roles/ +└── your_service_role/ + ├── tasks/main.yml + ├── handlers/main.yml + ├── vars/main.yml + ├── templates/ + │ └── docker-compose.yml.j2 + └── files/ +``` + +2. Define tasks, handlers, variables, and templates specific to your service within the role's subdirectories. +3. Create a templated docker compose file for your service in `templates/`. + + +## Deploying Docker Swarm Infrastructure Services + +Deploy the core infrastructure services: + +```bash +ansible-playbook swarm-services.yml +``` + +This sets up services like monitoring, logging, and storage that your application may depend on. + +## Optional: Docker Swarm Setup + +If you need to set up Docker Swarm for container orchestration: + +```bash +ansible-playbook swarm-setup.yml +ansible-playbook swarm-bootstrap.yml +``` + +Then deploy your application stacks: + +```bash +ansible-playbook swarm-.yml # Replace with your application playbook +``` + +## Maintenance + +### Update and Upgrade + +To update packages and reboot if necessary: + +```bash +ansible-playbook update.yml reboot.yml +``` + +### Database Backup and Restore + +If your project includes databases, refer to the backup procedures in the original README for automated backups and manual restore processes. + +## Troubleshooting + +- Ensure all prerequisites are met and virtual environment is activated. +- Check OpenStack quotas and resource availability. +- Verify SSH connectivity and key permissions. +- Use `ansible-playbook --check` for dry-run testing. +- Check logs in `/var/log/ansible/` on target hosts. + +## Additional Resources + +- [Ansible Documentation](https://docs.ansible.com/) +- [OpenStack SDK Documentation](https://docs.openstack.org/openstacksdk/) +- [de.NBI Cloud Documentation](https://cloud.denbi.de/) +- [Docker Swarm Documentation](https://docs.docker.com/engine/swarm/) + +This tutorial provides a foundation for deploying containerized applications on OpenStack using Ansible. Adapt the playbooks and variables to fit your specific project requirements. From 44989d0f29f1e4b99f7e07f439030984ad063d45 Mon Sep 17 00:00:00 2001 From: Nils Hoffmann <3309580+nilshoffmann@users.noreply.github.com> Date: Wed, 21 Jan 2026 15:12:05 +0000 Subject: [PATCH 3/8] Starting new tutorial for Ansible OpenStack IaC on the de.NBI Cloud --- _data/tutorial_groups.yml | 3 +- .../ansible_openstack_services/tutorial.md | 29 +++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 _tutorials/ansible_openstack_services/tutorial.md diff --git a/_data/tutorial_groups.yml b/_data/tutorial_groups.yml index e9b6332..8469e9b 100644 --- a/_data/tutorial_groups.yml +++ b/_data/tutorial_groups.yml @@ -4,10 +4,11 @@ - unix-course - title: Cloud computing - description: Tutorials focused on using the de.NBI Cloud infrastructure and project types. + description: Introduction to cloud computing concepts and hands-on tutorials tutorials: - simpleVMWorkshop - bibigrid + - ansible_webservices_denbi_cloud - title: Machine Learning on Cloud infrastructure description: Tutorials focused on setting up machine learning toolkits and applications on cloud infrastructure. diff --git a/_tutorials/ansible_openstack_services/tutorial.md b/_tutorials/ansible_openstack_services/tutorial.md new file mode 100644 index 0000000..d2d3fc7 --- /dev/null +++ b/_tutorials/ansible_openstack_services/tutorial.md @@ -0,0 +1,29 @@ +--- +layout: tutorial_hands_on + +title: Using Ansible to Deploy and Operate (Web)Services on the de.NBI Cloud +description: This tutorial teaches you how to use Ansible to deploy and manage (web)services on the de.NBI Cloud OpenStack infrastructure. It introduces you to the basics of Ansible and guides you through writing infrastructure-as-code to automate the deployment and operation of your services, using Docker and optionally Docker Swarm. +slug: ansible_webservices_denbi_cloud +time_estimation: 1H +questions: + - Which questions are addressed by the tutorial? +objectives: + - Learn to access and use the de.NBI Cloud OpenStack API with Ansible + - Learn how to Write infrastructure-as-code using Ansible to deploy your (web)service + - Learn how to set up additional +key_points: +- The take-home messages +- They will appear at the end of the tutorial +version: 0.1 +life_cycle: alpha +contributions: + authorship: + - Nils Hoffmann + - author 2 + editing: + funding: +--- + +## Motivation + + From 74cbb49fabfe5a837a484f80f17be9520ff02273 Mon Sep 17 00:00:00 2001 From: Nils Hoffmann <3309580+nilshoffmann@users.noreply.github.com> Date: Wed, 4 Feb 2026 12:26:03 +0000 Subject: [PATCH 4/8] First commit for Ansible, OpenStack, Swarm service project. --- _data/tutorial_groups.yml | 5 +- .../resources/openstack.yml | 190 ++++++++++++ .../ansible_openstack_services/tutorial.md | 284 +++++++++++++++++- 3 files changed, 473 insertions(+), 6 deletions(-) create mode 100644 _tutorials/ansible_openstack_services/resources/openstack.yml diff --git a/_data/tutorial_groups.yml b/_data/tutorial_groups.yml index 8469e9b..13f0225 100644 --- a/_data/tutorial_groups.yml +++ b/_data/tutorial_groups.yml @@ -4,11 +4,10 @@ - unix-course - title: Cloud computing - description: Introduction to cloud computing concepts and hands-on tutorials + description: Tutorials focused on using the de.NBI Cloud infrastructure and project types. tutorials: - simpleVMWorkshop - bibigrid - - ansible_webservices_denbi_cloud - title: Machine Learning on Cloud infrastructure description: Tutorials focused on setting up machine learning toolkits and applications on cloud infrastructure. @@ -28,7 +27,7 @@ - DM_in_the_deNBI_cloud - title: Metagenomics - description: Tutorials focused on handling of metagenomics sequencing data + description: Tutorials focused on handling of metagenomics sequencing data. tutorials: - basicsAmpliconQC diff --git a/_tutorials/ansible_openstack_services/resources/openstack.yml b/_tutorials/ansible_openstack_services/resources/openstack.yml new file mode 100644 index 0000000..3cbb697 --- /dev/null +++ b/_tutorials/ansible_openstack_services/resources/openstack.yml @@ -0,0 +1,190 @@ +my: + ansible_host: "129.70.51.190" + openstack_cloud: "myproject-prod" + openstack_project: "myproject" + openstack_site: "Bielefeld" + ssh: + key: + #the keyname in openstack under Compute/Key Pairs + name: "myproject-key" + public: "/Users/username/.ssh/id_rsa.pub" + network: + name: "myproject-network" + subnet: + name: "ingress-network" + cidr: "192.168.1.0/24" + gateway_ip: "192.168.1.1" + security_group: + name: "myproject-security-group" + rules: + - protocol: tcp + port_range_min: 80 + port_range_max: 80 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 443 + port_range_max: 443 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 22 + port_range_max: 22 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 50 + port_range_max: 50 + remote_ip_prefix: 0.0.0.0/0 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 53 + port_range_max: 53 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 111 + port_range_max: 111 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 111 + port_range_max: 111 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 2049 + port_range_max: 2049 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 2049 + port_range_max: 2049 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 2377 + port_range_max: 2377 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 5353 + port_range_max: 5353 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 7946 + port_range_max: 7946 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 7946 + port_range_max: 7946 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 4789 + port_range_max: 4789 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 9001 + port_range_max: 9001 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: tcp + port_range_min: 33333 + port_range_max: 33333 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + - protocol: udp + port_range_min: 33333 + port_range_max: 33333 + remote_ip_prefix: 192.168.1.0/24 + direction: ingress + ethertype: IPv4 + router: + name: "myproject-router" + network: "external" + vms: + gateway: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI small" + description: "Gateway Server" + host_groups: + - "gateway" + - "k8s_cluster" + - "masters" + - "swarmmanager" + - "swarmseed" + - "swarm" + - "nfsclient" + - "all" + rke2_type: "server" + # external ip to access project gateway + floating_ip: "129.70.51.247" + count: 1 + swarm: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI medium + ephemeral" + description: "Ephemeral fast local storage" + host_groups: + - "k8s_cluster" + - "masters" + - "swarmmanager" + - "swarm" + - "nfsclient" + - "swarmephemeral" + - "all" + rke2_type: "server" + count: 4 + swarmhighmem: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI highmem medium" + description: "High Mem Instances" + host_groups: + - "k8s_cluster" + - "workers" + - "swarm" + - "swarmworker" + - "swarmhighmem" + - "nfsclient" + - "all" + rke2_type: "agent" + count: 2 + nfsserver: + image: "Ubuntu 22.04 LTS (2024-07-03)" + flavor: "de.NBI small" + description: "NFS Server" + host_groups: + - "nfsserver" + - "all" + count: 1 + gpuserver: + image: "Ubuntu 22.04 LTS (2024-11-22)" + flavor: "de.NBI 2 GPU L4 medium + ephemeral" + description: "GPU Server" + host_groups: + - "workers" + - "swarm" + - "swarmworker" + - "nfsclient" + - "gpu" + - "all" + count: 1 diff --git a/_tutorials/ansible_openstack_services/tutorial.md b/_tutorials/ansible_openstack_services/tutorial.md index d2d3fc7..fb56329 100644 --- a/_tutorials/ansible_openstack_services/tutorial.md +++ b/_tutorials/ansible_openstack_services/tutorial.md @@ -14,16 +14,294 @@ objectives: key_points: - The take-home messages - They will appear at the end of the tutorial -version: 0.1 +version: main life_cycle: alpha contributions: authorship: - Nils Hoffmann - - author 2 editing: funding: --- -## Motivation +# Tutorial: Setting up a Docker Swarm Project with Ansible on OpenStack (de.NBI Cloud, Bielefeld) + +## Introduction + +This tutorial provides a step-by-step guide to setting up a Docker Swarm project using Ansible for automation and OpenStack integration on the de.NBI Cloud site in Bielefeld. The process involves preparing your local environment, configuring OpenStack resources, setting up Ansible, and deploying infrastructure and services. + +> ## Prerequisites +> This tutorial assumes a familiarity with the following concepts: +> - [Linux command line and SSH]( {% link _tutorials/unix-course/main/tutorial.md %} ) +> - [Basic knowledge of Ansible and YAML syntax](https://training.galaxyproject.org/training-material/topics/admin/tutorials/ansible/tutorial.html) +> - [Familiarity with OpenStack concepts (projects, flavors, networks)](https://cloud.denbi.de/wiki/Concept/basics/) +> - [Basic understanding of Docker and containerization](https://carpentries-incubator.github.io/docker-introduction/index.html) +> +> This tutorial is designed for advanced users who are comfortable with command-line tools, automation and who want to deploy and expose their own (bioinformatics) services to outside users. In order to follow along, you will **should** have an active OpenStack project on the de.NBI Cloud platform. If you do not have an account, please register at [de.NBI Cloud](https://cloud.denbi.de/) and apply for a project. +> Most steps in this tutorial can be adapted to other OpenStack providers with minor modifications. +> +{: .details} + +Note: This tutorial is generalized from the LipidCompass deployment playbooks. Docker Swarm setup is optional and can be skipped if not required for your project. + +## Concepts Covered + +- ssh key management and secure access +- OpenStack project and resource configuration +- Ansible basics and role-based architecture +- OpenStack resource management with Ansible +- Docker Swarm setup and service deployment +- Infrastructure-as-code principles + +## Prerequisites + +### Local Machine Setup + +Ensure the following software is installed on your local machine: + +- Ansible >= 2.16 +- Python >= 3.8 +- OpenStack SDK >= 4.0.0 + +Install the required Python packages in a virtual environment: + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip3 install -r requirements-pip.txt +``` + +Install necessary Ansible collections: + +```bash +ansible-galaxy collection install ansible.posix community.general openstack.cloud community.docker +``` + +### SSH Key Setup + +Generate or use an existing SSH key pair for secure connections: + +```bash +# Generate a new key pair (optional) +ssh-keygen -t rsa -b 4096 -C "your_email@example.com" +``` + +Refer to [de.NBI Cloud SSH setup guide](https://cloud.denbi.de/wiki/quickstart/#ssh-setup) for detailed instructions. + +## OpenStack Preparations + +### Create a New Project + +1. Access your OpenStack project dashboard. +2. Create a new project or select an existing one with appropriate permissions. +3. Ensure required VM flavors are available (check `group_vars/openstack.yml` for specifics). +4. Create a router named `-router` if it doesn't exist (under Network > Routers). + +### Configure OpenStack Credentials + +1. Go to Identity > Application Credentials. +2. Create new application credentials and save the secret securely. +3. Download the `clouds.yaml` file from API Access > Download OpenStack RC-File. +4. Place or append it to `~/.config/openstack/clouds.yaml`. +5. Edit the file to configure your cloud: + +```yaml +clouds: + -prod: + auth: + auth_url: https://openstack.cebitec.uni-bielefeld.de:5000 + application_credential_id: "your-application-credential-id" + application_credential_secret: "your-secret" + region_name: "Bielefeld" + interface: "public" + identity_api_version: 3 + auth_type: "v3applicationcredential" +``` + +## Ansible Configuration + +### Prepare Ansible Config + +1. Copy the template configuration: + +```bash +cp ansible.cfg.tmpl ansible.cfg +chmod go-rwx ansible.cfg +``` + +2. Review and adapt `ansible.cfg` as needed. + +### Update OpenStack Deployment Variables + +Edit `group_vars/openstack.yml` to set your SSH key path and other variables: + +```yaml +my: + openstack_cloud: "openstack" + openstack_project: "YourProjectName" + ssh: + key: + name: "YOUR_USER_NAME" + public: "/home/YOUR_USER_NAME/.ssh/ID_OF_YOUR_PUBLIC_KEY.pub" +``` + +### Configure SSH Access + +Add the following to your `~/.ssh/config` file: + +```bash +Host + HostName FLOATING_IP_OF_YOUR_JUMPHOST + IdentityFile ~/.ssh/ID_OF_YOUR_PRIVATE_KEY + User ubuntu + Port 22 + ForwardAgent yes + AddKeysToAgent yes + UserKnownHostsFile /dev/null + StrictHostKeyChecking no + +# Internal network subnet +Host 192.168.1.* + User ubuntu + IdentityFile ~/.ssh/ID_OF_YOUR_PRIVATE_KEY + Port 22 + ProxyJump +``` + +### Prepare Secrets + +1. Copy the secrets template: + +```bash +cp secrets.tmpl group_vars/all/secrets +``` + +2. Edit the secrets file with your passwords and sensitive data. +3. Encrypt the secrets file: + +```bash +ansible-vault encrypt group_vars/all/secrets +``` + +4. Set up the vault password file: + +```bash +mkdir -p ~/. +chmod -R go-rwx ~/. +chmod -R g+s ~/. +echo "your_vault_password" > ~/./vault.pwd +chmod o-rwx ~/./vault.pwd +``` + +## Deployment Configuration and Topology + +The main deployment configuration is located in `group_vars/openstack.yml`. This file defines the infrastructure topology, including VM flavors, network settings, and firewall rules. Adjust these settings to fit your project's requirements. + +> ## Customization of Deployment Configuration +> Please note that the provided configurations are examples and should be tailored to your specific needs and to the OpenStack quotas and available flavors in your project. +> The flavors defined in the example are based on the de.NBI Cloud OpenStack environment at the Bielefeld cloud site. +> +{: .details} + + + +## Bootstrapping the Infrastructure + +Run the bootstrap playbooks to set up the basic infrastructure: + +```bash +export ANSIBLE_CONFIG=ansible.bi.cfg +ansible-playbook bootstrap-openstack.yml +ansible-playbook bootstrap.yml +``` + +This process may take some time. The playbooks will create VMs, networks, and other necessary resources in your OpenStack project. + +## Service Configuration and Deployment + +Separation of concerns and DRY (Don't Repeat Yourself) are important design principles in software engineering and IT operations. For infrastructure-as-code, this means separating the configuration of different services into distinct roles and configurations, maintaining clear responsibilities. Ultimately, we want to avoid monolithic playbooks that handle everything in one place and instead have modular, reusable components, which can be granularly composed to form the desired infrastructure. + +To realize this requirement, Ansible supports you with the 'role' abstraction. + +### Introduction to Ansible Roles + +Ansible roles are self-contained units of configuration that can be shared and reused across different playbooks. Each role contains tasks, variables, files, templates, and handlers related to a specific functionality. Roles are defined in a directory structure below the 'roles' folder with specific subdirectories for each component. + +A helpful guide on creating Ansible roles can be found [here](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html). + +Roles can be understood as modular components that encapsulate specific configurations or functionalities, typically of a service, but also of cross-cutting functionalities. They help in organizing playbooks and promoting code reuse, following the DRY (Don't Repeat Yourself) principle. + +1. Create a custom ansible role for your application by creating a new directory in the `roles/` folder. + +The directory structure for a role with the name 'your_service_role' should look like this: + +```roles/ +└── your_service_role/ + ├── tasks/main.yml + ├── handlers/main.yml + ├── vars/main.yml + ├── templates/ + │ └── docker-compose.yml.j2 + └── files/ +``` + +2. Define tasks, handlers, variables, and templates specific to your service within the role's subdirectories. +3. Create a templated docker compose file for your service in `templates/`. + + +## Deploying Docker Swarm Infrastructure Services + +Deploy the core infrastructure services: + +```bash +ansible-playbook swarm-services.yml +``` + +This sets up services like monitoring, logging, and storage that your application may depend on. + +## Optional: Docker Swarm Setup + +If you need to set up Docker Swarm for container orchestration: + +```bash +ansible-playbook swarm-setup.yml +ansible-playbook swarm-bootstrap.yml +``` + +Then deploy your application stacks: + +```bash +ansible-playbook swarm-.yml # Replace with your application playbook +``` + +## Maintenance + +### Update and Upgrade + +To update packages and reboot if necessary: + +```bash +ansible-playbook update.yml reboot.yml +``` + +### Database Backup and Restore + +If your project includes databases, refer to the backup procedures in the original README for automated backups and manual restore processes. + +## Troubleshooting + +- Ensure all prerequisites are met and virtual environment is activated. +- Check OpenStack quotas and resource availability. +- Verify SSH connectivity and key permissions. +- Use `ansible-playbook --check` for dry-run testing. +- Check logs in `/var/log/ansible/` on target hosts. + +## Additional Resources + +- [Ansible Documentation](https://docs.ansible.com/) +- [OpenStack SDK Documentation](https://docs.openstack.org/openstacksdk/) +- [de.NBI Cloud Documentation](https://cloud.denbi.de/) +- [Docker Swarm Documentation](https://docs.docker.com/engine/swarm/) + +This tutorial provides a foundation for deploying containerized applications on OpenStack using Ansible. Adapt the playbooks and variables to fit your specific project requirements. From 49fc9e835f014746686db8181f0935147957f35a Mon Sep 17 00:00:00 2001 From: Nils Hoffmann <3309580+nilshoffmann@users.noreply.github.com> Date: Wed, 15 Apr 2026 09:21:53 +0200 Subject: [PATCH 5/8] Added tutorial to groups --- _data/tutorial_groups.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/_data/tutorial_groups.yml b/_data/tutorial_groups.yml index 13f0225..0cbaf5d 100644 --- a/_data/tutorial_groups.yml +++ b/_data/tutorial_groups.yml @@ -8,6 +8,7 @@ tutorials: - simpleVMWorkshop - bibigrid + - ansible_webservices_denbi_cloud - title: Machine Learning on Cloud infrastructure description: Tutorials focused on setting up machine learning toolkits and applications on cloud infrastructure. From ea1f9577220a89f2a3befbe2cd288489425962b4 Mon Sep 17 00:00:00 2001 From: Dilfuza Djamalova <53920815+ddjamalova@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:55:55 +0200 Subject: [PATCH 6/8] fix tutorial metadata Updated tutorial metadata and box titles --- _tutorials/ansible_openstack_services/tutorial.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/_tutorials/ansible_openstack_services/tutorial.md b/_tutorials/ansible_openstack_services/tutorial.md index fb56329..a1d8ee9 100644 --- a/_tutorials/ansible_openstack_services/tutorial.md +++ b/_tutorials/ansible_openstack_services/tutorial.md @@ -3,8 +3,9 @@ layout: tutorial_hands_on title: Using Ansible to Deploy and Operate (Web)Services on the de.NBI Cloud description: This tutorial teaches you how to use Ansible to deploy and manage (web)services on the de.NBI Cloud OpenStack infrastructure. It introduces you to the basics of Ansible and guides you through writing infrastructure-as-code to automate the deployment and operation of your services, using Docker and optionally Docker Swarm. -slug: ansible_webservices_denbi_cloud time_estimation: 1H +level: beginner +keywords: [ansible, openstack, docker] questions: - Which questions are addressed by the tutorial? objectives: @@ -15,7 +16,7 @@ key_points: - The take-home messages - They will appear at the end of the tutorial version: main -life_cycle: alpha +life_cycle: under development contributions: authorship: - Nils Hoffmann @@ -23,13 +24,13 @@ contributions: funding: --- -# Tutorial: Setting up a Docker Swarm Project with Ansible on OpenStack (de.NBI Cloud, Bielefeld) +## Tutorial: Setting up a Docker Swarm Project with Ansible on OpenStack (de.NBI Cloud, Bielefeld) ## Introduction This tutorial provides a step-by-step guide to setting up a Docker Swarm project using Ansible for automation and OpenStack integration on the de.NBI Cloud site in Bielefeld. The process involves preparing your local environment, configuring OpenStack resources, setting up Ansible, and deploying infrastructure and services. -> ## Prerequisites +>Prerequisites > This tutorial assumes a familiarity with the following concepts: > - [Linux command line and SSH]( {% link _tutorials/unix-course/main/tutorial.md %} ) > - [Basic knowledge of Ansible and YAML syntax](https://training.galaxyproject.org/training-material/topics/admin/tutorials/ansible/tutorial.html) @@ -196,7 +197,7 @@ chmod o-rwx ~/./vault.pwd The main deployment configuration is located in `group_vars/openstack.yml`. This file defines the infrastructure topology, including VM flavors, network settings, and firewall rules. Adjust these settings to fit your project's requirements. -> ## Customization of Deployment Configuration +>Customization of Deployment Configuration > Please note that the provided configurations are examples and should be tailored to your specific needs and to the OpenStack quotas and available flavors in your project. > The flavors defined in the example are based on the de.NBI Cloud OpenStack environment at the Bielefeld cloud site. > From 42b5ac5a26e461770906b7d03e3e310a677db566 Mon Sep 17 00:00:00 2001 From: Dilfuza Djamalova <53920815+ddjamalova@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:56:45 +0200 Subject: [PATCH 7/8] fix tutorial group --- _data/tutorial_groups.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_data/tutorial_groups.yml b/_data/tutorial_groups.yml index 0cbaf5d..f262752 100644 --- a/_data/tutorial_groups.yml +++ b/_data/tutorial_groups.yml @@ -8,7 +8,7 @@ tutorials: - simpleVMWorkshop - bibigrid - - ansible_webservices_denbi_cloud + - ansible_openstack_services - title: Machine Learning on Cloud infrastructure description: Tutorials focused on setting up machine learning toolkits and applications on cloud infrastructure. From 9863d86a02c3f1f60416fa7319e15197b587df1d Mon Sep 17 00:00:00 2001 From: Dilfuza Djamalova <53920815+ddjamalova@users.noreply.github.com> Date: Mon, 1 Jun 2026 09:11:47 +0200 Subject: [PATCH 8/8] fix tutorial level and add objectives Updated tutorial level to advanced and added question and objectives. --- _tutorials/ansible_openstack_services/tutorial.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_tutorials/ansible_openstack_services/tutorial.md b/_tutorials/ansible_openstack_services/tutorial.md index a1d8ee9..2236b6d 100644 --- a/_tutorials/ansible_openstack_services/tutorial.md +++ b/_tutorials/ansible_openstack_services/tutorial.md @@ -4,14 +4,14 @@ layout: tutorial_hands_on title: Using Ansible to Deploy and Operate (Web)Services on the de.NBI Cloud description: This tutorial teaches you how to use Ansible to deploy and manage (web)services on the de.NBI Cloud OpenStack infrastructure. It introduces you to the basics of Ansible and guides you through writing infrastructure-as-code to automate the deployment and operation of your services, using Docker and optionally Docker Swarm. time_estimation: 1H -level: beginner +level: advanced keywords: [ansible, openstack, docker] questions: - - Which questions are addressed by the tutorial? + - How do Ansible roles and Docker Swarm enable modular, reproducible deployment of containerized services on OpenStack? objectives: - - Learn to access and use the de.NBI Cloud OpenStack API with Ansible - - Learn how to Write infrastructure-as-code using Ansible to deploy your (web)service - - Learn how to set up additional + - Learn to access and use the de.NBI Cloud OpenStack API with Ansible. + - Learn how to write infrastructure-as-code using Ansible to deploy your (web)service. + - Learn how to set up additional Docker swarm for container orchestration. key_points: - The take-home messages - They will appear at the end of the tutorial