vania-janet/multiturn-rag-retrieval-data huggingface dataset:
* UI
* CLI
* API
* Terraform







 Storing arbitrary secrets 

You can use IBM Cloud® Secrets Manager to store arbitrary secrets that are used to access protected systems that are inside or outside of IBM Cloud.

An arbitrary secret is a type of application secret that can be used to hold structured or unstructured data, such as a key, configuration file, or any other piece of sensitive information. After you create the secret, you can use it to connect your application to a protected resource, such as a third-party app or database. Your secret is stored securely in your dedicated Secrets Manager service instance, where you can centrally manage its lifecycle.

To learn more about the types of secrets that you can manage in Secrets Manager, see [What is a secret?](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secret)



 Before you begin 

Before you get started, be sure that you have the required level of access. To create or add secrets, you need the [Writer service role or higher](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam).





 Creating arbitrary secrets in the UI 

To add an arbitrary secret by using the Secrets Manager UI, complete the following steps.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets table, click Add.
4. From the list of secret types, click the Other secret type tile.
5. Click Next.
6. Add a name and description to easily identify your secret.
7. Select the

secret groupthat you want to assign to the secret.

Don't have a secret group?
2. In the row for the secret that you want to edit, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Edit details.
3. Use the Automatic rotation option to enable or disable automatic rotation for the secret.





Rotation is available only for IAM credentials where the reuse key is set to true. The defined rotation interval cannot be higher than the defined time-to-live (TTL). You can set the TTL for secrets by using minute units of time but rotation is not available for those secrets.







 Scheduling automatic rotation from the CLI 

You can schedule the automatic rotation of secrets by using the Secrets Manager CLI plug-in.



 Setting an automatic rotation policy for user credentials 

Schedule the automatic rotation for user credentials by using the Secrets Manager CLI plug-in.

ibmcloud secrets-manager secret-metadata-update --id=SECRET_ID --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'

To remove a policy, keep the resources block empty.





 Setting an automatic rotation policy for public certificates 

Schedule the automatic rotation for public certificates by using the Secrets Manager CLI plug-in.

ibmcloud secrets-manager secret-metadata-update --id=SECRET_ID --rotation='{"auto_rotate": true, "rotate_keys": true}'





 Setting an automatic rotation policy for private certificates 

Schedule the automatic rotation for private certificates by using the Secrets Manager CLI plug-in.

ibmcloud secrets-manager secret-metadata-update --id=SECRET_ID --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'





 Setting an automatic rotation policy for IAM credentials 

Schedule the automatic rotation for IAM credentials by using the Secrets Manager CLI plug-in.
For basic information about referencing configmaps or secrets with the CLI, see [Referencing configmaps with the CLI](https://cloud.ibm.com/docs/codeengine?topic=codeengine-configmapconfigmap-ref-cli) and [Referencing secrets with the CLI](https://cloud.ibm.com/docs/codeengine?topic=codeengine-secretsecret-ref-cli).

The following scenarios can be completed for secrets or configmaps.



 Referencing a full secret with the CLI 

Secrets and configmaps are made up of key-value pairs. Environment variables are the result of providing an entry per key when referencing the full secret or configmap. If multiple secrets (or configmaps) contain the same named key, then you only get one of the keys in the referenced secret or configmap.

In this scenario, create a secret, which contains key-value pairs for a username and password, and then reference the full secret when you run a job. You can update the secret to add a key and then demonstrate the use of the new key in a job. While this scenario uses a secret, you can use the same steps to fully reference a configmap by substituting configmap for secret in the commands.



1. Create the mydatabasesec secret and specify the key-value pairs for a username and password by using the --from-literal option.

ibmcloud ce secret create -n mydatabasesec --from-literal username=reader --from-literal password=abcd
2. View details about the mydatabasesec secret by using the secret get command. The values for the password and username keys of the secret are encoded.

ibmcloud ce secret get -n mydatabasesec

Example output

Getting generic secret 'mydatabasesec'...
OK

Name: mydatabasesec
ID: abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
For more information about the command options, see [ibmcloud secrets-manager secret-version-create](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-version-create-command).







 Manually rotating secrets with the API 

You can manually rotate your secrets and certificates by using the Secrets Manager API.



 Rotating arbitrary secrets 

You can rotate arbitrary secrets by calling the Secrets Manager API.

The following example request creates a new version of your secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

curl -X POST -H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
"custom_metadata": {
"metadata_custom_key": "metadata_custom_value"
},
"payload": "Updated arbit",
"version_custom_metadata": {
"custom_version_key": "custom_version_value"
}
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

A successful response returns the ID value for the secret, along with other metadata. For more information about the required and optional request parameters, check out the [API docs](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2update-secret).





 Rotating key-value secrets 

You can rotate key-value secrets by calling the Secrets Manager API.

The following example request creates a new version of your secret.
The value must match regular expression /^[0-9]+[s,m,h,d]{0,1}$/.

--rotation ([RotationPolicy](https://cloud.ibm.com/docs/cli?topic=cli-secrets-manager-clicli-rotation-policy-example-schema))
: This field indicates whether Secrets Manager rotates your secrets automatically.





 Example 

ibmcloud secrets-manager secret-metadata-update --id=0b5571f7-21e6-42b7-91c5-3f5ac9793a46 --name=updated-arbitrary-secret-name --description='updated Arbitrary Secret description' --labels=dev,us-south --custom-metadata='{"anyKey": "anyValue"}' --expiration-date=2033-04-12T23:20:50.520Z







 ibmcloud secrets-manager secret-action-create 

Create a secret action. This operation supports the following actions:.

ibmcloud secrets-manager secret-action-create --id ID --secret-action-prototype SECRET-ACTION-PROTOTYPE



 Command options 

--id (string)
: The ID of the secret. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/.

--secret-action-prototype ([SecretActionPrototype](https://cloud.ibm.com/docs/cli?topic=cli-secrets-manager-clicli-secret-action-prototype-example-schema))
: The request body to specify the properties for your secret action. Required.
This release addresses [CVE-2017-1002101](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-1002101) and [CVE-2017-1002102](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-1002102) vulnerabilities. <br>Now secret, configMap, downwardAPI, and projected volumes are mounted as read-only. Previously, apps could write data to these volumes, but the system could automatically revert the data. If your apps rely on the previous insecure behavior, modify them accordingly. 
 IBM Cloud Provider v1.7.4-133 v1.7.16-17 NodePort and LoadBalancer services now support [preserving the client source IP](https://cloud.ibm.com/docs/containers?topic=containers-loadbalancerlb_source_ip) by setting service.spec.externalTrafficPolicy to Local. 
 General N/A N/A Fix [edge node](https://cloud.ibm.com/docs/containers?topic=containers-edgeedge) toleration setup for older clusters.
The request body of the action to revoke private certificate versions.

{
"action_type" : "private_cert_action_revoke_certificate",
"revocation_time_seconds" : 1667982994
}









 Secret locks 

Secure your secret data by attaching a lock to a secret version and preventing any modification or deletion.



 ibmcloud secrets-manager secrets-locks 

List the secrets and their locks in your Secrets Manager instance. Note: If the --all-pages option is not set, the command will only retrieve a single page of the collection.

ibmcloud secrets-manager secrets-locks [--offset OFFSET] [--limit LIMIT] [--search SEARCH] [--groups GROUPS]



 Command options 

--offset (int64)
: The number of secrets to skip. By specifying offset, you retrieve a subset of items that starts with the offset value. Use offset with limit to page through your available resources.

Usage: If you have 100 secrets in your instance, and you want to retrieve secrets 26 through 50, use ..?offset=25&limit=25.

The minimum value is 0.

--limit (int64)
: The number of secrets to list.

The maximum value is 1000. The minimum value is 1.

--search (string)
: Filter locks that contain the specified string in the field "name".

The maximum length is 128 characters. The minimum length is 2 characters. The value must match regular expression /(.?)/.

--groups ([]string)
: Filter secrets by groups.

The list items must match regular expression /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|default)$/. The maximum length is 201 items. The minimum length is 0 items.

--all-pages (bool)
: With IBM Cloud Secrets Manager, you can create secrets dynamically and lease them to applications while you control access from a single location. Built on open source HashiCorp Vault, Secrets Manager helps you get the data isolation of a dedicated environment with the benefits of a public cloud.

In this release, Secrets Manager offers support for the following types of secrets:



* IAM credentials, which consist of a service ID and API key that are generated dynamically on your behalf.
* Arbitrary secrets, such as custom credentials that can be used to store any type of structured or unstructured data.
* User credentials, such as usernames and passwords that you can use to log in to applications.



To find out more about capabilities and use cases for Secrets Manager, check out the [announcement blog](https://www.ibm.com/cloud/blog/announcements/introducing-ibm-cloud-secrets-manager-beta).
* UI
* CLI
* API







 Accessing secrets 

After you store secrets in your IBM Cloud® Secrets Manager service instance, you can retrieve their values programmatically by using the APIs.



 Before you begin 

Before you begin, be sure that you have the required level of access. To view a list of your available secrets, you need the [Reader service role or higher](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam). To retrieve the value of a secret, you need the [SecretsReader service role or higher](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam).





 Retrieving a secret in the UI 

Most secret types in Secrets Manager can't be retrieved directly from the Secrets Manager service dashboard. This security mechanism is in place by default to help to prevent inadvertent exposure of your sensitive data. Secret types that you can access in the UI include: [TLS certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-access-secrets&interface=apidownload-certificate-ui)

You can retrieve all secret types programmatically by using the CLI, API, or SDKs. To see the steps for accessing arbitrary, iam_credentials, kv, and username_password secrets, switch to the CLI or API instructions.



 Downloading certificates 

To download a certificate by using the Secrets Manager UI, complete the following steps.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets table, open the overflow menu for the certificate that you want to download.
4. Click Download. The certificate file is downloaded to your local system.
"crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/791f5fb10986423e97aa8512f18b7e65:e415e570-f073-423a-abdc-55de9b58f54e:secret:fe874c2b-e8fd-bbb6-9f19-e91bbe744735",
"id": "fe874c2b-e8fd-bbb6-9f19-e91bbe744735",
"labels": [],
"last_update_date": "2020-10-22T14:54:25Z",
"name": "updated-name-arbitrary-secret",
"secret_type": "ARBITRARY",
"state": 1,
"state_description": "Active"
},
"warnings": null
}







 Rotate a secret 

Use this command to rotate a secret. Allowable values for SECRET_TYPE are: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, and username_password.

vault write [-format=FORMAT] [-force] ibmcloud/SECRET_TYPE/secrets/SECRET_ID/rotate [payload="SECRET_DATA"] [password=PASSWORD] [certificate=CERTIFICATE_DATA] [private_key=PRIVATE_KEY_DATA] [intermediate=INTERMEDIATE_CERTIFICATE_DATA]



 Prerequisites 

You need the [Writer service role](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam) to rotate secrets.





 Command options 

payload
: The new data to store for an arbitrary secret. Only text-based payloads are supported. If you need to store a binary file, be sure to base64 encode it before you save it to Secrets Manager.
Best practices for rotating and locking secrets 

With IBM Cloud® Secrets Manager, you can design a strategy for rotating your secrets and sensitive data. Review the following suggested guidelines for implementing best practices around your secrets management.



 Define your rotation strategy 

As you use Secrets Manager to design your secrets management strategy, consider how often you want to rotate your secrets based on the internal guidelines for your organization. Determine ahead of time which users or service IDs require access to rotate secrets, and how those secrets can be rotated manually to avoid interruptions to your applications.



1. Determine a frequency of rotation for your secrets.

After you store a secret in Secrets Manager, you decide the frequency of its rotation. You might want to rotate secrets due to personnel turnover, process malfunction, or according to your organization's internal guidelines. Rotate your secrets regularly, for example every 90 days, to meet best practices around secrets management.
2. Test out rotation workflows for each type of secret that you manage in Secrets Manager.

The way in which Secrets Manager evaluates a request to rotate a secret differs depending on the type of secret. For example, some secrets are replaced immediately with the data that you provide on rotation, whereas other secrets, such as public certificates, move into an extra validation step. For more information about how Secrets Manager handles rotation requests, see [Manually rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manual-rotationmanual-rotate-by-type).
3. Establish a process for deploying the newest secret versions to your applications.

Use an automated flow to obtain and deploy the latest version of your secret after it is rotated. For more information, see [Avoid application outages by locking your secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-best-practices-rotate-secretsbest-practices-lock-secrets).







 Set up alerts for expiring secrets 

Connect to the Event Notifications service so that Secrets Manager can notify you in advance when your secrets or certificates are about to expire.



1. Set up alerts for your instance by enabling event notifications.
* UI
* API
* Terraform







 Enabling event notifications for Secrets Manager 

As an administrator of IBM Cloud® Secrets Manager, you might want to send notifications of events in Secrets Manager to other users, or human destinations, by using email, SMS, or other supported delivery channels. Additionally, you might want to send these notifications of events to other applications to build logic by using event-driven programming using webhooks, for example. This is made possible by the integration between Secrets Manager and IBM Cloud® Event Notifications.

To send information to Event Notifications, you must connect your Secrets Manager service instance to Event Notifications. For more information about working with Event Notifications, see [Getting started with Event Notifications](https://cloud.ibm.com/docs/event-notifications).



 How events are collected and sent by Secrets Manager 

When an event of interest takes place in your Secrets Manager instance, Secrets Manager communicates with a connected Event Notifications instance to forward a notification to a [supported destination](https://cloud.ibm.com/docs/event-notifications?topic=event-notifications-en-destination).

Secrets Manager aggregates a list of your pending notifications by [event type](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-event-notifications&interface=uievent-notifications-list), the type of secret, and expiry details if they apply. Every 1 - 2 minutes, the service checks for and dispatches any pending notifications to the connected Event Notifications service. For example, you might receive notifications that are similar to the following messages:



* You have 1 arbitrary secret that expires in 1 day.
* You have 5 public certificate secrets that expire in 10 days.
* You have 100 imported certificate secrets that expire in 30 days.



100 is the maximum number of secrets that you can be notified of in a single event notification.





 Events for Secrets Manager 

The following table lists the Secrets Manager actions that generate an event.

Depending on the type of secret that you're working with in the service, an event might not be generated by Secrets Manager.
This method supports the following actions:



* rotate: Replace the value of a secret.
* restore: Restore a previous version of an iam_credentials secret.
* revoke: Revoke a private certificate.
* delete_credentials: Delete the API key that is associated with an iam_credentials secret.
* validate_dns_challenge: Validate challenges for a public certificate that is ordered with a manual DNS provider.



ibmcloud secrets-manager secret-update --secret-type SECRET-TYPE --id ID --action ACTION [--body BODY]



 Command options 

--secret-type (string)
: The secret type. Required.

Allowable values are: arbitrary, iam_credentials, imported_cert, public_cert, private_cert, username_password, kv.

--id (string)
: The v4 UUID that uniquely identifies the secret. Required.

The value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/.

--action (string)
: The action to perform on the specified secret. Required.

Allowable values are: rotate, restore, revoke, delete_credentials, validate_dns_challenge.

--body ([SecretAction](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli-v1cli-secret-action-example-schema-v1))
: The properties to update for the secret.





 Examples 

ibmcloud secrets-manager secret-update --secret-type=arbitrary --id=exampleString --action=rotate --body='{"payload": "exampleString", "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}}'
* [CVE-2023-27493](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27493)
* [CVE-2023-27496](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27496)
* [CVE-2023-27533](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27533)
* [CVE-2023-27534](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27534)
* [CVE-2023-27535](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27535)
* [CVE-2023-27536](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27536)
* [CVE-2023-27538](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27538)
* [CVE-2023-23914](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-23914)
* [CVE-2023-23915](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-23915)
* [CVE-2023-23916](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-23916)
If you're auditing the version history of a secret, you can use the Secrets Manager CLI plug-in to view the general characteristics of each rotation.

To list all the versions that are associated with a secret, run the [ibmcloud secrets-manager secret-versions](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-versions-command) command. The options for SECRET_TYPE are: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, and username_password.

ibmcloud secrets-manager secret-versions --secret-id SECRET-ID

The command outputs information about the current and previous versions. For example, the date that each version was created. Up to 50 versions can be listed for a secret. For more information about the command options, see [ibmcloud secrets-manager secret-versions](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-versions-command).





 Listing secret versions with the API 

If you're auditing the version history of a secret, you can use the Secrets Manager API to view the general characteristics of each rotation.

The following example request lists metadata properties for each version. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance. The options for {secret_type} are: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, and username_password.

curl -X GET
--H "Authorization: Bearer {iam_token}" --H "Accept: application/json" "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

A successful response returns metadata details about each secret version.

{
"versions": [
{