Getting started with Ansible Automation Platform

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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.

6. Optional: you can also upload from the command line. Using the ansible-galaxy client, enter the following command:

   $ ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz --api-key=SECRET

   Copy to Clipboard Toggle word wrap

Procedure

1. Log in to registry.redhat.io.

   $ podman login registry.redhat.io

   Copy to Clipboard Toggle word wrap
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.

   1. 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.

   Your decision environment is now created and can be managed on the Decision Environments page.

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 → Jobs or Automation Execution → Templates.
2. Beneath the page heading, next to Domains, is a list of topic-related labels. Select a label to filter jobs and job templates so that only content related to the labels is shown. You can choose more than one label.
3. To clear your selection, click the X.
4. To customize your domain options, select the icon. In the modal that appears, select Add Domain to add new domains to filter with.

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.

   Expand

   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.

   Show more

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.

   Creating the template does not exit the job template page but advances to the Job Template Details tab. After saving the template, you can click Launch template to start the job. You can also click Edit to add or change the attributes of the template, such as permissions, notifications, view completed jobs, and add a survey (if the job type is not a scan). You must first save the template before launching, otherwise, Launch template remains disabled.

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.

   

   View larger image

   
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.

   Your rulebook activation is now created and can be managed on the Rulebook Activations page.

   Note

   Occasionally, when a source plugin shuts down, it causes a rulebook to exit gracefully after a certain amount of time. When a rulebook activation shuts down, any tasks that are waiting to be performed will be canceled, and an info level message is sent to the activation log. For more information, see Rulebooks.

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

   Copy to Clipboard Toggle word wrap

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

   Note

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

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

   Copy to Clipboard Toggle word wrap

Procedure

1. From the navigation panel, select Automation Execution → Templates.
2. Select a template to view its details. A default job template is created during your initial setup to help you get started, but you can also create your own.
3. From the Templates page, click the launch icon to run your job template.

Procedure

1. From the navigation panel, select Automation Execution → Templates.
2. Select the job template you want to create a survey for.
3. From the Survey tab, click Create survey question.

4. A survey can consist of any number of questions. For each question, enter the following information:

   • Question: The question to ask the user.
   • Optional: Description: A description of what is being asked of the user.
   • Answer variable name: The Ansible variable name to store the user’s response in. This is the variable to be used by the playbook. Variable names cannot contain spaces.

   • Answer type: Choose from the following question types:

     • Text: A single line of text. You can set the minimum and maximum length (in characters) for this answer.
     • Textarea: A multi-line text field. You can set the minimum and maximum length (in characters) for this answer.
     • Password: Responses are treated as sensitive information, much like an actual password is treated. You can set the minimum and maximum length (in characters) for this answer.
     • Multiple Choice (single select): A list of options, of which only one can be selected at a time. Enter the options, one per line, in the Multiple Choice Options field.
     • Multiple Choice (multiple select): A list of options, any number of which can be selected at a time. Enter the options, one per line, in the Multiple Choice Options field.
     • Integer: An integer number. You can set the minimum and maximum length (in characters) for this answer.
     • Float: A decimal number. You can set the minimum and maximum length (in characters) for this answer.
   • Required: Whether or not an answer to this question is required from the user.
   • Minimum length and Maximum length: Specify if a certain length in the answer is required.
   • Default answer: The default answer to the question. This value is pre-filled in the interface and is used if the answer is not provided by the user.

5. Once you have entered the question information, click Create question to add the question.

   The survey question displays in the Survey list. For any question, you can click to edit it.

   Check the box next to each question and click Delete to delete the question, or use the toggle option in the menu bar to enable or disable the survey prompts.

   If you have more than one survey question, click Edit Order to rearrange the order of the questions by clicking and dragging on the grid icon.

6. To add more questions, click Add.

Procedure

1. From the navigation panel, select Automation Execution → Infrastructure → Inventories. The Inventories window displays a list of inventories that are currently available, along with the following information:

   • Name: The inventory name.

   • Status: The statuses are:

     • Success: The inventory sync completed successfully.
     • Disabled: No inventory source added to the inventory.
     • Error: The inventory source completed with error.
   • Type: Identifies whether the inventory is a standard inventory, a smart inventory, or a constructed inventory.
   • Organization: The organization to which the inventory belongs.
2. Select an inventory name to display the Details page for the inventory, including the inventory’s groups and hosts.

Procedure

1. From the navigation panel, select Automation Execution → Jobs.

   The default view is collapsed (Compact) with the job name, status, job type, start, and finish times. You can click the arrow icon to expand and see more information. You can sort this list by various criteria, and perform a search to filter the jobs of interest.

2. From this screen, you can complete the following tasks:

   • View a job’s details and standard output.
   • Relaunch jobs.

   • Remove selected jobs.

     The relaunch operation only applies to relaunches of playbook runs and does not apply to project or inventory updates, system jobs, or workflow jobs.

Procedure

1. From the navigation panel, select Automation Execution → Jobs.

2. Select a job. This takes you to the Output view for that job, where you can filter job output by these criteria:

   • The Search output option allows you to search by keyword.
   • The Event option enables you to filter by the events of interest, such as errors, host failures, host retries, and items skipped. You can include as many events in the filter as necessary.