Complete Guide to Executing Shell Scripts on Remote Servers Using Ansible

Problem Background and Common Error Analysis

In automated operations scenarios, executing Shell scripts on remote servers using Ansible is a common requirement. However, many developers encounter situations where script transfer succeeds but execution fails during their initial attempts. This typically stems from misunderstandings about Ansible's execution model.

A typical erroneous example:

---
- name: Transfer and execute a script.
  hosts: server
  user: test_user
  sudo: yes
  tasks:
     - name: Transfer the script
       copy: src=test.sh dest=/home/test_user mode=0777

     - name: Execute the script
       local_action: command sudo sh /home/test_user/test.sh

The issue with this configuration is that the local_action module executes commands on the local host, not on the remote target server. When using local_action: command sudo sh /home/test_user/test.sh, Ansible attempts to execute this command on the control node, while the script file on the remote server remains unexecuted.

Correct Solutions

To resolve this issue, proper modules and configurations must be used. Below are improved solutions based on best practices:

Method 1: Using the command Module

The most direct solution is to replace local_action with the command module:

---
- name: Transfer and execute a script.
  hosts: server
  remote_user: test_user
  become: yes
  tasks:
     - name: Transfer the script
       copy:
         src: test.sh
         dest: /home/test_user/
         mode: '0777'

     - name: Execute the script
       command: sh /home/test_user/test.sh

Key improvements:

• Updated user parameter to remote_user, the recommended syntax since Ansible 1.4
• Updated sudo: yes to become: yes, the more modern privilege escalation syntax
• Removed local_action, directly using command module for remote execution
• No need to repeat sudo in command since privilege escalation is configured at playbook level

Method 2: Using the script Module

Ansible provides a dedicated script module for more concise script transfer and execution:

---
- name: Transfer and execute a script using script module
  hosts: server
  remote_user: test_user
  become: yes
  tasks:
     - name: Copy and execute the script
       ansible.builtin.script:
         cmd: /home/user/test.sh

Advantages of the script module:

• Automatically handles script transfer, eliminating separate copy tasks
• Executes scripts through shell environment on remote nodes
• Does not require Python installation on remote systems
• Supports Windows target systems

In-depth Technical Principles

Ansible Execution Model

Understanding Ansible's execution model is crucial for proper module usage. Ansible employs a push model where the control node connects to target nodes via SSH and executes tasks. Each task module has a clear scope:

• command, shell, script modules execute on remote hosts
• local_action executes on the control node
• Module selection should be determined by actual requirement scenarios

Permission Management Mechanism

Ansible's permission management operates at multiple levels:

---
- name: Example with proper privilege escalation
  hosts: webservers
  remote_user: deploy_user
  become: yes
  become_method: sudo
  become_user: root
  tasks:
     - name: Ensure script is executable
       file:
         path: /home/deploy_user/script.sh
         mode: '0755'

     - name: Execute with specific user
       command: /home/deploy_user/script.sh
       become: yes
       become_user: app_user

Error Handling and Debugging

When script execution fails, debugging can be performed using the following methods:

---
- name: Execute script with error handling
  hosts: server
  tasks:
     - name: Transfer script
       copy:
         src: test.sh
         dest: /tmp/
         mode: '0755'

     - name: Execute and capture output
       command: sh /tmp/test.sh
       register: script_result
       failed_when: script_result.rc != 0

     - name: Display output
       debug:
         var: script_result.stdout

     - name: Display errors
       debug:
         var: script_result.stderr

Best Practice Recommendations

Security Considerations

Security is paramount when executing remote scripts in production environments:

• Apply the principle of least privilege, avoid unnecessary become: yes
• Validate script content to prevent malicious code execution
• Use Ansible Vault to protect sensitive information
• Regularly audit script execution logs

Performance Optimization

For large-scale deployments, performance optimization is important:

• Use script module to reduce task count
• Reasonably set forks parameter to control concurrency
• Leverage Ansible's caching mechanism to improve execution efficiency
• Batch process related tasks to reduce connection overhead

Module Selection Guide

Choose appropriate modules based on specific scenarios:

Conclusion

Through the analysis in this article, we have gained a deep understanding of the correct methods for executing Shell scripts on remote servers using Ansible. The key lies in understanding the execution scope and mechanism of each module, avoiding common misuse of local_action. Whether using the command module or the script module, ensuring correct configuration and security is essential. In practical applications, it is recommended to choose the most suitable solution based on specific requirements and follow Ansible's best practice principles.