Chapter 3. Getting started as an automation developer

Procedure

1. In a terminal, navigate to the roles directory inside a collection.

2. Create a role called my_role inside the collection:

   $ ansible-galaxy role init my_role

   The collection now includes a role named my_role inside the roles directory, as you can see in this example:

   ~/.ansible/collections/ansible_collections/<my_namespace>/<my_collection_name>
       ...
       └── roles/
           └── my_role/
               ├── .travis.yml
               ├── README.md
               ├── defaults/
               │   └── main.yml
               ├── files/
               ├── handlers/
               │   └── main.yml
               ├── meta/
               │   └── main.yml
               ├── tasks/
               │   └── main.yml
               ├── templates/
               ├── tests/
               │   ├── inventory
               │   └── test.yml
               └── vars/
                   └── main.yml

3. A custom role skeleton directory can be supplied by using the --role-skeleton argument. This allows organizations to create standardized templates for new roles to suit their needs.

   $ ansible-galaxy role init my_role --role-skeleton ~/role_skeleton

   This creates a role named my_role by copying the contents of ~/role_skeleton into my_role. The contents of role_skeleton can be any files or folders that are valid inside a role directory.

Procedure

1. From the navigation panel, select Automation Content Namespaces.
2. Within the My namespaces tab, locate and click into the namespace to which you want to upload a collection.
3. Select the Collections tab, and then click Upload collection.
4. In the New collection modal, click Select file. Locate the file on your system.
5. Click Upload.

Procedure

1. Log in to registry.redhat.io.

   $ podman login registry.redhat.io

2. Pull the base images from the registry:

Procedure

1. From the navigation panel, select Automation Execution Infrastructure Execution Environments.
2. Click Create execution environment to create an execution environment.

3. Enter the appropriate details into the following fields:

   1. Name (required): Enter a name for the execution environment.
   2. Image (required): Enter the image name. The image name requires its full location (repository), the registry, image name, and version tag, as in the following example: quay.io/ansible/awx-ee:latestrepo/project/image-name:tag

   3. Optional: Pull: Choose the type of pull when running jobs:

      1. Always pull container before running: Pulls the latest image file for the container.
      2. Only pull the image if not present before running: Only pulls the latest image if none are specified.

      3. Never pull container before running: Never pull the latest version of the container image.

         Note

         If you do not set a type for pull, the value defaults to Only pull the image if not present before running.

   4. Optional: Description: Enter an optional description.
   5. Optional: Organization: Assign the organization to specifically use this execution environment. To make the execution environment available for use across multiple organizations, leave this field blank.
   6. Registry credential: If the image has a protected container registry, provide the credential to access it.
4. Click Create execution environment. Your newly added execution environment is ready to be used in a job template.
5. To add an execution environment to a job template, navigate to Automation Execution Templates and select your template. ..Click Edit template and specify your execution environment in the field labeled execution environment.

Procedure

1. Navigate to Automation Decisions Decision Environments.
2. Click Create decision environment.

3. Enter the following:

   Name

   Insert the name.

   Description

   This field is optional.

   Image

   This is the full image location, including the container registry, image name, and version tag.

   Credential

   This field is optional. This is the token needed to use the decision environment image.

4. Select Create decision environment.

Procedure

1. From the navigation panel, select Automation Execution Infrastructure Inventories. The Inventories view displays a list of the inventories currently available.
2. Click Create inventory, and from the list menu select the type of inventory you want to create.

3. Enter the appropriate details into the following fields:

   • Name: Enter a name for the inventory.
   • Optional: Description: Enter a description.
   • Organization: Choose among the available organizations.
   • Only applicable to Smart Inventories: Smart Host Filter: Filters are similar to tags in that tags are used to filter certain hosts that contain those names. Therefore, to populate this field, specify a tag that contains the hosts you want, not the hosts themselves. Filters are case-sensitive. For more information, see Smart host filters in the Using automation execution guide.
   • Instance groups: Select the instance group or groups for this inventory to run on. If the list is extensive, use the search to narrow the options. You can select multiple instance groups and sort them in the order that you want them run.
   • Optional: Labels: Add labels that describe this inventory, so they can be used to group and filter inventories and jobs.
   • Only applicable to constructed inventories: Input inventories: Specify the source inventories to include in this constructed inventory. Empty groups from input inventories are copied into the constructed inventory.
   • Optional and only applicable to constructed inventories: Cache timeout (seconds):Set the length of time you want the cache plugin data to timeout.

   • Only applicable to constructed inventories: Verbosity: Control the level of output that Ansible produces as the playbook executes related to inventory sources associated with constructed inventories. Select the verbosity from Normal to various Verbose or Debug settings. This only appears in the "details" report view.

     • Verbose logging includes the output of all commands.
     • Debug logging is exceedingly verbose and includes information on SSH operations that can be useful in certain support instances. Most users do not need to see debug mode output.
   • Only applicable to constructed inventories: Limit: Restricts the number of returned hosts for the inventory source associated with the constructed inventory. You can paste a group name into the limit field to only include hosts in that group. For more information, see the Source variables setting.

   • Only applicable to standard inventories: Options: Check the box next to Prevent instance group fallback to enable only the instance groups listed in the Instance groups field to execute the job. If unchecked, all available instances in the execution pool will be used based on the hierarchy described in Control where a job runs in the Configuring automation execution guide. Click the tooltip for more information.

     Note

     Set the prevent_instance_group_fallback option for smart inventories through the API.

   • Variables (Source variables for constructed inventories):

     • Variables: Variable definitions and values to apply to all hosts in this inventory. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two.
     • Source variables for constructed inventories are used to configure the constructed inventory plugin. Source variables create groups under the groups data key. The variable accepts Jinja2 template syntax, renders it for every host, makes a true or false evaluation, and includes the host in the group (from the key of the entry) if the result is true.
4. Click Create inventory.

Procedure

1. To review existing templates, select Automation Execution Templates from the navigation panel.
2. Click Demo Job Template to view its details.

Procedure

1. From the navigation panel, select Automation Execution Templates.
2. On the Templates page, select Create job template from the Create template list.

3. Enter the appropriate details in the following fields:

   Note

   If a field has the Prompt on launch checkbox selected, launching the job prompts you for the value for that field when launching.

   Most prompted values override any values set in the job template.

   Exceptions are noted in the following table.

   Field	Options	Prompt on Launch
   Name	Enter a name for the job.	N/A
   Description	Enter an arbitrary description as appropriate (optional).	N/A
   Job Type	Choose a job type: Run: Start the playbook when launched, running Ansible tasks on the selected hosts. Check: Perform a "dry run" of the playbook and report changes that would be made without actually making them. Tasks that do not support check mode are missed and do not report potential changes. For more information about job types see the Playbooks section of the Ansible documentation.	Yes
   Inventory	Choose the inventory to use with this job template from the inventories available to the logged in user. A System Administrator must grant you or your team permissions to be able to use certain inventories in a job template.	Yes. Inventory prompts show up as its own step in a later prompt window.
   Project	Select the project to use with this job template from the projects available to the user that is logged in.	N/A
   Source control branch	This field is only present if you chose a project that allows branch override. Specify the overriding branch to use in your job run. If left blank, the specified SCM branch (or commit hash or tag) from the project is used. For more information, see Job branch overriding.	Yes
   Execution Environment	Select the container image to be used to run this job. You must select a project before you can select an execution environment.	Yes. Execution environment prompts show up as its own step in a later prompt window.
   Playbook	Choose the playbook to be launched with this job template from the available playbooks. This field automatically populates with the names of the playbooks found in the project base path for the selected project. Alternatively, you can enter the name of the playbook if it is not listed, such as the name of a file (such as foo.yml) you want to use to run with that playbook. If you enter a filename that is not valid, the template displays an error, or causes the job to fail.	N/A
   Credentials	Select the icon to open a separate window. Choose the credential from the available options to use with this job template. Use the drop-down menu list to filter by credential type if the list is extensive. Some credential types are not listed because they do not apply to certain job templates.	If selected, when launching a job template that has a default credential and supplying another credential replaces the default credential if it is the same type. The following is an example of this message: Job Template default credentials must be replaced with one of the same type. Please select a credential for the following types in order to proceed: Machine. You can add more credentials as you see fit. Credential prompts show up as its own step in a later prompt window.
   Labels	Optionally supply labels that describe this job template, such as dev or test. Use labels to group and filter job templates and completed jobs in the display. Labels are created when they are added to the job template. Labels are associated with a single Organization by using the Project that is provided in the job template. Members of the Organization can create labels on a job template if they have edit permissions (such as the admin role). Once you save the job template, the labels appear in the Job Templates overview in the Expanded view. Select beside a label to remove it. When a label is removed, it is no longer associated with that particular Job or Job Template, but it remains associated with any other jobs that reference it. Jobs inherit labels from the Job Template at the time of launch. If you delete a label from a Job Template, it is also deleted from the Job.	If selected, even if a default value is supplied, you are prompted when launching to supply additional labels, if needed. You cannot delete existing labels, selecting only removes the newly added labels, not existing default labels.
   Forks	The number of parallel or simultaneous processes to use while executing the playbook. A value of zero uses the Ansible default setting, which is five parallel processes unless overridden in /etc/ansible/ansible.cfg.	Yes
   Limit	A host pattern to further constrain the list of hosts managed or affected by the playbook. You can separate many patterns by colons (:). As with core Ansible: a:b means "in group a or b" a:b:&c means "in a or b but must be in c" a:!b means "in a, and definitely not in b" For more information, see Patterns: targeting hosts and groups in the Ansible documentation.	Yes If not selected, the job template executes against all nodes in the inventory or only the nodes predefined on the Limit field. When running as part of a workflow, the workflow job template limit is used instead.
   Verbosity	Control the level of output Ansible produces as the playbook executes. Choose the verbosity from Normal to various Verbose or Debug settings. This only appears in the details report view. Verbose logging includes the output of all commands. Debug logging is exceedingly verbose and includes information about SSH operations that can be useful in certain support instances. Verbosity 5 causes automation controller to block heavily when jobs are running, which could delay reporting that the job has finished (even though it has) and can cause the browser tab to lock up.	Yes
   Job Slicing	Specify the number of slices you want this job template to run. Each slice runs the same tasks against a part of the inventory. For more information about job slices, see Job Slicing.	Yes
   Timeout	This enables you to specify the length of time (in seconds) that the job can run before it is canceled. Consider the following for setting the timeout value: There is a global timeout defined in the settings which defaults to 0, indicating no timeout. A negative timeout (<0) on a job template is a true "no timeout" on the job. A timeout of 0 on a job template defaults the job to the global timeout (which is no timeout by default). A positive timeout sets the timeout for that job template.	Yes
   Show Changes	Enables you to see the changes made by Ansible tasks.	Yes
   Instance Groups	Choose Instance and Container Groups to associate with this job template. If the list is extensive, use the icon to narrow the options. Job template instance groups contribute to the job scheduling criteria, see Job Runtime Behavior and Control where a job runs for rules. A System Administrator must grant you or your team permissions to be able to use an instance group in a job template. Use of a container group requires admin rights.	Yes. If selected, you are providing the jobs preferred instance groups in order of preference. If the first group is out of capacity, later groups in the list are considered until one with capacity is available, at which point that is selected to run the job. If you prompt for an instance group, what you enter replaces the normal instance group hierarchy and overrides all of the organizations' and inventories' instance groups. The Instance Groups prompt shows up as its own step in a later prompt window.
   Job Tags	Type and select the Create menu to specify which parts of the playbook should be executed. For more information and examples see Tags in the Ansible documentation.	Yes
   Skip Tags	Type and select the Create menu to specify certain tasks or parts of the playbook to skip. For more information and examples see Tags in the Ansible documentation.	Yes
   Extra Variables	Pass extra command line variables to the playbook. This is the "-e" or "-extra-vars" command line parameter for ansible-playbook that is documented in the Ansible documentation at Defining variables at runtime. Provide key or value pairs by using either YAML or JSON. These variables have a maximum value of precedence and overrides other variables specified elsewhere. The following is an example value: git_branch: production release_version: 1.5	Yes. If you want to be able to specify extra_vars on a schedule, you must select Prompt on launch for Variables on the job template, or enable a survey on the job template. Those answered survey questions become extra_vars.

4. You can set the following options for launching this template, if necessary:

   • Privilege escalation: If checked, you enable this playbook to run as an administrator. This is the equal of passing the --become option to the ansible-playbook command.
   • Provisioning callback: If checked, you enable a host to call back to automation controller through the REST API and start a job from this job template. For more information, see Provisioning Callbacks.

   • Enable webhook: If checked, you turn on the ability to interface with a predefined SCM system web service that is used to launch a job template. GitHub and GitLab are the supported SCM systems. If you enable webhooks, other fields display, prompting for additional information:

     • Webhook service: Select which service to listen for webhooks from.
     • Webhook URL: Automatically populated with the URL for the webhook service to POST requests to.
     • Webhook key: Generated shared secret to be used by the webhook service to sign payloads sent to automation controller. You must configure this in the settings on the webhook service in order for automation controller to accept webhooks from this service.

     • Webhook credential: Optionally, give a GitHub or GitLab personal access token (PAT) as a credential to use to send status updates back to the webhook service.

       Before you can select it, the credential must exist.

       See Credential Types to create one.

     • For additional information about setting up webhooks, see Working with Webhooks.
   • Concurrent jobs: If checked, you are allowing jobs in the queue to run simultaneously if not dependent on one another. Check this box if you want to run job slices simultaneously. For more information, see Automation controller capacity determination and job impact.
   • Enable fact storage: If checked, automation controller stores gathered facts for all hosts in an inventory related to the job running.
   • Prevent instance group fallback: Check this option to allow only the instance groups listed in the Instance Groups field to run the job. If clear, all available instances in the execution pool are used based on the hierarchy described in Control where a job runs.
5. Click Create job template, when you have completed configuring the details of the job template.

Verification

1. From the navigation panel, select Automation Execution Templates.
2. Verify that the newly created template appears on the Templates page.

Procedure

1. Open the template to edit it by using one of these methods:

   • Click Edit in the job template Details page.
   • From the navigation panel, select Automation Execution Templates. Click Edit next to the template name and edit the appropriate details.

2. Save your changes.

   
3. To exit after saving and return to the Templates list view, use the breadcrumb navigation links or click Cancel. Clicking Save does not exit the Details dialog.

Procedure

1. From the navigation panel, select Automation Decisions Rulebook Activations.
2. Click Create rulebook activation.

3. Enter the following information:

   • Name: Insert the name.
   • Description: This field is optional.
   • Organization: This field is optional.
   • Project: This field is optional.
   • Rulebook: Rulebooks are displayed according to the project you selected.

   • Credential: Select 0 or more credentials for this rulebook activation. This field is optional.

     Note

     The credentials that display in this field are customized based on your rulebook activation and only include the following credential types: Vault, Red Hat Ansible Automation Platform, or any custom credential types that you have created. For more information about credentials, see Credentials in the Using automation decisions guide.

   • Decision environment: A decision environment is a container image to run Ansible rulebooks.

     Note

     In Event-Driven Ansible controller, you cannot customize the pull policy of the decision environment. By default, it follows the behavior of the always policy. Every time an activation is started, the system tries to pull the most recent version of the image.

   • Restart policy: This is the policy that determines how an activation should restart after the container process running the source plugin ends. Select from the following options:

     • Always: This restarts the rulebook activation immediately, regardless of whether it ends successfully or not, and occurs no more than 5 times.
     • Never: This never restarts a rulebook activation when the container process ends.
     • On failure: This restarts the rulebook activation after 60 seconds by default, only when the container process fails, and occurs no more than 5 times.

   • Log level: This field defines the severity and type of content in your logged events. Select from one of the following options:

     • Error: Logs that contain error messages that are displayed in the History tab of an activation.
     • Info: Logs that contain useful information about rulebook activations, such as a success or failure, triggered action names and their related action events, and errors.
     • Debug: Logs that contain information that is only useful during the debug phase and might be of little value during production. This log level includes both error and log level data.
   • Service name: This defines a service name for Kubernetes to configure inbound connections if the activation exposes a port. This field is optional.
   • Rulebook activation enabled?: Toggle to automatically enable the rulebook activation to run.
   • Variables: The variables for the rulebook are in JSON or YAML format. The content would be equivalent to the file passed through the --vars flag of ansible-rulebook command.
   • Options: Check the Skip audit events option if you do not want to see your events in the Rule Audit.
4. Click Create rulebook activation.

Procedure

1. Select the switch on the row level to enable or disable your chosen rulebook.
2. In the window, select Yes, I confirm that I want to enable/disable these X rulebook activations.
3. Select Enable/Disable rulebook activation.

Procedure

1. Select the More Actions icon ⋮ next to Rulebook Activation enabled/disabled toggle.
2. Select Restart rulebook activation.
3. In the window, select Yes, I confirm that I want to restart these X rulebook activations.
4. Select Restart rulebook activations.

Procedure

1. Select the More Actions icon ⋮ next to the Rulebook Activation enabled/disabled toggle.
2. Select Delete rulebook activation.
3. In the window, select Yes, I confirm that I want to delete these X rulebook activations.
4. Select Delete rulebook activations.

Procedure

1. Create a Route (on OpenShift Container Platform) to expose the service. The following is an example Route for an ansible-rulebook source that expects POST’s on port 5000 on the decision environment pod:

   kind: Route
   apiVersion: route.openshift.io/v1
   metadata:
     name: test-sync-bug
     namespace: dynatrace
     labels:
       app: eda
       job-name: activation-job-1-5000
   spec:
     host: test-sync-bug-dynatrace.apps.aap-dt.ocp4.testing.ansible.com
     to:
       kind: Service
       name: activation-job-1-5000
       weight: 100
     port:
       targetPort: 5000
     tls:
       termination: edge
       insecureEdgeTerminationPolicy: Redirect
     wildcardPolicy: None

2. When you create the Route, test it with a Post to the Route URL:

   curl -H "Content-Type: application/json" -X POST
   test-sync-bug-dynatrace.apps.aap-dt.ocp4.testing.ansible.com -d
   '{}'

   Note

   You do not need the port as it is specified on the Route (targetPort).