Chapter 5. Catalogs and Services

5.1. About Catalogs and Services

Through the use of catalogs, CloudForms Management Engine 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.

5.2. Terminology

Terminology

Catalog Bundle
A grouping of Templates.
Catalog Item
A single Template or a group of Templates (catalog bundle).
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, VM Migration, or VM 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.
Template
A template is a copy of a preconfigured virtual machine, designed to capture installed software and software configurations, as well as the hardware configuration, of the original virtual machine.

5.3. Catalogs

5.3.1. 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.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 ServicesCatalogs.
  2. Click the Catalog Items accordion.
  3. Click 1847 (Configuration), and then 2055 (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. 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.3.3.1. Adding a Service Dialog

  1. Navigate to AutomateCustomization.
  2. Click the Service Dialogs accordion.
  3. Click 1847 (Configuration), and then 1848 (Add a new Dialog).
  4. In Dialog Information, type in 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.
  5. Add a tab to the dialog.

    1. Click 1848 (Add), then 1848 (Add a New Tab to this Dialog).
    2. Type in a Label and Description for this tab.
  6. Add a box to this tab.

    1. Click 1848 (Add), then 1848 (Add a New Box to this Tab).
    2. Type in a Label and Description for this box.
  7. Add an element to this box. Elements are controls that accept input.

    1. Click 1848 (Add), then 1848 (Add a New Element to this Box).
    2. Type in 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 type in 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.

  8. Click Add.

5.3.3.2. Importing Service Dialogs

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

  1. Navigate to AutomateCustomization.
  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.3.3.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.3.4. Methods

5.3.4.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.
#            CloudForms Management Engine Automate Method
#
$evm.log("info", "CloudForms Management Engine 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", "CloudForms Management Engine Automate Method ConfigureChildDialog Ended")
exit MIQ_OK

5.3.4.2. Creating a Method in the Service Class

Service methods have been split based on purpose.

  1. Navigate to AutomateExplorer.
  2. Service Class is located at DOMAINServiceProvisioningStateMachinesMethods and DomainServiceRetirementStateMachinesMethods.

    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 2360 (Add a New Method).
  5. Type in a Name and Display Name.
  6. In the Data field, type in the method contents.
  7. Click Validate and wait for your data entry to be successfully validated.
  8. Click Add. 6297

5.3.4.3. Creating an Instance in the Service Class

  1. Navigate to AutomateExplorer.
  2. Service Class is located at DOMAINServiceProvisioningStateMachinesMethods and DomainServiceRetirementStateMachinesMethods.

    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 2360 (Add a new Instance).
  5. Type in a Name and Display Name.
  6. In the Fields area, type in 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.3.4.4. Associating a Method with an Automate Instance

Service methods have been split based on purpose.

  1. Navigate to AutomateExplorer.
  2. From the accordion menu, click the required service method.
  3. Service Class is located at DOMAINServiceProvisioningStateMachinesMethods and DomainServiceRetirementStateMachinesMethods.

    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.

Now that the catalog items, service dialog, dialog methods, and service provision instance have been created, you can create the catalog bundle.

5.3.5. Creating a Catalog Bundle

  1. Navigate to ServicesCatalogs.
  2. Click the Catalog Items accordion.
  3. Click 1847 (Configuration), and then 1848 (Add a New Catalog Bundle).
  4. In Basic Info, type in a name and description images:2362.png[]
  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.5.1. Provisioning a Service

  1. Navigate to ServicesCatalogs.
  2. Click the Service Catalogs accordion, and select the service to provision.
  3. Click Order. The dialog appears.
  4. Select the options in the Service dialog.

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