Chapter 5. Catalogs and Services

Through the use of catalogs, Red Hat CloudForms provides support for multi-tier service provisioning to deploy layered workloads across hybrid environments. You can create customized dialogs that will give consumers of the services the ability to input just a few parameters and provision the entire service. The following table lists the terminology associated with catalogs that you will use within the CloudForms user interface for service provisioning.

Table 5.1. Terminology

TypeInformation

Catalog Bundle

A group of templates.

Catalog Item

A single template.

Template

A template is a copy of a preconfigured virtual machine, designed to capture the installed software and software configurations, as well as the hardware configuration of the original virtual machine.

Dialog Tabs

Part of a service dialog.

Element

An item on a tab in a dialog. It can be a button, check box, drop down list, radio button, tag control, text area box, or a text box.

Provisioning Dialogs

Dialogs created for host provisioning, virtual machine migration, or virtual machine provisioning. The dialog name must be added to the appropriate provision instance to be processed.

Service Catalog

A catalog item or catalog bundle that is available for provisioning.

Service Dialogs

Made up of fully customizable tabs, items, and values for use with service provisioning.

5.1. Service Dialogs

When provisioning a service, input will be needed from the requester. Service dialogs are used to take input from the user. This input is connected to a method in the Automate model that defines how the users input is translated into the provision request. Before creating a service dialog, be sure to plan what items you need the user to input.

5.1.1. Adding a Service Dialog

Important

When creating a service dialog for use with Ansible playbook catalog items, variable elements must use the prefix param_ when assigning the value. For example, a new variable labeled key1 should have its value set as param_key1.

  1. Navigate to Automate → Customization.
  2. Click the Service Dialogs accordion.
  3. Click 1847 (Configuration), and then 1862 (Add a new Dialog).

  4. In Dialog Information, enter a Label and Description. Check the boxes for the buttons you want available at the bottom of the dialog form. The description will appear as hover text.

    As you enter the Label of the dialog, it should appear in the Dialog pane on the left.

    1. Click 1862 (Add), then 1862 (Add a New Tab to this Dialog).

    2. Enter a Label and Description for this tab.

      As you enter the Label of the tab, it should appear in the Dialog pane on the left under the dialog you are creating.

    3. Click 1862 (Add), then 1862 (Add a New Box to this Tab).

    4. Enter a Label and Description for this box.

      As you enter the Label of the box, it should appear in the Dialog pane on the left under the tab you are creating.

  5. Add an element to this box. Elements are controls that accept input.

    1. Click 1862 (Add), then 1862 (Add a New Element to this Box).

    2. Enter a Label, Name, and Description for this element.

      Important

      Name must use only alphanumeric characters and underscores without spaces. It is also used to retrieve the value of this element in the method used with the dialog and must start with dialog_service_type

    3. Select a Type for an element type. All Type options have a Required and Default Value field. Check Required or set Required to true if the element is required to proceed. You can also specify a default value. The rest of the options presented are based on which type of element you select.

      Element TypesAdditional Info

      Check Box

      Check Default Value if you want this check box checked by default.

      Date Control

      Use Date Control to create a field where users can select a date. If you want users to be able to select a date and time, use the Date/Time Control option.

      Date/Time Control

      Use Date/Time Control to create a field where users can select a date and time. Only one Date Control or Date/Time Control element can be present in a dialog.

      Drop Down Dynamic List

      Use Drop Down Dynamic List if you want the list options to be created using automate methods. Use Entry Point (NS/Cls/Inst) to select an automate instance. Check Show Refresh Button to allow users to refresh the list options manually.

      Radio Button

      This element type serves the same purpose as Drop Down List but displays options using radio buttons.

      Tag Control

      Select a Category of tags you want assigned to the virtual machines associated with this service dialog. Check Single Select if only one tag can be selected.

      Text Area Box

      Provides text area for users to enter some text. You can also leave a message to users by typing in the Default Value field or leave it as blank.

      Text Box

      This element type serves the same purpose as Text Area Box with the option to check Protected so the text is shown as asterisks (*), instead of plain text.

  6. Continue adding the dialog items you need. You can switch between dialogs, tabs, boxes, and elements by selecting their respective labels from the Dialog pane on the left.
  7. Click Add. Your dialog should appear in the Service Dialogs accordion.

5.1.2. Importing Service Dialogs

You can share service dialogs between appliances using the export and import features.

  1. Navigate to Automate → Customization.
  2. In the Import/Export accordion, click Service Dialog Import/Export.
  3. In the Import area, click Browse to select an import file.
  4. Click Upload.

5.1.3. Exporting Service Dialogs

You can share service dialogs between appliances using the export and import features.

  1. Navigate to Automate → Customization.
  2. In the Import/Export accordion, click Service Dialog Import/Export.
  3. In the Export area, select the service dialogs that you want to export.
  4. Click Export.

5.2. Methods

5.2.1. Creating a Method to Associate with the Dialog

You will need to create a method that connects the values in the dialog with the provisioning request. The method should be created in the DOMAIN/Service/Provisioning/StateMachines/ServiceProvision_Template class of the Automate model.

Note

DOMAIN must be a user-defined Domain and not the locked ManageIQ Domain. If necessary, you can copy the class from the ManageIQ domain into a custom domain.

A method is provided below that was created for the following scenario:

  • You want to provision a three-tiered service that contains catalog items of web, app and DB. Each of these virtual machines (or cloud instances) has been tagged under the Service category with the appropriate value. Then, added as a catalog item and combined into a catalog bundle.
  • The Service Dialog captures the selection of small, medium or large application in a dropdown called service_type. When referring to a value captured in an element in a dialog, the name of the element should be prefixed with dialog_. For example, service_type becomes dialog_service_type when used in the method.
  • The method will set the memory sizes for each of the catalog items based on the service_type selection. 
#            Automate Method
#
$evm.log("info", "Automate Method ConfigureChildDialog Started")
#
#            Method Code Goes here
#
$evm.log("info", "===========================================")
$evm.log("info", "Listing ROOT Attributes:")
$evm.root.attributes.sort.each { |k, v| $evm.log("info", "\t#{k}: #{v}")}
$evm.log("info", "===========================================")

stp_task = $evm.root["service_template_provision_task"]
$evm.log("info", "===========================================")
$evm.log("info", "Listing task Attributes:")
stp_task.attributes.sort.each { |k, v| $evm.log("info", "\t#{k}: #{v}")}
$evm.log("info", "===========================================")

#############################################################
#### This is how the method would look for dialog variables
#############################################################
dialog_service_type = $evm.root['dialog_service_type']
$evm.log("info","User selected Dialog option = [#{dialog_service_type}]")

stp_miq_request_task = stp_task.miq_request_task
#$evm.log("info","(parent) miq_request_task:  = [#{stp_miq_request_task}]")

#############################################################
#### This is how you get the catalog items for the catalog bundle
#############################################################

stp_miq_request_tasks = stp_task.miq_request_tasks
#$evm.log("info","(children) miq_request_tasks count:  = [#{stp_miq_request_tasks.count}]")

#############################################################
#### By going through the children, you can set the dialog variable for each of the children (we based our values on the childrens service tags)
#############################################################

stp_miq_request_tasks.each do |t|

  $evm.log("info"," Setting dialog for: #{t.description}")
  service = t.source
  service_resource = t.service_resource
  #$evm.log("info"," Child service resource name: #{service_resource.resource_name}")
  #$evm.log("info"," Child service resource description: #{service_resource.resource_description}")

  service_tag_array = service.tags(:app_tier)
  service_tag = service_tag_array.first.to_s

  memory_size = nil

#############################################################
#### The dialog_service_type is the attribute set on the service dialog
#### We use the service_tag to decide what child gets what dialog
#############################################################

  case dialog_service_type
  when "Small"
    case service_tag
    when "app"
      memory_size = 1024
    when "web"
      memory_size = 1024
    when "db"
      memory_size = 4096
    else
      $evm.log("info","Unknown Dialog type")
    end
  when "Large"
    case service_tag
    when "app"
      memory_size = 4096
    when "web"
      memory_size = 4096
    when "db"
      memory_size = 8192
    else
      $evm.log("info","Unknown Dialog type")
    end
  else
    $evm.log("info","Unknown Dialog type - setting Dialog options here")
  end

#############################################################
#### set_dialog_option sets the dialog for the child
#############################################################

  t.set_dialog_option('memory',memory_size) unless memory_size.nil?
  $evm.log("info","Set dialog for selection: [#{dialog_service_type}]  Service_Tier: [#{service_tag}] Memory size: [#{memory_size}]")

end
#
#
#
$evm.log("info", "Automate Method ConfigureChildDialog Ended")
exit MIQ_OK

5.2.2. Creating a Method in the Service Class

Service methods have been split based on purpose.

  1. Navigate to Automate → Explorer.

  2. Service Class is located at DOMAIN → Service → Provisioning → StateMachines → Methods and Domain → Service → Retirement → StateMachines → Methods.

    Note

    DOMAIN must be a user-defined Domain and not the locked ManageIQ Domain. If necessary, you can copy the class from the ManageIQ domain into a custom domain.

  3. Click the Methods tab.
  4. Click 1847 (Configuration), then 1862 (Add a New Method).
  5. Enter a Name and Display Name.
  6. In the Data field, enter the method contents.
  7. Click Validate and wait for your data entry to be successfully validated.
  8. Click Add. 6297

5.2.3. Creating an Instance in the Service Class

  1. Navigate to Automate → Explorer.

  2. Service Class is located at DOMAIN → Service → Provisioning → StateMachines → Methods and Domain → Service → Retirement → StateMachines → Methods.

    Note

    DOMAIN must be a user-defined Domain and not the locked ManageIQ Domain. If necessary, you can copy the class from the ManageIQ domain into a custom domain.

  3. Click the Instances tab.
  4. Click 1847 (Configuration), then 1862 (Add a new Instance).
  5. Enter a Name and Display Name.
  6. In the Fields area, enter the method’s name in Value.
  7. Click Add.

The instance is created so that it can be called from the ServiceProvision class.

6298

Note

After the method has been created, it must be mapped to an instance in the DOMAIN/Service/Service/Provisioning/StateMachines class. The name of the instance must be specified as the Entry Point. This method must be called before the provision job begins.

5.2.4. Associating a Method with an Automate Instance

Service methods have been split based on purpose.

  1. Navigate to Automate → Explorer.
  2. From the accordion menu, click the required service method.

  3. Service Class is located at DOMAIN → Service → Provisioning → StateMachines → Methods and Domain → Service → Retirement → StateMachines → Methods.

    Note

    DOMAIN must be a user-defined Domain and not the locked ManageIQ Domain. If necessary, you can copy the class from the ManageIQ domain into a custom domain.

  4. Either create a new instance or select the clone_to_service instance.
  5. Click 1847 (Configuration), then 1851 (Edit Selected Instance).
  6. In the configurechilddialog value, put the path to the method.
  7. Click Save or Add if you are adding this to a new instance.

5.3. Catalogs

Catalogs are used to create groups of virtual machines or instances for provisioning. For example, a complete package of a database server, desktop with specialized software already on it, and a firewall. You will need to complete the following steps to create and provision a service catalog.

  1. Create Catalog Items for each virtual machine or instance that will be part of the service.
  2. Create a Service dialog. For example, create a dropdown with three options small, medium, and large.
  3. Create a method for the Service Dialog. This method defines what each of the options means to each of the individual virtual machines or cloud instances for the service. This method is called from a service provisioning instance in the Automate model.

  4. Create an instance in the DOMAIN/Service/Provisioning/StateMachines/ServiceProvision_Template class that calls the method.

    Note

    DOMAIN must be a user-defined Domain and not the locked ManageIQ Domain. If necessary, you can copy the class from the ManageIQ domain into a custom domain.

  5. Associate method with Automate instance.
  6. Create a Catalog Bundle, adding each of the catalog items to it. Select the Service Dialog you created. Use the instance created in the DOMAIN/Service/Provisioning/StateMachines/ServiceProvision_Template class as the Entry Point. Check Display in Catalog box.
  7. Provision a service.

5.3.1. Creating a Catalog Bundle

  1. Navigate to Services → Catalogs.
  2. Click the Catalog Items accordion.
  3. Click 1847 (Configuration), and then 1862 (Add a New Catalog Bundle).
  4. In Basic Info, enter a name and description: 2362
  5. Click Display in Catalog.
  6. Select the appropriate dialog name.
  7. Select the path to the appropriate ServiceProvision instance.
  8. Click on the Resources tab, then select the catalog items you want added to the bundle from the Add a Resource dropdown.
  9. Click Add.

A catalog bundle is created and visible in the Service Catalog accordion.

Note

You should also create and specify an Entry Point in the DOMAIN/Service/Provisioning/StateMachines/Methods/CatalogBundle class for each catalog item that is part of a bundle. If you do not, then the pre and post provision processing will occur for each item in the bundle in addition to processing for the Catalog Bundle. To set the entry point, go into each Catalog Item and check Display in Catalog. Then, you will see the Entry Point field.

5.3.2. Creating a Catalog Item

Create a catalog item for each virtual machine or cloud instance that will be part of the service.

  1. Navigate to Services → Catalogs.
  2. Click the Catalog Items accordion.
  3. Click 1847 (Configuration), and then 1862 (Add a New Catalog Item).

  4. Select the Catalog Item Type you are adding. The dialogs that appear will be filtered based on the selected type of provider. For example, you will only see templates residing on Red Hat Providers, if the Catalog Item Type is Redhat.

    2357

  5. In the Basic Info subtab:

    1. Type a Name/Description.

    2. Check Display in Catalog to edit Catalog, Dialog, and Entry Point(NS/Cls/Inst) options.

      1. Provisioning Entry Point (Domain/NS/Cls/Inst) requires you to select an Automate instance to run upon provisioning.

      2. Retirement Entry Point (Domain/NS/Cls/Inst) requires you to select an Automate instance to run upon retirement. Catalogitem statemachine

        Note

        The entry point must be a State Machine since the Provisioning Entry Point list is filtered to only show State Machine class instances. No other entry points will be available from the Provisioning Entry Point field.

        Note

        You can only choose from the catalogs and dialogs you have already created. If you haven’t done so, leave the values blank and edit later.

  6. In the Details subtab, write a Long Description for the catalog item.
  7. In the Request Info subtab, select provisioning options that apply to the provider chosen. For more information, refer to the sections on Provisioning Virtual Machines and Provisioning Instances.
  8. Click Add.

5.3.3. Creating a Generic Catalog Item

Create generic catalog items for services non-specific to virtualization or cloud environments. This catalog item type can serve a wide array of needs, from creating a vLAN across a network to accessing virtual machine IP addresses and adding them to a load balancer pool.

  1. Navigate to Services → Catalogs.
  2. Click the Catalog Items accordion.
  3. Click 1847 (Configuration), and then 1862 (Add a New Catalog Item).
  4. Select Generic from the Catalog Item Type list.

  5. In the Basic Info subtab:

    1. Type a Name/Description.
    2. Check Display in Catalog to display the item in the catalog. A Dialog will be required if you select Display in Catalog.
    3. Choose a Catalog to which to add the new item.
    4. Select a Dialog from the available options.
    5. Choose a Subtype from the list menu.

    6. Add Entry Point(NS/Cls/Inst) options.

      1. Provisioning Entry Point (Domain/NS/Cls/Inst) requires you to select an Automate instance to run upon provisioning.

      2. Retirement Entry Point (Domain/NS/Cls/Inst) requires you to select an Automate instance to run upon retirement.

        Note

        The entry point must be a State Machine since the Provisioning Entry Point list is filtered to only show State Machine class instances. No other entry points will be available from the Provisioning Entry Point field.

  6. In the Details subtab, write a Long Description for the catalog item.
  7. Click Add.

5.3.4. Creating an Ansible Playbook Service Catalog Item

Create a catalog item that uses an Ansible Playbook to back it.

Create a catalog item that uses an Ansible Playbook to back it.

Note

Before creating an Ansible service, at least one repository, one playbook, and one credential must exist in the Red Hat CloudForms inventory. Check your inventory and add the appropriate resources before creating an Ansible service. For more information, see Automation Management Providers in Managing Providers.

  1. Navigate to Services → Catalogs.
  2. In the Catalog Items accordion, click on the All Catalog Items.
  3. Click 1847 (Configuration), then 1862 (Add a New Catalog Item).
  4. Select Ansible Playbook from the Catalog Item Type drop-down list.
  5. Type a Name and Description for the new service catalog item.
  6. Click Display in Catalog.
  7. Select the appropriate Catalog from the drop-down list.

  8. In the Provisioning tab, set parameters for your catalog item to use by configuring a Playbook to back your service item:

    1. Choose a Repository from the drop-down list.
    2. Select the Ansible Playbook to use.
    3. Assign the appropriate Machine Credentials from the drop-down list.
    4. Add Cloud or Network Credentials from the drop-down lists.
    5. Choose the Host against which to run the service item.
    6. Use the Escalate Privilege toggle switch to enable user privilege escalation if called for in credentials during the playbook run.
    7. Add key value pairs for Variables and their corresponding Default Values.
    8. In the Dialog options, choose an existing dialog from the Use Existing drop-down list or select Create New to add a new dialog.

  9. In the Retirement tab, set parameters for your catalog item to use by selecting values for the following:

    1. Choose a Repository from the drop-down list.
    2. Select the Ansible Playbook to use.
    3. Assign the appropriate Machine Credentials from the drop-down list.
    4. Add Cloud or Network Credentials from the drop-down lists.
    5. Choose the Host against which to run the service item.
    6. Use the Escalate Privilege toggle switch to enable user privilege escalation if called for in credentials during the playbook run.
    7. Add key value pairs for Variables and their corresponding Default Values.
    8. In the Dialog options, choose an existing dialog from the Use Existing drop-down list or select Create New to add a new dialog.
  10. Click Add.

5.3.5. Creating an Ansible Tower Service Catalog Item

Create a service catalog item from an Ansible Tower template you can use to execute an Ansible Tower playbook in Red Hat CloudForms.

Create a service catalog item from an Ansible Tower template you can use to execute an Ansible Tower playbook in Red Hat CloudForms.

Important

You must first create the job template in Ansible Tower. The job templates are automatically discovered by CloudForms when refreshing your Ansible Tower provider’s inventory.

First, create a catalog:

  1. Navigate to Services → Catalogs.
  2. Click Configuration (Configuration), then Add a New Catalog (Add a New Catalog)
  3. Enter a Name and Description for the catalog.
  4. Click Add.

Then, create an Ansible Tower service catalog item:

  1. Navigate to Automation → Ansible Tower → Jobs.
  2. Click Ansible Tower Job Templates and select an Ansible Tower job template.
  3. Click Configuration (Configuration), then Create Service Dialog from this Job Template (Create Service Dialog from this Job Template).
  4. Enter a Service Dialog Name (for example, ansible_tower_job)and click Save.
  5. Navigate to Services → Catalogs. Click Catalog Items.

  6. Click Configuration (Configuration), then Add a New Catalog Item (Add a New Catalog Item) to create a new catalog item with the following details, at minimum:

    • For Catalog Item type, select Ansible Tower.
    • Enter a Name for the service catalog item.
    • Select Display in Catalog.
    • In Catalog, select the catalog you created previously.
    • In Dialog, select the service dialog you created previously (in this example, ansible_tower_job). No Dialog can be selected if the playbook does not require extra variables from the user. To ask the user to enter extra information when running the task, Service Dialog must be selected.
    • In Provider, select your Ansible Tower provider. This brings up the Ansible Tower Job Template option and configures the Provisioning Entry Point State Machine automatically.
    • Add configuration information for Reconfigure Entry Point and Retirement Entry Point as applicable.
    • Select your desired Ansible Tower Job Template from the list. Generally, this is the Ansible Tower job template previously used to create the service dialog.
  7. Click Add. The catalog item you created will appear in the All Service Catalog Items list.

5.3.5.1. Provisioning a Service

  1. Navigate to Services → Catalogs.
  2. Click the Service Catalogs accordion, and select the service to provision.
  3. Click Order.

The parameters are passed to the children based on the method tied to the choices made in the dialog.