Ansible plugin

7 minute readExtensibilityDeveloper productivity

Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs.

The CloudBees CD/RO EC-Ansible plugin allows users to run playbooks and ad hoc commands on Ansible. It can be configured to run on a variety of CloudBees CD/RO server/agent topologies, CloudBees CD/RO runtime contexts, and Ansible target hosts.

Features

  • Flexible Configuration: the plugin can be configured to any OS type and supports different user access and playbooks encryption. For more info go to Plugin Configuration.

  • Flexible Environments: plugin procedures can be running on different architecture types:

    • On the CloudBees CD/RO server

    • On an agent

    • On a CloudBees CD/RO cluster and multiple agents

  • Ad-Hoc commands support: Designed to run any kind of ad-hoc commands using any command module that is supported from Ansible. For example, ping, win_ping, file, shell, win_shell, and win_file.

  • Ansible playbook support: Using the run Ansible playbook procedure, you can run any playbooks and roles with additional parameters and variables.

  • Automated pipeline steps support: You can use EC-Ansible plugin procedures in pipeline stages, to be a part of release, to be run as parallel stages, or as parameterized pipeline stages.

  • Automated application stages support: Ansible procedures can run as a part of application stages.

Plugin version 2.0.0

Revised on December 15, 2022

Supported versions

The plugin has been tested with the following versions:

  • Ansible 2.9

  • Ansible 2.13

  • The plugin has been tested with Ansible targets on both Linux (Ubuntu, Debian) and Windows (10 Pro) hosts.

Plugin configurations

Plugin configurations are sets of parameters that can be applied across some, or all, of the plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD/RO, complete the following steps:

  1. Navigate to DevOps Essentials  Plugin Management  Plugin configurations.

  2. Select Add plugin configuration to create a new configuration.

  3. In the New Configuration window, specify a Name for the configuration.

  4. Select the Project that the configuration belongs to.

  5. Optionally, add a Description for the configuration.

  6. Select the appropriate Plugin for the configuration.

  7. Configure the parameters per the descriptions below.

Configuration procedure parameters

Parameter Description

Configuration Name

Required. The unique name for the configuration.

Description

A description of the configuration.

ansible-playbook path

Required. An absolute or relative path to ansible-playbook executable.

ansible path

Required. An absolute or relative path to ansible executable.

Disable host key check?

If checked, ansible will skip host key check.

Vault credentials

Credentials for vault.

Remote Connection Type

Required. Select the type of authentication to use for remote connection. Select Skip explicit auth if you don’t require any explicit auth, such as for local connections or when authentication is configured already on control machine.

Remote connection credentials

Credentials to connect.

Remote connection credentials

Credentials to connect.

Become credentials

Credentials to become.

Check Connection Resource

A resource which is used for the checking connection.

Check Connection?

If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.

Debug level

This option sets the debug level for logs. If Info is selected, only a summary is displayed. If Debug is selected, debug information is displayed. If Trace is selected, all requests and responses are displayed.

The following is an example configuration:

Configuring for Windows hosts

Windows Remote Management (WinRM) must be installed on your Windows host before configuration. For more information, refer to the Windows Remote Management documentation.

Windows configurations do not support become credentials.

Example Windows configuration:

Plugin procedures

Run Playbook

Run Ansible playbooks.

The Ansible plugin does not handle interactive prompts when executing commands. However, it invokes Ansible, which uses SSH to connect to remote machines. So, an implicit assumption is that SSH is configured so if the credentials are correct, no further interactive checks (such as fingerprint checks) are thrown as part of the SSH login.

Run Playbook parameters

Parameter Description

Configuration name

The unique name for the configuration.

Ansible playbook path

Required. Absolute path to Ansible playbook. For example, /home/ansible/playbook.yml.

Inventory

Specify inventory host path, such as`default=/etc/ansible/hosts`, or specify the content of an inventory file.

Tags

Only run plays and tasks tagged with these values. Tags can be defined per line or comma-separated.

Skip tags

Only run plays and tasks whose tags do not match these values. Tags can be defined per line or comma-separated.

Variables

Define the variables to pass to Ansible playbook. Variables may be defined in JSON or as newline separated key=value pairs and are passed as --extra-vars.

Verbose?

If checked, the output from ansible will be more verbose.

Additional parameters

Additional parameters to pass to ansible executable. Each parameter should start on a new line.

Result Property Sheet

Property Sheet name to save results into. The saved results are:

  • stdout: Raw STDOUT from ansible-playbook command.

  • recap: This property sheet will contain parsed RECAP part from the ansible-playbook output in the form like this:

    Host Name/
    changed: number
    failed: number
    ok: number
    unreachable: number
    passed: true|false
    • passed: true is returned only if there are no failed and unreachable tasks.

  • recapJSON: The same recap as above but in JSON.

  • verbose This property sheet will contain information about executed tasks with the following format:

    Task Name/
    Host Name/
    state: ok|failed|ignoring...
    raw: raw JSO output if any
    verbose: parsed output if any
  • verboseJSON: Contains the same data as verbose but in JSON.

Output parameters

Parameter Description

result

Run success/fail.

ansible_exitcode

Any returned Ansible exit codes.

ansible_stderr

STDERR output from Ansible.

Run Ad-Hoc Command

Run Ansible ad-hoc commands.

The Ansible plugin does not handle interactive prompts when executing commands. However, it invokes Ansible, which uses SSH to connect to remote machines. So, an implicit assumption is that SSH is configured so if the credentials are correct, no further interactive checks (such as fingerprint checks) are thrown as part of the SSH login.

Please refer to Introduction To Ad-Hoc Commands for more ad-hoc commands.

Run Ad-Hoc Command parameters

Parameter Description

Configuration name

The unique name for the configuration.

Server group

Required. Specify a server group to run a command.

Command/Module args

Specify a command to run, e.g. touch /tmp/myFile, or module arguments. The value of this field is passed as the argument --args.

Module

Module name to execute, such as command, shell, ping. Default is command.

Inventory

Specify inventory host path, such as default=/etc/ansible/hosts, or specify the content of an inventory file.

Verbose?

If checked, the output from Ansible will be more verbose.

Additional parameters

Additional parameters to pass to the Ansible executable. Start each parameter on a new line.

Output parameters

Parameter Description

result

Run success/fail.

ansible_exitcode

Any returned Ansible exit codes.

ansible_stderr

STDERR output from Ansible.

Use cases

Run Playbook procedure with snapshot

  1. Create a Task in your step and define the task to run the EC-Ansible plugin Run Playbook procedure.

  2. Add the parameters for the task, such as shown in:

    run playbook form
  3. Run the pipeline. The following is an example of the step’s operations:

The task’s log should look similar to:

The task’s output should look similar to:

Run Ad Hoc Command procedure with snapshot

  1. Create a Task in your step and define the task to run the EC-Ansible plugin Run adhoc procedure.

  2. Add the parameters for the task, such as shown in:

    run adhoc form
  3. Run the pipeline. The following is an example of the step’s operations:

The task’s log should look similar to:

Run Ansible command on Windows hosts

  1. Create Plugin configuration. If you have not created a Windows configuration, refer to Configuring for Windows hosts.

  2. Create Run Ad-Hoc Command procedure:

    demo win adhoc create
  3. Run the procedure. Expected outcome should be:

    demo win adhoc output
  4. Or use the following sample Windows playbook for the Run Playbook procedure on Windows hosts:

---
- name: WindowsVm
  hosts: windows-vm1
  connection: winrm
  vars:
    user: build
  tasks:
  - name: Create test folders on windows vm.
    win_file:
      path: C:\Users\build\test1
      state: directory

  - name: Show test folders on vm home directory.
    win_shell: ls C:\Users\{{ user }}\
    register: show_tables
  - debug: msg="{{ show_tables.stdout_lines }}"
....

Run Ansible from pipelines

  1. Create a pipeline.

  2. Add a pipeline stage with a step and define it to use the EC-Ansible plugin Run Playbook procedure.

    demo pipelines add
  3. Select Define and edit the Procedure Input Parameters.

    demo pipelines input params
  4. Define Procedure parameters:

    demo pipelines define
  5. Select OK and Save.

Run Ansible from applications

  1. Create an application.

  2. Create an application component using EC-Artifact or EC-Artifactory to retrieve the application’s Tomcat '*.war' artifact.

    demo apps component
  3. Create an application process

    demo apps process
  4. Create a step to run the EC-Ansible Run Playbook procedure.

    demo apps step process
  5. Choose Plugins  Resource Management  Ansible  Run Playbook procedure.

  6. Add your procedure parameters, path to Ansible inventory with hosts and path to the sample deploy-playbook.yml:

    demo apps params
  7. Deploy the following sample deploy-playbook.yml in the path you added for the procedure parameter.

    You can reuse the sample playbook with your application-specific changes.
    Windows platforms do not support the become options.
    ---
    - name: Deploy Application
     hosts: linux-vm1
     connection: ssh
     become: true
     become_user: root
     become_method: sudo
     vars:
       user: build
     tasks:
     - name: Delete application if exist
       file:
         state: absent
         path: /var/lib/tomcat7/webapps/hello-world.war
     - name: Copy Artifact to remote Tomcat Server
       copy:
         src: /home/ecloud/ansible/application/hello-world.war
         dest: /var/lib/tomcat7/webapps/
         owner: root
         group: root
         mode: 0644
     - name: Show application is copied
       shell: "ls -l /var/lib/tomcat7/webapps"
       register: out
     - debug: msg="{{ out.stdout_lines }}"
     - name: Restart Tomcat server
       shell: service tomcat7 restart
       register: restart
     - debug: msg="{{ restart.stdout_lines }}"
    ....
  8. Map the application to an existing an Ansible resource (local or remote) and run the application.

Running playbooks with Ansible vault

  1. Create a sample playbook and encrypt it using the following command:

    ansible-vault encrypt /path/to/playbook.yml --ask-vault-pass.
  2. Provide the vault password.

  3. Create a new plugin configuration and set the Vault credentials. Ensure your ansible playbook path and password match the vault you want to use. For instance:

    demo vault create
  4. When you run Ansible Run Playbook procedures, ensure you set the Configuration name to the one you configured the Vault credentials for.

Release notes

EC-Ansible 2.0.0

  • Plugin has been migrated to PDK.

EC-Ansible 1.4.4

  • Fixed an issue with Run Playbook procedure’s additional parameters only work when every word is on new line.

EC-Ansible 1.4.3

  • Documentation has been migrated to the documentation site.

EC-Ansible 1.4.2

  • Renaming to "CloudBees CD"

EC-Ansible 1.4.1

  • Fixed Binary Dependencies procedure to work with Gateways.

EC-Ansible 1.4.0

  • Provisioning of Binary Dependencies (for example Grape jars) in the agent resource, required by this plugin, is now delivered through a newly introduced mechanism called Plugin Dependency Management. Binary dependencies will now be seamlessly delivered to the agent resource from the Flow Server, any time a new version of a plugin is invoked the first time. Flow Repository set up is no longer required for this plugin.

EC-Ansible 1.3.1

  • Added Setup procedure to handle binary dependencies.

EC-Ansible 1.3.0

  • Add checking connection while creating/editing a configuration

EC-Ansible 1.2.1

  • Renaming to "CloudBees"

EC-Ansible 1.2.0

  • Improved plugin promotion time.

  • Added support for credentials stored in Vault, support for Become (Privilege Escalation).

  • Certified to work on Windows Hosts as Ansible Targets.

  • Improved support for large CLI command output.

EC-Ansible 1.1.2

  • Configurations can be created by users with "@" sign in a name.

EC-Ansible 1.1.1

  • Fix for getting actual parameters from different contexts.

EC-Ansible 1.1.0

  • Output processing has been added.

EC-Ansible 1.0.9

  • Fix for the intrinsic property names (i.e. "tags" parameter was not processed correctly in a context of a pipeline).

EC-Ansible 1.0.8

  • Labels for username and private key were added to the configuration.

EC-Ansible 1.0.7

  • Logo icon has been added.

EC-Ansible 1.0.6

  • Configured the plugin to allow the ElectricFlow UI to create configs inline of procedure form.

EC-Ansible 1.0.5

  • Configured the plugin to allow the ElectricFlow UI to render the plugin procedure parameters entirely using the configured form XMLs.

  • Enabled the plugin for managing the plugin configurations in-line when defining an application process step or a pipeline stage task.

EC-Ansible 1.0.4

  • Added logic for arguments escaping.

EC-Ansible 1.0.3

  • Added the Run Ad Hoc Command procedure.

EC-Ansible 1.0.2

  • Added an option to the config to skip host key check.

EC-Ansible 1.0.1

  • The documentation has been improved.

EC-Ansible 1.0.0

  • First release.