shell-to-ansible

Shell-to-Ansible Conversion Skill

Convert procedural shell scripts into declarative, idempotent Ansible playbooks following Red Hat Communities of Practice standards.

Mindset Shift: Procedural vs. Declarative

Shell Scripts (Procedural)

• How to do it: Step-by-step instructions
• Imperative: "Install package, then configure it, then start service"
• State unaware: Runs all commands every time
• Error-prone: Partial failures leave inconsistent state

Ansible (Declarative)

• What should exist: Desired end state
• Declarative: "Package should be installed, configured correctly, service running"
• State aware: Only makes necessary changes
• Idempotent: Safe to run repeatedly

Conversion Process

Step 1: Analyze the Shell Script

Identify what the script accomplishes:

1. Packages to install
2. Files to create/modify
3. Services to manage
4. Users/groups to create
5. Permissions to set
6. Conditional logic
7. Loops and iterations

Step 2: Map to Ansible Modules

Replace shell commands with appropriate Ansible modules (see Module Mapping reference).

Step 3: Make it Idempotent

Ensure the playbook can run multiple times safely:

• Use declarative modules (package, service, file)
• Add creates/removes to commands
• Use changed_when: false for checks
• Leverage fact-based guards

Step 4: Add Error Handling

Replace || exit 1 with proper Ansible error handling:

• failed_when conditions
• ignore_errors where appropriate
• Assertions for validation

Step 5: Organize into Roles

For complex scripts, organize into proper role structure following Red Hat CoP.

Module Mapping

Package Management

# Shell
yum install -y httpd
apt-get install -y apache2

# Ansible
- name: Install Apache
  ansible.builtin.package:
    name: "{{ __rolename_package_name }}"
    state: present

# Shell
yum update -y
apt-get update && apt-get upgrade -y

# Ansible
- name: Update all packages
  ansible.builtin.package:
    name: '*'
    state: latest
  when: rolename_update_all_packages | default(false) | bool

Service Management

# Shell
systemctl enable httpd
systemctl start httpd
systemctl restart httpd

# Ansible
- name: Enable and start Apache
  ansible.builtin.service:
    name: "{{ __rolename_service_name }}"
    state: started
    enabled: true

- name: Restart Apache
  ansible.builtin.service:
    name: "{{ __rolename_service_name }}"
    state: restarted

File Operations

# Shell
cp /source/file.conf /etc/app/file.conf
chmod 644 /etc/app/file.conf
chown root:root /etc/app/file.conf

# Ansible
- name: Deploy configuration file
  ansible.builtin.copy:
    src: file.conf
    dest: /etc/app/file.conf
    owner: root
    group: root
    mode: '0644'

# Shell
cat > /etc/app/config.conf <<EOF
setting1=value1
setting2=value2
EOF

# Ansible
- name: Create configuration file
  ansible.builtin.copy:
    content: |
      setting1=value1
      setting2=value2
    dest: /etc/app/config.conf
    owner: root
    group: root
    mode: '0644'

# Or better - use template
- name: Deploy configuration from template
  ansible.builtin.template:
    src: config.conf.j2
    dest: /etc/app/config.conf
    owner: root
    group: root
    mode: '0644'

# Shell
sed -i 's/^MaxClients.*/MaxClients 150/' /etc/httpd/conf/httpd.conf

# Ansible
- name: Configure MaxClients
  ansible.builtin.lineinfile:
    path: /etc/httpd/conf/httpd.conf
    regexp: '^MaxClients'
    line: 'MaxClients 150'
    state: present

# Shell
mkdir -p /opt/app/data
chmod 755 /opt/app/data

# Ansible
- name: Create application data directory
  ansible.builtin.file:
    path: /opt/app/data
    state: directory
    owner: root
    group: root
    mode: '0755'

User and Group Management

# Shell
groupadd -r appgroup
useradd -r -g appgroup -s /sbin/nologin appuser

# Ansible
- name: Create application group
  ansible.builtin.group:
    name: appgroup
    system: true
    state: present

- name: Create application user
  ansible.builtin.user:
    name: appuser
    group: appgroup
    system: true
    shell: /sbin/nologin
    createhome: false
    state: present

Downloads and Archives

# Shell
wget https://example.com/app.tar.gz -O /tmp/app.tar.gz
tar -xzf /tmp/app.tar.gz -C /opt/

# Ansible
- name: Download and extract application
  ansible.builtin.unarchive:
    src: https://example.com/app.tar.gz
    dest: /opt/
    remote_src: true
    creates: /opt/app/bin/app

# Shell
curl -o /usr/local/bin/app https://example.com/app
chmod +x /usr/local/bin/app

# Ansible
- name: Download application binary
  ansible.builtin.get_url:
    url: https://example.com/app
    dest: /usr/local/bin/app
    mode: '0755'
    owner: root
    group: root

Conditionals

# Shell
if [ -f /etc/redhat-release ]; then
  yum install -y httpd
elif [ -f /etc/debian_version ]; then
  apt-get install -y apache2
fi

# Ansible
- name: Install Apache on RedHat
  ansible.builtin.yum:
    name: httpd
    state: present
  when: ansible_os_family == "RedHat"

- name: Install Apache on Debian
  ansible.builtin.apt:
    name: apache2
    state: present
  when: ansible_os_family == "Debian"

# Or use the generic module
- name: Install Apache (platform-agnostic)
  ansible.builtin.package:
    name: "{{ __rolename_package_name }}"
    state: present
  # Set __rolename_package_name in vars/RedHat.yml and vars/Debian.yml

# Shell
if [ ! -f /opt/app/.initialized ]; then
  /usr/local/bin/init-app.sh
  touch /opt/app/.initialized
fi

# Ansible
- name: Initialize application
  ansible.builtin.command: /usr/local/bin/init-app.sh
  args:
    creates: /opt/app/.initialized

Loops

# Shell
for module in ssl rewrite headers; do
  a2enmod $module
done

# Ansible
- name: Enable Apache modules
  ansible.builtin.command: "a2enmod {{ item }}"
  loop:
    - ssl
    - rewrite
    - headers
  args:
    creates: "/etc/apache2/mods-enabled/{{ item }}.load"

# Shell
for user in alice bob charlie; do
  useradd $user
done

# Ansible
- name: Create users
  ansible.builtin.user:
    name: "{{ item }}"
    state: present
  loop:
    - alice
    - bob
    - charlie

Environment Variables

# Shell
export APP_ENV=production
export APP_PORT=8080

# Ansible
- name: Run application with environment
  ansible.builtin.command: /usr/local/bin/app
  environment:
    APP_ENV: production
    APP_PORT: 8080

Command Execution with Checks

# Shell
if ! httpd -t; then
  echo "Configuration test failed"
  exit 1
fi

# Ansible
- name: Validate Apache configuration
  ansible.builtin.command: httpd -t
  changed_when: false
  register: config_test
  failed_when: config_test.rc != 0

Idempotency Patterns

Pattern 1: Use Declarative Modules

# Shell (Not idempotent)
yum install -y httpd

# Ansible (Idempotent)
- name: Ensure Apache is installed
  ansible.builtin.package:
    name: httpd
    state: present

Pattern 2: Use creates Parameter

# Shell
wget https://example.com/app.tar.gz
tar -xzf app.tar.gz

# Ansible
- name: Download and extract application
  ansible.builtin.unarchive:
    src: https://example.com/app.tar.gz
    dest: /opt/
    remote_src: true
    creates: /opt/app/bin/app  # Only runs if this doesn't exist

Pattern 3: Check Before Acting

# Shell
/usr/local/bin/setup.sh

# Ansible
- name: Check if setup is needed
  ansible.builtin.stat:
    path: /var/lib/app/.setup_complete
  register: setup_status

- name: Run setup if needed
  ansible.builtin.command: /usr/local/bin/setup.sh
  when: not setup_status.stat.exists

- name: Mark setup as complete
  ansible.builtin.file:
    path: /var/lib/app/.setup_complete
    state: touch
  when: not setup_status.stat.exists

Pattern 4: Use changed_when

# Shell (checks always report as changed)
grep -q "setting" /etc/app.conf || echo "setting=value" >> /etc/app.conf

# Ansible (proper change detection)
- name: Ensure setting is present
  ansible.builtin.lineinfile:
    path: /etc/app.conf
    line: "setting=value"
    state: present
  # Automatically only changes if line is missing

Complex Conversion Example

Before: Shell Script

#!/bin/bash
# install-web-server.sh

set -e

# Update packages
yum update -y

# Install Apache
yum install -y httpd mod_ssl

# Create application user
if ! id -u webadmin > /dev/null 2>&1; then
  useradd -r -s /sbin/nologin webadmin
fi

# Create directories
mkdir -p /var/www/myapp
chown webadmin:webadmin /var/www/myapp
chmod 755 /var/www/myapp

# Deploy configuration
cat > /etc/httpd/conf.d/myapp.conf <<EOF
<VirtualHost *:80>
  ServerName myapp.example.com
  DocumentRoot /var/www/myapp
  <Directory /var/www/myapp>
    AllowOverride All
  </Directory>
</VirtualHost>
EOF

# Enable and start services
systemctl enable httpd
systemctl start httpd

# Configure firewall
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --reload

echo "Installation complete"

After: Ansible Playbook

---
# install-web-server.yml

- name: Install and configure web server
  hosts: webservers
  become: true

  vars:
    app_user: webadmin
    app_document_root: /var/www/myapp
    app_server_name: myapp.example.com

  tasks:
    - name: Update all packages
      ansible.builtin.yum:
        name: '*'
        state: latest
      when: update_packages | default(false) | bool
      tags: ['packages']

    - name: Install Apache and mod_ssl
      ansible.builtin.package:
        name:
          - httpd
          - mod_ssl
        state: present
      tags: ['packages']

    - name: Create application user
      ansible.builtin.user:
        name: "{{ app_user }}"
        system: true
        shell: /sbin/nologin
        createhome: false
        state: present
      tags: ['users']

    - name: Create application directory
      ansible.builtin.file:
        path: "{{ app_document_root }}"
        state: directory
        owner: "{{ app_user }}"
        group: "{{ app_user }}"
        mode: '0755'
      tags: ['filesystem']

    - name: Deploy virtual host configuration
      ansible.builtin.copy:
        content: |
          <VirtualHost *:80>
            ServerName {{ app_server_name }}
            DocumentRoot {{ app_document_root }}
            <Directory {{ app_document_root }}>
              AllowOverride All
            </Directory>
          </VirtualHost>
        dest: /etc/httpd/conf.d/myapp.conf
        owner: root
        group: root
        mode: '0644'
      notify: Reload Apache
      tags: ['configuration']

    - name: Enable and start Apache service
      ansible.builtin.service:
        name: httpd
        state: started
        enabled: true
      tags: ['services']

    - name: Configure firewall for HTTP/HTTPS
      ansible.posix.firewalld:
        service: "{{ item }}"
        permanent: true
        state: enabled
        immediate: true
      loop:
        - http
        - https
      tags: ['firewall']

  handlers:
    - name: Reload Apache
      ansible.builtin.service:
        name: httpd
        state: reloaded

Better: Convert to Role

For production use, organize as a role:

# playbook.yml
---
- name: Install web application
  hosts: webservers
  become: true

  roles:
    - role: company.web.myapp_install
      myapp_install_server_name: myapp.example.com
      myapp_install_document_root: /var/www/myapp

Conversion Checklist

When converting a shell script to Ansible:

• Identify all operations (install, configure, deploy, manage)
• Map shell commands to Ansible modules
• Replace all yum/apt with package module
• Replace all systemctl with service module
• Replace file operations with copy, template, lineinfile, file
• Convert loops to Ansible loop or with_items
• Convert conditionals to when clauses
• Add creates to commands that should run once
• Use changed_when: false for check/validation commands
• Move service restarts to handlers
• Add proper error handling with failed_when
• Make all operations idempotent
• Test by running twice - second run should show no changes
• Add tags for selective execution
• Document variables if creating a role
• Run ansible-lint for validation

Common Pitfalls

1. Directly Using shell Module

# Bad - just wraps shell script in Ansible
- name: Install Apache
  ansible.builtin.shell: |
    yum install -y httpd
    systemctl enable httpd
    systemctl start httpd

# Good - uses proper modules
- name: Install Apache
  ansible.builtin.package:
    name: httpd
    state: present

- name: Enable and start Apache
  ansible.builtin.service:
    name: httpd
    state: started
    enabled: true

2. Hardcoding Platform-Specific Commands

# Bad - only works on RedHat
- name: Install package
  ansible.builtin.command: yum install -y httpd

# Good - platform-agnostic
- name: Install Apache
  ansible.builtin.package:
    name: "{{ __rolename_package_name }}"
    state: present
# Set __rolename_package_name in vars/RedHat.yml (httpd) and vars/Debian.yml (apache2)

3. Not Using Handlers

# Bad - always restarts
- name: Deploy config
  ansible.builtin.template:
    src: httpd.conf.j2
    dest: /etc/httpd/conf/httpd.conf

- name: Restart Apache
  ansible.builtin.service:
    name: httpd
    state: restarted

# Good - only restarts if config changed
- name: Deploy config
  ansible.builtin.template:
    src: httpd.conf.j2
    dest: /etc/httpd/conf/httpd.conf
  notify: Restart Apache

# In handlers/main.yml:
# - name: Restart Apache
#   ansible.builtin.service:
#     name: httpd
#     state: restarted

Validation

After conversion, validate the playbook:

# Syntax check
ansible-playbook --syntax-check playbook.yml

# Lint
ansible-lint --profile moderate playbook.yml

# Dry run
ansible-playbook --check playbook.yml

# Run once
ansible-playbook playbook.yml

# Run again - should show no changes (idempotence test)
ansible-playbook playbook.yml

When asked to convert a shell script to Ansible, analyze the script operations, map to appropriate Ansible modules, ensure idempotency, and produce a well-structured playbook or role following Red Hat CoP standards.