Getting started with Automation Services Catalog

Red Hat Ansible Automation Platform 1.0

Initial configurations and workflows

Red Hat Customer Content Services

Abstract

This guide provides instructions to begin using Automation Services Catalog, including prerequisites and procedures for connecting your Ansible Tower provider, as well as configuring users and permissions. We also provide instructions for working with platforms, portfolios, and products.

Chapter 1. About Automation Services Catalog

Automation Services Catalog is a service within the Red Hat Ansible Automation Platform. Automation Services Catalog allows customers to organize and govern product catalog sources on Ansible Tower across various environments.

Using Automation Services Catalog you can:

  • Apply multi-level approval to individual platform inventories
  • Organize content in the form of products from your platforms into portfolios
  • Choose portfolios to share with specific groups of users
  • Set boundaries around values driving execution of user requests

Chapter 2. Getting started with Automation Services Catalog

This guide provides instructions to begin using Automation Services Catalog, including prerequisites and procedures for connecting your Ansible Tower provider, as well as configuring users and permissions. We also provide instructions for working with platforms, portfolios, and products.

After completing the setup described and following the steps in this guide, you will have a portfolio of products, governed by an approval process, accessible to users.

Note

Entitlements

To begin using Automation Service Catalog, you need:

At least one Red Hat account user with Organization Administrator entitlements. The account number for this Red Hat corporate account.

Chapter 3. User access for Automation Services Catalog

When configuring Automation Services Catalog for your organization, consider the scope of your user environments, how those users are grouped, and the roles to assign. You can manage this workflow through User Access.

Automation Services Catalog features and workflows are governed by groups that have specific roles attached to them. The Organization Administrator role performs the initial creation of groups, assigns roles, and adds users.

Groups

Groups are user-defined and flexible to include many users and have multiple roles. Create new groups based on your organization’s requirements for working with Automation Services Catalog.

Roles

Roles provide a defined set of actions each group performs. Determine the required level of access for your users based on the following roles Automation Services Catalog uses:

Table 3.1. Role Reference Table

 RoleDescription

Administration

Organization Administrator

  • Manage user access for Catalog and Approval
  • Add platform sources to Catalog

Approval

Approval Administrator

  • Create and assign users to approval groups
  • Create and configure approval processes
  • Approval or deny requests
  • Monitor existing requests

Approval Approver

  • Approve or deny requests
  • Monitor existing requests

Approval User

  • Request a product
  • Monitor existing requests

Catalog

Catalog Administrator

  • Create / Edit order processes
  • Set an order process to a product or portfolios
  • Delete order processes

Catalog User

  • Request a product
  • Monitor existing requests
Note

By default, all users will have Catalog User and Approval User roles assigned to them.

Important

Due of potential security implications, limit the number of users in cloud.redhat.com with Organization Administrator privileges.

3.1. Creating administrator groups

The Organization Administrator can create new groups of administrators and users in Automation Services Catalog. Catalog and Approval administrators are required to perform initial workflows in configuring Automation Services Catalog. In this section, we will create groups for both Catalog and Approval administrators.

3.1.1. Creating a Catalog Administrator group

The Catalog Administrator is a role that grants create, read, update and order permissions. This role is used in creating and managing processes associated with portfolios and products.

To create a Catalog Administrator group:

  1. Navigate to SettingsUser Access.
  2. Click Create group.
  3. Enter group name and set the description.
  4. Click Next.
  5. In the Add members modal, check each user to add to the group. Click Next when finished.
  6. Check Catalog Administrator on the Assign roles modal.
  7. Review details for the new group and click Confirm.

We have created a group of Catalog Administrators and will now create a group of Approval administrators.

3.1.2. Creating an Approval Administrator group

The Approval Administrator is a role that grants create, read, update and order permissions. This role is used in creating and managing processes associated with portfolios and products.

To create an Approval Administrator group:

  1. Navigate to SettingsUser Access.
  2. Click Create group.
  3. Enter group name and set the description.
  4. Click Next.
  5. In the Add members modal, check each user to add to the group. Click Next when finished.
  6. Check Approval Administrator on the Assign roles modal.
  7. Review details for the new group and click Confirm.

The new group of Approval Administrators has been created. Approval Administrators can create new approval processes to set to platforms, portfolios, and products.

3.1.3. Creating Approval Approver Groups

The Approval Approver is a role that grants create and read permissions to users who will approve or deny requests generated when a Automation Services Catalog user orders a product.

To create an Approval Approver group:

  1. Navigate to SettingsUser Access.
  2. Click Create group.
  3. Enter group name and set the description.
  4. Click Next.
  5. In the Add members modal, check each user to add to the group. Click Next when finished.
  6. Check Approval Approvers on the Assign roles modal.
  7. Review details for the new group and click Confirm.

The new group of Approval Approvers has been created..

3.1.4. Adding new users to existing Groups

The Catalog Administrator can add new users to existing groups. Once added, users will have the level of permissions associated with that group.

You can add users to a group in the Groups view in User Access.

  1. Navigate to SettingsUser Access.
  2. Click Groups.
  3. Select a group from the list.
  4. Click Members and then click Add Member.
  5. Check those users that appear in the modal that you wish to add to the group.
  6. Click Add to group.

A message will appear notifying you if the member was added successfully.

Chapter 4. Configuring Approval

Automation Services Catalog supports group-based approval processes applied to portfolios, products, and platform inventories, providing the flexibility to include selected organizational groups in approving requests utilizing the Approval service.

Approval administrators can create approval groups and processes, view request details, approve or deny requests, and monitor the status of existing requests.

4.1. Approval requests

Approval requests are created when a user orders a product that has an approval policy attached to it. The order will initiate the approval processes assigned to the product and users designated as approvers in each approval process receive an email notifying them that a request is ready.

Users logging in to Catalog can access approval requests via the following tabs:

  • My requests - Requests that the user can approve based on their group permissions.
  • All requests - All requests across all approver groups.
  • Approval processes - List of approval processes that can be configured by the Approval Administrator. Accessible by the Approval Administrator only.

4.2. Approval processes

Approval processes consist of one or many groups required to approve a request. Each group is notified through the email address associated with that user when requests are created that require approval.

Approval administrators can design approval processes for a product to execute in serial or parallel when set to a portfolio. Simple serial and parallel approval processes are described below:

Set approval processes at the platform, portfolio, or product level. Approval processes set to a platform will apply to all products originating from that platform.

  • Serial process - a product has multiple approval processes that must execute in a hierarchical sequence. If two approval processes are assigned to a product in serial, the approval group in the first approval process must approve the request before notification is sent to the second approval group. Priority of approval process execution is based on its position on the approval process list view. Approval processes at the top of the list will execute before the processes below it.
  • Parallel process - a product has one approval process containing multiple groups. All groups are notified simultaneously when a request is created and the order is not granted until all groups approve it. Any group that declines the request ends the process and the user is notified the order has been denied.
Note

To create and list groups when creating Approval processes, the Approval Administrator must also have Organization Administrator privileges.

4.2.1. Creating an approval process

Creating an approval process designates specific groups required to approve product orders placed by Automation Services Catalog users.

You can create an approval process from the Approval processes list view.

  1. Select Approval from the main navigation.
  2. Select the Approval processes tab.
  3. Click Create.
  4. Provide an approval process name and description.
  5. Select a group from the Set groups drop-down menu. You may set multiple groups for approval.
  6. Click Submit when finished.

Implement an approval process against a platform, portfolio, or product.

4.3. Approval process sequences

Each approval process is assigned a sequence ID that determines the priority in which it executes when included in a serial approval process set to a portfolio. An approval process with the sequence ID of 1 will execute and notify groups in that approval process of a new request before a process with a sequence ID greater than 1.

4.3.1. Editing an approval process sequence

You can edit the sequence number for an approval process from the Approval process list view.

  1. Select Approval from the main navigation.
  2. Click the Approval processes tab.
  3. Navigate to the approval process, then click More actions .
  4. Click Edit.
  5. Enter the desired sequence number under Enter sequence.
  6. Click Save.

The approval process list view will update to reflect the newly sequence.

4.4. Automatic approval

You can designate products to approve automatically by not setting an approval process at the following levels:

  • the inventory hosting the product
  • the portfolio containing it
  • the product itself

Products without an approval process at any of these levels will approve upon order creation.

Chapter 5. Working with platforms, portfolios, and products

This section demonstrates the basic workflows for platforms, portfolios, and products to get started using Automation Services Catalog

We will demonstrate how to:

  • connect to a source platform
  • create portfolios
  • add products from the source platform into the portfolio
  • set approval processes for the portfolio
  • share the portfolio with users

5.1. Adding sources

Sources are the platforms Automation Services Catalog connects to in order to collect inventory information used to organize and present products available to users. To use Automation Services Catalog, you need to connect the application to at least one source.

5.2. Adding Ansible Tower as a source platform

Connect an Ansible Tower instance to Automation Services Catalog to create products from its inventory of playbooks and workflows your users can view and order from.

To begin, we will add an Ansible Tower instance as a source of products.

Part I. Adding Ansible Tower as a Source platform

Connect an Ansible Tower instance to Automation Services Catalog to create products from its inventory of playbooks and workflows your users can view and order from. To add an Ansible Towersource:

  1. Click menu:Settings.
  2. Select Sources
  3. Click Add source.
  4. Enter the source Name and click Next.
  5. Select Catalog from the available applications.
  6. Select Ansible Tower as the source type.
  7. Enter user name and Secret Key credentials.
  8. Provide the Ansible Tower endpoint URL
  9. (Optional) Toggle the switch to verify the endpoint SSL certificate.

    1. Enter the SSL certificate in the Certificate Authority field.
  10. Click Next.
  11. Review your Ansible Tower source details.
  12. Click Finish to add your source.

After connecting your Ansible Tower instance, navigate back to Catalog to review templates available on that platform, and add those products to your portfolios.

1. Creating a portfolio and adding products to it

Now that we have a source for products, we can proceed to create an example portfolio and add a few products from our Ansible Tower to it.

Part II. Creating a portfolio and adding products to it

To create a portfolio:

  1. Click Create portfolio.
  2. Provide a New Portfolio Name and Description.
  3. Choose an Approval workflow from the drop-down list.
  4. Click Save.

Our initial portfolio is empty, and we can start adding products from this empty state.

Procedure

  1. Click in the Filter by Platform field to view connected platforms.
  2. Select a platform. The screen will populate with products from that platform.
  3. Check each product to add to the portfolio.
  4. Click Add.

1. Setting approval processes for the portfolio

We have now created a portfolio and added some products to it. Our next step is to set the approval process for the portfolio. Setting the approval process for our portfolio ensure that specific groups are designated to approve any orders placed by a user.

Part III. Setting approval processes for the portfolio

Procedure

  1. Navigate to Portfolios.
  2. Click More actions on a portfolio tile and select Set approval.
  3. From the Set approval process drop-down menu, select an approval processes to set to the portfolio.
  4. Click Save.

1. Sharing the portfolio with users

The portfolio is now ready to share with groups of users. These designated user groups can order products collected in the portfolio, and their orders are approved or denied using the approval process set for the portfolio.

To share a portfolio:

  1. Click Portfolios.
  2. Click More actions on a portfolio, then click Share. The icon:[Y] indicates a shared portfolio.
  3. Adding groups:

    1. Under Invite group search groups to share the portfolio with.
    2. Select the level of permissions using the drop-down list.
  4. Edit sharing settings for existing groups:

    1. Under Groups with access adjust permissions using the drop-down for each group.
    2. To stop sharing a portfolio with a group, click icon:[X].
  5. Click Send when finished.

Our portfolio is now accessible to the groups of users, who can order the products we collected in it. We can now duplicate this portfolio, change its name and add new products, to share with different user groups.

Chapter 6. Copying existing portfolios to edit and share with new groups

Copying portfolios allows you to quickly duplicate an already organized portfolio to offer to different groups of users. Once a copy is created, you can add or remove products, share with new groups, and apply new approval processes to meet organizational requirements.

We can also copy products from various portfolios to additional portfolios.

Chapter 7. Copying products to different portfolios

You can copy products from one portfolio to another as part of developing new portfolios to meet group needs. Once a product is copied you can edit its basic fields, update its survey, and apply different approval processes.

7.1. Workflows summary

The workflows in this section of the guide demonstrated how to perform the basic actions for platforms, portfolios and products necessary to get started using Automation Services Catalog:

  • add entitlements to access Automation Service Catalog;
  • create the necessary groups and users;
  • connect to a source platform;
  • create portfolios;
  • add products from the source platform into the portfolio;
  • set approval processes for the portfolio;
  • share the portfolio with users;
  • make a copy of our existing portfolio to share with different users;
  • copy products from one portfolio to another.

In the next section, we will describe working with the survey editor, and provide an overview of working with requests and orders.

Chapter 8. Using the survey editor

When ordering a product in Automation Services Catalog, users may be required to provide additional information to complete the request. This prompt is created by a survey associated with the product. Initially created and edited in Ansible Tower, Catalog Administrators and portfolio users with update permissions can edit the survey in Automation Services Catalog. Once submitted and validated, the surveys pass user-submitted extra variables to the job or workflow template run on Ansible Tower on the execution of an order.

See Surveys in the Ansible Tower User Guide to learn more creating and editing surveys for job templates.

Using the survey properties editor, you can:

  • Set labels, helper text or placeholders to enhance the user experience of users providing information
  • Further restrict existing validation parameters.
  • Change validation messages.
  • Hide, disable or set to read-only chosen fields in the survey.

8.1. Survey properties editor

Values for surveys are defined in Ansible Tower and the Automation Services Catalog properties editor allows Catalog Administrators to restrict survey options, such as adjusting default values and removing items from drop-down menus.

Additionally, use the properties editor to hide, disable, or set a field to read only.

Note

Provide an initial value for any required field set to Hidden or Disabled. This includes read only fields.

8.2. Editing surveys

You can edit fields in the surveys from the product detail view. Edit each field individually using the Properties editor.

Prerequisites

The product has an associated survey, created in Ansible Tower.

Procedure

  1. Click Products.
  2. Locate the product and click on its title.
  3. Click More actions and select Edit survey.
  4. Select a field in the survey. The Properties editor will appear.
  5. Click Properties to view the elements to edit for that field.
  6. Select Validation to configure the validator types used to validate user input.
  7. Click Save when finished.

Chapter 9. Managing orders

Orders are created once a user successfully submits the request and provides any required validation. The approval process then governs the user’s order status.

9.1. Approving or denying requests

Once a user places an order it is created and available for review on the orders page. Groups assigned the Approval Approver role can then approve or deny orders. Detailed information is provided for each request, with information on the ordered product and its associated requester and project. A stage transcript is also provided. Denied requests require justification and the approver must enter a reason.

To approve or deny a request:

  1. Navigate to Approval.
  2. Click the Requests tab and then click on a request to expand it to detailed view.
  3. Click Approve or Deny. Provide a Reason when denying a request.
  4. Click Submit.

9.2. Commenting on requests

Comment on requests as an administrator or approver. Comments are captured by the system and visible at each stage of approval.

To comment on a request:

  1. Navigate to Approval.
  2. Click the Requests tab and then click on a request..
  3. Click Comment.
  4. Add a comment and click Submit.

Chapter 10. Conclusion

In the previous sections of this guide we walked through the primary workflows necessary to get started using Automation Services Catalog.

Following these workflows you have:

  • Created the necessary groups and users to use both Catalog and Approval through the User access,
  • Connected to a source platform,
  • Created portfolios,
  • Added products from the source platform into the portfolio,
  • Created and set approval processes for the portfolio,
  • Shared the portfolio with users,
  • Approved or denied orders created by users,
  • and comment on orders where necessary.

Legal Notice

Copyright © 2020 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.