Ansible

uv tool install ansible-core  # or: pipx install ansible-core
uvx --from ansible-core ansible --version  # no install
ansible-galaxy collection install community.general
ansible-galaxy collection install -r requirements.yml
ansible-galaxy collection list
ansible-doc ansible.builtin.copy   # docs + examples
ansible-doc -l community.docker    # list a collection

collections:
  - name: community.general
    version: ">=13.0.0"
  - name: community.docker
  - name: ansible.posix
roles:
  - name: geerlingguy.docker

[defaults]
inventory = inventory/
roles_path = roles
collections_path = ./collections
remote_user = deploy
host_key_checking = True
forks = 20
stdout_callback = ansible.builtin.default
callback_result_format = yaml
vault_password_file = ~/.vault_pass
interpreter_python = auto_silent
retry_files_enabled = False
 
[privilege_escalation]
become = True
become_method = sudo
 
[ssh_connection]
pipelining = True
ssh_args = -o ControlMaster=auto -o ControlPersist=60s

[web]
web1.example.com
web[2:4].example.com ansible_user=ubuntu
 
[db]
db1 ansible_host=10.0.0.21 ansible_port=2222
 
[prod:children]
web
db
 
[prod:vars]
env=prod

all:
  children:
    web:
      hosts:
        web1.example.com:
        web2.example.com:
          http_port: 8080
    db:
      hosts:
        db1:
          ansible_host: 10.0.0.21
    prod:
      children:
        web:
        db:
      vars:
        env: prod

ansible-inventory -i inventory/ --graph
ansible-inventory -i inventory/ --host web1.example.com
ansible-inventory -i inventory/ --list -y

plugin: amazon.aws.aws_ec2
regions: [eu-west-1]
filters:
  tag:Env: prod
keyed_groups:
  - key: tags.Role
    prefix: role
hostnames: [private-ip-address]

ansible all -m ansible.builtin.ping
ansible web -a "uptime"                  # default: command
ansible web -m ansible.builtin.shell -a "df -h | grep /$"
ansible db -b -m ansible.builtin.apt \
  -a "name=htop state=present update_cache=true"
ansible web -b -m ansible.builtin.service \
  -a "name=nginx state=restarted"
ansible all -m ansible.builtin.setup \
  -a "filter=ansible_distribution*"
ansible web -m ansible.builtin.copy \
  -a "src=motd dest=/etc/motd" -b --check --diff
ansible 'web:!web1*' -f 50 -a "systemctl is-active app"

- name: Configure web servers
  hosts: web
  become: true
  gather_facts: true
  vars:
    app_port: 3000
  vars_files:
    - vars/common.yml
 
  pre_tasks:
    - name: Refresh apt cache
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600
 
  roles:
    - common
    - role: nginx
      vars:
        nginx_port: 80
 
  tasks:
    - name: Install packages
      ansible.builtin.apt:
        name: [git, curl]
        state: present
 
    - name: Write nginx config
      ansible.builtin.template:
        src: site.conf.j2
        dest: /etc/nginx/sites-enabled/app.conf
        mode: "0644"
      notify: Reload nginx
 
  handlers:
    - name: Reload nginx
      ansible.builtin.systemd_service:
        name: nginx
        state: reloaded

tasks:
  - name: Update app config
    ansible.builtin.template:
      src: app.env.j2
      dest: /etc/app/app.env
      mode: "0640"
    notify:
      - Restart app
 
  - name: Flush now, not at end of play
    ansible.builtin.meta: flush_handlers
 
handlers:
  - name: Restart app
    ansible.builtin.systemd_service:
      name: app
      state: restarted
      daemon_reload: true
    listen: app changed   # notify "app changed" works too

- name: Initialize database once
  ansible.builtin.command:
    cmd: /opt/app/bin/migrate --init
    creates: /var/lib/app/.initialized
 
- name: Probe without reporting a change
  ansible.builtin.command:
    cmd: grep -q '^FEATURE_X=1' /etc/app/app.env
  register: feature_x
  changed_when: false
  failed_when: feature_x.rc not in [0, 1]

- name: Show facts
  ansible.builtin.debug:
    msg: >-
      {{ ansible_facts['distribution'] }}
      {{ ansible_facts['distribution_version'] }},
      {{ ansible_facts['memtotal_mb'] }} MB,
      {{ ansible_facts['default_ipv4']['address'] }}

{{ ansible_managed | comment }}
PORT={{ app_port }}
NODE_ENV={{ env | default('production') }}
DB_HOSTS={{ groups['db'] | map('extract', hostvars,
  'ansible_host') | join(',') }}
{% for key, value in app_env | dictsort %}
{{ key | upper }}={{ value }}
{% endfor %}
{% if enable_debug | bool %}
LOG_LEVEL=debug
{% endif %}

- name: Only on Ubuntu 24.04+
  ansible.builtin.apt:
    name: needrestart
  when:
    - ansible_facts['distribution'] == 'Ubuntu'
    - >-
      ansible_facts['distribution_version']
      is version('24.04', '>=')
 
- name: Create users
  ansible.builtin.user:
    name: "{{ item.name }}"
    groups: "{{ item.groups | default([]) }}"
    append: true
  loop: "{{ users }}"
  loop_control:
    label: "{{ item.name }}"   # shorter output
 
- name: Check health endpoint
  ansible.builtin.uri:
    url: http://localhost:3000/health
  register: health
  until: health.status == 200
  retries: 10
  delay: 3
 
- name: Fail with context
  ansible.builtin.fail:
    msg: "unhealthy: {{ health.status }}"
  when: health is failed

- name: Deploy with rollback
  block:
    - name: Run migration
      ansible.builtin.command: /opt/app/bin/migrate
      run_once: true
      changed_when: true
  rescue:
    - name: Roll back
      ansible.builtin.command: /opt/app/bin/migrate --down
      run_once: true
      changed_when: true
  always:
    - name: Report
      ansible.builtin.debug:
        msg: "migration finished"

ansible-galaxy role init roles/nginx
ansible-galaxy collection init acme.platform
ansible-galaxy role install geerlingguy.docker

argument_specs:
  main:
    short_description: Install and configure nginx
    options:
      nginx_port:
        type: int
        default: 80
      nginx_server_name:
        type: str
        required: true

- name: Use a role three ways
  hosts: web
  roles:
    - nginx                      # static, at play start
  tasks:
    - name: Static import
      ansible.builtin.import_role:
        name: nginx
    - name: Dynamic, conditional
      ansible.builtin.include_role:
        name: nginx
        tasks_from: install
      when: install_nginx | bool

ansible-playbook -i inventory/prod site.yml
ansible-playbook site.yml --syntax-check
ansible-playbook site.yml --list-hosts --list-tasks
ansible-playbook site.yml --check --diff     # dry run
ansible-playbook site.yml -l web1.example.com
ansible-playbook site.yml -t nginx,config
ansible-playbook site.yml --skip-tags slow
ansible-playbook site.yml --start-at-task "Install packages"
ansible-playbook site.yml --step             # confirm each
ansible-playbook site.yml -e app_version=1.4.2
ansible-playbook site.yml -e @vars/release.yml

ansible-vault create group_vars/prod/vault.yml
ansible-vault edit group_vars/prod/vault.yml
ansible-vault encrypt secrets.yml        # in place
ansible-vault decrypt secrets.yml
ansible-vault view secrets.yml
ansible-vault rekey secrets.yml
ansible-vault encrypt_string 'hunter2' --name db_password
ansible-playbook site.yml --ask-vault-pass
ansible-playbook site.yml --vault-password-file ~/.vp
ansible-playbook site.yml \
  --vault-id prod@~/.vp-prod --vault-id dev@prompt

db_password: "{{ vault_db_password }}"   # visible name

vault_db_password: s3cr3t

uvx ansible-lint                  # lint the project
uvx ansible-lint --fix            # autofix fqcn, yaml, etc.
uvx ansible-lint --profile production
molecule init scenario default    # in a role or project
molecule test                     # full sequence
molecule converge && molecule verify
molecule login                    # shell into the instance
molecule destroy

profile: production
exclude_paths:
  - collections/
skip_list:
  - yaml[line-length]

- name: Bootstrap
  hosts: new
  become: true
  tasks:
    - name: Admin user
      ansible.builtin.user:
        name: deploy
        groups: sudo
        append: true
        shell: /bin/bash
    - name: Authorized key
      ansible.posix.authorized_key:
        user: deploy
        key: "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"
    - name: Packages
      ansible.builtin.apt:
        name: [ufw, unattended-upgrades, fail2ban]
        update_cache: true
    - name: Harden
      ansible.builtin.import_tasks: harden.yml
  handlers:
    - name: Reload ssh
      ansible.builtin.systemd_service:
        name: ssh
        state: reloaded

- name: Key-only SSH, no root
  ansible.builtin.copy:
    dest: /etc/ssh/sshd_config.d/10-hardening.conf
    content: |
      PasswordAuthentication no
      PermitRootLogin no
    mode: "0644"
    validate: /usr/sbin/sshd -t -f %s
  notify: Reload ssh
- name: Allow SSH through ufw
  community.general.ufw:
    rule: allow
    name: OpenSSH
- name: Enable ufw, deny other incoming
  community.general.ufw:
    state: enabled
    policy: deny
- name: Enable unattended upgrades
  ansible.builtin.copy:
    dest: /etc/apt/apt.conf.d/20auto-upgrades
    content: |
      APT::Periodic::Update-Package-Lists "1";
      APT::Periodic::Unattended-Upgrade "1";
    mode: "0644"

- name: Docker repo
  ansible.builtin.deb822_repository:
    name: docker
    uris: https://download.docker.com/linux/ubuntu
    suites: "{{ ansible_facts['distribution_release'] }}"
    components: stable
    signed_by: https://download.docker.com/linux/ubuntu/gpg
- name: Docker engine and compose plugin
  ansible.builtin.apt:
    name:
      - docker-ce
      - docker-ce-cli
      - containerd.io
      - docker-compose-plugin
    update_cache: true
- name: Project files
  ansible.builtin.copy:
    src: app/
    dest: /opt/app/
    mode: preserve
- name: Compose up
  community.docker.docker_compose_v2:
    project_src: /opt/app
    remove_orphans: true
    wait: true

- name: Checkout release
  ansible.builtin.git:
    repo: https://github.com/acme/app.git
    dest: /srv/app
    version: "{{ app_version }}"
  become: true
  become_user: app
  notify: Restart app
- name: Install dependencies
  ansible.builtin.command:
    cmd: bun install --frozen-lockfile --production
    chdir: /srv/app
  become: true
  become_user: app
  changed_when: false
- name: Enabled and running
  ansible.builtin.systemd_service:
    name: app
    enabled: true
    state: started

server {
  listen 80;
  server_name {{ nginx_server_name }};
  location / {
    proxy_pass http://127.0.0.1:{{ app_port }};
    proxy_set_header Host $host;
  }
}

- name: Site config
  ansible.builtin.template:
    src: site.conf.j2
    dest: /etc/nginx/sites-available/app.conf
    mode: "0644"
  notify: Reload nginx
- name: Enable site
  ansible.builtin.file:
    src: /etc/nginx/sites-available/app.conf
    dest: /etc/nginx/sites-enabled/app.conf
    state: link
  notify: Reload nginx
- name: Validate
  ansible.builtin.command: nginx -t
  changed_when: false

- name: Rolling deploy
  hosts: web
  serial: [1, "25%"]         # canary, then quarters
  max_fail_percentage: 0
  pre_tasks:
    - name: Drain from LB
      ansible.builtin.command: >-
        lbctl disable {{ inventory_hostname }}
      delegate_to: lb1
      changed_when: true
  roles:
    - app
  post_tasks:
    - name: Wait until healthy
      ansible.builtin.uri:
        url: "http://{{ inventory_hostname }}:3000/health"
      register: h
      until: h.status == 200
      retries: 20
      delay: 3
    - name: Back into LB
      ansible.builtin.command: >-
        lbctl enable {{ inventory_hostname }}
      delegate_to: lb1
      changed_when: true

ansible-vault encrypt_string --vault-id prod@prompt \
  'p4ssw0rd' --name vault_db_password \
  >> group_vars/prod/vars.yml

- name: Write DB credentials
  ansible.builtin.template:
    src: db.env.j2
    dest: /etc/app/db.env
    mode: "0600"
    owner: app
  no_log: true