vania-janet/multiturn-rag-retrieval-data huggingface dataset:
curl -X POST 'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/wrap' -H 'accept: application/vnd.ibm.kms.key_action+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action+json' -H 'x-kms-key-ring: <key_ring_ID>' -H 'correlation-id: <correlation_ID>' -d '{
"plaintext": "<data_key>"
}'

Replace the variables in the example request according to the following table.



Table 1. Describes the variables needed to wrap a specified key

 Variable Description 

 region Required. The region abbreviation, such as us-south or au-syd, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 key_ID Required. The unique identifier for the root key that you want to use for wrapping. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the cURL request. For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 
 key_ring_ID Optional.
The unique, human-readable name that identifies your key. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 
 correlation_ID The unique identifier that is used to track and correlate transactions. 



A successful DELETE api/v2/keys/<key_ID>/aliases/<key_alias> request returns an HTTP 204 No Content response, which indicates that the alias associated with your key was deleted.

It takes up to 10 minutes for an alias to be deleted from the service.









 APIs that use key alias 

The following table lists the APIs where you can use key alias.



Table 3. Describes the variables that are APIs that use key alias.

 API Key Alias Impact 

 [Create Root Keys.](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys) You can create up to five aliases while you create a root key. 
 [Create Standard Keys.](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-standard-keys) You can create up to five aliases while you create a standard key. 
 [Retrieve a key.](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-key) You can retrieve a key by ID or alias.
Why does encryption fail with an invalid KMS endpoint? 

Virtual Private Cloud

Classic infrastructure

 What’s happening 

When you provision Portworx and set up encryption, you receive an error similar to the following:

kp.Error: correlation_id='673bb68a-be17-4720-9ae1-85baf109924e', msg='Unauthorized: The user does not have access to the specified resource'"

 Why it’s happening 

The endpoint that you entered in your Kubernetes secret is incorrect. If the KMS endpoint is entered incorrectly, Portworx can't access the KMS provider that you configured.

For more information about enabling encryption on your Portworx volumes, see [Setting up encryption](https://cloud.ibm.com/docs/containers?topic=containers-storage_portworx_encryption).

 How to fix it 

Edit your Kubernetes secret to include the correct endpoint for your KMS provider.



1. Retrieve the correct endpoint for your KMS provider.



* IBM Key Protect: [Retrieve the region](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsregions) where you created your service instance. Make sure that you note your API endpoint in the correct format. Example: https://us-south.kms.cloud.ibm.com.
* Hyper Protect Crypto Services: [Retrieve the Key Management public endpoint URL](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). Make sure that you note your endpoint in the correct format. Example: https://api.us-south.hs-crypto.cloud.ibm.com:<port>. For more information, see the [Hyper Protect Crypto Services API documentation](https://cloud.ibm.com/apidocs/hs-cryptogetinstance).



2. Encode the endpoint to base64.

echo -n "<endpoint>" | base64
If you have manager or writer privileges for your Key Protect instance, [you can retrieve the key material for a specific key by making a GET /v2/keys/<keyID_or_alias> request](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keysview-keys-api).
3. Copy the ID of the root key that you want to use for wrapping.
4. Run the following curl command to protect the key with a wrap operation.

$ curl -X POST "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/wrap" -H "accept: application/vnd.ibm.kms.key_action+json" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key_action+json" -H "x-kms-key-ring: <key_ring_ID>" -H "correlation-id: <correlation_ID>" -d '{
"plaintext": "<data_key>",
"aad": [
"<additional_data>",
"<additional_data>"
]
}'



Replace the variables in the example request according to the following table.



Table 1. Describes the variables that are needed to wrap a specified key in Key Protect.

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 keyID_or_alias Required. The unique identifier or alias for the root key that you want to use for wrapping. 
 IAM_token Required. Your IBM Cloud access token.
If not set, the context instance specified by ibmcloud dns instance-target INSTANCE is used.
* --output value specifies output format. Currently, json is the only supported format.







 Editing a secondary zone using the API 

To edit a secondary zone using the API, follow these steps:



1. Set up your [API environment](https://cloud.ibm.com/apidocs/dns-svcsauthentication) with the correct variables.
2. Store the following values in variables to be used in the API command:



* INSTANCE_ID, which is the unique identifier of a service instance.
* RESOLVER_ID, which is the unique identifier of a custom resolver.
* SECONDARY_ZONE_ID is the unique identifier of a secondary zone.
* X-Correlation-ID (optional), which uniquely identifies a request.



3. When all variables are initiated, edit the secondary zone:



curl -X PATCH https://api.dns-svcs.cloud.ibm.com/v1/instances/2be5d4a7-78f0-4c62-a957-41dc15342777/custom_resolvers/ddbe7a53-7971-46dc-b021-420335c31562/secondary_zones/f97ef698-d5fa-4f91-bc5a-33f17d143b7d -H 'Content-Type: application/json' -H 'Authorization: Bearer xxxxxx' -d '{
"description": "secondary zone",
"enabled": false,
"transfer_from": [
"10.0.0.7"
]
}'
To delete a custom resolver using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* resolver_id, which is the unique identifier of a custom resolver.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3. When all variables are initiated, update your custom resolver.

curl -X DELETE https://api.dns-svcs.cloud.ibm.com/v1/instances/2be5d4a7-78f0-4c62-a957-41dc15342777/custom_resolvers/ddbe7a53-7971-46dc-b021-420335c31562 -H 'Authorization: Bearer xxxxxx'
Metrics Routing CLI 

The IBM Cloud® command-line interface (CLI) provides extra capabilities for service offerings. This information describes how you can use the CLI to define and manage settings for your IBM Cloud® Metrics Routing instance by using the CLI.



 Installing the CLI 



* Install the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started).
* Install the CLI by running the following command:

ibmcloud plugin install metrics-router



You're notified on the command line when updates to the IBM Cloud CLI and plug-ins are available. Be sure to keep your CLI up to date so that you can use the most current commands. You can view the current version of all installed plug-ins by running ibmcloud plugin list.





 Before you begin 

Before you configure IBM Cloud Metrics Routing routes or targets, you must configure a primary metadata region. The primary metadata region is configured using the [ibmcloud metrics-router setting update command --primary-metadata-region option.](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-metrics-router-clisettings-update-cli)

If you you do not have a primary metadata region configured, your route and target command will fail.





 ibmcloud metrics-router route create 

Use this command to create a new route to IBM Cloud Metrics Routing targets.

Targets must be IBM Cloud Monitoring instances.

ibmcloud metrics-router route create --name ROUTE_NAME ( --rules RULES | --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT] [--force]



 Command options 

--name ROUTE_NAME
: The name to be given to the route.

Do not include any personal identifying information (PII) in any resource names.

--file RULES_DEFINITION_JSON_FILE
: A JSON file that contains the definition of the rules for route. The file needs to be formatted as follows:

[
{
Create a root key by making a POST call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys



1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).
2. Create a root key by running the following curl command.

$ curl -X POST "https://<region>.kms.cloud.ibm.com/api/v2/keys" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "x-kms-key-ring: <key_ring_ID>" -H "correlation-id: <correlation_ID>" -d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"name": "<key_name>",
"aliases": alias_list],
"description": "<key_description>",
"expirationDate": "<expiration_date>",
"extractable": <key_type>
}
]
}'

Replace the variables in the example request according to the following table.





Table 1. Describes the variables that are needed to add a root key with the Key Protect API.

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints).
Retrieving service instance <service-name> in resource group Default under account <account name> as <email address>...
OK

Name: <service-name>
ID: crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6::
GUID: a152eee4-262e-4a39-ae13-a71b9882dcb6
Location: us-south
Service Name: kms
Service Plan Name: tiered-pricing
Resource Group Name: Default
State: active
Type: service_instance
Sub Type: kms
Created at: 2020-05-31T15:10:23Z
Created by: <email address>
Updated at: 2020-05-31T15:10:23Z
Last Operation:
Status create succeeded
Message Completed create instance operation

 list keys in the private service instance
$ ibmcloud kp keys -i a152eee4-262e-4a39-ae13-a71b9882dcb6
Retrieving keys...

FAILED

kp.Error: correlation_id='59578794-2b5b-48ca-9074-bbe23760d94a', msg='Unauthorized: The user does not have access to the specified resource'

 delete the private service instance
$ ibmcloud resource service-instance-delete <service-name>
Deleting service instance <service-name> in resource group Default under account <account name> as <email address>...
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/key_rings



1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api).
2. View general characteristics about your key rings by running the following curl command.

$ curl -X GET "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/key_rings" -H "accept: application/vnd.ibm.kms.key_ring+json" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "correlation-id: <correlation_ID>"

Replace the variables in the example request according to the following table.



Table 4. Describes the variables needed to view key rings with the key management service API

 Variable Description 

 region Required. The region abbreviation, such as us-south, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Hyper Protect Crypto Services instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID).
Transfer a key to a different key ring by making a PATCH call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>



1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).

To update the key ring of a key, you must have at least Manager service access to the key and the target key ring. To learn how IAM roles map to Key Protect service actions, check out [Service access roles](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-accessmanage-access-roles).
2. Update the key ring of a key by running the following curl command.

$ curl -X PATCH https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias> -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key+json' -H "x-kms-key-ring: <original_key_ring_ID>" -H "correlation-id: <correlation_ID>" -d '{
"keyRingID": "<new_key_ring_ID>"
}'

Replace the variables in the example request according to the following table.





Table 2. Describes the variables that are needed to update a key's key ring with the Key Protect API.

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where yourKey Protect instance resides. <br> <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints).
"dns_server_ip": "10.10.16.8"
}
],
"created_on": "2021-04-21T08:18:25Z",
"modified_on": "2021-04-21T08:18:25Z"
}







 List all custom resolvers 

To list all custom resolvers using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3. When all variables are initiated, list your custom resolvers:

{
"custom_resolvers": [
{
"id": "5365b73c-ce6f-4d6f-ad9f-d9c131b26370",
"name": "my-resolver",
"description": "custom resolver",
"enabled": false,
"health": "HEALTHY",
"locations":
{
"id": "9a234ede-c2b6-4c39-bc27-d39ec139ecdb",
"subnet_crn": "crn:v1:bluemix:public:is:us-south-1:a/01652b251c3ae2787110a995d8db0135::subnet:0716-b49ef064-0f89-4fb1-8212-135b12568f04",
"enabled": true,
"healthy": true,
"dns_server_ip": "10.10.16.8"
}
],
"created_on": "2021-04-21T08:18:25Z",
DNS Services requires you have appropriate access to VPC resources in one of the following operations:



* Add a VPC to permitted networks of a DNS zone.
* Create custom resolver on a particular VPC.
* Create GLB origin pool with healthcheck on VPC subnets.



You must work with an account administrator to ensure appropriate VPC operator permission for IAM access policy, and to ensure that no CBR rules blocking you operate on the VPC. For the latter two operations, you must also have subnet reader permission and ensure no CBR rules blocking you get details of the subnets.





 Monitoring context-based restrictions in DNS Services 

The context-based restriction service generates audit logs every time a context-based rule is enforced. For more information, see [Monitoring context-based restrictions](https://cloud.ibm.com/docs/account?topic=account-cbr-monitor).

Activity tracker events that are generated by the context-based restriction service contain a CorrelationId field. You can search the value of this field to find the audit events that are generated by DNS Services.
To enable metrics policies, you must be assigned a Manager IAM role for your Hyper Protect Crypto Services instance. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessservice-access-roles).
2. Enable a metrics policy for your Hyper Protect Crypto Services instance by running the following curl command.

curl -X PUT "https://api.<region>.hs-crypto.cloud.ibm.com/api/v2/instance/policies?policy=metrics" -H "accept: application/vnd.ibm.kms.policy+json" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.policy+json" -d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "metrics",
"policy_data": {
"enabled": false
}
}
]
}'

Replace the variables in the example request according to the following table.



Table 1. Describes the variables needed to enable a metrics policy

 Variable Description 

 region Required. The region abbreviation, such as us-south, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request.
To update a custom resolver using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* resolver_id, which is the unique identifier of a custom resolver.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3. When all variables are initiated, update your custom resolver:

{
"name": "my-resolver",
"description": "custom resolver",
"enabled": false
}







 Next steps 



* [Adding custom resolver locations](https://cloud.ibm.com/docs/dns-svcs?topic=dns-svcs-cr-res-loc-add)
* [Adding custom resolver forwarding rules](https://cloud.ibm.com/docs/dns-svcs?topic=dns-svcs-cr-fwd-rules-add)
* [Deleting a custom resolver](https://cloud.ibm.com/docs/dns-svcs?topic=dns-svcs-cr-delete)
keyID_or_alias Required. The identifier or alias for the key that you would like to associate with an alias. To retrieve a key ID, see the [list keys API](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keysretrieve-keys-api). 
 key_alias Required. A unique, human-readable name for easy identification of your key. <br> <br>Alias must be alphanumeric, case sensitive, and cannot contain spaces or special characters other than dashes (-) or underscores (_). The alias cannot be a version 4 UUID and must not be a Key Protect reserved name: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings,rotate, wrap, unwrap, rewrap, version, versions.Alias size can be between 2 - 90 characters (inclusive). <br> <br>Note You cannot have duplicate alias names in your Key Protect instance. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. <br> <br>For more information, see[Retrieving an access token](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Key Protect service instance. <br> <br>For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). 
 correlation_ID Optional.The unique identifier that is used to track and correlate transactions. 



To protect the confidentiality of your personal data, avoid entering personally identifiable information (PII), such as your name or location, when you create a key alias.
"resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:9d4353d8-6b85-4689-90dd-1ccfb4a275ab:bucket:my-cos-kms-bucket",
"createdBy": "crn-crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:9d4353d8-6b85-4689-90dd-1ccfb4a275ab::",
"creationDate": "2020-06-15T20:41:23Z",
"lastUpdated": "2020-06-15T20:41:23Z",
"keyVersion": { "id": "52a9d772-8982-4620-bfb4-b070dd812a0c", "creationDate": "2020-06-15T20:36:46Z"
}
}
]

 delete the authorization policy between COS AND KMS - this breaks everything
$ ibmcloud iam authorization-policy-delete $COS_KMS_AUTHORIZATION --force

 delete the KP root key - this fails because the registration was not deleted
$ ibmcloud kp key delete $MY_COS_KEY_ID

Deleting key: 52a9d772-8982-4620-bfb4-b070dd812a0c, from instance: b0d84b32-09d0-4314-8049-da78e3b9ab6f...
FAILED
kp.Error:
correlation_id='c27b7948-4a1f-4cbd-8770-cb3616888e27',
msg='Conflict: Key could not be deleted.
Create a root key, disable it, and attempt to use the root key to wrap another key.

 create a root key
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

63d044d9-b38b-4803-85ef-ed9a1e5087c2

 disable the root key
$ ibmcloud kp key disable $KEY_ID

Disabling key: '63d044d9-b38b-4803-85ef-ed9a1e5087c2', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK

 create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)

$ echo $PLAINTEXT

BNxtU9B4kXOZA45Cnyz3wOh4J77TakTXI1n2rj0ZiMc=

 wrap the plaintext key with the root key, creating a DEK (this is the ciphertext)
 this should fail (the root key is disables)
$ ibmcloud kp key wrap $KEY_ID -p $PLAINTEXT --output json

FAILED
kp.Error:
correlation_id='c2edbdad-7e62-4690-8fcc-10515ade9913',
msg='Conflict: Action could not be performed on key. Please see "reasons" for more details.',
reasons='[KEY_ACTION_INVALID_STATE_ERR: Key is not in a valid state -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'





 Example 3