From 3a9946fd2ec4a7d403a4807bde4f4195bad31af7 Mon Sep 17 00:00:00 2001 From: David Shrewsbury Date: Thu, 7 Nov 2024 14:40:18 -0500 Subject: [PATCH] Move parameter documentation from run() to RunnerConfig --- docs/ansible_runner.rst | 8 -- docs/porting_guides/porting_guide_v2.5.rst | 4 +- src/ansible_runner/config/_base.py | 54 ++++++++++- src/ansible_runner/config/runner.py | 49 +++++++++- src/ansible_runner/interface.py | 100 ++++++--------------- 5 files changed, 126 insertions(+), 89 deletions(-) diff --git a/docs/ansible_runner.rst b/docs/ansible_runner.rst index 1f64d7b6..f1fe6e65 100644 --- a/docs/ansible_runner.rst +++ b/docs/ansible_runner.rst @@ -45,14 +45,6 @@ ansible_runner.runner module :undoc-members: :show-inheritance: -ansible_runner.runner\_config module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: ansible_runner.runner_config - :members: - :undoc-members: - :show-inheritance: - ansible_runner.utils module ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/porting_guides/porting_guide_v2.5.rst b/docs/porting_guides/porting_guide_v2.5.rst index 899e0d63..c0bf47aa 100644 --- a/docs/porting_guides/porting_guide_v2.5.rst +++ b/docs/porting_guides/porting_guide_v2.5.rst @@ -35,7 +35,7 @@ object. For example: .. code-block:: python import ansible_runner - config = ansible_runner.RunnerConfig('private_data_dir': '/tmp/demo', 'playbook': 'test.yml') + config = ansible_runner.RunnerConfig(private_data_dir='/tmp/demo', playbook='test.yml') r = ansible_runner.interface.run(config=config) The above is identical to the more familiar usage of the API: @@ -43,4 +43,4 @@ The above is identical to the more familiar usage of the API: .. code-block:: python import ansible_runner - r = ansible_runner.interface.run('private_data_dir': '/tmp/demo', 'playbook': 'test.yml') + r = ansible_runner.interface.run(private_data_dir='/tmp/demo', playbook='test.yml') diff --git a/src/ansible_runner/config/_base.py b/src/ansible_runner/config/_base.py index f8e05159..7ce75b75 100644 --- a/src/ansible_runner/config/_base.py +++ b/src/ansible_runner/config/_base.py @@ -73,9 +73,57 @@ class BaseConfig: """The base configuration object. This object has multiple initialization responsibilities, including: - - guaranteeing the 'private_data_dir' directory exists - - guaranteeing that 'ident' value is set - - setting the various work directory attributes based on 'private_data_dir' + - guaranteeing the ``private_data_dir`` directory exists + - guaranteeing that ``ident`` value is set + - setting the various work directory attributes based on ``private_data_dir`` + + :param str private_data_dir: The directory containing all runner metadata needed to invoke the runner + module. Output artifacts will also be stored here for later consumption. + :param str artifact_dir: The path to the directory where artifacts should live. This defaults to + ``artifacts`` under ``private_data_dir``. + :param bool check_job_event_data: Check if job events data is completely generated. If event data is + not completely generated and if value is set to ``True`` it will raise an `AnsibleRunnerException` exception. + If set to ``False``, it log a debug message and continue execution. Default value is ``False``. + :param dict container_auth_data: Container registry authentication data containing ``host``, ``username``, and + ``password`` entries. + :param str container_image: Container image to use when running an ansible task. + :param list container_options: List of container options to pass to execution engine. + :param list container_volume_mounts: List of bind mounts in the form 'host_dir:/container_dir`. Default to ``None``. + :param str container_workdir: The working directory within the container. + :param dict envvars: Environment variables to be used when running Ansible. Environment variables will also be + read from ``env/envvars`` in ``private_data_dir``. + :param str fact_cache: A string that will be used as the name for the subdirectory of the fact cache in + artifacts directory. This is only used for ``jsonfile`` type fact caches. + :param str fact_cache_type: A string of the type of fact cache to use. Defaults to ``jsonfile``. + :param str host_cwd: The host current working directory to be mounted within the container (if enabled) and will be + the work directory within container. + :param str ident: The run identifier for this invocation of Runner. Will be used to create and name + the artifact directory holding the results of the invocation. + :param bool json_mode: Store event data in place of stdout on the console and in the stdout file. + :param int keepalive_seconds: Use within the streaming Worker object to inject a keepalive event. + :param dict passwords: A dictionary containing password prompt patterns and response values used when processing + output from Ansible. Passwords will also be read from ``env/passwords`` in ``private_data_dir``. + :param bool process_isolation: Enable process isolation, using either a container engine (e.g. podman) or a + sandbox (e.g. bwrap). + :param str process_isolation_executable: Process isolation executable or container engine used to isolate + execution. (default: podman) + :param str project_dir: The path to the playbook content. Defaults to ``project`` within ``private_data_dir``. + :param bool quiet: Disable all output. + :param int rotate_artifacts: Keep at most n artifact directories. Disable with a value of ``0`` (the default). + :param dict settings: A dictionary containing settings values for the ``ansible-runner`` runtime environment. + These will also be read from ``env/settings`` in ``private_data_dir``. + :param str ssh_key: The ssh private key passed to ``ssh-agent`` as part of the ansible-playbook run. + :param bool suppress_env_files: Disable the writing of files into the ``env`` which may store sensitive information. + :param int timeout: The timeout value, in seconds, that will be passed to either ``pexpect`` of ``subprocess`` + invocation (based on ``runner_mode`` selected) while executing command. It the timeout is triggered it will + force cancel the execution. + :param Callable event_handler: An optional callback that will be invoked any time an event is received by Runner itself. + Return ``True`` to keep the event + :param Callable cancel_callback: An optional callback that can inform runner to cancel (returning ``True``) or not + (returning ``False``). + :param Callable finished_callback: An optional callback that will be invoked at shutdown after process cleanup. + :param Callable status_handler: An optional callback that will be invoked any time the status changes (e.g...started, running, failed, successful, timeout) + :param Callable artifacts_handler: An optional callback that will be invoked at the end of the run to deal with the artifacts from the run. """ # This MUST be the first field we define to handle the use case where a RunnerConfig object diff --git a/src/ansible_runner/config/runner.py b/src/ansible_runner/config/runner.py index 0378855b..e6c7c3af 100644 --- a/src/ansible_runner/config/runner.py +++ b/src/ansible_runner/config/runner.py @@ -50,12 +50,11 @@ class ExecutionMode(): @dataclass class RunnerConfig(BaseConfig): - """ - A ``Runner`` configuration object that's meant to encapsulate the configuration used by the + """A ``Runner`` configuration object that's meant to encapsulate the configuration used by the :py:mod:`ansible_runner.runner.Runner` object to launch and manage the invocation of ``ansible`` and ``ansible-playbook`` - Typically this object is initialized for you when using the standard ``run`` interfaces in :py:mod:`ansible_runner.interface` + Typically, this object is initialized for you when using the standard ``run`` interfaces in :py:mod:`ansible_runner.interface` but can be used to construct the ``Runner`` configuration to be invoked elsewhere. It can also be overridden to provide different functionality to the Runner object. @@ -65,6 +64,48 @@ class RunnerConfig(BaseConfig): >>> r = Runner(config=rc) >>> r.run() + This class inherites all the initialization parameters of the `BaseConfig` parent class, plus: + + :param BinaryIO _input: An optional file or file-like object for use as input in a streaming pipeline. + :param BinaryIO _output: An optional file or file-like object for use as output in a streaming pipeline. + :param str binary: Path to an alternative ansible command. + :param str cmdline: Command line options passed to Ansible read from ``env/cmdline`` in ``private_data_dir`` + :param str directory_isolation_base_path: An optional path will be used as the base path to create a temp directory. + The project contents will be copied to this location which will then be used as the working directory during + playbook execution. + :param dict extravars: Extra variables to be passed to Ansible at runtime using ``-e``. Extra vars will also be + read from ``env/extravars`` in ``private_data_dir``. + :param int forks: Control Ansible parallel concurrency. + :param str host_pattern: The host pattern to match when running in ad-hoc mode. + :param str or dict or list inventory: Overrides the inventory directory/file (supplied at ``private_data_dir/inventory``) with + a specific host or list of hosts. This can take the form of: + + - Path to the inventory file in the ``private_data_dir/inventory`` directory or + an absolute path to the inventory file + - Native python dict supporting the YAML/json inventory structure + - A text INI formatted string + - A list of inventory sources, or an empty list to disable passing inventory + :param str limit: Matches ansible's ``--limit`` parameter to further constrain the inventory to be used. + :param str module: The module that will be invoked in ad-hoc mode by runner when executing Ansible. + :param str module_args: The module arguments that will be supplied to ad-hoc mode. + :param bool omit_event_data: Omits extra ansible event data from event payload (stdout and event still included). + :param bool only_failed_event_data: Omits extra ansible event data unless it's a failed event (stdout and event still included). + :param bool only_transmit_kwargs: If ``True``, the streaming Transmitter process will only send job arguments. + :param str or dict or list playbook: The playbook (either a list or dictionary of plays, or as a path relative to + ``private_data_dir/project``) that will be invoked by runner when executing Ansible. + :param str or list process_isolation_hide_paths: A path or list of paths on the system that should be hidden from the playbook run. + :param str or list process_isolation_ro_paths: A path or list of paths on the system that should be exposed to the playbook run as read-only. + :param str or list process_isolation_show_paths: A path or list of paths on the system that should be exposed to the playbook run. + :param str process_isolation_path: Path that an isolated playbook run will use for staging. (default: ``/tmp``) + :param str role: Name of the role to execute. + :param bool role_skip_facts: If ``True``, ``gather_facts`` will be set to ``False`` for execution of the namedgit ``role``. + :param str or list roles_path: Directory or list of directories to assign to ``ANSIBLE_ROLES_PATH``. + :param dict role_vars: Variables and their values to use with the named ``role``. + :param str skip_tags: Value to pass to the ``--skip-tags`` option of ``ansible-playbook``. + :param bool suppress_ansible_output: If ``True``, Ansible output will not appear to stdout. + :param bool suppress_output_file: If ``True``, Ansible output will not be written to a file in the artifacts directory. + :param str tags: Value to pass to the ``--tags`` option of ``ansible-playbook``. + :param int verbosity: Control the verbosity level of ansible-playbook. """ _input: BinaryIO | None = field(metadata={MetaValues.TRANSMIT: False}, default=None) @@ -205,7 +246,7 @@ def prepare(self): - prepare_command It's also responsible for wrapping the command with the proper ssh agent invocation - and setting early ANSIBLE_ environment variables. + and setting early ``ANSIBLE_`` environment variables. """ # ansible_path = find_executable('ansible') # if ansible_path is None or not os.access(ansible_path, os.X_OK): diff --git a/src/ansible_runner/interface.py b/src/ansible_runner/interface.py index 7b7e6726..387860fd 100644 --- a/src/ansible_runner/interface.py +++ b/src/ansible_runner/interface.py @@ -116,81 +116,37 @@ def run(config: RunnerConfig | None = None, logfile: str = "", ignore_logging: bool = True, **kwargs): - ''' - Run an Ansible Runner task in the foreground and return a Runner object when complete. + """Run an Ansible Runner task in the foreground and return a Runner object when complete. - :param str private_data_dir: The directory containing all runner metadata needed to invoke the runner - module. Output artifacts will also be stored here for later consumption. - :param str ident: The run identifier for this invocation of Runner. Will be used to create and name - the artifact directory holding the results of the invocation. - :param bool json_mode: Store event data in place of stdout on the console and in the stdout file - :param str or list playbook: The playbook (either a list or dictionary of plays, or as a path relative to - ``private_data_dir/project``) that will be invoked by runner when executing Ansible. - :param str module: The module that will be invoked in ad-hoc mode by runner when executing Ansible. - :param str module_args: The module arguments that will be supplied to ad-hoc mode. - :param str host_pattern: The host pattern to match when running in ad-hoc mode. - :param str or dict or list inventory: Overrides the inventory directory/file (supplied at ``private_data_dir/inventory``) with - a specific host or list of hosts. This can take the form of: - - - Path to the inventory file in the ``private_data_dir/inventory`` directory or - an absolute path to the inventory file - - Native python dict supporting the YAML/json inventory structure - - A text INI formatted string - - A list of inventory sources, or an empty list to disable passing inventory - - :param str role: Name of the role to execute. - :param str or list roles_path: Directory or list of directories to assign to ANSIBLE_ROLES_PATH - :param dict envvars: Environment variables to be used when running Ansible. Environment variables will also be - read from ``env/envvars`` in ``private_data_dir`` - :param dict extravars: Extra variables to be passed to Ansible at runtime using ``-e``. Extra vars will also be - read from ``env/extravars`` in ``private_data_dir``. - :param dict passwords: A dictionary containing password prompt patterns and response values used when processing output from - Ansible. Passwords will also be read from ``env/passwords`` in ``private_data_dir``. - :param dict settings: A dictionary containing settings values for the ``ansible-runner`` runtime environment. These will also - be read from ``env/settings`` in ``private_data_dir``. - :param str ssh_key: The ssh private key passed to ``ssh-agent`` as part of the ansible-playbook run. - :param str cmdline: Command line options passed to Ansible read from ``env/cmdline`` in ``private_data_dir`` - :param bool suppress_env_files: Disable the writing of files into the ``env`` which may store sensitive information - :param str limit: Matches ansible's ``--limit`` parameter to further constrain the inventory to be used - :param int forks: Control Ansible parallel concurrency - :param int verbosity: Control how verbose the output of ansible-playbook is - :param bool quiet: Disable all output - :param str artifact_dir: The path to the directory where artifacts should live, this defaults to 'artifacts' under the private data dir - :param str project_dir: The path to the playbook content, this defaults to 'project' within the private data dir - :param int rotate_artifacts: Keep at most n artifact directories, disable with a value of 0 which is the default - :param int timeout: The timeout value in seconds that will be passed to either ``pexpect`` of ``subprocess`` invocation - (based on ``runner_mode`` selected) while executing command. It the timeout is triggered it will force cancel the - execution. - :param str streamer: Optionally invoke ansible-runner as one of the steps in the streaming pipeline - :param typing.BinaryIO _input: An optional file or file-like object for use as input in a streaming pipeline - :param typing.BinaryIO _output: An optional file or file-like object for use as output in a streaming pipeline - :param Callable event_handler: An optional callback that will be invoked any time an event is received by Runner itself, return True to keep the event - :param Callable cancel_callback: An optional callback that can inform runner to cancel (returning True) or not (returning False) - :param Callable finished_callback: An optional callback that will be invoked at shutdown after process cleanup. - :param Callable status_handler: An optional callback that will be invoked any time the status changes (e.g...started, running, failed, successful, timeout) - :param Callable artifacts_handler: An optional callback that will be invoked at the end of the run to deal with the artifacts from the run. - :param bool process_isolation: Enable process isolation, using either a container engine (e.g. podman) or a sandbox (e.g. bwrap). - :param str process_isolation_executable: Process isolation executable or container engine used to isolate execution. (default: podman) - :param str process_isolation_path: Path that an isolated playbook run will use for staging. (default: /tmp) - :param str or list process_isolation_hide_paths: A path or list of paths on the system that should be hidden from the playbook run. - :param str or list process_isolation_show_paths: A path or list of paths on the system that should be exposed to the playbook run. - :param str or list process_isolation_ro_paths: A path or list of paths on the system that should be exposed to the playbook run as read-only. - :param str container_image: Container image to use when running an ansible task - :param list container_volume_mounts: List of bind mounts in the form 'host_dir:/container_dir. (default: None) - :param list container_options: List of container options to pass to execution engine. - :param str directory_isolation_base_path: An optional path will be used as the base path to create a temp directory, the project contents will be - copied to this location which will then be used as the working directory during playbook execution. - :param str fact_cache: A string that will be used as the name for the subdirectory of the fact cache in artifacts directory. - This is only used for 'jsonfile' type fact caches. - :param str fact_cache_type: A string of the type of fact cache to use. Defaults to 'jsonfile'. - :param bool omit_event_data: Omits extra ansible event data from event payload (stdout and event still included) - :param bool only_failed_event_data: Omits extra ansible event data unless it's a failed event (stdout and event still included) - :param bool check_job_event_data: Check if job events data is completely generated. If event data is not completely generated and if - value is set to 'True' it will raise 'AnsibleRunnerException' exception, - if set to 'False' it log a debug message and continue execution. Default value is 'False' + This function may be called in two different formats, both of which are equivalent. The first uses only + keyword arguments and does NOT specify a value for the ``config`` parameter. + + .. code-block:: python + + run(private_data_dir='/tmp/demo', playbook='test.yml') + run(private_data_dir='/tmp/streaming-demo', playbook='test.yml', streamer='transmit') + + The second format uses a `RunnerConfig` object supplied in the ``config`` parameter for all available + run values. All other ``**kwarg`` keywords and their values are ignored. + + .. code-block:: python + + config = RunnerConfig(private_data_dir='/tmp/demo', playbook='test.yml') + run(config=config) + + streaming_config = RunnerConfig(private_data_dir='/tmp/streaming-demo', playbook='test.yml') + run(config=streaming_config, streamer='transmit') + + :param RunnerConfig config: A configuration object describing the run characteristics. + :param str streamer: Optionally invoke ansible-runner as one of the steps in the streaming pipeline. + Valid values are ``transmit``, ``worker``, or ``process``. + :param bool debug: If ``True``, debugging output from ansible-runner is enabled. + :param str logfile: Path to a file where logging output will be sent. + :param bool ignore_logging: If ``True``, ansible-runner log output will be disabled. + :param dict kwargs: Keyword arguments that match the parameters for a `RunnerConfig` object. :returns: A :py:class:`ansible_runner.runner.Runner` object, or a simple object containing ``rc`` if run remotely - ''' + """ # Initialize logging if not ignore_logging: