Ansible

Integrating Ansible to perform deployments.

Using Ansible to Perform Deployments

DeployHub supports the ability to run any Ansible Playbook you create. It does this using pre-defined DeployHub Procedures that you can use to create a DeployHub Action of your choosing. Once created, you the Action can call any Ansible Playbook. The most common use is for performing deployments, but you can also use the Action to execute Pre Actions or Post Actions to the deployment.

Ansible as Your Deployment Engine

DeployHub allows you to override the default deployment engine with external deployment solutions such as Ansible. This is supported so you can use your own previously developed Ansbile deployment process instead of re-defining the process to the DeployHub deployment engine. Or it may be the case that you are experienced with Ansible and choose to continue using it for new deployments. DeployHub uses an Ansible Action that allows you to make a call to your Ansible process and turn over the deployment processing to Ansible.

How the Ansible Actions Works

The Ansible Action will clone your Playbook Git repository into the working directory of the Deployhub engine (DropZone). It will then create a “values” file based on the Component you are deploying, and then it will run your Playbook. The results of your Playbook are included in the deployment log.

Creating Your Ansible Action

You will need to create an Ansible Action that will use your Ansible Playbook. This is done by adding the DeployHub pre-defined Procedures and then defining them to an Action that your Component will use for deployment. For more details on creating Procedures and Actions see:

The following steps will take you through the process:

Step 1 - Download and Import the Ansible Playbooks as Procedures

Download the following 3 DeployHub Procedures from the Ortelius Git Repo. These Procedures will support the steps you need to run your own Ansbile Playbook.

  • GitCheckout.re - This Procedure pulls the repo into the DeployHub Dropzone and then checks out the commit, branch or tag specified.

  • WriteEnv2File.re - This Procedure writes the Attributes to a file that will be used by the Playbook.

  • RunAnsiblePlayBook.re - This Procedure executes the Playbook using variables file created by WriteEnv2File.

Step 2 - Create your Procedures

Once downloaded, you will need to Import the scripts into DeployHub as Procedures. To import these Procedures navigate to the Func/Procs Menu option on the left hand side of the DeployHub Main Menu panel. This will take you to the Functions and Procedures List View. From the Functions and Procedures List View select the Import option. The Import will bring you to your operating system “file open” dialog box for selecting the GitCheckout.re, WriteEnv2File.re and RunAnsiblePlayBook.re files.

Next, select your “Global,” or highest level, Domain and upload the Procedure into DeployHub. If you select a lower level Subdomain you will restrict access. By defining it to your highest level Domain, all Users will be able to see the Procedures. Once you have both imported, you are now ready to create your Action.

Step 3 - Create your Ansible Action using your Procedures

Once you have imported the Ansible files as Procedures, you ready to define your Action. Navigate to the Actions list view from the Actions menu option on the left hand side of the DeployHub Main Menu panel.

Use the +Add option to create a new Action for you Procedure. In the “Full Domain” field select your “Global” Domain. If you select a lower level Subdomain you will restrict access to this Custom Action. By defining it to your highest level Domain, all Users will be able to execute the process regardless of their SubDomain.

Name the new Action AnsiblePlaybook (no spaces).

Now we are going to customize this Action. On the right hand side, you will see a list of Functions and Procedures you can choose from. Navigate to your Domain to find the GitCheckout.re, WriteEnv2File.re and RunAnsiblePlayBook.re imported Procedures. Drag them onto the area under “Start”. The order should be GitCheckout, WriteEnv2File, RunAnsiblePlaybook.

When you drag your Ansible Procedures onto the area under “Start” a pop-up dialog box will open for you to complete the following parameters:

GitCheckout Parameters

Field Value Description
Title Not Required Name of the step in your deployment workflow.
Summary Not Required Enter a summary of this step.
Git Repo $GIT_URL Repo containing the Playbook
Git Commit $GIT_COMMIT The commit, tag or branch to checkout
To Dir $GIT_DIR The directory to checkout into. Use “.” for the default directory

RunAnsiblePlaybook Parameters

Field Value Description
Title Not Required Name of the step in your deployment workflow.
Summary Not Required Enter a summary of this step.
RspFile $RspFile The results from the WriteEnv2Toml.re Procedure

WriteEnv2File Parameters

No Parameter fields are required for WriteEnv2File.

At this point the Action is ready to be used by anyone with access (based on Domain and security options). Each Component that uses the Action will need to define specific values. Because this new Action is reusable, no Component variables are defined at the Action level.

Step 4 - Assign the AnsiblePlaybook Action to a Component

Now that you have defined your Ansible Action you are ready to assign it to the Components. For using your Ansible Playbook to perform the deployment of the Component you define it to the Custom Action field at the Component level. If a Custom Action is defined, DeployHub will call the Custom Action instead of using its internal deployment engine. When you define your Custom Action you will select “AnsiblePlaybook.” You will be given a dialog box to input the needed variable values. Values are specific to the Component. Values will override those defined at the Application or Environment level. The values from DeployHub will be passed along to the Playbook at execution time. See Defining Components for more information.

You can also use the AnsiblePlaybook Action to execute Pre and Post Actions. Using it in these fields will not override the standard deployment processing.

**Step 5 - Set Your Component Attributes_**

The following variables must be added to the Attributes Section for all Components using the AnsiblePlaybook Action. The Attributes section can be found on the Component Dashboard. Use the +Add option in this section to add a row for the variable. You must use Save to commit the row to the table:

Variable Name Value Description
GIT_URL Repo containing the Playbook
GIT_COMMIT The commit, tag or branch to checkout
GIT_DIR The directory to checkout into. Use “.” for the default directory
taskfile The name of the Playbook to run
Last modified July 9, 2020: small cleanup (b45ee8f)