Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Using self-service automation portal

Red Hat Ansible Automation Platform 2.6

Use self-service automation portal

Red Hat Customer Content Services

Abstract

This guide describes how to use self-service automation portal to implement role-based access control and run automation.

Preface
Copy link

Thank you for your interest in Red Hat Ansible Automation Platform. Ansible Automation Platform is a commercial offering that helps teams manage complex multi-tier deployments by adding control, knowledge, and delegation to Ansible-powered environments.

This guide describes how to add templates to your self-service automation portal instance, and how to launch them to run automation jobs. It also describes how to configure role-based access control (RBAC) so that you can restrict the teams and users who can run the jobs.

This document has been updated to include information for the latest release of Ansible Automation Platform.

Providing feedback on Red Hat documentation
Copy link

If you have a suggestion to improve this documentation, or find an error, you can contact technical support at https://access.redhat.com to open a request.

Chapter 1. Overview
Copy link

You can launch templates from self-service automation portal to execute job templates from your existing Ansible Automation Platform setup.

  • Auto-generated self-service templates are automatically synced from the job templates in Ansible Automation Platform to the self-service automation portal. The forms for the auto-generated templates are identical to the forms for the job templates.
  • You can import custom self-service templates from a Git repository. A configuration file links each custom template to a specific job template in Ansible Automation Platform and contains the forms that users must complete.

You can associate multiple custom self-service templates with a single Ansible Automation Platform job template. You can use role-based access control (RBAC) to assign different custom self-service templates for users with different levels of automation experience. For example, you can design a simplified template with a narrow scope for configuration for new users, and a more detailed template for automation experts.

Learn how to access and authenticate to the self-service automation portal using your Ansible Automation Platform credentials.

2.1. Signing in to self-service automation portal
Copy link

Log in to the deployed self-service automation portal using your existing Ansible Automation Platform credentials. The portal uses these credentials for authentication.

Prerequisites

  • You have configured an OAuth application in Ansible Automation Platform for self-service automation portal.
  • You have configured a user account in Ansible Automation Platform.

Procedure

  1. In a browser, navigate to the URL for self-service automation portal to open the sign-in page.

    Self-service sign-in page
    View larger image
    Self-service sign-in page
  2. Click Sign In.

  3. The sign-in page for Ansible Automation Platform appears:

    Ansible Automation Platform sign-in page
    View larger image
    Ansible Automation Platform sign-in page
  4. Enter your Ansible Automation Platform credentials and click Log in.
  5. The self-service automation portal web console opens.

Troubleshooting

If your are using custom SSL certificates and when attempting to log in to self-service automation portal, it displays the error:

Login failed; caused by Error: Failed to send POST request: fetch failed

You must disable SSL validation in the Helm chart configuration.

  1. In the self-service automation portal Helm chart, locate the checkSSL parameter and set its value to false: 

     upstream:
    backstage:
      appConfig:
        ansible:
          creatorService:
            baseUrl: 127.0.0.1
            port: '8000'
          rhaap:
            baseUrl: '${AAP_HOST_URL}'
            checkSSL: false <-- Update this to false
            token: '${AAP_TOKEN}'
    Copy to Clipboard Toggle word wrap
  2. Apply the updated configuration by upgrading the self-service automation portal Helm chart to allow users to log in.

2.2. Viewing templates
Copy link

View your accessible automation templates, displayed as tiles, on the Templates landing page of the self-service automation portal console.

Prerequisites

  • You have signed in to self-service automation portal.

Procedure

  1. In a browser, sign in to self-service automation portal.

  2. In the navigation pane, select Templates to open a landing page where tiles are displayed, representing the templates that you have access to.

    Templates view
    View larger image
    Templates view

2.3. Synchronizing auto-generated templates
Copy link

The auto-generated self-service templates are synchronized from the job templates in Ansible Automation Platform to self-service automation portal. You can manually trigger a sync from the Templates page.

Note

This synchronization fetches updates for auto-generated self-service templates only.

Procedure

  1. In a browser, sign in to self-service automation portal.

  2. In the navigation pane, select Templates to display the templates that you have access to.

    Templates view
    View larger image
    Templates view
  3. Select Sync now to launch a synchronization.

2.4. Viewing task run history
Copy link

You can view a list of all the tasks that have been run from self-service automation portal. You can manually trigger a sync from the Templates page.

Procedure

  1. In a browser, sign in to self-service automation portal.

  2. In the navigation pane, select History.

    The Task list page displays the tasks that have been run.

    Templates view
    View larger image
    Templates view

Troubleshooting

If the Task List page does not display the tasks that have been run, contact your administrator to ensure that the scaffolder.task.read permission is selected in RBAC for your account.

Chapter 3. Working with templates
Copy link

Understand how to deploy and manage both auto-generated and customized templates within the self-service automation portal to run your automation jobs.

3.1. Customized self-service templates
Copy link

Custom self-service templates are stored as YAML files in repositories in GitHub or Gitlab. When a user launches a software template from self-service automation portal, they must fill in a form with the values needed to run the associated job template in Ansible Automation Platform.

The custom self-service template YAML file must have a token: section that includes a ui:field: key for the authentication token for Ansible Automation Platform. This generates a field for the token in the form that appears when the user launches the template in self-service automation portal. The user enters the token: it is used to authenticate job template execution in Ansible Automation Platform.

The following example shows the token: section in a template. For security reasons, set the value of token.ui:backstage.review.show to false to ensure that the token is not visible to the user. 

spec:
  ...
  parameters:
    ...
      properties:
        token:
          title: Token
          type: string
          description: Oauth2 token
          ui:field: AAPTokenField
          ui:widget: hidden
          ui:backstage:
            review:
              show: false
Copy to Clipboard Toggle word wrap
Note

Setting the ui:widget: hidden field hides the Red Hat Ansible Automation Platform token input in the form.

You can add a custom self-service template to the Templates view of your self-service automation portal instance. Custom self-service templates are stored in git repositories. self-service automation portal supports GitLab and GitHub Source Control Management (SCM).

Note

Names for custom self-service templates must be unique. Custom self-service templates must have a different name to auto-generated job templates and also to other custom self-service templates.

Prerequisites

  • You have created repositories in your Git SCM for the templates that you want to use.
  • In the git repository for your custom templates, ensure that the metadata.name field is unique and does not match an existing auto-generated template or another custom self-service template. For example, append *-custom to the value of the metadata.name key. 
metadata:
  name: provision-database-custom
Copy to Clipboard Toggle word wrap
  • You must be logged in to self-service automation portal as an Ansible Automation Platform platform administrator.

Procedure

  1. In a browser, navigate to your self-service automation portal instance and sign in with your Ansible Automation Platform credentials.
  2. Navigate to the Templates Page.
  3. Click Add template.
  4. Enter a valid Git SCM URL for the template that you want to add.
  5. Click Analyze to fetch the template.
  6. After the template has been fetched, review the list of what will be imported and added to the catalog.
  7. Click Import.

Verification

After the import is complete, return to the Templates page to view the newly created template. You can now launch your template.

3.3. Launching a template
Copy link

This procedure describes how to launch a template from a tile in the Templates view of your self-service automation portal instance.

Prerequisites

  • You have configured RBAC in Ansible Automation Platform for templates that are associated with Ansible Automation Platform job templates.

Procedure

  1. In a browser, navigate to your self-service automation portal instance and sign in with your Ansible Automation Platform credentials.
  2. Navigate to the Templates page. The templates you have set up are displayed as tiles on the page.

  3. In the template that you want to launch, click Start.

    A description of the template is displayed.

  4. Click Launch to begin configuring the parameters for running the template.
  5. Fill out the required fields.
  6. Click Next.
  7. Review the entered information.
  8. Click Create to launch the template.
  9. The progress for the template execution is displayed.

Custom self-service templates that you set up in self-service automation portal use a different set of RBAC rules than the RBAC rules for auto-generated self-service templates that are synchronized from Ansible Automation Platform.

  • Auto-generated self-service templates: The RBAC settings for these templates are synchronized from Ansible Automation Platform.
  • Custom self-service templates: You must set up RBAC for these templates in self-service automation portal.

By default, Ansible Automation Platform administrators can define self-service automation portal RBAC roles.

This procedure describes how to create a role in self-service automation portal that allows only a selected team to view and execute particular custom self-service templates.

Custom self-service templates in self-service automation portal are associated with job templates in Ansible Automation Platform. This association is set in the steps.actions section of the YAML file for the custom self-service template.

If you assign permissions to a particular team to launch a custom self-service template from self-service automation portal, then you must make sure that that team has permission to run the associated job templates in Ansible Automation Platform.

Prerequisites

  • You have created a user, for example example-user. For more details, see Creating a user.
  • You have added this user as a member of a team, for example example-team. Fore more details, see Adding users to a team.

Procedure

  1. In a browser, log in to your self-service automation portal instance as an Ansible Automation Platform user with Ansible Automation Platform administrator privileges.
  2. In the navigation panel, select Administration → RBAC.

  3. In the RBAC view, click Create.

    The Create Role view appears.

    1. Enter a name for the role.
    2. Select the user or group that you want to allow to use the role.
    3. In the Add Permission policies section, select the plug-ins that you want to enable for the role.
    4. Select Permission in the list of plug-ins to configure the fine-grained permission policies for the role.
  4. Click Next.
  5. Review the settings that you have selected for the role.
  6. Click Create to create the role.

4.2. Verifying RBAC
Copy link

This procedure describes how to verify that the role you set up is working correctly.

Procedure

  1. Verify that users with permissions can use a template:

    1. Log in to self-service automation portal as a user who is a member of a team that has been enabled to use a role.
    2. Verify that RBAC is applied and that the user can use the templates that you enabled for the role.
  2. Log out of self-service automation portal.

  3. Verify that users without permissions can not see or use a template:

    1. Log in to self-service automation portal as a user who is not a member of the new team that has been enabled to use the role.
    2. Verify that RBAC is applied and that the user cannot use the templates that you enabled for the role.
  4. Log out of self-service automation portal.

4.3. Deregistering custom self-service templates
Copy link

You can deregister custom self-service templates. Deregistering templates deletes them from the Templates view in the self-service automation portal console.

Procedure

  1. In a browser, log in to self-service automation portal as a user with administrative privileges.
  2. Select Templates to display the self-service templates.

  3. For each custom self-service template that you want to delete, execute the following steps:

    1. Click a custom self-service template to open the Template detail view. The navigation bar contains the Unregister Template option.

    2. Click Unregister Template.

      Unregister template option
      View larger image
      Unregister template option
    3. In the dialog, confirm that you want to deregister the template.
    4. Click Delete Entity to unregister the template.

Verification

In a browser, navigate to the Templates view for your self-service automation portal instance. Verify that the custom self-service templates that you deregistered have been deleted.

The self-service automation portal is built on a Red Hat Developer Hub base image. It uses Backstage Software Templates, which are YAML-based workflow definitions that provide user forms to execute automation tasks in Ansible Automation Platform.

5.1. Overview
Copy link

Learn how to use the custom actions, filters, and UI components provided by the Ansible Backstage Plugins to create and manage custom software templates for the self-service automation portal.

Important

Red Hat does not support the use of the Red Hat Developer Hub image for standalone purposes outside the scope of the Ansible Automation Platform self-service automation portal functionality. Refer to the official support policy for details.

5.2. Ansible backstage plugins
Copy link

The portal’s capabilities are delivered through Ansible Backstage Plugins that extend Red Hat Developer Hub functionality; the base Red Hat Developer Hub image is not customized. These plugins provide additional Backstage actions and filters that you use to create custom software templates.

Expand
PluginFunctionality

auth-backend-module-rhaap-provider

Provides OAuth 2.0 authentication with Ansible Automation Platform.

catalog-backend-module-rhaap

Synchronizes Ansible Automation Platform job templates as Backstage Software Templates.

scaffolder-backend-module-backstage-rhaap

Provides the rhaap:launch-job-template action.

backstage-rhaap-common

Contains shared libraries and utilities for Ansible Automation Platform integration.

self-service

Provides the user interface for all listed functionality.

5.3. Custom backstage actions
Copy link

The following actions enable you to manage Ansible Automation Platform resources within a software template workflow.

5.3.1. rhaap:create-project
Copy link

Create an Ansible Automation Platform project that links to a source control repository containing Ansible content.

Input parameters

Expand
ParameterTypeRequiredDescription

token

string

Yes

OAuth2 token for Ansible Automation Platform authentication.

deleteIfExist

boolean

No

If true, the action deletes the project if it already exists before creating a new one.

values

object

Yes

The project configuration object. See the "values" Object Structure table.

“values” Object Structure

Expand
FieldTypeRequiredDescription

projectName

string

Yes

Name of the project.

projectDescription

string

No

Description of the project.

organization

object

Yes

Organization object with id (number, required) and name (string, optional).

credentials

object

No

Credential object with id (number, required), name (string, optional), and kind (string, optional).

scmUrl

string

Yes

Source control URL (for example, GitHub/GitLab repository URL).

scmBranch

string

No

Source control branch, tag, or commit.

scmUpdateOnLaunch

boolean

No

If true, updates the project revision before each job run.

Output parameters

Expand
ParameterTypeDescription

project

object

Created project details.

project.id

number

Project ID in Ansible Automation Platform (AAP).

project.name

string

Project name.

project.description

string

Project description.

project.url

string

Ansible Automation Platform URL for the project.

Example 

steps:
  - id: create-aap-project
    name: Create AAP Project
    action: rhaap:create-project
    input:
      token: ${{ parameters.AAP_TOKEN }}
      deleteIfExist: true
      values:
        projectName: ${{ parameters.projectName }}
        organization: ${{ parameters.organization }}
        scmUrl: https://github.com/my-org/ansible-playbooks
        scmBranch: main
        scmUpdateOnLaunch: true
        credentials: GitHub Token
Copy to Clipboard Toggle word wrap

5.3.2. rhaap:create-execution-environment
Copy link

Create an execution environment in Ansible Automation Platform that defines the container image used to run Ansible jobs.

Input parameters

Expand
ParameterTypeRequiredDescription

token

string

Yes

OAuth2 token for Ansible Automation Platform authentication.

deleteIfExist

boolean

No

If true, the action deletes the execution environment if it already exists.

values

object

Yes

The execution environment configuration object.

“values” Object Structure

Expand
FieldTypeRequiredDescription

environmentName

string

Yes

Name of the execution environment.

environmentDescription

string

No

Description of the execution environment.

organization

object

Yes

Organization object with required id (number) and optional name (string).

image

string

Yes

Full image location, including registry, image name, and tag (for example, quay.io/ansible/creator-ee:latest).

pull

string

No

Image pull policy: always, missing, or never. Default is missing.

Output parameters

Expand
ParameterTypeDescription

executionEnvironment

object

Created execution environment details.

executionEnvironment.id

number

Execution environment ID.

executionEnvironment.name

string

Execution environment name.

executionEnvironment.description

string

Execution environment description.

executionEnvironment.url

string

Ansible Automation Platform (AAP) URL for the execution environment.

Example 

steps:
  - id: create-ee
    name: Create Execution Environment
    action: rhaap:create-execution-environment
    input:
      token: ${{ parameters.AAP_TOKEN }}
      deleteIfExist: false
      values:
        environmentName: Custom EE
        environmentDescription: Execution environment with custom collections
        organization: ${{ parameters.organization }}
        image: quay.io/ansible/creator-ee:v0.16.0
        pull: missing
Copy to Clipboard Toggle word wrap

5.3.3. rhaap:create-job-template
Copy link

Create a job template in Ansible Automation Platform that defines a reusable configuration for running Ansible playbooks.

Input parameters

Expand
ParameterTypeRequiredDescription

token

string

Yes

OAuth2 token for Ansible Automation Platform authentication.

deleteIfExist

boolean

No

If true, the action deletes the job template if it already exists.

values

object

Yes

The job template configuration object.

“values” Object Structure

Expand
FieldTypeRequiredDescription

templateName

string

Yes

Name of the job template.

templateDescription

string

No

Description of the job template.

project

object

Yes

Project object with required id (number) and optional name (string).

organization

object

No

Organization object with id (number, required) and name (string, optional).

jobInventory

object

Yes

Inventory object with required id (number) and optional name (string).

playbook

string

Yes

Path to the playbook file to execute.

templateDescription

string

No

Description of the job template.

scmType

string

No

Source control type (for example, Github or Gitlab).

executionEnvironment

object

No

Execution environment object with required id (number) and optional name (string).

extraVariables

object

No

Extra variables to pass to the playbook (key-value pairs).

Output parameters

Expand
ParameterTypeDescription

template

object

Created job template details.

template.id

number

Job template ID.

template.name

string

Job template name.

template.description

string

Job template description.

template.url

string

Ansible Automation Platform (AAP) URL for the job template.

Example 

steps:
  - id: create-job-template
    name: Create Job Template
    action: rhaap:create-job-template
    input:
      token: ${{ parameters.AAP_TOKEN }}
      deleteIfExist: true
      values:
        templateName: Deploy Application
        templateDescription: Deploys the application to production
        project: ${{ steps['create-aap-project'].output.project }}
        organization: ${{ parameters.organization }}
        jobInventory: ${{ parameters.jobInventory }}
        playbook: deploy.yml
        executionEnvironment: ${{ steps['create-ee'].output.executionEnvironment }}
        extraVariables:
          app_version: 1.0.0
          environment: production
Copy to Clipboard Toggle word wrap

5.3.4. rhaap:launch-job-template
Copy link

Launch an existing job template in Ansible Automation Platform.

Input parameters

Expand
ParameterTypeRequiredDescription

token

string

Yes

OAuth2 token for Ansible Automation Platform authentication.

values

object

Yes

The job launch configuration object.

“values” Object Structure

Expand
FieldTypeRequiredDescription

template

string

Yes

Job template name to launch.

inventory

object

No

Override inventory with id (number) and name (string).

credentials

array

No

Array of credential objects to use.

extraVariables

object

No

Extra variables to pass to the job (key-value pairs).

limit

string

No

Host pattern to constrain which hosts the job runs against.

jobType

string

No

Job type: run or check.

executionEnvironment

object

No

Override execution environment with id (number) and name (string).

verbosity

object

No

Verbosity level object with id and name.

forks

number

No

Number of parallel processes (default: 5).

jobSliceCount

number

No

Divide the job into N slices.

timeout

number

No

Job timeout in seconds (0 = no timeout).

diffMode

boolean

No

Enable diff mode to show changes.

jobTags

string

No

Comma-separated tags to run only specific tasks.

skipTags

string

No

Comma-separated tags to skip specific tasks.

Output parameters

Expand
ParameterTypeDescription

data

object

Job execution details.

data.id

number

Job ID.

data.status

string

Job status.

data.url

string

Ansible Automation Platform (AAP) URL for the job.

Example 

steps:
  - id: launch-job
    name: Launch Job Template
    action: rhaap:launch-job-template
    input:
      token: ${{ parameters.AAP_TOKEN }}
      values:
        template: Deploy Application
        inventory: ${{ parameters.jobInventory }}
        credentials: ${{ parameters.credentials }}
        extraVariables:
          app_version: v1.0.1
          deploy_env: production
        jobType: run
        verbosity: Normal
        diffMode: true
        timeout: 3600
Copy to Clipboard Toggle word wrap

5.3.5. Example with all backstage actions present
Copy link

The following example displays how you can use multiple actions together. 

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: ansible-complete-setup
  title: Complete Ansible Setup
  description: Creates an Ansible project, execution environment, job template, and launches it
spec:
  owner: platform-team
  type: service

  parameters:
    - title: Project Information
      required:
        - projectName
        - repoUrl
      properties:
        projectName:
          title: Project Name
          type: string
          description: Name of the Ansible project
        repoUrl:
          title: Repository URL
          type: string
          description: Git repository URL containing Ansible content

    - title: AAP Configuration
      required:
        - organization
        - jobInventory
        - credentials
      properties:
        organization:
          title: Organization
          type: string
          description: AAP Organization name
          default: 1-org
          ui:field: hidden  # To hide this field in the UI
        jobInventory:
          title: Inventory name
          type: string
          description: AAP Inventory name
          resource: inventories
          ui:field: AAPResourcePicker
          default: my-inventory
        credentials:
          title: Credentials
          description: Select SCM credential for Private repositories
          resource: credentials
          ui:field: AAPResourcePicker
          default: my-machine-credential
  steps:
    # Step 1: Create AAP Project
    - id: create-project
      name: Create AAP Project
      action: rhaap:create-project
      input:
        token: ${{ parameters.AAP_TOKEN }}
        deleteIfExist: true
        values:
          projectName: ${{ parameters.projectName }}
          organization: ${{ parameters.organization }}
          scmUrl: ${{ parameters.repoUrl }}
          scmBranch: main
          scmUpdateOnLaunch: true

    # Step 2: Create Execution Environment
    - id: create-ee
      name: Create Execution Environment
      action: rhaap:create-execution-environment
      input:
        token: ${{ parameters.AAP_TOKEN }}
        values:
          environmentName: ${{ parameters.projectName }}-ee
          organization: ${{ parameters.organization }}
          image: quay.io/ansible/creator-ee:latest
          pull: missing

    # Step 3: Create Job Template
    - id: create-template
      name: Create Job Template
      action: rhaap:create-job-template
      input:
        token: ${{ parameters.AAP_TOKEN }}
        values:
          templateName: ${{ parameters.projectName }}-deploy
          templateDescription: Deployment job template
          project: ${{ steps['create-project'].output.project }}
          organization: ${{ parameters.organization }}
          jobInventory: ${{ parameters.jobInventory }}
          playbook: site.yml
          executionEnvironment: ${{ steps['create-ee'].output.executionEnvironment }}

    # Step 4: Launch the Job
    - id: launch-job
      name: Launch Job
      action: rhaap:launch-job-template
      input:
        token: ${{ parameters.AAP_TOKEN }}
        values:
          template: ${{ parameters.projectName }}-deploy
          inventory: ${{ parameters.jobInventory }}
          credentials: ${{ parameters.credentials }}
          jobType: run
          extraVariables:
            created_by: backstage
            timestamp: ${{ '' | now }}

  output:
    links:
      - title: AAP Project
        url: ${{ steps['create-project'].output.project.url }}
      - title: Job Template
        url: ${{ steps['create-template'].output.template.url }}
      - title: Job Execution
        url: ${{ steps['launch-job'].output.data.url }}
Copy to Clipboard Toggle word wrap

5.4. Custom UI components and filters
Copy link

The Ansible Backstage Plugins provide custom UI components that enhance the software template experience by integrating directly with Ansible Automation Platform resource selection and authentication.

5.4.1. AAPTokenField
Copy link

The AAPTokenField is a secure authentication field used in backstage scaffolder templates. It automatically fetches and stores an Ansible Automation Platform OAuth2 token, which is then available for all rhaap:* actions, enabling seamless authentication.

AAPTokenField Properties

The following table details the field’s properties for use in a template’s properties section.

Expand
PropertyTypeDescription

title

string

The label displayed in the UI (for example, "AAP Token"). Defaults to "AAP Token".

description

string

A short help text displayed below the input field.

ui:field

string

Must be set to AAPTokenField. This setting instructs Backstage to render a custom react component instead of a default input field.

ui:backstage.review.show

boolean

If true, this field appears in the Review step before scaffolding executes. The default value is true.

Authentication flow and token management

All rhaap:* actions require an OAuth2 token for authenticating with Ansible Automation Platform. The field manages the token through the following process:

  • Token Source: The token is automatically obtained from the Ansible Automation Platform OAuth2 authentication provider.
  • Storage: The token is stored securely in Backstage secrets or fetched through the @ansible/backstage-plugin-auth-backend-module-rhaap-provider.
  • Usage: The token is passed to each action using the token input parameter.

When the RHAAP auth provider is used, the token is injected automatically and can be referenced in the workflow steps as shown: 

  - id: create-project
    action: rhaap:create-project
    input:
      token: ${{ parameters.AAP_TOKEN }}
      # ... other inputs
Copy to Clipboard Toggle word wrap

Example

The following example shows how to declare and reference the AAPTokenField within a backstage template. Note that ui:widget: hidden and ui:backstage: review: show: false are used to ensure the token is not exposed in the UI. 

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: my-AAP-template
  title: Example AAP Template
spec:
  parameters:
    - title: Authentication
      properties:
        token:
          title: AAP Authentication Token
          type: string
          description: Oauth2 token
          ui:field: AAPTokenField
          ui:widget: hidden
          ui:backstage:
            review:
              show: false
  steps:
    - id: launch-job
      name: Launch AAP Job Template
      action: rhaap:launch-job-template
      input:
        token: ${{ parameters.token }}
        ...
Copy to Clipboard Toggle word wrap

Error and validation handling

All rhaap:* actions include built-in validation and user-friendly error reporting:

  • Validation: If the token is missing or invalid, the action throws the error: "`Authorization token not provided`."
  • Error Messages: Actions catch API client errors, extracting and surfacing meaningful messages without exposing stack traces.
  • Workflow Safety: If a step fails due to authentication, subsequent steps are automatically skipped, ensuring a safe and predictable workflow.

5.4.2. AAPResourcePicker
Copy link

The AAPResourcePicker is a dynamic field for backstage scaffolder templates. It fetches and displays a list of Ansible Automation Platform resources (such as inventories, organizations, or credentials) directly from the Ansible Automation Platform API, allowing users to select a resource for their automation workflow.

AAPResourcePicker Properties

The following table details the essential properties for configuring the resource picker in a template’s properties section.

Expand
PropertyTypeDescription

title

string

The label displayed in the UI (for example, "Inventory").

description

string

A short help text shown below the field.

ui:field

string

Must be set to AAPResourcePicker.

resource

string

The specific Ansible Automation Platform (AAP) resource type to fetch and display (for example, inventories, credentials, or organizations).

idKey

string

The property name used to retrieve the resource ID (default: “id”).

nameKey

string

The property name used to display the resource name in the list (default: “name”).

type

string

Set to “array” for a multi-select field; omit this property for a single-select field.

Example

The following example demonstrates how to use the AAPResourcePicker to create a single-select field for choosing an Inventory. 

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: my-AAP-template
  title: Example AAP Template
spec:
  parameters:
    - title: Authentication
      properties:
        jobInventory:
          title: Inventory
          description: Select inventory
          resource: inventories
          ui:field: AAPResourcePicker
          default: DemoInventory
Copy to Clipboard Toggle word wrap

5.4.3. Custom filters
Copy link

The plugins provide custom filters to extract specific properties from resource objects, which is essential for passing data between backstage steps.

Expand
FilterPurposeExample Usage

resourceFilter

Extracts a single, specific property from a resource object.

`$!{{ parameters.organization

resourceFilter('name') }}`

multiResourceFilter

Extracts a specific property from multiple resource objects (when the input is an array).

5.5. Standard UI widgets
Copy link

Standard UI widgets provide enhanced components for user forms to capture various types of input.

5.5.1. Textarea widget
Copy link

The textarea widget renders a multi-line text input field for capturing long-form user input such as descriptions or configuration content. 

properties:
  description:
    type: string
    title: Description
    ui:widget: textarea
    ui:options:
      rows: 5
      placeholder: "Enter description..."
Copy to Clipboard Toggle word wrap

5.5.2. Select widget
Copy link

The select widget displays a dropdown menu that enables users to choose a single value from a predefined list of options. 

properties:
  environment:
    type: string
    title: Environment
    enum: ['dev', 'staging', 'prod']
    ui:widget: select
    default: 'dev'
Copy to Clipboard Toggle word wrap

5.5.3. Checkboxes widgets
Copy link

The checkboxes widget renders a group of checkboxes, enabling the selection of multiple options from a list. The original plural "Checkboxes Widgets" is corrected to the singular form for style consistency. 

properties:
  features:
    type: array
    title: Base Images
    items:
      type: string
      enum: ['baseImage1', 'baseImage2', 'baseImage3']
    ui:widget: checkboxes
    uniqueItems: true
Copy to Clipboard Toggle word wrap

5.5.4. Hidden widget
Copy link

The hidden widget holds a fixed or prefilled value that is not visible to the user but is included in the submitted data. Use this widget for passing non-user-editable data, such as authentication tokens. 

kind: Template
metadata:
  name: my-AAP-template
  title: Example AAP Template
spec:
  parameters:
    - title: Authentication
      properties:
        token:
          title: AAP Authentication Token
          type: string
          description: Oauth2 token
          ui:field: AAPTokenField
          ui:widget: hidden
          ui:backstage:
            review:
              show: false
  steps:
    - id: launch-job
      name: Launch AAP Job Template
      action: rhaap:launch-job-templat
      input:
        token: ${{ parameters.token }}
      ...
Copy to Clipboard Toggle word wrap

Create custom execution environment (EE) definitions through Self Service Automation Portal using the EE Builder.

Note

Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

An administrator must enable the EE definition files feature in the configuration to display it in the left navigation panel.

To enable the EE definition files feature, you must modify the enabled key in your Helm chart configuration.

Procedure

  1. Open the configuration file for your Helm chart.
  2. Navigate to the default.main-menu-items section.

  3. Set the value of the enabled key under the default.ee configuration block to true.

    Note

    Setting enabled: true enables the EE definition files feature for all users.

    Example

    The final configuration must look like the following example: 

    default.main-menu-items:
  menuItems:
    default.mycatalog:
      title: Templates
      icon: home
      to: /self-service/catalog
      priority: 120
    default.myitem:
      title: History
      icon: category
      to: /self-service/create/tasks
      priority: 110
    default.ee:
      enabled: false
    Copy to Clipboard Toggle word wrap

Understand how to successfully plan and configure your custom execution environment (EE) definition. Review the available options for base images, automation presets, and dependency requirements before you start the creation process to ensure your EE supports your organization’s automation content.

6.2.1. Execution Environment (EE) definition
Copy link

The components and configurations for defining your EE are organized into two main categories: Pre-defined templates (presets) and custom components.

6.2.2. Pre-defined EE templates
Copy link

Pre-defined EE templates are pre-configured templates designed to accelerate environment setup for common use cases. They already include specific base images, collections, and dependencies tailored for their respective domain.

Expand
PresetDescriptionKey considerations and use cases

Start from scratch

A template which acts as a generic blank slate to start creating custom EEs from.

Use this preset when you require complete control over the base image and dependencies to build a highly customized or minimized EE.

Networking Automation

A template optimized for environments focused on network device interaction and network-specific content.

Use this preset when your automation primarily interacts with switches, routers, firewalls, and other network infrastructure.

Cloud Automation

A template optimized for environments focused on deploying and managing cloud resources (such as AWS or Microsoft).

Use this preset when your automation targets provisioning, configuration, and management of cloud services.

6.2.3. Disabling pre-built templates
Copy link

For environments where these pre-built templates are not needed or conflict with organizational standards, they can be disabled in the Helm chart configuration.

Procedure

  • You can disable pre-built templates by commenting them out in the Helm chart configuration. The following is an example of all three pre-built templates commented out: 

    catalog:
  locations:
    # Local templates
    - type: file
      target: ../../examples/entities.yaml

    # The following Ansible pre-built templates are disabled:
    # - type: url
    #   target: https://github.com/ansible/ansible-rhdh-templates/blob/main/templates/ee-start-from-scratch.yaml
    # - type: url
    #   target: https://github.com/ansible/ansible-rhdh-templates/blob/main/templates/ee-network-automation.yaml
    # - type: url
    #   target: https://github.com/ansible/ansible-rhdh-templates/blob/main/templates/ee-cloud-automation.yaml
    Copy to Clipboard Toggle word wrap

6.2.4. Components for custom EE definitions
Copy link

When creating a custom EE, you define the core underlying elements that dictate the environment’s capabilities, security, and dependencies. These components are used to define the custom EE, and are also utilized internally by the pre-defined presets.

Expand
Component or settingDescriptionKey considerations and examples

Base images

The foundation layer of your EE, pre-configured with a specific operating system and toolset.

By default, the following base images are available in all 3 pre-defined templates:

  • Red Hat Ansible Minimal EE - Ansible Core 2.18 (RHEL 8)
  • Red Hat Ansible Minimal EE - Ansible Core 2.18 (RHEL 9)
  • Red Hat Ansible Minimal EE - Ansible Core 2.16 (RHEL 8)
  • Red Hat Ansible Minimal EE - Ansible Core 2.16 (RHEL 9)

Select a base image that aligns with your organization’s security and Python compatibility needs. Popular base images are optimized for minimal overhead or specific compliance requirements.

If you are providing a custom image, it must include ansible-core and ansible-runner.

Select a base image that aligns with your organization’s security and Python compatibility needs.

Collections

Specifies the Ansible Collections and Python libraries required by your automation content.

Ensure all necessary content is included from the documentation’s list. You can add collections manually or upload a requirements.yml file.

When collections overlap, the system merges the contents. If duplicates occur:

  • If a version is not specified, the system prioritizes the collection using the most recent version available.
  • If versions are explicitly specified for both collections, the system defaults to using the most recent version.

Python requirements

Defines the minimum Python version and any extra Python packages required for this execution environment.

Must reflect the version compatibility used across your organization for running automation reliably.

Avoid repeating Python requirements already specified as a dependency by the selected collections (for example, in their respective requirements.txt files).

System packages

Operating system (OS) libraries and packages required by the Python packages or collections.

Defines the extra OS libraries and packages required by the Python packages or collections listed in the EE.

Examples: git, gcc, python3-devel. These are necessary for compiling Python packages during the build process.

This list supplements, and must not repeat, any base OS dependencies already managed by your environment’s build system.

Additional build steps

Additional build steps are custom shell commands injected directly into the container runtime instruction file.

Use additional build steps to perform actions like installing private certificates or configuring environment variables not covered by standard package installation.

The EE Builder supports the optional integration of a Model Context Protocol (MCP) server. MCP servers are an advanced feature used to expose automation actions to AI assistants or other cognitive services.

If you select an MCP server, the EE Builder automatically handles the necessary configuration files and dependencies. This portal feature generates execution environment definition files for building an execution environment with your selected MCP servers.

The EE Builder currently supports the following MCP servers:

  • Git Hub

  • AWS

    • AWS CCAPI
    • AWS CDK
    • AWS IAM
    • AWS Core
  • Azure

You can use the Execution Environment (EE) Builder in the self-service automation portal to create custom EE definitions through a guided workflow.

Prerequisites

Procedure

  1. Log into the self-service automation portal and select EE definition files from the lefthand navigation pane.
  2. If this is your first time creating an EE definition file, click Create Execution Environment definition file, otherwise select the Create tab.
  3. Click Start on your preferred template.

  4. Select your preferred base image and click Next.

    Note

    Red Hat recommends using the Red Hat Minimal EE base. If selecting Custom Image, it is important you fully understand what the contents of your base image are. For example, a base image without Ansible core or Ansible runner will fail to build.

  5. Select a collection from Add popular Collections or Add Collection Manually and click Next.

    1. Optional: To add additional Python or System requirements, select Specify additional python requirements and system packages, and then click Add packages manually or Choose File.
  6. Select your desired MCP servers and click Next.

  7. Optional: In the Additional Build Steps section, you can specify custom build instructions that will be executed at specific steps during the build process:

    1. Select Add build Step.
    2. Select a step from the Step type drop-down list.
    3. Input a command you want to run at that step. You can provide a string of commands by giving each command a new line.
    4. Click Next.

  8. In the Generate and publish section:

    1. Fill in the following mandatory fields:

      • EE File name
      • Description
      • Select source control provider
      • SCM repository organization name or username
      • Repository name
    2. Ensure the execution-environment tag is applied. Click the plus (+) icon to add additional tags if required.
    3. Ensure Publish to a Git repository is selected. If unselected, your EE will be provided as a download after the build process.
    4. If the Repository name you provided does not already exist, select Create new repository. If it does exist and you check the box, a pull request will be created instead.
    5. Click Next.
  9. Confirm your details are correct and click Create. This begins the scaffolding process.
  10. After the scaffolding is complete, click Getting started for next steps on how to build your EE definition.

Verification

Verify the creation and deployment of the EE definition file using one of the following methods:

  1. In the self-service automation portal:

    1. Click View details in catalog or Download EE files (downloads the generated files as a .tar file).
    2. Alternatively, select EE definition files in the left-hand navigation pane. The new file appears in the Execution Environment definition files box.

  2. In the repository:

    1. Click GitHub repository or Gitlab repository to confirm the files were scaffolded into your repository.

6.5. Importing your custom EE definition
Copy link

The EE definition workflow generates a reusable Backstage software template, named <ee-name>-template.yaml. This template includes the specified default configurations when you select Publish to a Git repository during the creation of your custom EE definition.

The template is also generated for non-SCM based publishings.

You can import this template into the self-service automation portal to make the default configuration available to others.

Prerequisites

  • You have installed the self-service automation portal.
  • You have the EE Builder feature enabled.
  • You have a custom EE definition hosted in a repository.

Procedure

  1. Go to the repository where your <ee-name>-template.yaml is stored and open it.
  2. Copy the URL of the template.yaml page.
  3. Log into the self-service automation portal and select EE definition files from the lefthand navigation pane.
  4. Click Create > Add Template.
  5. Paste the template URL into the Select URL field and click Analyze.
  6. Click Import.

Verification

To verify your template was added successfully, go to EE definition files > Create. Here you should see your newly created custom template.

6.6. Managing your EE files
Copy link

Download your Execution Environment (EE) file to create a local backup. Copy an existing EE to use it as a template for a new, similar environment. Delete an EE to remove obsolete or unwanted definitions.

Prerequisites

  • You have created an EE definition through the EE Builder.

Procedure

  1. Log into the self-service automation portal and select EE definition files from the lefthand navigation pane.

  2. Under the Name column, select the EE you want to take action on:

    • To download your EE definition, click Download EE files.
    • To delete your EE definition, click the vertical dots icon and then select Unregister entity.

    • To copy your EE definition:

      • Click the vertical dots icon and then select Copy entity URL.
      • Select EE definition files from the lefthand navigation pane.
      • Click Create and then Add template.
      • Paste your entity URL into the Select URL field and click Analyze.
      • Click Import. The new template now appears in the Execution Environment definition files page.

Self-service automation portal provides a feedback form where you can suggest new features and content, as well as provide general feedback.

Note

The feedback form is disabled by default. If the Feedback button is not visible in the console, your administrator must enable it in the portal configuration.

  1. Click Feedback in the self-service automation portal console to display the feedback form.

    Self-service automation portal feedback form
    View larger image
    Self-service automation portal feedback form
  2. Enter the feedback you want to provide.
  3. Tick the I understand that feedback is shared with Red Hat checkbox.
  4. Click Submit.
Note

To ensure that Red Hat receives your feedback, exclude your self-service automation portal URL in any browser ad blockers or privacy tools.

Legal Notice
Copy link

Copyright © Red Hat.
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, 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 Software Collections 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.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top