using oracle orchestration · 1 getting started with oracle orchestration oracle orchestration is a...

30
Oracle® Cloud Using Oracle Orchestration E78055-06 May 2018

Upload: phamhuong

Post on 28-Aug-2018

245 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Oracle® CloudUsing Oracle Orchestration

E78055-06May 2018

Page 2: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Oracle Cloud Using Oracle Orchestration,

E78055-06

Copyright © 2017, 2018, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are"commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of theprograms, including any operating system, integrated software, any programs installed on the hardware,and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron,the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced MicroDevices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services unless otherwiseset forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not beresponsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

Page 3: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Contents

1 Getting Started with Oracle Orchestration

About Oracle Orchestration 1-1

Understanding Oracle Orchestration Roles and Privileges 1-1

Configuring Oracle Orchestration 1-2

Setting Up Your Environment 1-2

Setting Up Authentication for Calling REST APIs 1-4

Setting Up Credentials 1-4

2 Before You Begin Using Oracle Orchestration

Target Audiences 2-1

Useful Concepts 2-2

Integration with Other Oracle Management Cloud Services 2-3

3 Authoring a Single-step Workflow

4 Submitting Workflows

Submitting REST-based Workflows 4-1

Submitting Entity-based Workflows (Optional) 4-1

5 Integrating with Log Analytics

6 Analyzing Workflow Submissions

7 Simplifying IT Management

Scheduling Jobs (Cloud CRON) 7-1

Performing Bulk Configuration Management 7-2

Automating Provisioning and Deployment 7-2

iii

Page 4: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Managing Incidents: Remediation or Preventative Actions Initiated by OracleManagement Cloud 7-3

REST API Use Cases 7-3

iv

Page 5: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Abstract

Documentation for Oracle Orchestration that describes how to use orchestrationworkflows to automate complex tasks and processes.

5

Page 6: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Preface

Oracle Orchestration automates tasks and processes within your enterprise.

Topics:

• Audience

• Related Resources

• Conventions

Using Oracle Orchestration describes how to use this service to automate businessprocesses and tasks.

AudienceUsing Oracle Orchestration is intended for administrators who want to automateprocesses and tasks across cloud and on-premises environments.

Related ResourcesFor more information about Oracle Management Cloud see:

• Oracle Cloud

ConventionsTable Text Conventions

Convention Meaning

boldface Boldface type indicates graphical user interfaceelements associated with an action, or terms defined intext or the glossary.

italic Italic type indicates the book titles, emphasis, orplaceholder variables for which you supply particularvalues.

monospace Monospace type indicates commands within aparagraph. URLs, code in examples, text that appearson the screen, or text that you enter.

Audience

6

Page 7: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

1Getting Started with Oracle Orchestration

Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you scheduleand track workflows that execute scripts on hosts or call Web service endpoints, allfrom a single location: You can schedule recurring maintenance tasks across your on-premises and cloud infrastructure environments.

Developers can use this cloud service to integrate a scheduler into their applications.For IT managers looking to start or migrate an existing DevOps project to the cloud,Oracle Orchestration provides a simple REST API that allows easy integration withexisting tools, and scripts to provision new environments and applications.

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

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

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

Understanding Oracle Orchestration Roles and PrivilegesOnce you are an Oracle Cloud customer and you create an Oracle ManagementCloud instance, the following user roles are provisioned:

• Oracle Management Cloud Administrator

• Oracle Management Cloud User

1-1

Page 8: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Table 1-1 Roles for Oracle Orchestration

Role Tasks

Oracle Management Cloud Administrator • View workflow submission, details, status, andresults.

• Create a workflow submission.• Stop, retry, and delete any workflow submission.

Oracle Management Cloud User View workflow submission, details, status, and results.

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

Sharing Workflow Submissions

You can see workflow submissions based on your tenant relationship:

• Users with the same tenant: Workflow submissions can be seen by all users whohave been granted the Oracle Management Cloud Administrator or the OracleManagement Cloud User role.

• All users across all tenants: No objects are shared across tenants. Workflowsubmissions can’t be seen by users on other tenants.

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

Topics:

• Setting Up Your Environment

• Setting Up Authentication for Calling REST APIs

• Setting Up Credentials

Setting Up Your EnvironmentThe first step in using Oracle Orchestration is to make sure your environment is set upto handle orchestration workflows.

Prerequisites:

• Obtain a trial or paid subscription to Oracle Orchestration. See ManageSubscriptions for more information.

• Make sure Oracle Management Cloud Agents have been deployed to managedhosts.

• Make sure you’ve added entities.

You set up your environment and create your first Oracle Orchestration using theREST API by performing the following tasks.

1. Obtain your account information.

Chapter 1Configuring Oracle Orchestration

1-2

Page 9: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

From your account administrator, obtain the appropriate account credentials toenable you to Oracle Orchestration. Specifically, you will need:

• Username

• Password

• Identity Domain Name

2. Install cURL

The REST API can be accessed from any application or programming platformthat correctly and completely understands the Hypertext Transfer Protocol (HTTP)and has Internet connectivity. The REST API uses advanced facets of HTTP suchas secure communication over HTTPS, HTTP headers, and specialized HTTPverbs (PUT, DELETE).Some applications that meet these requirements are:

• cURL - cURL is a command-line tool that you can use to invoke REST APIcalls by sending HTTP requests.

To use cURL, see http://curl.haxx.se and the tutorial, Installing cURL onCygwin on Windows.

• Web browsers - Support varies across vendors. Some browser plugins may beneeded for full support.

Many programming platforms (Java, Ruby, Perl, PHP, .NET, and so on) also meetthese requirements, although some may require the use of third party libraries forfull support. See your programming platform's documentation for guidance.

Using cURLSpecify one or more of the following command-line options, as required, to direct theexecution of cURL. The following table summarizes the cURL options used in thecommand examples in this document.

For more command line options refer to http://curl.haxx.se/docs/manpage.html.

cURL Option Description

-d, --data @file.json Identifies the request document, in JSONformat, on the local machine.

-F, --form @file.json Identifies form data, in JSON format, on thelocal machine.

-H, --header headerInfo Defines one or both of the following:• Content type of the request document (for

example, -H "Content-type:application/json" )

• Custom header, X-ID-TENANT-NAME or X-USER-IDENTITY-DOMAIN-NAME, to declarethe identity domain

-i, --include Include HTTP response header information inthe output. Useful for those commands that donot generate a JSON response.

-u, --user username:password Specifies the user name and password for theOracle Orchestration account.

-X, --request requestType Indicates the type of request (forexample, GET, POST, and so on). If nonespecified, then defaults to GET).

Chapter 1Configuring Oracle Orchestration

1-3

Page 10: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Setting Up Authentication for Calling REST APIsIn order to use the REST APIs, proper authentication is required.

Cloud Service API Authentication

Oracle Orchestration uses a certificate authority (CA) certificate, issued by Verisign, toenable clients to connect securely to the server.

Note:

Ensure that you have the appropriate administrator login credentials forcreating, managing, and deleting Oracle Orchestration instances.

You access Oracle Orchestration REST resources over HTTPS and must provide thefollowing information for authentication:

• A Secure Socket Layer (SSL) certificate authority (CA) certificate file or bundle toauthenticate against the Verisign CA certificate.

• User name and password for your Oracle Orchestration account.

For example, to authenticate using cURL:

• Set the cURL environment variable, CURL_CA_BUNDLE, to the location of your localCA certificate bundle. For information about CA certificate verification using cURL,see: http://curl.haxx.se/docs/sslcerts.html.

• Pass the user name and password for your Oracle Orchestration account.

Example cURL command:

curl -i -X GET -u <username>:<password> -H <request-header>:<value>https://<subdomain>.<domain>.com:<port>/<resource-path>

Setting Up CredentialsWhen you submit a workflow, Oracle Orchestration performs the workflow steps onyour behalf. You must specify the named credentials reference (or credential name)information as part of the workflow payload.

Oracle Orchestration uses the named credential to retrieve the credentials from theappropriate store to perform the authentication. The service requires the configurationof the named credentials based on the following step types:

• REST Credentials

• Entity Credentials

REST Credentials

Oracle Management Cloud Credentials Store Service provides a credentials storageservice on Oracle Cloud that lets you securely store your credentials for REST step-based operations. This service is backed by the Oracle Platform Security Services(OPSS) product deployed in Oracle Cloud to manage this store securely. BecauseREST-step implementation works on top of HTTP, the call needs to carry appropriate

Chapter 1Configuring Oracle Orchestration

1-4

Page 11: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

authorization tokens for the endpoint to acknowledge the request and perform theoperation appropriately. Each endpoint potentially may support different forms ofauthorization schemes and each authorization scheme would require different types ofcredentials for the authorization. This service supports the following authenticationschemes for V1:

• Basic HTTP

• Oracle Public Cloud

• Amazon Web Services (AWS)

Note:

Credentials are needed only for sites requiring authentication. The use ofcredentials is driven by the endpoint being accessed.

Entity Credentials

Entity-based steps execute host-based scripts that may run shell scripts on the givenhost entity that may further call SQL*Plus on a database. These operations requireyou to provide the reference of entity credentials in the workflow definition so thatOracle Orchestration can perform required authentication on your behalf as the onewho submitted the operation. Entity credentials are highly sensitive and can’t be storedin Oracle Cloud like REST step credentials, so maintenance of these credentials mustbe handled locally at each Cloud agent. A credential definition on the agent has aunique 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 analias or remove an alias.

Chapter 1Configuring Oracle Orchestration

1-5

Page 12: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

2Before You Begin Using OracleOrchestration

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

This chapter covers the following topics:

• Target Audiences

• Useful Concepts

• Integration with Other Oracle Management Cloud Services

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

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

DevOps

• Automate configuration tasks by running commands or scripts across distributedenvironments.

• 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 distributedenvironment.

• 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.

2-1

Page 13: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Useful ConceptsBefore using the Oracle Orchestration, you should be familiar with the followingconcepts:

• Orchestration: A set of activities performed on multiple entities or hosts toachieve a specific purpose. With Oracle Orchestration Cloud Service, theseactivities 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 systemor a set of systems. A workflow can be viewed as a fundamental building block fora business activity that can be automated by Oracle Orchestration Cloud Service.For example, creating an instance on Amazon Web Services (AWS) to spin anInfrastructure-as-a-Service (IaaS) instance is a workflow. A workflow is formattedin JSON and submitted via REST API.

• Workflow Execution: A workflow execution is a collection of multiple workersbased on the worker specification in the workflow submission. OracleOrchestration Cloud Service creates an instance of a workflow execution based onthe schedule specified in the workflow submission.

• Workflow Step: The workflow step is the unit of activity that executes on thedestination entity or web-service endpoint based on the step type. The definition ofa step in a workflow submission has a name, input parameters, body, andauthentication details. When the step is executed, it generates the result thatindicates its success or failure statuses along with output. For an entity step, theoutput is the stdout of the spawned process on the host. For a REST-based step,the HTTP status code determines the result of the step while output is determinedby the HTTP response body.

• Workflow Submission: The instance of a workflow that’s submitted using theSubmission API of the Oracle Orchestration Cloud Service. A workflow submissionpayload consists of plan, steps, step (single step), input, workers, credentialreference, schedule and notification. Orchestration uses this definition of workflowto 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 repeat at specified intervals. The orchestration engine usesan appropriate scheduler to calculate the necessary expected execution time(cloud-based CRON).

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

• Workflow Worker: Workflow workers define the level of parallelism for the entireworkflow. Each workflow worker runs its own instance of the workflow in parallel.There is no "crosstalk" or synchronization of data between workflow workerinstances. A workflow may instantiate one or more workflow workers.

• REST Step Type: This step type lets you call a RESTful web-service endpointusing Oracle Orchestration Cloud Service. You specify the URI, and request inputand authorization details in the workflow definition. For instance, you might retrievethe list of objects or files from the Oracle Storage Service.

• Entity Step Type: This step type lets you execute host-based operations in thecontext of an Oracle Management Cloud-discovered entity using the OracleManagement Cloud agent. For instance, execute a Chef recipe to update aserver's configuration. The definition of the operation to be performed (programlocation, arguments, credentials, stdin, and so on) would be under your control,

Chapter 2Useful Concepts

2-2

Page 14: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

that is, you would specify the command and arguments used to spawn theprocess, the destination host where the process needs to be spawned, the hostcredentials that the process needs to execute as and also pass in input via theprocess' standard input. The host of the process that may be spawned couldeither be the host that monitors the entity or the host that the monitoring agent ofthe entity resides on. The entity step type allows certain contextual information ofthe entity to be passed on to the spawned process using the command, argumentsor the standard input of the process.

• Oracle Management Cloud Agent: A Cloud Agent collects metrics for targetsand enables workflow entity steps to be executed on the target hosts.

Integration with Other Oracle Management Cloud ServicesOracle Orchestration is tightly integrated with Workflow Log Retention and Oracle LogAnalytics. Orchestration workflow executions produce logs and these logs providevaluable information for understanding failures and forecasting execution times. OracleOrchestration automatically retains workflow logs and generated output for sevendays. For additional retention and analysis, logs can optionally be sent directly toOracle Log Analytics where they’re automatically parsed and efficiently stored. Youcan view Oracle Orchestration workflow logs alongside other log sources tounderstand and correlate outside factors affecting performance parameters such asexecution time and service failures.

Chapter 2Integration with Other Oracle Management Cloud Services

2-3

Page 15: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

3Authoring a Single-step Workflow

As discussed earlier, a workflow is a fundamental building block for a business activitythat can be automated using Orchestration. You define a single-step workflowsubmission in JSON using the following elements and structural format.

name workflow plan name steps step step payload uploadToLA logSource input workflow workers (multiple workers are supported)workflowProperties property 1 property 2 ... property nschedulenotification

The following table explains the primary elements used to define a workflowsubmission JSON file.

Table 3-1 Workflow Elements

Element Description

Name A name given to the workflow submission. Thename is an identifier you can use to search fora workflow submission for status and results.

Note:

The workflowsubmissionname does nothave to beunique within agiven tenantscope.

3-1

Page 16: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Table 3-1 (Cont.) Workflow Elements

Element Description

Plan A list of steps where each step is a task thatneeds to be performed on an entity or a RESTcall.

Note:

For this release,you can onlyspecify one stepper workflow.

• Each step has a name, type (REST/ENTITY) and step-specific input.

• Step-specific input can reference thevariables declared in the input section ofthe workflow.

When defining a step, you can also specifythat workflow details be sent to Oracle LogAnalytics by setting the uploadToLA propertyto true. Additionally, you can have theuploaded logs associated with an existing logsource known to Log Analytics by setting thelogSource property.

Workflow Properties A map of key-value pairs that can beassociated with the workflow submission.These key-value pairs let you associatekeywords that will help in searching for theworkflow submission at some later point intime.

Note:

You can specifyup to five tagsusing the namesproperty1,property2,property3,property4, andproperty5.

Input The input for the workflow. Input may consistof multiple workers.

Chapter 3

3-2

Page 17: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Table 3-1 (Cont.) Workflow Elements

Element Description

Workers Workers define the level of parallelism for theentire workflow:

Consider a use case (ENTITY) where a set ofsteps needs to be executed across 10 differenthosts. Similarly, consider a use case (REST)where a REST call needs to be made to 10different endpoints. For both cases, the sameset of steps needs to be executed withdifferent hostnames/port numbers. Eachexecution is a worker.All steps specified in the plan (for the currentrelease, only one step is permitted) would beexecuted for each worker using the specifiedinput values.

Schedule The time when a workflow should beexecuted.

For example, say a workflow needs to beexecuted every day at 9:00 PM or everySaturday at 10:30 PM. For both cases,schedule information is passed in the workflowsubmission so that the workflow can beexecuted at the scheduled time.

Notification A list of email addresses that will receiveworkflow status updates.

Example Workflow Submission JSON Files

The following examples show how workflows can be used to automate common tasks.

Example 1: Invoking a Web Service to Obtain the Current Time

Note:

In order to submit this workflow successfully, you need to replacemylinuxhost and omc_host_linux with a valid entity name and type for yourenvironment..

{ "name":"My Current Time Workflow Submission", "workflow":{ "plan":{ "name":"PLAN_NAME", "steps":[ { "name":"step1", "type":"REST", "input": { "method":"GET" } } ]

Chapter 3

3-3

Page 18: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

}, "input": { "workers": { "thread1": { "uri": "https://script.google.com/macros/s/AKfycbyd5AcbAnWi2Yn0xhFRbyzS4qMq1VucMVgVvhul5XqS9HkAyJY/exec?tz=America/Los_Angeles", "entity": { "entityByName": { "name": "mylinuxhost", "type": "omc_host_linux" } } } } } }}

Example 2: Workflow Extracts AWS Plan Information

{ "name": "AWS S3 File content Workflow", "workflow": { "plan": { "name": "AWS S3 Get Plan", "steps": [ { "name": "AWS S3 Get Plan", "type": "REST", "input": { "method": "GET" "authScheme": "AWS", "credentialName": "MyAWSCred1" } "uploadToLA": true, "logSource" : <any existing log source> } ] }, "input": { "workers": { "worker1": { "uri": "https://mys3bucketname.s3.amazonaws.com/filename.txt" } } } }, "workflowProperties": { "property1": "value1", "property2": "value2" } }, "schedule": { "startTime" : "2016-02-15T07:00:00.0", "endTime" : "2018-07-31T08:00:00.0", "scheduleExpr" : "*/15 * * * *", "timezone" : "America/Los_Angeles" }, "notification": { "recipients": ["[email protected]", "[email protected]"]

Chapter 3

3-4

Page 19: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

}}

Example 3: Executing a Script on a Host

{ "name":"Install Patch 142536", "workflow":{ “plan":{ "name":"Install Patch", "steps":[ { "name":"RunInstall", "type":"ENTITY" } ] }, "input":{ “workers":{ “worker1":{ "entity":{ "entityByName": { "type": "omc_host_linux", "name": "mycompany.com" } }, "command":"/net/mycompany/scratch/scripts/patch.sh", "arguments" : ["142536"], "credential":"mycredential", "runOnAgent": "true" } } } }}

Example 4: Scheduling a Script (Cloud CRON)

{ "name":"Counter Example", "workflow":{ “plan":{ "name":"IncrementCounter", "steps":[ { "name":"RunCounterScript", "type":"ENTITY" } ] }, "input":{ “workers":{ “worker1":{ "entity":{ "entityByName": { "type": "omc_host_linux", "name": "mycompany.com" } }, "command":"/net/mycompany/scratch/scripts/counter.bsh",

Chapter 3

3-5

Page 20: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

"credential":"mycredential", "runOnAgent": "true" } } } }, "schedule":{ "scheduleExpr":"0 0/5 * 1/1 * ? *", "timezone":"America/Los_Angeles" }}

For more information on adding credentials, see the Orchestration REST API.

Note:

For this release, Oracle Orchestration REST API documentation access willbe limited to approved customers. Contact your Oracle Support or SalesRepresentative for more information about accessing and using the OracleOrchestration REST API. In addition, see the My Oracle Support noteOrchestration Cloud Service Master Note (Doc ID 2229523.1) for the latestinformation.

Chapter 3

3-6

Page 21: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

4Submitting Workflows

Note:

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

When you submit a workflow, one or more instances of that workflow are executedbased on the workflow schedule. Each execution runs the steps (workers) defined inthe workflow JSON file.

The service’s REST API lets you submit two types of workflows:

• Submitting REST-based Workflows

• Submitting Entity-based Workflows (Optional)

Submitting REST-based WorkflowsBefore submitting a REST-based workflow, the System Administrator first needs toensure that the credentials store is configured with appropriate named credentialsrequired for authenticating the REST API during invocation. Once configured, multipleOracle Cloud Orchestration Service users within same tenant can refer to the namedcredentials for submitting the REST-based workflows. The following proceduralexample is fully documented in the Oracle Orchestration REST API. For moreinformation about REST API availability, see the My Oracle Support note REST APIfor Oracle Management Cloud Orchestration Cloud Service (Doc ID 2243981.1).

1. List all current credentials data (returned as JSON).

2. Create a named credential (For example: Amazon Web Service).

3. Use POST workflows REST API to submit the workflow to Oracle Orchestration.

4. Use List Workflow Executions endpoint to retrieve list of executions for thesubmission.

5. Use the List Workflow Execution Workers API to retrieve the details for workers ofa specific executionID.

6. Use Get Results of the Step Execution API to retrieve the result of the REST step.

Submitting Entity-based Workflows (Optional)In addition to REST-based workflows, you can execute entity (host)-basedoperations in the context of an Oracle Management Cloud-discovered entity using theOracle Management Cloud agent. The entity-based workflow shown below is fully

4-1

Page 22: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

documented in the Oracle Orchestration REST API. For more information about RESTAPI availability, see the My Oracle Support note REST API for Oracle ManagementCloud Orchestration Cloud Service (Doc ID 2243981.1).

1. Log into the Cloud Agent to add entity credentials.

2. Use POST Workflows REST API to submit the workflow to Oracle Orchestration.

3. Retrieve the Executions List for the Workflow submission.

4. Use the List Workflow Execution Workers API to retrieve the details for workers ofa specific ExecutionID.

5. Use Get Results of a Step Execution API to retrieve the result of the REST step.The response of this command returns the output of the step as a string.

Chapter 4Submitting Entity-based Workflows (Optional)

4-2

Page 23: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

5Integrating with Log Analytics

Oracle Log Analytics lets you monitor, aggregate, index, analyze, search, explore, andcorrelate all log data from your applications and system infrastructure. OracleOrchestration can automatically upload workflow execution logs to Log Analytics forfurther analysis.

The workflow execution log upload option is specified when defining the workflowsubmission. You specify that Orchestration upload the logs using the followingproperties:

• uploadToLA: true/false. When set to true, specifies that the step execution outputwill be uploaded to Log Analytics

• logSource: Any existing log source with which the step execution output should beassociated with. This allows you to combine log output for more effective analysis.

As shown below, the uploadToLA and logSource properties are set within a workflowstep definition.

name workflow plan name steps step step payload uploadToLA logSource input workflow workers (multiple workers are supported)workflowProperties property 1 property 2 ... property nschedulenotification

The following example workflow submission illustrates how the uploadToLA property isset.

{ "name": "AWS S3 File content Workflow", "workflow": { "plan": { "name": "AWS S3 Get Plan", "steps": [ { "name": "AWS S3 Get Plan", "type": "REST", "input": { "method": "GET" "authScheme": "AWS", "credentialName": "MyAWSCred1"

5-1

Page 24: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

} "uploadToLA": true, "logSource" : <any existing log source> } ] }, "input": { "workers": { "worker1": { "uri": "https://mys3bucketname.s3.amazonaws.com/filename.txt" } } } }, "workflowProperties": { "property1": "value1", "property2": "value2" } }, "schedule": { "startTime" : "2016-02-15T07:00:00.0", "endTime" : "2018-07-31T08:00:00.0", "scheduleExpr" : "*/15 * * * *", "timezone" : "America/Los_Angeles" }, "notification": { "recipients": ["[email protected]", "[email protected]"] }}

Once the workflow has been submitted, its details can be viewed on the Log Analyticspage.

Orchestration Entities types and display options are available from the Log Analyticspalette and can be used to view pertinent details of the workflow.

Chapter 5

5-2

Page 25: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Chapter 5

5-3

Page 26: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

6Analyzing Workflow Submissions

Oracle Orchestration gives you an intuitive way to view and analyze both the currentand historic status of workflow submissions using the Orchestration Workflowsdashboard. The Orchestration Workflows dashboard provides an overview of allworkflow submissions and execution activity. Each widget and data grid providesvaluable information and insight into the status and health of your workflows.

The information displayed in a widget or data grid pertains to a specific date range,which lets you view workflow behavior more accurately. Each widget and data grid hasits own time selector.

The summary region provides a count of the total number of workflow executions aswell as a breakdown of the total by status (successful, failed or running).

Execution Details contains detailed information for Running, Completed andScheduled workflow executions.

• Running Executions displays the status and step details for workflow executionsthat are executing but not yet completed.

• Completed Executions displays detailed information about workflow executionsthat have completed all steps included in the overall elapsed time and step countby status.

• Scheduled Executions displays a list of scheduled workflow submissions includingtheir next scheduled execution time and the user who submitted the workflow

6-1

Page 27: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Sharing Dashboards with other Oracle Management Cloud Users

By default, after you’ve created and saved a custom Orchestration dashboard, onlyyou can see it. However, by changing the dashboard’s Share Settings property, youcan let other Oracle Management Cloud users view the dashboard as well.

Viewing Workflow Execution Details

You can drill down to view detailed information about a specific workflow execution byclicking on the workflow Execution ID link in the Orchestration Workflows dashboard.The following graphic shows the Workflow Execution Details page.

From this page, you can view the workflow’s execution summary. The executionsummary shows you information such as the name, status, submitted by, totalworkers, total steps, start & end time, and target entities. The execution is displayed ina tree view, which gives you an easy way to drill-down further into individual step-leveldetails such as the corresponding input, output and results. It also provides convenientaccess to the execution logs as well as a direct link to Oracle Log Analytics.

Chapter 6

6-2

Page 28: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

7Simplifying IT Management

Oracle Orchestration is much more than a simple way to automate IT administrativetasks. The service’s comprehensive orchestration capabilities let you to plan, organize,and automatically implement complex administrative and developmental workflowsthat are typically carried out in IT and development environments. The following usecases illustrate the flexibility of Oracle Orchestration and how it can save yousignificant time and effort.

• Scheduling Jobs (Cloud CRON)

• Performing Bulk Configuration Management

• Automating Provisioning and Deployment

• Managing Incidents: Remediation or Preventative Actions Initiated by OracleManagement Cloud

• REST API Use Cases

Scheduling Jobs (Cloud CRON)As a cloud-based system, Oracle Orchestration is easier to manage and provides amore secure replacement for a Linux CRON utility, or as a replacement for legacytools such as Control-M or HP Operations Orchestration. Oracle Orchestration givesyou a simple REST API interface to run both on-demand and scheduled operationstasks.

Oracle Orchestration's job scheduling capability lets you:

• Schedule and organize tasks that were previously triggered manually.

• Provide visibility into jobs that were previously run through CRON or other customtools.

• Replace expensive and hard to manage legacy job schedulers.

• Seamlessly execute jobs across both cloud and on-premises IT data centerassets.

• As part of Oracle Management Cloud, provide rich integration with Oracle LogAnalytics Cloud Service and Oracle IT Analytics Cloud Service.

Examples of Scheduled Jobs

• Operating System: Log rotation, backups

• Shut down development compute instances at night

• Database Automatic Workload Repository (AWR) Generation, Data GuardMonitor, Log File Manager, Gather Statistics

7-1

Page 29: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Performing Bulk Configuration ManagementUsing Oracle Orchestration as a central engine to orchestrate specialized scripts, youcan easily deploy or scale entire applications in the cloud with minimal effort. OracleOrchestration can seamlessly execute complex workflows across your on-premisesand cloud resources. For example, the service can run a command to list all runningAmazon Elastic Compute Cloud (EC2) instances under your Amazon Web Services(AWS) account and narrow it down by region or with a special tag like test. OracleOrchestration can then execute a command to shut down or terminate instances thathave the test tag defined.

Oracle Orchestration lets you:

• Execute workflow operations in bulk across multiple resources either on-demandor schedule.

• Configure and store your cloud credentials securely.

Example Bulk Configuration Management Jobs

• Cloud resources: Create new Oracle Compute Cloud Service, Oracle DatabaseCloud Service, Oracle Java Cloud Service resources.

• Component applications: Provision new instances of applications such as DB,Middleware, or Web servers.

• Provision entire application stacks: Seamlessly provision complete topologies.

Automating Provisioning and DeploymentYou can use Oracle Orchestration as a central engine to orchestrate specializedscripts to deploy or scale entire applications in the cloud. The service also can serveas the fabric to bind the scripts from disparate tools like Chef, Puppet, and so on. tobuild or update development and QA environments. For example, after building asoftware release, Oracle Orchestration can automatically deploy the latest build tomachines within your IT environment. Some service benefits are:

• Lets your organization move toward continuous delivery (CD) by having your buildor continuous integration (CI) server trigger an Oracle Orchestration workflow toexecute the post-build deployment process and deployment verification testing.

• Lets you reuse those same jobs to deploy your software across all environmentsautomatically (zero-click) or with a manual trigger (one-click).

• Oracle Orchestration exposes its complete functionality using the REST APIinterface, making it easy to integrate workflows with existing processes in yourorganization.

Example Provisioning and Deployment Jobs

• Cloud resources: Create new Oracle Compute Cloud Service, Oracle DatabaseCloud Service, Oracle Java Cloud Service resources.

• Component applications: Provision new instances of database, middleware, webservers, and so on.

• Provision entire application stacks: Wire all topologies together.

Chapter 7Performing Bulk Configuration Management

7-2

Page 30: Using Oracle Orchestration · 1 Getting Started with Oracle Orchestration Oracle Orchestration is a Software-as-a-Service (SaaS) solution that lets you schedule and track workflows

Managing Incidents: Remediation or Preventative ActionsInitiated by Oracle Management Cloud

Oracle Orchestration can execute immediate and automated actions as a result of anevent generated by another Oracle Management Cloud . Oracle Orchestration canalso pass and leverage event context to predetermined workflows to target specificissues, such as compliance violations.

Example Remediation/Preventative Action Jobs

• Automatically correct rule violations detected by Oracle Configuration andCompliance.

• Automatically scale applications based on performance issues detected by OracleApplication Performance Monitoring.

• Resize cloud resources based on capacity constraints detected by OracleInfrastructure Monitoring.

• Increase compliance assessment level based on suspicious activity detected inOracle Security Monitoring and Analytics.

• Generate alerts from a saved search (an error in a workflow log, for example) inOracle Log Analytics.

REST API Use CasesOracle Orchestration use cases have been tested and are fully documented in theREST API for Orchestration Cloud Service guide.

See the REST API for Oracle Orchestration guide for explicit instructions on how toperform the following:

• Running a Script On Multiple Hosts

• Debug Failed Threads of an Execution

• Running an Ad-hoc SQL Script On Multiple Databases

• Running a Create Instance on Oracle Cloud To Spin A JCS Instance

Note:

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

Chapter 7Managing Incidents: Remediation or Preventative Actions Initiated by Oracle Management Cloud

7-3