Developing Connection & Become Plugins
Relevant source files
The following files were used as context for generating this wiki page:Connection and Become plugins are fundamental components for extending Ansible's capabilities. Connection plugins define how Ansible communicates with managed nodes, handling the transport mechanism for executing tasks. Examples include the default ssh for POSIX systems and winrm for Windows. Become plugins define how Ansible performs privilege escalation on managed nodes, such as using sudo or su.
Developing new plugins allows Ansible to manage a wider variety of systems and use different privilege escalation methods. While ansible-core includes several essential plugins, new plugins are generally expected to be developed and distributed within Ansible Collections. All contributions must adhere to the project's licensing requirements, which are primarily GPLv3-compatible for ansible-core.
Sources: AGENTS.md, lib/ansible/plugins/connection/ssh.py, lib/ansible/plugins/connection/winrm.py, lib/ansible/plugins/become/sudo.py
Core Concepts
Ansible's extensibility relies heavily on its plugin architecture. Connection and Become plugins are two of the most critical types for interacting with remote hosts.
- Connection Plugins: These plugins are responsible for establishing a connection to the target host, executing commands, transferring files, and closing the connection. They form the transport layer of Ansible's communication.
- Become Plugins: These plugins are used to switch to a different user on the remote host to execute tasks with different privileges. They wrap the command provided by the connection plugin with the necessary privilege escalation syntax.
New plugins are rarely accepted into the ansible-core repository itself. Instead, they should be developed as part of a collection.
Sources: AGENTS.md, lib/ansible/plugins/connection/ssh.py, lib/ansible/plugins/become/sudo.py
Plugin Structure and Documentation
A well-formed plugin must include specific documentation blocks and adhere to a standard structure. These blocks are parsed by ansible-doc to generate documentation.
The following diagram illustrates the typical structure of a plugin file.
This diagram shows the standard layout of an Ansible plugin source file.
Sources: lib/ansible/plugins/connection/ssh.py:1-25, lib/ansible/plugins/become/sudo.py:1-20, AGENTS.md
Documentation Blocks
All plugins must contain DOCUMENTATION, EXAMPLES, and RETURN strings. These are YAML-formatted strings that ansible-doc uses to generate help text.
| Block | Description |
|---|---|
DOCUMENTATION | Contains metadata about the plugin, including its description, options, and author information. |
EXAMPLES | Provides one or more examples of how to use the plugin in a playbook. |
RETURN | Documents the values that the plugin can return upon execution. |
Sources: lib/ansible/cli/doc.py:1410-1412, lib/ansible/plugins/connection/ssh.py:25-156, lib/ansible/plugins/become/sudo.py:20-74
The DOCUMENTATION block itself has a required structure with several key fields.
| Field | Description |
|---|---|
module / plugin | The name of the plugin. |
short_description | A one-line summary of the plugin's purpose. |
description | A more detailed explanation of what the plugin does. |
version_added | The Ansible version in which the plugin was introduced. |
options | A dictionary of the parameters the plugin accepts. Each option should have a description and type. |
author | The name and handle of the plugin's author. |
Sources: lib/ansible/cli/doc.py:1410-1420, lib/ansible/plugins/connection/ssh.py:26-120, lib/ansible/plugins/become/sudo.py:21-59
Documentation Markup
The documentation strings support a special markup format for linking and styling, which is parsed by ansible-doc.
| Markup | Description | Example |
|---|---|---|
I(text) | Italicize text. | I(each line) |
B(text) | Bold text. | B(not) |
M(module) | Link to an Ansible module. | M(ansible.builtin.ping) |
U(url) | A raw URL. | U(https://docs.ansible.com) |
L(text, url) | A named link. | L(OpenSSL Cipher List Format,https://... |
C(text) | A constant or value. | C(Content-Type) |
O(text) | An option name. | O(dest) |
V(text) | An option value. | V(json) |
Sources: lib/ansible/cli/doc.py:448-461
Connection Plugin Development
Connection plugins must inherit from ConnectionBase. They implement the logic for connecting to, executing commands on, and transferring files to a managed node.
Sources: lib/ansible/plugins/connection/ssh.py:161, lib/ansible/plugins/connection/winrm.py:100
Core Methods
A connection plugin must implement several key methods to be functional.
| Method | Description |
|---|---|
_connect() | Establishes the connection to the remote host and initializes any required resources. |
exec_command(cmd, in_data, sudoable) | Executes a command on the remote host. |
put_file(in_path, out_path) | Transfers a file from the controller to the remote host. |
fetch_file(in_path, out_path) | Transfers a file from the remote host to the controller. |
close() | Terminates the connection and cleans up resources. |
Sources: lib/ansible/plugins/connection/ssh.py:313,889,1015,1032,1051, lib/ansible/plugins/connection/winrm.py:215,310,345,362,374
The following sequence diagram shows the typical lifecycle of a connection plugin during a task execution.
This diagram shows the sequence of method calls for a connection plugin during a single task execution.
Common Options
Connection plugins define their configurable parameters in the DOCUMENTATION block. Many options are common across different plugins.
| Option | Description | Found In |
|---|---|---|
host | The remote host to connect to. | ssh.py, winrm.py |
port | The connection port number. | ssh.py, winrm.py |
remote_user | The user to log in as on the remote host. | ssh.py, winrm.py |
password | The password for authentication. | ssh.py, winrm.py |
private_key_file | Path to the private key for authentication. | ssh.py |
timeout | Connection timeout in seconds. | ssh.py, winrm.py |
Sources: lib/ansible/plugins/connection/ssh.py:26-120, lib/ansible/plugins/connection/winrm.py:31-89
Become Plugin Development
Become plugins handle privilege escalation. They must inherit from BecomeBase and implement the logic for constructing the escalation command.
Sources: lib/ansible/plugins/become/sudo.py:79
Core Logic
The primary responsibility of a become plugin is to construct the full command that will be executed on the remote host. This typically involves wrapping the original command with the privilege escalation tool (e.g., sudo).
The main method to implement is build_become_command.
# lib/ansible/plugins/become/sudo.py
class BecomeModule(BecomeBase):
def build_become_command(self, cmd, shell):
super(BecomeModule, self).build_become_command(cmd, shell)
# ... logic to build the sudo command ...
return self.prompt and self.prompt.strip() or cmd
Sources: lib/ansible/plugins/become/sudo.py:82-84,124
The following flowchart illustrates how a become plugin modifies a command.
This diagram shows the process of a become plugin wrapping a command for privilege escalation.
Common Options
Become plugins define their options in the DOCUMENTATION block.
| Option | Description | Found In |
|---|---|---|
become_user | The user to escalate privileges to. Defaults to root. | sudo.py |
become_pass | The password for privilege escalation. | sudo.py |
become_exe | The executable to use for privilege escalation. | sudo.py |
become_flags | Flags to pass to the become executable. | sudo.py |
Sources: lib/ansible/plugins/become/sudo.py:21-59
Testing Plugins
Thorough testing is critical for plugin development. The ansible-test tool is used to run sanity, unit, and integration tests.
- Sanity Tests: Static analysis and linting (
ansible-test sanity). - Unit Tests: Test specific functions in isolation (
ansible-test units). - Integration Tests: Test the plugin against a live environment. These are essential for connection and become plugins (
ansible-test integration).
Almost all plugin changes require the addition of integration tests to verify the public-facing API and behavior.
Sources: AGENTS.md
Example Test Commands
The following commands are used to run tests during development.
| Command | Description |
|---|---|
ansible-test sanity -v --docker default | Run all sanity tests. |
ansible-test units -v --docker default | Run all unit tests. |
ansible-test integration -v --docker ubuntu2204 <target> | Run a specific integration test target. |
Sources: AGENTS.md
Summary
Connection and Become plugins are the cornerstones of Ansible's ability to interact with managed systems. By following the established structure for class inheritance, documentation, and testing, developers can create new plugins that extend Ansible's reach to new platforms and environments. Key takeaways include adhering to the DOCUMENTATION block format for ansible-doc compatibility, implementing the required methods from the base classes, and providing comprehensive integration tests to ensure reliability.