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







 Managing secrets versions 

When you rotate a secret in IBM Cloud® Secrets Manager, you create a new version of its value. You can use IBM Cloud® Secrets Manager to view the version history and update version metadata of secrets. If you accidentally replace or overwrite a secret, you can also restore it to a previous version.



 Before you begin 

Before you get started, be sure that you have the required level of access. To view the version history of a secret, update the metadata of a secret version, and restore a secret to its previous version, you need the [Writer service role or higher](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam).





 Viewing the version history of secrets 

When you rotate a secret in IBM Cloud® Secrets Manager, you create a new version of its value. You can quickly examine the version history of your secrets by using the UI or API.





 Before you begin 

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





 Viewing version history in the UI 

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



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 Manager UI, go to your Secrets list.
4. In the row for the secret that you want to inspect, click the Actions menu !
<br>If you have configured a Secrets Manager instance as described in [Encrypt and protect your data](https://cloud.ibm.com/docs/overview?topic=overview-get-started-checklistsecuring), you can use that instance to dynamically generate a service ID and an API key each time a protected resource is read or accessed. For more information, see [Creating IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials&interface=ui). 
 <br><br> * Create API keys<br><br><br> An API key is a unique code passed into an API to identify the calling application or user. You can use platform IBM Cloud API keys that are associated with user identities, and you can create other API keys for service IDs. For more information, see [Understanding API keys](https://cloud.ibm.com/docs/account?topic=account-manapikey). <br>If you have configured a Secrets Manager instance as described in [Encrypt and protect your data](https://cloud.ibm.com/docs/overview?topic=overview-get-started-checklistsecuring), you can use that instance to dynamically generate a service ID and an API key each time a protected resource is read or accessed. For more information, see [Creating IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials&interface=ui). 
 <br><br> * Learn about IAM policies<br><br><br> A policy consists of a subject, target, and a role. A policy grants a subject one or multiple roles to a set of resources so that specific actions can be taken. The role defines the level of access that is granted. For more information, see [What are IAM policies and who can assign them?](https://cloud.ibm.com/docs/account?topic=account-iamusermanpol) 







 Get support and other resources
(https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/secrets-manager/images/event-notifications-connected.svg)

Figure 2. Sending a test event to Event Notifications



1. In the IBM Cloud console, go to your Secrets Manager instance.
2. Go to Settings > Event Notifications, and click Send test event.
3. Check the Slack channel that is associated with your webhook to verify the results.

If the Functions action completed successfully, you receive a Slack message that is similar to the following example:

Secrets Manager notification

{"event_type":"test_event","secret_type":"test_secret_type","secrets":[{"event_time":"2022-03-09T21:14:32Z","secret_group_id":"default","secret_id":"27d3368f-bb4a-2792-a4b0-ee79a5383866","secret_name":"test_secret_name"}],"source_instance_api_public_url":"https://<instance_id>.<region>.secrets-manager.appdomain.cloud/api","source_instance_crn":"crn:v1:bluemix:public:secrets-manager:<region>:a/<account_id>:<instance_id>::","source_instance_dashboard_url":"https://cloud.ibm.com/services/secrets-manager/<your_service_dashboard_url>","source_service":"SecretsManager"}
4. Optional. Check your Cloud Functions activations logs if you encounter issues.

From the [Cloud Functions activations dashboard](https://cloud.ibm.com/functions/dashboard), you can check to see your activated action. Notification successfully forwarded to Slack!
This format allows for greater flexibility because you can reference secrets from an Secrets Manager instance in a different account if the correct [authorization](https://cloud.ibm.com/iam/authorizations) is in place. For more information see [Configuring Secrets Manager](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-secretsmanager).

The secrets that are used in both CI and CD are outlined as follows:

A Hint is a suggested default name that is automatically resolved against the first matching secret with the same name across any of the available by name secrets integrations that are bound to the toolchain.



 DevSecOps Pipeline Secrets 



Table 1. DevSecOps Secrets

 Secret Hint Information 

 IBM Cloud API Key ibmcloud-api-key Required: CI & CDUsed to authenticate with IBM public cloud and perform a wide range of operations 
 GPG Private Key signing_key Required: CI onlyThis is the certificate that is used to sign images built by the CI pipeline 
 IBM Private Worker Service API Key private-worker-service-api-key Required: CI onlyA Service ID API Key Used to run delivery pipeline workloads on a Tekton Private Worker Service 
 GitHub Access Token git-token Optional: CI & CDUsed to authenticate with GitHub and provide access to the repositories 
 Artifactory API token artifactory-token Required: CI & CDUsed to access images used by pipeline tasks 
 Slack Web Hook slack-webhook Optional: CI & CDThis webhook is required if you choose to use the Slack tool integration to post toolchain status notifications 
 ServiceNow API Token servicenow-token Required: CD onlyUsed to access Service Now for change management operations 
 HashiCorp Vault Role ID role-id Required: CI & CDUsed to authenticate with the HashiCorp Vault server 
 HashiCorp Vault Secret ID secret-id Required: CI & CDUsed to authenticate with the HashiCorp Vault server 
 IBM Cloud Object Storage Writer API Key cos-api-key Required: CI & CDUsed to authenticate with the Object Storage service - This key must have writer permission
* [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)
* [CVE-2023-0361](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-0361)
* [CVE-2022-48303](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-48303)
* [CVE-2023-27320](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27320)
* [usn-5964-1](https://ubuntu.com/security/notices/USN-5964-1)
Versions 2 versions per certificate (current and previous)<br><br>For auditing purposes, the service retains the metadata of up to 50 versions for each secret, which you can review as part of a secret's [version history](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history). 
 Locks 1000 
 Custom metadata 10 KB 
 Version custom metadata 10 KB 







 Limits for user credentials 

The following limits apply to user credentials.



Table 9. User credential limits

 Attribute Limit 

 Name 2 - 256 characters<br><br>The name of the secret can contain only alphanumeric characters, dashes, and dots. It must start and end with an alphanumeric character. 
 Description 2 - 1024 characters 
 Username 2 - 64 characters 
 Password 64 characters 
 Labels 2 - 30 characters<br><br>30 labels per secret 
 Versions For auditing purposes, the service retains the metadata of up to 50 versions for each secret, which you can review as part of a secret's [version history](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history). 
 Locks 1000 
 Custom metadata 10 KB 
 Version custom metadata 10 KB
"not_after" : "2022-03-24T05:06:15Z",
"not_before" : "2022-03-07T13:05:46Z"
}
} ],
"locks_total" : 1,
"custom_metadata" : {
"custom_key" : "custom_value"
}
} ]
}







 ibmcloud secrets-manager secret-version-metadata 

Get the metadata of a secret version by specifying the ID of the version or the alias previous.

A successful request returns the metadata that is associated with the specified version of your secret.

ibmcloud secrets-manager secret-version-metadata --secret-type SECRET-TYPE --id ID --version-id VERSION-ID



 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}/.

--version-id (string)
: The v4 UUID that uniquely identifies the secret version. You can also use previous to retrieve the previous version.

Note: To find the version ID of a secret, use the Get secret metadata method and check the response details. 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}|previous)$/.





 Examples
If you have existing configurations on secrets engines in your instance, you can also retrieve the information programmatically so that it can be re-created in a new instance. For more information, see the [Get the configuration of a secret type](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-config) API.
2. Add your downloaded secrets to the newly created instance.







 Automatically backing up secrets 

Creating an automatic backup of your secrets is possible by automating the manual flow, which can be done in various ways. Check out some of the following examples to see whether one of them might work for you.



* Create a script that periodically downloads all of your secrets and then imports them into your backup instance.
* [Create a destination and subscription in Event Notifications](https://cloud.ibm.com/docs/event-notifications) that points to an IBM Cloud Functions action. Configure the action to listen for lifecycle events such as secret_created and secret_rotated. Then, when the action receives the event, the action downloads the secret from one instance and adds it to the backup instance.

Currently, Secrets Manager supports notifications for certificates only. To learn about the various available lifecycle event types, see [Enabling event notifications](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-event-notifications).







 Recovering data from a Key Protect backup instance 

Did you experience a failure with your IBM Key Protect instance? If you backed up your data to a new Key Protect instance by using the same root keys, you can update your Secrets Manager instance with data from your backup Key Protect instance. To do so, open a case and include the following information.



* Your Secrets Manager instance's CRN
* Your backup Key Protect instance's CRN
* The key ID
* The original Key Protect instance's CRN and key ID, if available



You must enable service-to-service authorization between your backup Key Protect instance and your Secrets Manager instance.
* Added payload_available and downloaded boolean parameters to the response details of the [Get a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-secret), [Get secret version metadata](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-secret-version-metadata), [List versions of a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2list-secret-versions) methods. These parameters can help you to identify whether the a secret version is available to be restored, and whether it has already been previously read or accessed.
* Added the restore query parameter as a request option on the [Invoke an action on a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2update-secret) method. You can use this action to [restore the previous version](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history) of a secret.
* Updated the [Get a version of a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-secret-version) method that can be used to retrieve the previous version of a secret. This API now supports arbitrary, iam_credentials, and username_password secrets, in addition to public_cert and imported_cert.







 20 September 2021 

This release includes the following updates:



* Added public_cert secret type that can be used to order domain-validated TLS certificates with the service. For more information, see [Ordering certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-public-certificatesorder-public-certificates).
A successful response returns the ID value for the certificate, along with other metadata. For more information about the required and optional request parameters, check out the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-secret).







 Setting an automatic rotation policy for IAM credentials 

The following example request creates an automatic rotation policy for a IAM credentials (iam_credentials) secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

curl -X PATCH
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H 'Content-Type: application/merge-patch+json' -d '{
"rotation": {
"auto_rotate": true,
"interval": 30,
"unit": "day"
}
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/metadata"

To remove a policy, keep the resources block empty.

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

The defined rotation interval cannot be higher than the defined time-to-live. Rotation is available only for IAM credentials where the Re-use key is set to true. You can set the TTL for secrets by using minute units of time but rotation is not available for those secrets.
{region}.secrets-manager.appdomain.cloud/v1/auth/ibmcloud/manage/groups/{group_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'





 Example response 

{
"request_id": "37065859-3238-f671-941f-d43ac340ad99",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": null,
"auth": null
}









 Secrets 



 Create a secret 

Creates or imports a secret by using the Secrets Manager secrets engines. You can add one of the following [secret types](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secret):



* Arbitrary secrets (arbitrary)
* IAM credentials (iam_credentials)
* Key-value secrets (kv)
* User credentials (user_credentials)
* Imported certificates (import_cert)
* Private certificates (private_cert)
* Public certificates (public_cert)



Arbitrary secrets

IAM credentials

Key-value secrets



Table 6. Create secret request parameters - Arbitrary secrets

 Request parameters Description 

 name Required. The human-readable alias that you want to assign to the secret. 
 description An extended description of the secret. 
 payload Required. The secret data to assign to the secret. 
 expiration_date The expiration date that you want to assign to the secret. The date format follows [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). 
 labels[] Labels that you can use to filter for secrets in your instance. Up to 30 labels can be added. 





 Example requests 

Create an arbitrary secret in the default secret group.

curl -X POST "https://{instance_id}.
newapp-mytest-00002-deployment-7c87cfbf66-xnwkp/user-container:
2021-07-15 20:40:56 Listening on port 8080









 Secret commands 

A secret provides a method to include sensitive configuration information, such as passwords or SSH keys, to your deployment. By referencing values from your secret, you can decouple sensitive information from your deployment to keep your app or job portable. Anyone who is authorized to your project can also view your secrets; be sure that you know that the secret information can be shared with those users. Secrets contain information in key-value pairs.

You must be within the context of a [project](https://cloud.ibm.com/docs/cli?topic=cli-clicli-project) before you use secret commands.

For more information about working with secrets, see [Working with secrets](https://cloud.ibm.com/docs/codeengine?topic=codeengine-secret).

To see CLI help for the secret commands, run ibmcloud ce secret -h.

Beginning with CLI version 1.42.0, defining and working with secrets in the CLI is unified under the secret command group. Use the --format option to specify the category of secret, such as basic_auth, generic, ssh, tls, or registry. The default value for the --format option is generic.



 ibmcloud ce secret create 

Create a secret.
{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/arbitrary/secrets/groups/{group_id}/{secret_id}/rotate" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -d '{
"payload": "new-secret-data"
}'

Rotate a kv secret in the default secret group. [Learn more](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-vault-manage-kv&interface=apioverview-kv).

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/secrets/{secret_id}/rotate' -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -H 'Content-Type: application/json' -d '{
"payload": {
"key7":"value7"
}
}'

Rotate a kv secret in an existing secret group.

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/secrets/groups/{group_id}/{secret_id}/rotate' -H 'Accept: application/json'
-H 'X-Vault-Token: {Vault-Token}' -H 'Content-Type: application/json' -d '{
"payload": {
"key7":"value7"
}
}'

Rotate a username_password secret in the default secret group.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/username_password/secrets/{secret_id}/rotate" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -d '{
* [CVE-2021-35942](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-35942)
* [CVE-2021-23840](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-23840)
* [CVE-2021-23841](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-23841)
* [CVE-2021-20231](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-20231)
* [CVE-2021-20232](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-20232)
* [CVE-2021-3580](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-3580)
* [CVE-2021-28153](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-28153)
* [CVE-2021-3800](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-3800)
* [CVE-2019-18218](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-18218)
* [CVE-2020-12762](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-12762)
Why can't I restore the previous version of an IAM credentials secret? 

You try to restore the previous version of an IAM credentials secret in IBM Cloud® Secrets Manager, but you're unable to do so.

  What’s happening 

You want to restore the previous service ID API key that was associated with an IAM credentials secret. When you try to [restore the secret version](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history) by using the Secrets Manager UI or API, you get one of the following errors:

Rotating IAM credentials is not supported when reuse credentials is off.

Version previous is not active.

  Why it’s happening 

You might receive these errors due to the following reasons:



*  The secret was initially created with the [Reuse IAM credentials until lease expires option](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentialsiam-credentials-reuse-ui) set to Off (or, the reuse_api_key property set to false). This means that the secret can hold only a short-lived ephemeral value that is created and and then deleted after each read operation, so its previous version can't be restored.
*  The service ID API key reached its defined time-to-live (TTL) or lease duration, and it can no longer be restored.
And, ultimately, it makes it a little more efficient for the management of your secrets while you're going through your DevOps operations.

Thank you. If you have questions, please drop us a line. If you want to see more videos like this in the future, please like and subscribe, and don't forget you can grow your skills and earn a badge with IBM Cloud Labs which, are free browser-based interactive Kubernetes labs.





 Working with secrets of different types 

Secrets that you create in Secrets Manager can be static or dynamic in nature. A static secret has its expiration date and time enforced at secret creation or rotation time. In contrast, a

dynamic secrethas its expiration date and time enforced when its secret data is read or accessed.

Secrets Manager further classifies static and dynamic secrets by their general purpose or function. For example, each secret type is identified by programmatic name, such as username_password. If you're looking to manage your secret by using the Secrets Manager API or CLI, you can use these programmatic names to run operations on secrets according to their type.

Review the following table to understand the types of static and dynamic secrets that you can create and manage with the service.



Table 1. Secret types in Secrets Manager

 Type Programmatic name Kind Description 

 [Arbitrary secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-arbitrary-secrets) arbitrary Static Arbitrary pieces of sensitive data, including any type of structured or unstructured data, that you can use to access an application or resource. 
 [IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials) iam_credentials* Dynamic A dynamically generated service ID and API key that can be used to access an IBM Cloud service that requires IAM authentication. 
 [Key-value secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-key-value) kv Static Pieces of sensitive data that is structured in JSON format that you can use to access an application or resource.