Ansible shell vs command vs raw: When to Use Each Module (Comparison)

- name: Check disk space
  ansible.builtin.command: df -h /
  register: disk_space
  changed_when: false

- name: Get hostname
  ansible.builtin.command: hostname -f
  register: fqdn
  changed_when: false

- name: Run a binary with arguments
  ansible.builtin.command:
    cmd: /opt/app/bin/migrate --direction up
    chdir: /opt/app
  register: migration

# ❌ FAILS — no pipe support
- ansible.builtin.command: cat /etc/passwd | grep root

# ❌ FAILS — no redirect
- ansible.builtin.command: echo "hello" > /tmp/file.txt

# ❌ FAILS — no glob expansion
- ansible.builtin.command: ls /tmp/*.log

# ❌ FAILS — no environment variable expansion
- ansible.builtin.command: echo $HOME

# With shell, this is dangerous:
- ansible.builtin.shell: "rm -rf {{ user_input }}/"
# If user_input contains "; rm -rf /" → catastrophic

# With command, shell injection is impossible:
- ansible.builtin.command: "rm -rf {{ user_input }}/"
# Arguments are passed directly, no shell interpretation

- name: Find large files (pipe needed)
  ansible.builtin.shell: find /var/log -size +100M | head -20
  register: large_files
  changed_when: false

- name: Redirect output to file
  ansible.builtin.shell: mysqldump mydb > /tmp/backup.sql
  args:
    creates: /tmp/backup.sql

- name: Use environment variable
  ansible.builtin.shell: source /opt/app/.env && /opt/app/bin/start
  args:
    executable: /bin/bash

# ❌ BAD — always reports changed
- name: Create user
  ansible.builtin.shell: useradd appuser

# ✅ GOOD — creates prevents re-execution
- name: Create user
  ansible.builtin.shell: useradd appuser
  args:
    creates: /home/appuser

# ✅ GOOD — changed_when based on output
- name: Run database migration
  ansible.builtin.shell: /opt/app/bin/migrate up
  register: migrate_result
  changed_when: "'Migrated' in migrate_result.stdout"

# ✅ BEST — use the actual user module
- name: Create user
  ansible.builtin.user:
    name: appuser
    state: present

# Install Python on a minimal system (bootstrap)
- name: Install Python for Ansible
  ansible.builtin.raw: apt-get update && apt-get install -y python3
  become: true
  changed_when: false

# Network device without Python
- name: Show interface status
  ansible.builtin.raw: show interface brief
  register: interface_status

# ❌ shell — fragile, not idempotent
- ansible.builtin.shell: apt-get install -y nginx

# ✅ Module — idempotent, cross-platform
- ansible.builtin.apt:
    name: nginx
    state: present

# ❌ shell
- ansible.builtin.shell: systemctl restart nginx

# ✅ Module
- ansible.builtin.systemd:
    name: nginx
    state: restarted

# ❌ shell
- ansible.builtin.shell: cp /tmp/file /etc/file && chmod 644 /etc/file

# ✅ Module
- ansible.builtin.copy:
    src: /tmp/file
    dest: /etc/file
    mode: '0644'
    remote_src: true

# ❌ shell
- ansible.builtin.shell: "echo '{{ line }}' >> /etc/config"

# ✅ Module
- ansible.builtin.lineinfile:
    path: /etc/config
    line: "{{ line }}"

# ansible-lint will warn on this:
- ansible.builtin.command: chown root:root /etc/config
# Suggestion: Use ansible.builtin.file with owner/group parameters

- ansible.builtin.shell: |
    if [[ -f /etc/config ]]; then
      source /etc/config
    fi
  args:
    executable: /bin/bash

- name: Find large files and sort by size
  ansible.builtin.shell: find /var/log -type f -size +100M | sort -rn
  register: large_files

- name: Process pipeline with grep
  ansible.builtin.shell: ps aux | grep nginx | grep -v grep | wc -l
  register: nginx_count
  changed_when: false

- name: Redirect output to file
  ansible.builtin.shell: df -h > /tmp/disk_report.txt 2>&1

- name: Run with custom environment
  ansible.builtin.shell: echo $MY_VAR && printenv | grep MY
  environment:
    MY_VAR: "custom_value"
    PATH: "/usr/local/bin:{{ ansible_env.PATH }}"

- name: Multi-line shell script
  ansible.builtin.shell: |
    #!/bin/bash
    set -euo pipefail
    
    BACKUP_DIR="/backup/$(date +%Y%m%d)"
    mkdir -p "$BACKUP_DIR"
    
    for db in $(mysql -e "SHOW DATABASES" -s --skip-column-names); do
      mysqldump "$db" > "$BACKUP_DIR/$db.sql"
    done
    
    echo "Backup completed: $(ls $BACKUP_DIR | wc -l) databases"
  args:
    executable: /bin/bash
  register: backup_result

- name: Build application (skip if already built)
  ansible.builtin.command:
    cmd: make build
    chdir: /opt/app/src
    creates: /opt/app/bin/myapp
  # Only runs if /opt/app/bin/myapp doesn't exist

- name: Run cleanup (only if temp files exist)
  ansible.builtin.command:
    cmd: /opt/scripts/cleanup.sh
    removes: /tmp/app-cache
  # Only runs if /tmp/app-cache exists

- name: Safe argument passing (no shell injection)
  ansible.builtin.command:
    argv:
      - /usr/bin/git
      - clone
      - --depth
      - "1"
      - "{{ repo_url }}"
      - /opt/app

# DANGEROUS - user input in shell
- ansible.builtin.shell: "grep {{ user_input }} /etc/passwd"
  # If user_input is "; rm -rf /" → disaster

# SAFE - use command module instead
- ansible.builtin.command: "grep {{ user_input }} /etc/passwd"
  # Special characters are treated literally

# ansible.cfg
[ssh_connection]
pipelining = True

# Slow — 3 SSH connections
- ansible.builtin.command: systemctl stop nginx
- ansible.builtin.command: cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
- ansible.builtin.command: systemctl start nginx

# Faster — 1 SSH connection
- ansible.builtin.shell: |
    systemctl stop nginx
    cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
    systemctl start nginx

# Best — use proper modules (idempotent + no shell)
- ansible.builtin.service:
    name: nginx
    state: stopped
- ansible.builtin.copy:
    src: /etc/nginx/nginx.conf
    dest: /etc/nginx/nginx.conf.bak
    remote_src: true
- ansible.builtin.service:
    name: nginx
    state: started

- name: Install Python on fresh Ubuntu
  ansible.builtin.raw: apt-get install -y python3 python3-apt
  become: true

- name: Install Python on fresh CentOS
  ansible.builtin.raw: yum install -y python3
  become: true

- name: Gather facts after Python is available
  ansible.builtin.setup:

- name: Show running config on Cisco device
  ansible.builtin.raw: show running-config
  register: config

- name: Show interface status
  ansible.builtin.raw: show ip interface brief
  register: interfaces