Chapter 3. Getting started as an automation developer
Chapter 3. Getting started as an automation developer As an automation developer, you can use Ansible Automation Platform to implement your organization's automation strategy. Ansible Automation Platform can help you write, test, and share automation content, and download and use Red Hat certified collections. This guide will walk you through the basic steps to get set up as an automation developer on Ansible Automation Platform, with information on how to: Set up your development environment Create, publish, and use custom automation content Build and use automation execution environments and decision environments Create and run rulebook activations for Event-Driven Ansible Create and use job templates 3.1. Setting up your development environment Before you begin to create content, consult our guide to Developing automation content . There you can find information on Ansible development tools, which you can integrate into your environment, and learn how to scaffold a playbook project. 3.2. Create automation content with playbooks Ansible playbooks are blueprints that tell Ansible Automation Platform what tasks to perform with which devices. You can use a playbook to define the automation tasks that you want the platform to run. 3.2.1. Create a playbook A playbook contains one or more plays. A basic play contains the following parameters: Name : a brief description of the overall function of the playbook, which assists in keeping it readable and organized for all users. Hosts : identifies the target or targets for Ansible to run against. Become statements : this optional statement can be set to true or yes to enable privilege escalation using a become plugin (such as sudo , su , pfexec , doas , pbrun , dzdo , ksu ). Tasks : this is the list of actions that get executed against each host in the play. Here is an example of a play in a playbook. You can see the name of the play, the host, and the list of tasks included in the play. - name: Set Up a Project and Job Template hosts: host.name.ip become: true tasks: - name: Create a Project ansible.controller.project: name: Job Template Test Project state: present scm_type: git scm_url: https://github.com/ansible/ansible-tower-samples.git - name: Create a Job Template ansible.controller.job_template: name: my-job-1 project: Job Template Test Project inventory: Demo Inventory playbook: hello_world.yml job_type: run state: present For more detailed instructions on authoring playbooks, see Developing automation content , or consult our documentation on Red Hat Ansible Lightspeed with IBM watsonx Code Assistant User Guide to learn how to generate a playbook with AI assistance. 3.3. Define events with rulebooks An Ansible rulebook is a collection of rulesets that references one or more sources, rules, and conditions. Rulebooks are to Event-Driven Ansible what playbooks are to Ansible Automation Platform as a whole. Like a playbook, a rulebook defines automation tasks for the platform, along with when they should be triggered. 3.3.1. Rulebook actions Rulebooks use an "if-this-then-that" logic that tells Event-Driven Ansible what actions to activate when a rule is triggered. Event-Driven Ansible listens to the controller event stream and, when an event triggers a rule, activates an automation action in response. Rulebooks can trigger the following activations: run_job_template run_playbook (only supported with ansible-rulebook CLI) debug print_event set_fact post_event retract_fact shutdown To read more about rulebook activations, see Actions in the Ansible Rulebook documentation. 3.4. Bundle content with Ansible roles A role is like a customized piece of automation content that bundles together relevant bits from playbooks to fit your system's specific needs. Roles are self-contained and portable, and can include groupings of tasks, variables, configuration templates, handlers, and other supporting files to orchestrate complicated automation flows. Instead of creating huge playbooks with hundreds of tasks, you can use roles to break the tasks apart into smaller, more discrete units of work. To learn more about roles, see What is an Ansible Role-and how is it used? . 3.4.1. Creating a role You can create roles using the Ansible Galaxy CLI tool, which is included with your Ansible Automation Platform bundle. Access role-specific commands from the role subcommand: ansible-galaxy role init <role_name> Standalone roles outside of Collections are supported. Create new roles inside a Collection to take advantage of the features Ansible Automation Platform has to offer. Procedure In a terminal, navigate to the roles directory inside a collection. Create a role called my_role inside the collection: USD 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 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. USD 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. 3.5. About content collections Ansible content collections are assemblages of automation content. There are two types of Ansible collections: Ansible Certified Content Collections , which contain fully-supported roles and modules that are enterprise- and production-ready for use in your environments. Ansible validated content collections , which provide you with a trusted, expert-guided approach for performing foundational operations and tasks in your product. Both types of content collections can be found in automation hub through the Hybrid Cloud Console . 3.6. Publishing to a collection You can configure your projects to be uploaded to Git, or to the source control manager of your choice. Procedure From the navigation panel, select Automation Execution Projects . Locate or create the project that you want to publish to your source control manager. In the project Details tab, select Edit project . Select Git from the Source Control Type drop-down menu. Enter the appropriate details into the following fields: Source Control URL - see an example in the tooltip. Optional: Source control branch/tag/commit : Enter the SCM branch, tags, commit hashes, arbitrary refs, or revision number (if applicable) from the source control to checkout. Some commit hashes and references might not be available unless you also provide a custom refspec in the field. If left blank, the default is HEAD , which is the last checked out branch, tag, or commit for this project. Source Control Refspec - This field is an option specific to Git source control and only advanced users familiar and comfortable with Git should specify which references to download from the remote repository. For more information, see Job branch overriding . Source Control Credential - If authentication is required, select the appropriate source control credential. Optional: Options - select the launch behavior, if applicable: Clean - Removes any local modifications before performing an update. Delete - Deletes the local repository in its entirety before performing an update. Depending on the size of the repository this can significantly increase the amount of time required to complete an update. Track submodules - Tracks the latest commit. See the tooltip for more information. Update Revision on Launch - Updates the revision of the project to the current revision in the remote source control, and caches the roles directory from Ansible Galaxy or Collections support . Automation controller ensures that the local revision matches and that the roles and collections are up-to-date with the last update. In addition, to avoid job overflows if jobs are spawned faster than the project can synchronize, selecting this enables you to configure a cache timeout to cache project synchronizations for a given number of seconds. Allow Branch Override - Enables a job template or an inventory source that uses this project to start with a specified SCM branch or revision other than that of the project. For more information, see Job branch overriding . Click Save to save your project. 3.6.1. Uploading a collection to automation hub If you want to share a collection that you have created with the rest of the Ansible community, you can upload it to automation hub. Note Sharing a collection with the Ansible community requires getting the collection certified or validated by our Partner Engineering team. This action is available only to partner clients. For more about becoming a partner, see our documentation on software certification . You can upload your collection by using either the automation hub user interface or the ansible-galaxy client. Prerequisites You have configured the ansible-galaxy client for automation hub. You have at least one namespace. You have run all content through ansible-test sanity Procedure From the navigation panel, select Automation Content Namespaces . Within the My namespaces tab, locate and click into the namespace to which you want to upload a collection. Select the Collections tab, and then click Upload collection . In the New collection modal, click Select file . Locate the file on your system. Click Upload . Using the ansible-galaxy client, enter the following command: USD ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz --api-key=SECRET 3.7. Build and use an execution environment All automation in Red Hat Ansible Automation Platform runs on container images called automation execution environments. Automation execution environments are consistent and shareable container images that serve as Ansible control nodes. Automation execution environments reduce the challenge of sharing Ansible content that has external dependencies. If automation content is like a script that a developer has written, an automation execution environment is like a replica of that developer's environment, thereby enabling you to reproduce and scale the automation content that the developer has written. In this way, execution environments make it easier for you to implement automation in a range of environments. Automation execution environmentss contain: Ansible Core Ansible Runner Ansible Collections Python libraries System dependencies Custom user needs You can either use the default base execution environment included in your Ansible Automation Platform subscription, or you can define and create an automation execution environment using Ansible Builder. 3.7.1. Using the base automation execution environment Your subscription with Ansible Automation Platform gives you access to some base automation execution environments. You can use a base automation execution environments as a starting point for creating a customized execution environment. Base images included with Ansible Automation Platform are hosted on the Red Hat Ecosystem Catalog (registry.redhat.io). Prerequisites You have a valid Red Hat Ansible Automation Platform subscription. Procedure Log in to registry.redhat.io. USD podman login registry.redhat.io Pull the base images from the registry: USDpodman pull registry.redhat.io/aap/<image name> 3.7.1.1. Customize the base execution environment image Ansible Automation Platform includes the following default execution environments: Minimal - Includes the latest Ansible-core 2.15 release along with Ansible Runner, but does not include collections or other content EE Supported - Minimal, plus all Red Hat-supported collections and dependencies While these environments cover many automation use cases, you can add additional items to customize these containers for your specific needs. For more information about customizing your execution environment, see Customizing an existing automation execution environment image in the Creating and using execution environments guide. 3.7.1.2. About Ansible Builder You also have the option of creating an entirely new execution environment with Ansible Builder, also referred to as execution environment builder. Ansible Builder is a command line tool you can use to create an execution environment for Ansible. You can only create execution environments with Ansible Builder. To build your own execution environment, you must: Download Ansible Builder Create a definition file that defines your execution environment Create an execution environment image based on the definition file For more information about building an execution environment, see Creating and using execution environments . 3.7.2. Adding an execution environment to a job template Prerequisites An execution environment must have been created using ansible-builder as described in Using Ansible Builder . When an execution environment has been created, you can use it to run jobs. Use the automation controller UI to specify the execution environment to use in your job templates. Depending on whether an execution environment is made available for global use or tied to an organization, you must have the appropriate level of administrator privileges to use an execution environment in a job. Execution environments tied to an organization require Organization administrators to be able to run jobs with those execution environment. Before running a job or job template that uses an execution environment that has a credential assigned to it, ensure that the credential has a username, host, and password. Procedure From the navigation panel, select Automation Execution Infrastructure Execution Environments . Click Create execution environment to create an execution environment. Enter the appropriate details into the following fields: Name (required): Enter a name for the execution environment. 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 Optional: Pull : Choose the type of pull when running jobs: Always pull container before running : Pulls the latest image file for the container. Only pull the image if not present before running : Only pulls the latest image if none are specified. 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 . Optional: Description : Enter an optional description. 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. Registry credential : If the image has a protected container registry, provide the credential to access it. Click Create execution environment . Your newly added execution environment is ready to be used in a job template. 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 . When you have added an execution environment to a job template, the template will be listed in the Templates tab in your execution environment details. 3.7.2.1. About container registries If you have many execution environment that you want to maintain, you can store them in a container registry linked to your private automation hub. For more information, see Populating your private automation hub container registry from the Creating and using execution environments guide. 3.8. Build and use a decision environment Event-Driven Ansible includes an ansible.eda collection, which contains sample sources, event filters and rulebooks. All the collections, ansible rulebooks and their dependencies use a decision environment, which is an image that can be run on either Podman or Kubernetes. In decision environments, sources, which are typically Python code, are distributed through ansible-collections. They inject external events into a rulebook for processing. The rulebook consists of the following: The python interpreter Java Runtime Environment for Drools rule engine ansible-rulebook python package ansible.eda collection You can use the base decision environment and build your own customized Decision Environments with additional collections and collection dependencies. You can build a decision environment using a Dockerfile or optionally you can deploy your CA certificate into the image. 3.8.1. Setting up a new decision environment The following steps describe how to import a decision environment into the platform. Prerequisites You have set up any necessary credentials. For more information, see the Setting up credentials section of the Using automation decisions guide. You have pushed a decision environment image to an image repository or you chose to use the image de-supported provided at registry.redhat.io . Procedure Navigate to Automation Decisions Decision Environments . Click Create decision environment . 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. Select Create decision environment . Your decision environment is now created and can be managed on the Decision Environments page. After saving the new decision environment, the decision environment's details page is displayed. From there or the Decision Environments list view, you can edit or delete it. 3.9. Creating an automation execution project A project is a logical collection of playbooks. Projects are useful as a way to group your automation content according to the organizing principle of your choice. You can set up an automation execution project in the platform UI. Procedure From the navigation panel, select Automation Execution Projects . On the Projects page, click Create project to launch the Create Project window. Enter the appropriate details into the following required fields: Name (required) Optional: Description Organization (required): A project must have at least one organization. Select one organization now to create the project. When the project is created you can add additional organizations. Optional: Execution Environment : Enter the name of the execution environment or search from a list of existing ones to run this project. Source Control Type (required): Select an SCM type associated with this project from the menu. Options in the following sections become available depending on the type chosen. For more information, see Managing playbooks manually or Managing playbooks using source control . Optional: Content Signature Validation Credential : Use this field to enable content verification. Specify the GPG key to use for validating content signature during project synchronization. If the content has been tampered with, the job will not run. For more information, see Project signing and verification . Click Create project . 3.10. Creating an automation decision project Like automation execution projects, automation decision projects are logical collections of automation decision content. You can use the project function to organize your automation decision content in a way that makes sense to you. Prerequisites You have set up any neccessary credentials. For more information, see the Setting up credentials section of the Using automation decisions guide. You have an existing repository containing rulebooks that are integrated with playbooks contained in a repository to be used by automation controller. Procedure From the navigation panel, select Automation Decisions Projects . Click Create project . Enter the following information: Name : Enter project name. Description : This field is optional. Organization : Select the organization associated with the project. Source control type : Git is the only SCM type available for use. Proxy : Proxy used to access HTTP or HTTPS servers. Source control branch/tag/commit : Branch to checkout. Can also be tags, commit hashes, or arbitrary refs. Source control refspec : A refspec to fetch. This parameter allows access to references through the branch field not otherwise available. Optional: Source control credential : The token needed to use the source control URL. Content signature validation credential : Enables content signing to verify that the content has remained secure during project syncing. If the content is tampered with, the job will not run. Options : Checking the box to Verify SSL verifies the SSL with HTTPS when the project is imported. Click Create project . Your project is now created and can be managed in the Projects screen. After saving the new project, the project's details page is displayed. From there or the Projects list view, you can edit or delete it. 3.11. About inventories An inventory is a file listing the collection of hosts managed by Ansible Automation Platform. Organizations are assigned to inventories, while permissions to launch playbooks against inventories are controlled at the user or team level. 3.11.1. Browsing and creating inventories You can find inventories in the UI by navigating to Automation Execution Infrastructure Inventories . The Inventories window displays a list of the inventories that are currently available. You can sort the inventory list by name and search by inventory type, organization, description, inventory creators or modifiers, or additional criteria. Use the following procedure to create a new inventory. Procedure From the navigation panel, select Automation Execution Infrastructure Inventories . The Inventories view displays a list of the inventories currently available. Click Create inventory , and from the list menu select the type of inventory you want to create. 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 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 . Click Create inventory . After creating the new inventory, you can proceed with configuring permissions, groups, hosts, sources, and viewing completed jobs, if applicable to the type of inventory. 3.12. Work with job templates A job template is a definition and set of parameters for running an Ansible job. A job template combines an Ansible playbook from a project and the settings required to launch it, including information about the target host against which the playbook will run, authentication information to access the host, and any other relevant variables . Job templates are useful to run the same job many times. Job templates also encourage the reuse of Ansible playbook content and collaboration between teams. For more information, see Job Templates in the Automation controller User Guide. 3.12.1. Getting started with job templates As part of the initial setup, a Demo Job Template is created for you. Procedure To review existing templates, select Automation Execution Templates from the navigation panel. Click Demo Job Template to view its details. 3.12.2. Creating a job template Procedure From the navigation panel, select Automation Execution Templates . On the Templates page, select Create job template from the Create template list. 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 . 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 . 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 From the navigation panel, select Automation Execution Templates . Verify that the newly created template appears on the Templates page. 3.12.3. Editing a job template As part of the initial setup, you can leave the default Demo Job Template as it is, but you can edit it later. Procedure 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 to the template name and edit the appropriate details. Save your changes. 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. 3.13. Create and run a rulebook activation In Event-Driven Ansible, a rulebook activation is a process running in the background defined by a decision environment executing a specific rulebook. 3.13.1. Setting up a rulebook activation Prerequisites You have set up a project. You have set up a decision environment. Procedure From the navigation panel, select Automation Decisions Rulebook Activations . Click Create rulebook activation . 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. Click Create rulebook activation . Your rulebook activation is now created and can be managed on the Rulebook Activations page. After saving the new rulebook activation, the rulebook activation's details page is displayed, with either a Pending , Running , or Failed status. From there or the Rulebook Activations list view, you can restart or delete it. 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 . 3.13.1.1. Rulebook activation list view On the Rulebook Activations page, you can view the rulebook activations that you have created along with the Status , Number of rules with the rulebook, the Fire count , and Restart count . If the Status is Running , it means that the rulebook activation is running in the background and executing the required actions according to the rules declared in the rulebook. You can view more details by selecting the activation from the Rulebook Activations list view. For all activations that have run, you can view the Details and History tabs to get more information about what happened. 3.13.2. Enabling and disabling rulebook activations Procedure Select the switch on the row level to enable or disable your chosen rulebook. In the window, select Yes, I confirm that I want to enable/disable these X rulebook activations . Select Enable/Disable rulebook activation . 3.13.3. Restarting rulebook activations Note You can only restart a rulebook activation if it is currently enabled and the restart policy was set to Always when it was created. Procedure Select the More Actions icon ... to Rulebook Activation enabled/disabled toggle. Select Restart rulebook activation . In the window, select Yes, I confirm that I want to restart these X rulebook activations . Select Restart rulebook activations . 3.13.4. Deleting rulebook activations Procedure Select the More Actions icon ... to the Rulebook Activation enabled/disabled toggle. Select Delete rulebook activation . In the window, select Yes, I confirm that I want to delete these X rulebook activations . Select Delete rulebook activations . 3.13.5. Activating webhook rulebooks In Openshift environments, you can allow webhooks to reach an activation-job-pod over a given port by creating a Route that exposes that rulebook activation's Kubernetes service. Prerequisites You have created a rulebook activation. Note The following is an example of rulebook with a given webhook: - name: Listen for storage-monitor events hosts: all sources: - ansible.eda.webhook: host: 0.0.0.0 port: 5000 rules: - name: Rule - Print event information condition: event.meta.headers is defined action: run_job_template: name: StorageRemediation organization: Default job_args: extra_vars: message: from eda sleep: 1 Procedure 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 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).
- name: Set Up a Project and Job Template hosts: host.name.ip become: true tasks: - name: Create a Project ansible.controller.project: name: Job Template Test Project state: present scm_type: git scm_url: https://github.com/ansible/ansible-tower-samples.git - name: Create a Job Template ansible.controller.job_template: name: my-job-1 project: Job Template Test Project inventory: Demo Inventory playbook: hello_world.yml job_type: run state: present ansible-galaxy role init <role_name> ansible-galaxy role init my_role ~/.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 ansible-galaxy role init my_role --role-skeleton ~/role_skeleton ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz --api-key=SECRET podman login registry.redhat.io USDpodman pull registry.redhat.io/aap/<image name> - name: Listen for storage-monitor events hosts: all sources: - ansible.eda.webhook: host: 0.0.0.0 port: 5000 rules: - name: Rule - Print event information condition: event.meta.headers is defined action: run_job_template: name: StorageRemediation organization: Default job_args: extra_vars: message: from eda sleep: 1 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 curl -H "Content-Type: application/json" -X POST test-sync-bug-dynatrace.apps.aap-dt.ocp4.testing.ansible.com -d '{}'