1 Getting Started with Oracle Orchestration

Oracle Orchestration is a Platform-as-a-Service (PaaS) solution that lets you schedule, track, and execute workflow scripts on hosts or call Web service endpoints, all from a single location. You can schedule recurring maintenance tasks across your on-premises and cloud infrastructure environments.

Oracle Orchestration allows developers, system administrators and DevOps engineers to easily Author, Manage, Submit and Monitor workflows via a comprehensive easy to use UI and integrated JSON editor. Developers can use this Oracle Management Cloud service to integrate a scheduler into their applications. DevOps engineers can use Oracle Orchestration to automate and schedule deployments. System administrators can use Orchestration to rapidly and efficiently respond in an automatic fashion to service interruptions, backups, schedule downtime and restarts. Oracle Orchestration can also provide a simple REST API that allows easy integration with existing tools, and scripts to provision new environments and applications.

Note:

For this release, Oracle Orchestration REST API documentation access will be limited to approved customers. Contact your Oracle Support or Sales Representative for more information about accessing and using the Oracle Orchestration REST API. In addition, see the My Oracle Support note Orchestration Master Note (Doc ID 2229523.1) for the latest information.

About Oracle Orchestration

Orchestration is a set of activities performed on multiple entities or hosts to achieve a specific purpose. With Oracle Orchestration, these activities can be performed as a single step across large number of systems.

Oracle Orchestration provides you with a workflow automation tool in Oracle Cloud for system administrators and developers to automate processes and tasks across cloud and on-premises environments. You can define schedules for workflow executions repeatedly or in the future. This service uses the Oracle Management Cloud platform to deliver a highly scalable service that’s integrated with other Oracle Management Cloud feature-rich solutions for an on-premises data center or public cloud task automation. 

Benefits

• Single solution for on-premises and cloud

• Centralized operations

• Reduced complexity

• Lower investment

• Enhanced capacity prediction and planning

• Customized analysis to produce business insights

Before You Begin Using Oracle Orchestration

Before you use Oracle Orchestration, you should be familiar with the basic concepts of orchestration and setting up your environment.

This chapter covers the following topics:

• Target Audiences

• Useful Concepts

• Integration with Other Oracle Management Cloud Components

Target Audiences

Oracle Orchestration simplifies common tasks performed by IT personnel. Typically, job functions performed by IT personnel can be categorized as: DevOps, system administrators, and developers. Depending on the role that you have within your organization, your approach to learning and using Oracle Orchestration may differ.

The following examples illustrate how the three categories of IT personnel can use Oracle Orchestration to automate and simplify their typical job responsibilities.

DevOps

• Automate configuration tasks by running commands or scripts across distributed environments.

• Provision, patch, deploy, and maintain the IT infrastructure.

• Respond to critical incidents quickly and reduce IT support costs.

System Administrators

• Schedule, organize, and manage jobs or tasks.

• Automate configuration tasks by running commands or scripts across distributed environment.

• Provision, patch, and maintain the IT infrastructure.

• Respond to critical incidents quickly and reduce IT support costs.

Developers

• Automate application deployment.

• Enable continuous integration to trigger the post-build deployment process, including verification.

Useful Concepts

Before using the Oracle Orchestration, you should be familiar with the following concepts:

• Orchestration: A set of activities performed on multiple entities or hosts to achieve a specific purpose. With Oracle Orchestration Cloud Service, these activities can be performed as a single step across a large number of systems.
• Workflow: The specific pattern of activity that needs to be performed on a system or a set of systems. A workflow can be viewed as a fundamental building block for a business activity that can be automated by Oracle Orchestration Cloud Service. Workflows allow you to automate tasks and activities. For example, creating an instance on Amazon Web Services (AWS) to spin an Infrastructure-as-a-Service (IaaS) instance is a workflow. A workflow is formatted in JSON and submitted via the Orchestration UI. To view the different workflow elements and JSON examples please refer to Author Workflows Using V2.0 Syntax.
• Workflow Execution: A workflow execution is a collection of multiple workers based on the worker specification in the workflow submission. Oracle Orchestration Cloud Service creates an instance of a workflow execution based on the schedule specified in the workflow submission.
• Workflow Submission: The instance of a workflow that’s submitted using the Submission API of the Oracle Orchestration Cloud Service. A workflow submission payload consists of plan, steps, input, workers, credential reference, schedule and notification. Orchestration uses this definition of workflow to spawn one or more executions based on its schedule across multiple entities. These operations could be scheduled to run at the earliest time (or immediately), at a specified time, or at repeat specified intervals. The orchestration engine uses an appropriate scheduler to calculate the necessary expected execution time (cloud-based CRON).

  The workflow submission can be used to group and analyze multiple past executions and the executions scheduled in the future.

• Workflow Plan: A plan is a structured list of steps, where each step is a task that needs to be performed on an entity All workflows from single step to multistep have a plan section. Steps are a set of instructions within the plan that are executed by the workers.
• Workflow Step: The workflow step is the unit of activity that executes on the destination entity or web-service endpoint based on the step type. A step within a workflow has a name, type (REST, ENTITY, WAIT, WORKFLOW), input parameters, body, and authentication details. Steps are conformed by four parts PRE, OPERATION, POST and PUBLISH . When the step is executed, it generates a result that indicates its success or failure status along with output.
  • REST Step Type: This step type lets you call a RESTful web-service endpoint using Oracle Orchestration Cloud Service. You specify the URI, and request input and authorization details in the workflow definition. For instance, you might retrieve the list of objects or files from the Oracle Storage Service. For a REST-based step, the HTTP status code determines the result of the step, while the output is determined by the HTTP response body.
  • ENTITY Step Type: This step type lets you execute host-based operations within an Oracle Management Cloud-discovered entity using Oracle Management Cloud agent. For instance, execute a Chef recipe to update a server's configuration or patch Oracle database servers. The definition of the operation to be performed (program location, arguments, credentials, stdin, etcetera) would be under your control. You would specify the command and arguments used to spawn the process; the destination host where the process needs to be spawned; the host credentials that the process needs to execute as and also pass input via the process' standard input.  The host of the process that may be spawned could either be the host that monitors the entity or the host that the monitoring agent of the entity resides on. The entity step type allows certain contextual information of the entity to be passed on to the spawned process using the command, arguments or the standard input of the process. For an entity step, the output is the stdout of the spawned process on the host.
  • WAIT Step Type: This step type allows you to add an intended delay in the execution flow with the command waitInSeconds. A minimum wait time of 5 seconds and maximum wait time of 1800 seconds (or 30 minutes) can be entered. Decimal and partial seconds are not allowed, expressions must always be expressed in seconds and not minutes. WAIT step types have no output.
  • WORKFLOW Step Type: This step type allows you to execute nested workflows, or workflows within workflows in a Parent-child manner. The nested workflow to be called from the parent will be delineated within the WORKFLOW step type, and will require a name for the nested workflow, the name of the workflow in the workflow library and a version and inputs parameters to be sent to the child workflow.
• Workflow Worker: Workers define the level of parallelism for the entire workflow. Each workflow worker runs its own instance of the workflow in parallel. There is no "crosstalk" or synchronization of data between workflow worker instances. A workflow may instantiate one or more workflow workers. Consider an ENTITY use case where a set of steps needs to be executed across 10 different hosts. Similarly, consider a use case, where a REST call needs to be made to 10 different endpoints. For both cases, the same set of steps needs to be executed with different host names/port numbers. Each execution is a worker.
• Input Parameters:
  • String: Text based input, it is conformed by a set of characters like letters, numbers and spaces.
  • Boolean: Input based on only two values, true and false. Does not allow any other character.
  • Integer: Number based input, is comprised of whole (no decimal place) numbers.
  • Sensitive: Allows for sensitive information to be sent to either an agent (ENTITY) or thru a REST step type. Sensitive information should be encrypted using a symmetric key provided on the agent or target. Sensitive input parameters are only allowed in stdin and not allowed under arguments for security reasons.
• Oracle Management Cloud Agent:  A Cloud Agent collects metrics for targets and enables workflow entity steps to be executed on the target hosts.

Integration with Other Oracle Management Cloud Components

Oracle Orchestration is tightly integrated with Oracle Log Analytics. Orchestration workflow executions produce logs and these logs provide valuable information for understanding failures and forecasting execution times. Oracle Orchestration automatically retains workflow logs and generated output for seven days. For additional retention and analysis, logs can optionally be sent directly to Oracle Log Analytics where they’re automatically parsed and efficiently stored. You can view Oracle Orchestration workflow logs alongside other log sources to understand and correlate outside factors affecting performance parameters such as execution time and service failures.

Understanding Oracle Orchestration Roles and Privileges

Once you are an Oracle Cloud customer and you create an Oracle Management Cloud instance, the following user roles are provisioned:

• Oracle Management Cloud Administrator
• Oracle Management Cloud User

Table 1-1 Roles for Oracle Orchestration

Role	Tasks
Oracle Management Cloud Administrator	With this role you can perform the following tasks: Author, Publish and Manage Workflows in the Library Submit a Workflow View and Monitor Workflow Submissions and associated Workflow Executions, including output results.

For more information about the tasks that the users assigned with the above roles can perform, see Adding Users and Assigning Roles in Getting Started with Oracle Management Cloud.

Currently in Orchestration, no objects are shared across tenants. Workflow submissions cannot be seen by users on other tenants.

Configure Oracle Orchestration

To use Oracle Orchestration, you need to perform some initial setup.

Topics:

• Perform Pre-requisite Setup Tasks

• Set Up Credentials for Cloud-based Entities

Perform Pre-requisite Setup Tasks

To get started with Oracle Orchestration, you must enable the license editions and install the cloud agents. Cloud agents are installed on both physical and virtual hosts and are used to collect data and allow workflows to properly execute. To complete these tasks, you must have the Oracle Management Cloud Administrator role.

1. Install a gateway on a host in your data center (the host should have internet access to Oracle Management Cloud). This is an optional task.
   A gateway acts as a channel between Oracle Management Cloud and all other Oracle Management Cloud agents. See Install a Gateway in Installing and Managing Oracle Management Cloud Agents.
2. Install cloud agents on the hosts you want to monitor or perform administration tasks.
   Cloud agents collect availability, performance and configuration data from the entities that run on those hosts.
3. Add entities
   Add the entities that your cloud agent will monitor. Oracle Orchestration performs workflow tasks on entities discovered within your enterprise. See Adding Entities for Infrastructure Monitoring in Using Oracle Infrastructure Monitoring.
4. Assign licenses
   Orchestration is part of Oracle Management Cloud Enterprise Edition. Oracle Orchestration needs the Enterprise Edition enabled on entities (at least the host entity) to properly execute workflows. See Auto-Assign License Editions to All Entities in Getting Started with Oracle Management Cloud.

   Option 1: Enable license editions from the Oracle Management Cloud console. Assign the Enterprise Edition automatically to all your entities. See Auto-Assign License Editions to All Entities in Getting Started with Oracle Management Cloud.

   Option 2: If you do not enable auto-assignment of license editions, assign the Enterprise Edition license to selected entities. Assign this license to least to the host entity you will be running workflows on. See Assign License Editions to Selected Entities in Getting Started with Oracle Management Cloud.

Set Up Credentials for Cloud-based Entities

Oracle Orchestration allows for a large host of credentials to be setup. There are two entity types that you can define credentials for: Cloud-based entities and Agent-based entities.

Set Up Credentials for Cloud-based Entities:

• Oracle Management Cloud Credentials Store securely stores credentials for operations against cloud-based entities. These credentials require appropriate authorization tokens for the cloud-based endpoints to acknowledge the request and perform the operation appropriately. Each endpoint potentially may support different forms of authorization schemes and each authorization scheme would require different types of credentials for the authorization. To create and manage credentials in the OMC credentials store, navigate to the OMC Global Menu, select Administration, navigate to the Credential Store and click on New Credential.

Set up Credentials for Agent-based Entities:

• Entity-based workflows execute host-based scripts that may run shell scripts on the given host entity that may further call SQL*Plus on a database. These operations require you to provide the reference of entity HostSSHCreds credentials in the workflow definition so that Oracle Orchestration can perform required authentication on your behalf as the one who submitted the operation. HostSSHCreds credentials are highly sensitive and can’t be stored in Oracle Cloud, so maintenance of these credentials must be handled locally at each Cloud agent. A credential definition on the agent has a unique name and can be specified in the context of a single target as key/value pairs. The cloud agent can add, update, and remove a credential. The agent also can add an alias or remove an alias. To create and manage credentials in a cloud agent credential store, see Manage Agent Credentials in Installing and managing Oracle Management Cloud Agents