Create an AKV configuration for all clusters and SVMs
Configures the AKV settings for all clusters and SVMs to manage encryption keys with Azure Key Vault. Use this endpoint when setting up or updating the key management configuration for secure storage operations.
HTTP method and endpoint
POST /security/azure-key-vaults
Introduced in
ONTAP 9.8
Usage notes
Configures the AKV configuration for all clusters and SVMs.
Required properties:
-
svm.uuidorsvm.name- Existing SVM in which to create a AKV. -
client_id- Application (client) ID of the deployed Azure application with appropriate access to an AKV. -
tenant_id- Directory (tenant) ID of the deployed Azure application with appropriate access to an AKV. -
client_secretorclient_certificate- Secret or PKCS12 Certificate used by the application to prove its identity to AKV. -
key_id- Key Identifier of AKV encryption key. -
name- Name of the deployed AKV used by ONTAP for storing keys.
Optional properties:
-
port- Authorization server and vault port number. -
oauth_host- Open authorization server host name. -
vault_host- AKV host subdomain. -
proxy_type- Type of proxy (http, https etc.) if proxy configuration is used. -
proxy_host- Proxy hostname if proxy configuration is used. -
proxy_port- Proxy port number if proxy configuration is used. -
proxy_username- Proxy username if proxy configuration is used. -
proxy_password- Proxy password if proxy configuration is used. -
configuration.name- The configuration name to use when also setting thecreate_inactiveflag.
Optional parameters:
-
create_inactive- Create an AKV configuration without enabling it. This flag is set to "false" by default.
Related ONTAP commands
-
security key-manager external azure enable (DEPRECATED) -
security key-manager keystore enable -
security key-manager external azure create-config -
security key-manager external azure update-config
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
create_inactive |
boolean |
query |
False |
Indicates whether to create an active or inactive configuration.
|
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.
|
return_records |
boolean |
query |
False |
The default is false. If set to true, the records are returned.
|
Request Body
| Name | Type | Description |
|---|---|---|
_links |
||
authentication_method |
string |
Authentication method for the AKV instance. |
azure_reachability |
Indicates whether or not the AKV service is reachable from all the nodes in the cluster.
This is an advanced property; there is an added computational cost to retrieving its value. The property is not populated for either a collection GET or an instance GET unless it is explicitly requested using the |
|
client_certificate |
string |
PKCS12 Certificate used by the application to prove its identity to AKV. |
client_id |
string |
Application client ID of the deployed Azure application with appropriate access to an AKV. |
client_secret |
string |
Secret used by the application to prove its identity to AKV. |
configuration |
Security keystore object reference. |
|
ekmip_reachability |
array[ekmip_reachability] |
|
enabled |
boolean |
Indicates whether the configuration is enabled. |
key_id |
string |
Key Identifier of AKV key encryption key. |
name |
string |
Name of the deployed AKV that will be used by ONTAP for storing keys.
|
oauth_host |
string |
Open authorization server host name. |
port |
integer |
Authorization server and vault port number. |
proxy_host |
string |
Proxy host. |
proxy_password |
string |
Proxy password. Password is not audited. |
proxy_port |
integer |
Proxy port. |
proxy_type |
string |
Type of proxy. |
proxy_username |
string |
Proxy username. |
scope |
string |
Set to "svm" for interfaces owned by an SVM. Otherwise, set to "cluster". |
skip_verification |
boolean |
Set to true to skip the verification of the updated user credentials when updating credentials. The default value is false. |
state |
Indicates whether or not the AKV wrapped internal key is available cluster wide.
This is an advanced property; there is an added computational cost to retrieving its value. The property is not populated for either a collection GET or an instance GET unless it is explicitly requested using the |
|
svm |
SVM, applies only to SVM-scoped objects. |
|
tenant_id |
string |
Directory (tenant) ID of the deployed Azure application with appropriate access to an AKV. |
uuid |
string |
A unique identifier for the Azure Key Vault (AKV). |
vault_host |
string |
AKV host subdomain. |
Example request
{
"authentication_method": "client_secret",
"azure_reachability": {
"code": "346758",
"message": "AKV service is not reachable from all nodes - reason."
},
"client_certificate": "<CERTIFICATE-CONTENT>",
"client_id": "aaaaaaaa-bbbb-aaaa-bbbb-aaaaaaaaaaaa",
"client_secret": "abcdef",
"configuration": {
"name": "default",
"uuid": "1cd8a442-86d1-11e0-ae1c-123478563434"
},
"ekmip_reachability": [
{
"code": "346758",
"message": "embedded KMIP server status unavailable on node.",
"node": {
"name": "node1",
"uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
}
}
],
"key_id": "https://keyvault1.vault.azure.net/keys/key1/12345678901234567890123456789012",
"name": "https://kmip-akv-keyvault.vault.azure.net/",
"oauth_host": "login.microsoftonline.com",
"port": 443,
"proxy_host": "proxy.eng.com",
"proxy_password": "proxypassword",
"proxy_port": 1234,
"proxy_type": "http",
"proxy_username": "proxyuser",
"scope": "string",
"skip_verification": "",
"state": {
"code": "346758",
"message": "Top-level internal key protection key (KEK) is unavailable on the following nodes with the associated reasons: Node: node1. Reason: No volumes created yet for the SVM. Wrapped KEK status will be available after creating encrypted volumes."
},
"svm": {
"name": "svm1",
"uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
},
"tenant_id": "zzzzzzzz-yyyy-zzzz-yyyy-zzzzzzzzzzzz",
"uuid": "1cd8a442-86d1-11e0-ae1c-123478563412",
"vault_host": "vault.azure.net",
"verify_host": "",
"verify_ip": ""
}
Response
Status: 202, Accepted
| Name | Type | Description |
|---|---|---|
job |
Example response
{
"job": {
"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 |
|---|---|
3735553 |
Failed to create self-signed certificate. |
3735664 |
The specified key size is not supported in FIPS mode. |
3735665 |
The specified hash function is not supported in FIPS mode. |
3735700 |
The specified key size is not supported. |
52559972 |
The certificates start date is later than the current date. |
65537500 |
A key manager has already been configured for this SVM. |
65537504 |
Internal error. Failed to store configuration in internal database. |
65537506 |
AKV is not supported in MetroCluster configurations. |
65537514 |
Failed to check if the Azure Key Vault feature is enabled. |
65537518 |
Failed to find an interface with Cluster role. |
65537523 |
Invalid key ID format. Example key ID format":" "https://mykeyvault.vault.azure.net/keys/key1/a8e619fd8f234db3b0b95c59540e2a74". |
65537526 |
Failed to enable Azure Key Vault feature. |
65537553 |
Invalid vault name format. Example vault name format":" "https://mykeyvault.vault.azure.net". |
65537567 |
No authentication method provided. |
65537573 |
Invalid client certificate. |
65537589 |
The specified configuration.name already exists on the given SVM. |
65537594 |
The configuration.name field is required when the create_inactive flag is set to true. |
65537595 |
The configuration.name field can only be specified when the create_inactive flag is set to true. |
65538902 |
The configuration.name is reserved for use by the system. |
65538903 |
The configuration.name field cannot be an empty string. |
65539704 |
The key manager cannot be configured because the SVM has NAE volumes. |
Also see the table of common errors in the Response body overview section of this documentation.
Definitions
See Definitions
href
| Name | Type | Description |
|---|---|---|
href |
string |
_links
azure_reachability
Indicates whether or not the AKV service is reachable from all the nodes in the cluster.
This is an advanced property; there is an added computational cost to retrieving its value. The property is not populated for either a collection GET or an instance GET unless it is explicitly requested using the fields query parameter or GET for all advanced properties is enabled.
| Name | Type | Description |
|---|---|---|
code |
string |
Code corresponding to the status message. Returns a 0 if AKV service is reachable from all nodes in the cluster. |
message |
string |
Error message set when reachability is false. |
reachable |
boolean |
Set to true when the AKV service is reachable from all nodes of the cluster. |
configuration
Security keystore object reference.
| Name | Type | Description |
|---|---|---|
name |
string |
Name of the configuration. |
uuid |
string |
Keystore UUID. |
node
| Name | Type | Description |
|---|---|---|
name |
string |
|
uuid |
string |
ekmip_reachability
Provides the connectivity status for the given SVM on the given node to all EKMIP servers configured on all nodes of the cluster.
This is an advanced property; there is an added computational cost to retrieving its value. The property is not populated for either a collection GET or an instance GET unless it is explicitly requested using the fields query parameter or GET for all advanced properties is enabled.
| Name | Type | Description |
|---|---|---|
code |
string |
Code corresponding to the error message. Returns a 0 if a given SVM is able to communicate to the EKMIP servers of all of the nodes in the cluster. |
message |
string |
Error message set when cluster-wide EKMIP server availability from the given SVM and node is false. |
node |
||
reachable |
boolean |
Set to true if the given SVM on the given node is able to communicate to all EKMIP servers configured on all nodes in the cluster. |
state
Indicates whether or not the AKV wrapped internal key is available cluster wide.
This is an advanced property; there is an added computational cost to retrieving its value. The property is not populated for either a collection GET or an instance GET unless it is explicitly requested using the fields query parameter or GET for all advanced properties is enabled.
| Name | Type | Description |
|---|---|---|
available |
boolean |
Set to true when an AKV wrapped internal key is present on all nodes of the cluster. |
code |
string |
Code corresponding to the status message. Returns a 0 if AKV wrapped key is available on all nodes in the cluster. |
message |
string |
Error message set when top-level internal key protection key (KEK) availability on cluster is false. |
svm
SVM, applies only to SVM-scoped objects.
| Name | Type | Description |
|---|---|---|
name |
string |
The name of the SVM. This field cannot be specified in a PATCH method. |
uuid |
string |
The unique identifier of the SVM. This field cannot be specified in a PATCH method. |
azure_key_vault
| Name | Type | Description |
|---|---|---|
_links |
||
authentication_method |
string |
Authentication method for the AKV instance. |
azure_reachability |
Indicates whether or not the AKV service is reachable from all the nodes in the cluster.
This is an advanced property; there is an added computational cost to retrieving its value. The property is not populated for either a collection GET or an instance GET unless it is explicitly requested using the |
|
client_certificate |
string |
PKCS12 Certificate used by the application to prove its identity to AKV. |
client_id |
string |
Application client ID of the deployed Azure application with appropriate access to an AKV. |
client_secret |
string |
Secret used by the application to prove its identity to AKV. |
configuration |
Security keystore object reference. |
|
ekmip_reachability |
array[ekmip_reachability] |
|
enabled |
boolean |
Indicates whether the configuration is enabled. |
key_id |
string |
Key Identifier of AKV key encryption key. |
name |
string |
Name of the deployed AKV that will be used by ONTAP for storing keys.
|
oauth_host |
string |
Open authorization server host name. |
port |
integer |
Authorization server and vault port number. |
proxy_host |
string |
Proxy host. |
proxy_password |
string |
Proxy password. Password is not audited. |
proxy_port |
integer |
Proxy port. |
proxy_type |
string |
Type of proxy. |
proxy_username |
string |
Proxy username. |
scope |
string |
Set to "svm" for interfaces owned by an SVM. Otherwise, set to "cluster". |
skip_verification |
boolean |
Set to true to skip the verification of the updated user credentials when updating credentials. The default value is false. |
state |
Indicates whether or not the AKV wrapped internal key is available cluster wide.
This is an advanced property; there is an added computational cost to retrieving its value. The property is not populated for either a collection GET or an instance GET unless it is explicitly requested using the |
|
svm |
SVM, applies only to SVM-scoped objects. |
|
tenant_id |
string |
Directory (tenant) ID of the deployed Azure application with appropriate access to an AKV. |
uuid |
string |
A unique identifier for the Azure Key Vault (AKV). |
vault_host |
string |
AKV host subdomain. |
job_link
| Name | Type | Description |
|---|---|---|
uuid |
string |
The UUID of the asynchronous job that is triggered by a POST, PATCH, or DELETE operation. |
error_arguments
| Name | Type | Description |
|---|---|---|
code |
string |
Argument code |
message |
string |
Message argument |
returned_error
| Name | Type | Description |
|---|---|---|
arguments |
array[error_arguments] |
Message arguments |
code |
string |
Error code |
message |
string |
Error message |
target |
string |
The target parameter that caused the error. |