Creating a Runbook

• Console
• CLI
• API

• On the Runbooks list page, select Create runbook. If you need help finding the list page, see Listing Runbooks.

  Creating a runbook consists of the following pages:

  • 1. Basic information

  • 2. Streamline (Design runbook)

  • 3. Review

  Run each of the following workflows in order. You can return to a previous page by selecting Previous.

  1. Basic information

  The Basic information page is where you provide the basic information for the runbook.

  Enter the following information:

  • Name: Enter a friendly name for the runbook. The name doesn't have to be unique, but it can't be changed in the Console. You can, however, change it with the API. Avoid entering confidential information.
  • Description: Enter a suitable description for the runbook.
  • Create in compartment: Select the compartment that you want to create the runbook in.
  • Lifecycle operation compartment: Select a compartment where the specific lifecycle operation exists. To know about various lifecycle operations, see Lifecycle Operation in Fleet Application Management.
  • Lifecycle operation: Select a lifecycle operation—for example, patch, discovery, provision, or custom.
  • For patch or discovery lifecycle operations, enter the following information:
    • Product/Product stack compartment: Select the compartment where the product or product stack is in.
    • Product/Product stack: Select a product or product stack to which the task belongs from the compartment.
  • OS type: Select a supported platform from the options on which the runbook runs.
  • Estimated time (Hours): Select the estimated time in hours to complete the runbook execution.
  • Set as default runbook: Switch on the toggle to let Fleet Application Management use this runbook as the default runbook for performing lifecycle operations.
    Note
    
    You can set only one runbook for a particular lifecycle operation and product or product stack combination as the default runbook. Fleet Application Management uses the default discovery runbook of a product or product stack to discover the software inventory of the product and the default patching runbook to automatically select a runbook during the schedule creation and compliance fix tasks.
  • This runbook need SUDO access: Switch on the toggle if the OS type is Oracle Linux for discovering and applying patches for the software running on Compute instances.

    The sudo access is required when product support is needed for Oracle WebLogic Server, Oracle HTTP Server (OHS), and Oracle Java, which aren't OCI-specific.

    Note
    
    When the runbook has sudo access enabled, the Fleet Application Management plugin executes the tasks with the sudo privilege. The Fleet Application Management plugin uses a built-in sudo privilege, but it's fully controlled through the runbook property isSudoAccessNeeded. See Runbook Reference.

  Select Next to proceed to the next step.

  2. Streamline (Design Runbook)

  The Streamline (Design runbook) page is where you design a runbook workflow using the visual designer or runbook code.

  With the visual designer, you can drag an action from the actions pane into the canvas, placing it where you want it in your runbook's workflow. You can also reorder actions in your workflow by dragging them to a different location.

  1. Select one of the following options:
     • Design view: Use the visual designer by dragging the components and configuring them. Skip to step 2.
     • Code view: Upload the runbook code in a YAML or JSON file. Skip to step 3.
  2. If you selected Design view for runbook creation, perform the following steps:
     Important
     
     To add a task, you must first add a parallel or rolling resource group. A task must be inside a group. To learn about using the visual designer, see Designing a Runbook with Visual Designer.
     1. From the Components tab of the actions pane, select a parallel resource group or a rolling resource group and drag it on the canvas. Add as many groups as you need.
        • For parallel execution of runbook tasks across resources, select a parallel group. A parallel resource group is a placeholder for one or more tasks within it, or another parallel task group that runs several tasks on a target resource in parallel. For each task that's added to a parallel resource group, the list of tasks is run one after another on a specific resource but simultaneously across a list of resources.
        • For sequential execution of runbook tasks, select a rolling resource group. A rolling resource group is a placeholder for one or more tasks where the list of tasks is run one after another on a specific resource. After the tasks are run successfully in the resource, the next task is run on another resource.

        Tip
        
        You can reorder components by using the drag handle icon () at the right corner of a component and dragging it to a different location on the runbook's work area. After you place a component onto the canvas, its code is automatically generated and added to the runbook's code.
     2. Select a new task and drag it to a resource group that you added. Enter details in the Create task page. For instructions, see steps 4 to 17 in Creating a task using the Console. You can also add a predefined task by dragging it to a resource group.
        • The tasks you create within the runbook are local to the runbook and can't be reused by other runbooks.
        • The tasks library provides a list of reusable tasks that exist, or that you created. You can use the drag handle icon ( ) at the right corner of a task to drag it into the resource group.
          Tip
          
          You can first create runbook tasks as needed and then add them to one or more runbooks later.
        • To create a copy of the task in the task library, select Make a copy of this task in library. This task is then a part of the runbook and the task library. However, you can reuse and update the library task independent of the runbook task.
     3. To update the properties of a task, select the edit icon next to the task and then update the field values in the Edit task page.
     4. After adding the required components to the runbook, select the properties icon () of the component to configure it by using the Properties tab.
     5. Enter a unique step name preferably based on its purpose. Avoid entering confidential information.
     6. Select one of the following actions from the On failure list to configure how automation can handle errors in the runbook's workflow:
        Note
        
        By default, when a runbook component reports an error, the Fleet Application Management automation stops the runbook's workflow entirely. This is because the default value for the On Failure property for all components is Abort.

        • Abort: Stop the runbook's workflow entirely when the component execution fails. This action is set by default.
        • Continue: Continue to the next step in the runbook workflow when the component execution fails.
        • Rollback: Undo the change and return to the level at which the runbook component was initially.

          To roll back, ensure you select the On Failure property as Rollback. You can specify the rollback function at the target or group levels (action group.) To roll back at the target level, select On failure of tasks or select On failure of rollback tasks to roll back at the group level.

     7. To build conditional statements for each runbook component by using the Condition option,
        Enter a variable on the condition box, select one of the arithmetic operators, such as AND, NOT, or others, and enter a value for the condition. The following is an example of conditional statement:

        For the following condition, if the backuptype variable for a task equals the value hot, the task is run, or the condition builder skips and proceeds to the next task.

        backuptype=hot

     8. Configure Run on to select one of the following options to run a task:
        • Instances specified by schedule: To allow a task to run conditionally only on certain components applicable to the product (as defined in the product metadata) on the resource, select Filter instances. For instructions on how to add filter conditions, see substep i.
        • Self-hosted instance: To check for post provisioning activity if needed, select an appropriate self-hosted instance that you have created under Metadata management in the Administration section.
          Note
          
          The selection of an instance ensures that the task is run only on this host (instance).

          For example, there can be two tasks where the action type of the first task is Run a Terraform that provisions the resources. The second task can be with the action type Run a script, where the script includes the self-hosted instance (central host) that checks whether the resources are provisioned and running.

          Important
          
          Ensure you enable the Fleet Application Management plugin on your self-hosted instance and its associated instance. This step ensures that Fleet Application Management can effectively consider these instances for lifecycle operations.
        • Instance specified by previous task: To check if provisioned resources are created and running when you don't configure a central host.
          For example, there can be two tasks that performs the following operations:

          1. Create a first task with the action type as Run a Terraform that provisions the Compute instances and returns the OCID of the provisioned resources as an output variable.
          2. Create a second task with the action type as Run a script.
          3. Select Output variable from previous task to provide the task variables.
          4. Enter the resource OCID that substep i returns or an optional resource type. Add more host information as created by the first task. The OCIDs or resource types serve as an input to the second task.
             Tip
             
             The host information can be provided as a JSON file with resource OCIDs described as an array.

          Fleet Application Management now parses the output variables and executes the script on the resources.

     9. If you selected Instances specified by schedule in substep h, select instances to open the Filter instances dialog box.
        • Select product or component properties from the box on the left side to add it to the filter box on the right side.
        • Select one of the arithmetic operators, such as AND, NOT, or others.
        • Enter a value for the condition in the condition box.
          Note
          
          As you select product or component properties, the filter box is populated with a relevant grammar condition.
          An example for the Run on grammar condition is as follows:

          target.product.name = <product_name>
          target.product.properties.<property_name> = <property_value>
          target.product.components.has(<component_name>)
          target.product.components.<component_name>.properties.<property_name> = <property_value>

          Note
          
          The conditions based on properties depend on your understanding of product discovery.

        Add more filter instances as needed. These instances are added to the next row in the filter box.
     10. Switch on the Pause execution toggle to halt or delay the running of tasks for a specific time until certain conditions are met. For example, you can choose to pause the running of a task indefinitely or until you resume the task, or for a specific time that you select.
     11. To get notified when the task status changes, switch on the Notification toggle, and then select the checkbox for the activity of the task for which you want to be notified—for example, on task failure, on pause, or when the task succeeds.
     12. Configure the properties of the tasks that you add. For field description of task properties, see steps 4 to 17 in Creating a Task using the Console.
  3. If you selected Code view for runbook creation in step 1, select whether you're using JSON or YAML and then select Upload runbook code to add the appropriate file.

  Select Next to proceed to the next step.

  3. Review

  Verify the contents of the runbook in the Review page. Edit settings or return to previous screens to add information.

  Select Save as draft to save the runbook initially until you're sure of all the components.

  Note
  
  This draft version of the runbook isn't active, can't be used, and is marked as a Draft.

  To make the runbook usable after you're sure about all its tasks and streamline (sequence of execution), select Publish latest version from the runbook's details page.

  The published runbook is available for use in provisioning, discovery, application of patches, or rollback, and it has an active status.

  Note
  
  The runbook is created with version 1 as the initial version and it has an active status.

• Use the oci fleet-apps-management fleet-apps-management-runbooks runbook create command and required parameters to create a custom runbook:

  oci fleet-apps-management fleet-apps-management-runbooks runbook create --compartment-id <compartment_OCID> --display-name <text> --operation <text> --runbook-version <json_file_or_string> [OPTIONS]

  For a complete list of flags and variable options for Fleet Application Management CLI commands, see the CLI for Fleet Application Management.

• Run the CreateRunbook operation to create a custom runbook.