Skip to main content

Create an application

Contributors
PDFs

POST /application/applications

Introduced In: 9.6

Creates an application.

Template properties

The application APIs appear to be complex and long in this documentation because we document every possible template, of which there are currently 14. When creating an application, only a single template is used, so it is best to focus only on the template of interest. Other than the properties for the chosen template, only the name and svm of the application must be provided. The following three sections provided guidelines on using the properties of the templates, but the whole idea behind the templates is to automatically follow the best practices of the given application, so the only way to determine the exact list of required properties and default values is to dig in to the model section of the template. The templates are all top level properties of the application object with names matching the values returned by GET /application/templates .

Required properties

  • svm.uuid or svm.name - The existing SVM in which to create the application.

  • name - The name for the application.

  • <template> - Properties for one template must be provided. In general, the following properties are required, however the naming of these may vary slightly from template to template.

    • <template>.name - The generic templates require names for the components of the application. Other templates name the components automatically.

    • <template>.application_component.size - This generally refers to the size of an application component, which may be spread across multiple underlying storage objects (volumes, LUNs, etc…​).

    • One of the following must be specified:

  • nas.nfs_access or an identifier (name or id) of an existing export-policy.

  • nas.cifs_access

  • san.application_application.igroup_name

    • To specify that a NAS application is not to be exposed via NFS nor CIFS:

  • nas.application_component.export_policy.name is 'none', and

  • nas.application.cifs_share_name is 'none'.

    • The name of the CIFS share can be provided through the nas.application.cifs_share_name attribute. If not provided, the CIFS share name will be the same as the nas.application_component.name attribute, including any suffix applied due to creating multiple application components in one post.

    • san.os_type - All SAN applications require an os_type to be specified in some way. Some templates refer to this as the hypervisor.

  • <template> - The following properties are available in some templates.

    • san.new_igroups.* - SAN applications can use existing initiator groups or create new ones. When creating new initiator groups, new_igroups.name is required and the other properties may be used to fully specify the new initiator group.

Default property values

If not specified in POST, the follow default property values are assigned. It is recommended that most of these properties be provided explicitly rather than relying upon the defaults. The defaults are intended to make it as easy as possible to provision and connect to an application.

  • template.name - Defaults to match the <template> provided. If specified, the value of this property must match the provided template properties.

  • <template> - The majority of template properties have default values. The defaults may vary from template to template. See the model of each template for complete details. In general the following patterns are common across all template properties. The location of these properties varies from template to template.

    • <template>.storage_service.name - value

    • <template>.protection_type.local_rpo - hourly (Hourly Snapshot copies)

    • <template>.protection_type.remote_rpo - none (Not MetroCluster)

    • san.new_igroups.os_type - Defaults to match the os_type provided for the application, but may need to be provided explicitly when using virtualization.

Optional components

A common pattern across many templates are objects that are optional, but once any property in the object is specified, other properties within the object become required. Many applications have optional components. For example, provisioning a database without a component to store the logs is supported. If the properties related to the logs are omitted, no storage will be provisioned for logs. But when the additional component is desired, the size is required. Specifying any other property of a component without specifying the size is not supported. In the model of each template, the required components are indicated with a red '*'. When a size property is listed as optional, that means the component itself is optional, and the size should be specified to include that component in the application.

POST body examples

  1. Create a generic SAN application that exposes four LUNs to an existing initiator group, igroup_1.

  {
    "name": "app1",
    "svm": { "name": "svm1" },
    "san": {
      "os_type": "linux",
      "application_components": [
        { "name": "component1", "total_size": "10GB", "lun_count": 4, "igroup_name": "igroup_1" }
      ]
    }
  }

  1. Create an SQL application that can be accessed via initiator iqn.2017-01.com.example:foo from a new initiator group, igroup_2.

  {
    "name": "app2",
    "svm": { "name": "svm1" },
    "sql_on_san": {
      "db": { "size": "5GB" },
      "log": { "size": "1GB" },
      "temp_db": { "size": "2GB" },
      "igroup_name": "igroup_2",
      "new_igroups": [
        { "name": "igroup_2", "initiators": [ "iqn.2017-01.com.example:foo" ] }
      ]
    }
  }

  1. The following body creates the exact same SQL application, but manually provides all the defaults that were excluded from the previous call.

Note The model of a sql_on_san application documents all these default values. 
  {
    "name": "app3",
    "svm": { "name": "svm1" },
    "template": { "name": "sql_on_san" },
    "sql_on_san": {
      "os_type": "windows_2008",
      "server_cores_count": 8,
      "db": { "size": "5GB", "storage_service": { "name": "value" } },
      "log": { "size": "1GB", "storage_service": { "name": "value" } },
      "temp_db": { "size": "2GB", "storage_service": { "name": "value" } },
      "igroup_name": "igroup_2",
      "new_igroups": [
        {
          "name": "igroup_2",
          "protocol": "mixed",
          "os_type": "windows",
          "initiators": [ "iqn.a.new.initiator" ]
        }
      ],
      "protection_type": { "local_rpo": "none" }
    }
  }

Learn more

Parameters

Name Type In Required Description

return_timeout

integer

query

False

The number of seconds to allow the call to execute before returning. When doing a POST, PATCH, or DELETE operation on a single record, the default is 0 seconds. This means that if an asynchronous operation is started, the server immediately returns HTTP code 202 (Accepted) along with a link to the job. If a non-zero value is specified for POST, PATCH, or DELETE operations, ONTAP waits that length of time to see if the job completes so it can return something other than 202.

  • Default value: 1

  • Max value: 120

  • Min value: 0

return_records

boolean

query

False

The default is false. If set to true, the records are returned.

  • Default value:

Request Body

Name Type Description

_links

_links

creation_timestamp

string

The time when the application was created.

delete_data

boolean

Should application storage elements be deleted? An application is considered to use storage elements from a shared storage pool. Possible values are 'true' and 'false'. If the value is 'true', the application will be deleted in its entirety. If the value is 'false', the storage elements will be disassociated from the application and preserved. The application will then be deleted.

generation

integer

The generation number of the application. This indicates which features are supported on the application. For example, generation 1 applications do not support Snapshot copies. Support for Snapshot copies was added at generation 2. Any future generation numbers and their feature set will be documented.

mongo_db_on_san

mongo_db_on_san

MongoDB using SAN.

name

string

Application Name. This field is user supplied when the application is created.

nas

nas

A generic NAS application.

nvme

zapp_nvme

An NVME application.

oracle_on_nfs

oracle_on_nfs

Oracle using NFS.

oracle_on_san

oracle_on_san

Oracle using SAN.

oracle_rac_on_nfs

oracle_rac_on_nfs

Oracle RAC using NFS.

oracle_rac_on_san

oracle_rac_on_san

Oracle RAC using SAN.

protection_granularity

string

Protection granularity determines the scope of Snapshot copy operations for the application. Possible values are "application" and "component". If the value is "application", Snapshot copy operations are performed on the entire application. If the value is "component", Snapshot copy operations are performed separately on the application components.

rpo

rpo

s3_bucket

zapp_s3_bucket

A generic S3 bucket application.

san

san

A generic SAN application.

smart_container

boolean

Identifies if this is a smart container or not.

sql_on_san

sql_on_san

Microsoft SQL using SAN.

sql_on_smb

sql_on_smb

Microsoft SQL using SMB.

state

string

The state of the application. For full functionality, applications must be in the online state. Other states indicate that the application is in a transient state and not all operations are supported.

statistics

statistics

svm

svm

template

template

uuid

string

Application UUID. This field is generated when the application is created.

vdi_on_nas

vdi_on_nas

A VDI application using NAS.

vdi_on_san

vdi_on_san

A VDI application using SAN.

vsi_on_nas

vsi_on_nas

A VSI application using NAS.

vsi_on_san

vsi_on_san

A VSI application using SAN.
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    },
    "snapshots": {
      "href": "/api/resourcelink"
    }
  },
  "creation_timestamp": "string",
  "generation": 0,
  "name": "string",
  "nas": {
    "application_components": [
      {
      }
    ],
    "cifs_access": [
      {
        "access": "string",
        "user_or_group": "string"
      }
    ],
    "cifs_share_name": "string",
    "exclude_aggregates": [
      {
        "name": "string",
        "uuid": "string"
      }
    ],
    "nfs_access": [
      {
        "access": "string",
        "host": "string"
      }
    ],
    "protection_type": {
      "local_policy": "string",
      "local_rpo": "string",
      "remote_rpo": "string"
    }
  },
  "nvme": {
    "components": [
      {
        "name": "string",
        "os_type": "string",
        "performance": {
          "storage_service": {
            "name": "string"
          }
        },
        "qos": {
          "policy": {
            "name": "string",
            "uuid": "string"
          }
        },
        "subsystem": {
          "hosts": [
            {
              "dh_hmac_chap": {
                "controller_secret_key": "string",
                "group_size": "string",
                "hash_function": "string",
                "host_secret_key": "string"
              },
              "nqn": "string",
              "priority": "string"
            }
          ],
          "name": "string",
          "os_type": "string",
          "uuid": "string"
        },
        "tiering": {
          "control": "string",
          "object_stores": [
            {
              "name": "string"
            }
          ],
          "policy": "string"
        }
      }
    ],
    "os_type": "string",
    "rpo": {
      "local": {
        "name": "string",
        "policy": "string"
      },
      "remote": {
        "name": "string"
      }
    }
  },
  "protection_granularity": "string",
  "rpo": {
    "components": [
      {
        "name": "string",
        "rpo": {
          "local": {
            "description": "string",
            "name": "string"
          },
          "remote": {
            "description": "string",
            "name": "string"
          }
        },
        "uuid": "string"
      }
    ],
    "local": {
      "description": "string",
      "name": "string"
    },
    "remote": {
      "description": "string",
      "name": "string"
    }
  },
  "s3_bucket": {
    "application_components": [
      {
        "access_policies": [
          {
            "actions": [
              "string"
            ],
            "conditions": [
              {
                "delimiters": [
                  "string"
                ],
                "max_keys": [
                  "integer"
                ],
                "operator": "string",
                "prefixes": [
                  "string"
                ],
                "source_ips": [
                  "string"
                ],
                "usernames": [
                  "string"
                ]
              }
            ],
            "effect": "string",
            "principals": [
              "string"
            ],
            "resources": [
              "string"
            ],
            "sid": "string"
          }
        ],
        "bucket_endpoint_type": "string",
        "comment": "string",
        "default_retention_period": "string",
        "exclude_aggregates": [
          {
            "name": "string",
            "uuid": "string"
          }
        ],
        "name": "string",
        "nas_path": "string",
        "qos": {
          "policy": {
            "name": "string",
            "uuid": "string"
          }
        },
        "retention_mode": "string",
        "storage_service": {
          "name": "string"
        },
        "uuid": "string",
        "versioning_state": "string"
      }
    ],
    "protection_type": {
      "remote_rpo": "string"
    }
  },
  "san": {
    "application_components": [
      {
        "igroup_name": "string",
        "name": "string",
        "os_type": "string",
        "qos": {
          "policy": {
            "name": "string",
            "uuid": "string"
          }
        },
        "storage_service": {
          "name": "string"
        },
        "tiering": {
          "control": "string",
          "object_stores": [
            {
              "name": "string"
            }
          ],
          "policy": "string"
        }
      }
    ],
    "exclude_aggregates": [
      {
        "name": "string",
        "uuid": "string"
      }
    ],
    "new_igroups": [
      {
        "comment": "string",
        "igroups": [
          {
            "name": "string",
            "uuid": "string"
          }
        ],
        "initiator_objects": [
          {
            "comment": "string",
            "name": "string"
          }
        ],
        "initiators": [
          "string"
        ],
        "name": "string",
        "os_type": "string",
        "protocol": "string"
      }
    ],
    "os_type": "string",
    "protection_type": {
      "local_policy": "string",
      "local_rpo": "string",
      "remote_rpo": "string"
    }
  },
  "state": "string",
  "statistics": {
    "components": [
      {
        "iops": {
          "per_tb": 0,
          "total": 0
        },
        "latency": {
          "average": 0,
          "raw": 0
        },
        "name": "string",
        "snapshot": {
          "reserve": 0,
          "used": 0
        },
        "space": {
          "available": 0,
          "logical_used": 0,
          "provisioned": 0,
          "reserved_unused": 0,
          "savings": 0,
          "used": 0,
          "used_excluding_reserves": 0,
          "used_percent": 0
        },
        "storage_service": {
          "name": "string",
          "uuid": "string"
        },
        "uuid": "string"
      }
    ],
    "iops": {
      "per_tb": 0,
      "total": 0
    },
    "latency": {
      "average": 0,
      "raw": 0
    },
    "snapshot": {
      "reserve": 0,
      "used": 0
    },
    "space": {
      "available": 0,
      "logical_used": 0,
      "provisioned": 0,
      "reserved_unused": 0,
      "savings": 0,
      "used": 0,
      "used_excluding_reserves": 0,
      "used_percent": 0
    }
  },
  "svm": {
    "name": "string",
    "uuid": "string"
  },
  "template": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "string",
    "protocol": "string",
    "version": 0
  },
  "uuid": "string"
}

Response

Status: 202, Accepted
Name Type Description

job

job_link
Example response 
{
  "job": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "uuid": "string"
  }
}

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Response

Status: 201, Created

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

65995775

The size provided is too small.

65995776

The size provided is too large.

Also see the table of common errors in the Response body overview section of this documentation.

Name Type Description

error

returned_error
Example error 
{
  "error": {
    "arguments": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

self

href

snapshots

href

storage_service

Name Type Description

name

string

The storage service of the database.

dataset

Name Type Description

element_count

integer

The number of storage elements (LUNs for SAN) of the database to maintain. Must be an even number between 2 and 16. Odd numbers will be rounded up to the next even number within range.

replication_factor

integer

The number of data bearing members of the replicaset, including 1 primary and at least 1 secondary.

size

integer

The size of the database. Usage: {<integer>[KB|MB|GB|TB|PB]}

storage_service

storage_service