The intersection of infrastructure automation and operational orchestration represents a critical evolution in modern DevOps practices. While Ansible provides an unmatched declarative approach to configuration management and application deployment, it lacks a native, multi-tenant graphical interface for scheduling, access control, and complex workflow chaining. Rundeck fills this operational gap by acting as a sophisticated orchestration layer that wraps around Ansible's execution engine. This integration allows organizations to leverage the power of Ansible playbooks and roles while introducing a layer of governance, auditability, and self-service capability. By synthesizing the two, teams can move from manual CLI-driven executions to a centralized, governed platform where non-Ansible users can trigger complex deployments through a secure web interface without needing direct access to the underlying server shells or the Ansible codebase.
The Strategic Value of Rundeck in the Ansible Ecosystem
Integrating Rundeck with Ansible is not merely about adding a UI to a command-line tool; it is about implementing a comprehensive operational framework. Ansible is fundamentally a push-based configuration tool, which is powerful but can be dangerous if given unrestrained access to production environments. Rundeck mitigates this risk by providing an abstraction layer.
The primary drivers for this integration are centered on operational governance. Fine-grained Role-Based Access Control (RBAC) allows administrators to define exactly who can execute specific playbooks on which sets of hosts, preventing accidental execution of destructive scripts by unauthorized personnel. Furthermore, the introduction of job scheduling via cron support transforms Ansible from a manual tool into an automated maintenance engine.
Self-service execution is another pivotal advantage. In many enterprise environments, there is a disconnect between the developers who write the playbooks and the operations staff who execute them. Rundeck enables the creation of simplified "buttons" or forms that trigger complex Ansible workflows, allowing non-experts to perform routine tasks—such as restarting a service or clearing a cache—without risk of syntax errors in the CLI.
Beyond execution, the integration provides a robust audit trail. Every action taken in Rundeck is logged, providing a definitive record of who ran what, when it happened, and the exact output of the execution. This is critical for compliance and troubleshooting. Additionally, the platform extends Ansible's capabilities through built-in notifications to Slack, PagerDuty, or email, and the ability to chain multiple jobs into a complex workflow, where the success of one Ansible playbook triggers the start of another.
Technical Prerequisites and System Requirements
Before implementing the integration, certain technical baseline requirements must be met to ensure the stability of the execution environment.
Ansible Versioning and Environment
The integration requires Ansible version 1.7 or higher. The Ansible executables must be present in the $PATH of the user account that runs the Rundeck process. This is a critical requirement because the Rundeck Ansible plugin does not implement Ansible itself; rather, it invokes the ansible and ansible-playbook binaries installed on the host operating system.
User Permissions and File System Access
The Rundeck user must have full read/write access to its own home directory. A common failure point during installation is when the $HOME directory of the rundeck user is not writable, which can be resolved using the command chown rundeck /var/lib/rundeck. Furthermore, if the system is running on CentOS 6.7 or RHEL with SELinux enabled, the libselinux-python package must be installed via yum install libselinux-python to prevent permission denials during node discovery and execution.
Shell Execution Context
When starting the Rundeck service via su or similar mechanisms, the environment may lack necessary variables. It is recommended to use a login shell via the -l flag to ensure the full environment is loaded. Verification of the integration can be performed by executing the following command to test the connectivity from the Rundeck user's perspective:
su rundeck -s /bin/bash -c "ansible all -m ping"
Installing and Deploying Rundeck via Docker
The most efficient method for deploying a modern Rundeck instance is through Docker, which ensures a consistent environment across development and production.
The Base Docker Compose Configuration
A standard deployment utilizes a docker-compose.yml file to orchestrate the Rundeck application and its database backend (PostgreSQL 15).
```yaml version: '3.8' services: rundeck: image: rundeck/rundeck:5.0.0 ports: - "4440:4440" environment: RUNDECKGRAILSURL: http://localhost:4440 RUNDECKDATABASEDRIVER: org.postgresql.Driver RUNDECKDATABASEURL: jdbc:postgresql://postgres:5432/rundeck RUNDECKDATABASEUSERNAME: rundeck RUNDECKDATABASEPASSWORD: rundeck-db-pass volumes: - rundeck-data:/home/rundeck/server/data - rundeck-logs:/home/rundeck/var/logs - ./ansible:/home/rundeck/ansible - ~/.ssh:/home/rundeck/.ssh:ro depends_on: - postgres
postgres: image: postgres:15 environment: POSTGRESUSER: rundeck POSTGRESPASSWORD: rundeck-db-pass POSTGRES_DB: rundeck volumes: - postgres-data:/var/lib/postgresql/data
volumes: rundeck-data: rundeck-logs: postgres-data: ```
Customizing the Image for Ansible Support
Because the official Rundeck Docker image does not include Ansible, a custom Dockerfile is required to install the necessary binaries and Python environment.
dockerfile
FROM rundeck/rundeck:5.0.0
USER root
RUN apt-get update && \
apt-get install -y python3 python3-pip openssh-client && \
pip3 install ansible==8.7.0 && \
rm -rf /var/lib/apt/lists/*
RUN ansible-galaxy collection install community.general ansible.posix
USER rundeck
To implement this, the docker-compose.yml must be updated to use the build context:
yaml
services:
rundeck:
build:
context: .
dockerfile: Dockerfile.rundeck-ansible
The deployment is initiated using docker compose up -d, and logs can be monitored via docker compose logs -f rundeck. The initial administrative access is available at http://localhost:4440 with the default credentials admin / admin.
Implementing the Ansible Plugin
The Ansible plugin provides the essential glue between Rundeck's project management and Ansible's execution model. This plugin allows Rundeck to import hosts from Ansible's inventory and execute modules and playbooks directly.
Plugin Installation Procedures
The plugin is distributed as a .jar file. Depending on the installation method, the placement varies:
- For standard installations: The file must be placed in the Rundeck plugins directory, typically
/var/lib/rundeck/libext. - For Docker installations: The plugin can be mounted as a volume to ensure persistence and easy updates.
The plugin can be downloaded and installed using the following command:
wget https://github.com/Batix/rundeck-ansible-plugin/releases/download/3.2.4/ansible-plugin-3.2.4.jar -O /home/rundeck/libext/ansible-plugin.jar
In a Docker context, the volume mapping would be:
- ./plugins/ansible-plugin.jar:/home/rundeck/libext/ansible-plugin.jar
Project Configuration and Integration Logic
Once the plugin is installed, the project must be configured to utilize Ansible as the primary driver for node execution and file transfers.
User Interface Configuration
Within the Rundeck UI, a new project (e.g., "Infrastructure") is created. The following settings must be applied: - Default Node Executor: Ansible Ad-Hoc Node Executor - Default File Copier: Ansible File Copier
File-Based Configuration (project.properties)
For those preferring configuration-as-code, the /home/rundeck/projects/infrastructure/etc/project.properties file can be edited directly to define the Ansible environment:
properties
project.ansible.executable=/usr/local/bin/ansible
project.ansible-playbook.executable=/usr/local/bin/ansible-playbook
project.ansible.config-file-path=/home/rundeck/ansible/ansible.cfg
resources.source.1.type=com.batix.rundeck.plugins.AnsibleResourceModelSourceFactory
resources.source.1.config.ansible-inventory=/home/rundeck/ansible/inventory/production.ini
resources.source.1.config.ansible-gather-facts=true
service.NodeExecutor.default.provider=com.batix.rundeck.plugins.AnsibleNodeExecutor
service.FileCopier.default.provider=com.batix.rundeck.plugins.AnsibleFileCopier
Managing Node Sources via Ansible Inventory
One of the most powerful features of the Ansible plugin is the ability to treat an Ansible inventory file as the authoritative source of truth for Rundeck nodes.
The Resource Model Source
By selecting the "Ansible Resource Model Source" in the Project Settings > Edit Nodes menu, Rundeck can dynamically discover hosts.
| Configuration Parameter | Value/Setting | Impact |
|---|---|---|
| Ansible Inventory Path | /home/rundeck/ansible/inventory/production.ini |
Defines the source of host definitions. |
| Gather Facts | Yes | Imports OS and hardware info into Rundeck nodes. |
| Resource Model Type | AnsibleResourceModelSourceFactory |
Enables the plugin to parse Ansible inventory. |
The "Gather Facts" setting is particularly important. When enabled, Rundeck invokes Ansible to collect system-level information (facts) about the target nodes. This allows Rundeck to use the data for node filtering and targeting, effectively mirroring the flexibility of Ansible's internal grouping.
Creating and Executing Ansible Playbook Jobs
Jobs in Rundeck are the primary vehicle for executing Ansible playbooks. These can be configured via the GUI or defined in YAML for version control.
Web UI Configuration Steps
To create a deployment job, such as "Deploy Web Application":
1. Navigate to Jobs > New Job.
2. Define the name and description.
3. Add a step of type "Ansible Playbook".
4. Specify the playbook path: /home/rundeck/ansible/playbooks/deploy.yml.
5. Specify the inventory path: /home/rundeck/ansible/inventory/production.ini.
6. Add extra arguments such as --diff to see the changes made during the execution.
Job Definition via YAML
For professional DevOps pipelines, jobs should be version-controlled. An exported job file (jobs/deploy-web.yml) looks like this:
yaml
- defaultTab: output
description: Deploy web application to production
executionEnabled: true
group: deployments
loglevel: INFO
name: Deploy Web
Advanced Technical Considerations and Troubleshooting
Authentication and Credential Management
A significant advantage of the Ansible plugin is that it does not require the sharing of SSH keys between Ansible and Rundeck. Since all operations—including node imports—are executed through the ansible or ansible-playbook binaries, the existing Ansible SSH configuration and keys are used.
Regarding passwords, specifically for "become" (privilege escalation) and SSH authentication, the plugin follows a specific precedence: the first password provided in the evaluation chain takes precedence over the second.
Plugin Governance
The maintenance of the plugin transitioned in March 2022 from PagerDuty to the Rundeck Plugins organization. This move was designed to improve the management of issues and the merging of pull requests from the open-source community. The plugin utilizes Gradle Version Catalogs for dependency management, which ensures that dependency versions are security-hardened and consistent across builds.
Conclusion: Analysis of the Integrated Workflow
The integration of Rundeck and Ansible transforms a powerful but fragmented set of scripts into a cohesive operational platform. By leveraging the Ansible Resource Model Source, organizations eliminate the need to manually maintain separate inventories in both Rundeck and Ansible, thereby removing a significant source of configuration drift.
The technical synergy is found in the delegation of execution: Rundeck handles the "Who, When, and Where" (RBAC, Scheduling, Targeting), while Ansible handles the "How" (Playbooks, Modules, Roles). The use of a custom Docker image to bundle Ansible with Rundeck ensures that the environment is portable and reproducible, reducing the "it works on my machine" syndrome common in automation.
From a strategic perspective, this architecture enables a "Self-Service Infrastructure" model. By exposing complex Ansible playbooks as simple Rundeck jobs, the organization can democratize operational tasks. For example, a developer can trigger a "Database Schema Update" job through the Rundeck UI; Rundeck validates their permissions via RBAC, logs the request for auditing, and then executes the pre-validated Ansible playbook on the specific production database nodes. This significantly reduces the risk of manual error and increases the velocity of deployments while maintaining strict institutional control over the production environment.