Skip to main content
ONTAP Automation

Prepare to use the workflows

Contributors dmp-netapp
PDFs

You should be familiar with the structure and format of the workflows before using them with a live ONTAP deployment.

Tip You should make sure that your ONTAP release supports all the API calls in the workflows you plan to use. See API reference for more information.

Introduction

A workflow is a sequence of one or more steps needed to accomplish a specific administrative task or goal. The ONTAP workflows include the core steps and parameters you need to accomplish each task. They provide a starting point for customizing your ONTAP automation environment.

Step types

Each step in an ONTAP workflow is one of the following types:

  • REST API call (with details such as curl and JSON examples)

  • Perform or invoke another ONTAP workflow

  • Miscellaneous related task (such as making a configuration decision)

REST API calls

Most of the workflow steps are REST API calls. These steps use a common format which includes a curl example and other information. See the API reference for more details about the REST API calls.

Single-step workflows

A workflow can contain only one step. These single-step workflows are formatted slightly differently than workflows containing multiple steps. For example, the explicit step name is removed. The action or operation should be clear based on the workflow title.

Input variables

The workflows are designed to be as general as possible so they can be used in any ONTAP environment. With this in mind, the REST API calls use variables in the curl examples and other input. The REST API calls can then be easily adapted to different ONTAP environments.

Base URL format

You can access the ONTAP REST API directly through curl or a programming language. In this case, the base URL is different than the URL you use when accessing the ONTAP online documentation or System Manager.

When accessing the API directly, you need to append api to the domain or IP address. For example:

https://ontap.demo-example.com/api

See How to access the ONTAP REST API for more information.

Common input parameters

There are several input parameters commonly used with most of the REST API calls. These parameters are typically not described in the individual workflows. You should be familiar with the parameters. See Input variables controlling an API request for more information.

If additional parameters are needed for a specific REST API call, they are included in the section Additional input parameters for the curl example for each workflow.

Variable format

The ID values and other variables used with the workflow examples are opaque and can vary with each ONTAP cluster. To improve the readability of the examples, actual values are not used. Variables are used instead. This approach, based on a consistent format and set of reserved names, has several benefits including:

  • The curl and JSON samples are more readable and easier to understand.

  • Because all the keywords use the same format, you can quickly identify them.

  • There is no security exposure because the values cannot be copied and reused.

The variables are formatted to be used in a Bash shell environment. Each variable begins with a dollar sign and is enclosed in double quotes as needed. This makes them recognizable to Bash. Upper case is consistently used for the names.

Here are some of the common variable keywords. This list is not exhaustive and additional variables are used as needed. Their meaning should be obvious based on the context.

Keyword Type Description

$FQDN_IP

URL

The fully qualified domain name or IP address of the ONTAP management LIF.

$CLUSTER_ID

Path

The UUIDv4 value identifying the ONTAP cluster where the API operations run.

$BASIC_AUTH

Header

The credentials string used for HTTP basic authentication.

JSON input examples

Some of the REST API calls, such as those using POST or PATCH, require JSON input in the body of the request. The JSON input examples are presented separately from the curl examples for clarity. You can use the JSON input examples with one of the techniques described below.

Save to local file

You can copy the JSON input example to a file and save it locally. The curl command refers to the file using the --data parameter with the value indicating the file name with a @ prefix.

Paste into terminal after the curl example

First you need to copy and paste the curl example into a terminal shell. Then edit the example to completely remove the --data parameter at the end and replace it with the --data-raw parameter. Finally, copy and paste in the JSON example so that it follows the curl command with the updated parameter. You should use single quotes to wrap the JSON input example.

Authentication options

The primary authentication technique available for the REST API is HTTP basic authentication. Beginning with ONTAP 9.14, you also have the option of using the Open Authorization (OAuth 2.0) framework with token-based authentication and authorization.

HTTP basic authentication

When using basic authentication, the user credentials must be included with each HTTP request. There are two options for sending the credentials.

Construct the HTTP request header

You can manually construct the Authorization header and include it with the HTTP requests. This can be done when using a curl command in the CLI or a programming language with your automation code. The high-level steps include:

  1. Concatenate the user and password values with a colon:

    admin:david123

  2. Convert the entire string to base64:

    YWRtaW46ZGF2aWQxMjM=

  3. Construct the request header:

    Authorization: Basic YWRtaW46ZGF2aWQxMjM=

The workflow curl examples include this header with the variable $BASIC_AUTH which you need to update before using.

Use a curl parameter

Another option when using curl is to remove the Authorization header and use the curl user parameter instead. For example:

--user username:password

You need to substitute the appropriate credentials for your environment. The credentials are not encoded in base64. When executing the curl command with this parameter, the string is encoded and the Authorization header is generated for you.

OAuth 2.0

When using OAuth 2.0, you need to request an access token from an external authorization server and include it with each HTTP request. The basic high-level steps are described below. Also see Overview of the ONTAP OAuth 2.0 implementation for more details about OAuth 2.0 and how to use it with ONTAP.

Prepare your ONTAP environment

Before using the REST API to access ONTAP, you need to prepare and configure the ONTAP environment. At a high level, the steps include:

  • Identify the ONTAP protected resources and clients

  • Review the existing ONTAP REST role and user definitions

  • Install and configure the authorization server

  • Design and configure the client authorization definitions

  • Configure ONTAP and enable OAuth 2.0

Request an access token

With ONTAP and the authorization server defined and active, you can make a REST API call using an OAuth 2.0 token. The first step is to request an access token from the authorization server. This is done outside of ONTAP using one of several different techniques based on the server. ONTAP does not issue access tokens or perform redirection.

Construct the HTTP request header

After obtaining an access token, you can construct an Authorization header and include it with the HTTP requests. Regardless of whether you use curl or a programming language to access the REST API, you must include the header with every client request. You can construct the header as follows:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSld …​

Using the examples with Bash

If you use the workflow curl examples directly, you must update the variables they contain with values appropriate for your environment. You can manually edit the examples or rely on the Bash shell to do the substitution for you as described below.

Note One advantage of using Bash is that you can set the variable values one time in a shell session instead of once per curl command.
Steps

  1. Open the Bash shell provided with Linux or similar operating system.

  2. Set the variable values included in the curl example you want to run. For example:

    CLUSTER_ID=ce559b75-4145-11ee-b51a-005056aee9fb

  3. Copy the curl example from the workflow page and paste it into the shell terminal.

  4. Press ENTER which will do the following:

    1. Substitute the variable values you set

    2. Execute the curl command