vania-janet/multiturn-rag-retrieval-data huggingface dataset:
ibmcloud secrets-manager secret-metadata-update --secret-type=arbitrary --id=exampleString --metadata='{"collection_type": "application/vnd.ibm.secrets-manager.secret+json", "collection_total": 1}' --resources='[{"labels": "dev","us-south"], "name": "updated-secret-name", "description": "Updated description for this secret.", "custom_metadata": {"anyKey": "anyValue"}, "expiration_date": "2030-04-01T09:30:00Z"}]'









 Locks 

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



 ibmcloud secrets-manager locks 

List the locks that are associated with a specified secret.

ibmcloud secrets-manager locks --secret-type SECRET-TYPE --id ID [--limit LIMIT] [--offset OFFSET] [--search SEARCH]



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

--limit (int64)
: The number of locks to retrieve. By default, list operations return the first 25 items. To retrieve a different set of items, use limit with offset to page through your available resources.

Usage: If you have 20 locks associated with your secret, and you want to retrieve only the first 5 locks, use ..?limit=5.

The maximum value is 100. The minimum value is 1.
Additionally, because the previous version doesn't have any other locks that are attached to it, the secret data that is associated with the previous version is also deleted. 





 Creating a lock on the current secret version 

You can lock the current version of a secret by using the Secrets Manager UI. A successful request attaches a new lock to the current version of your selected secret, or replaces a lock of the same name if it already exists.



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 the Secrets list.
4. In the row for the secret that you want to lock, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Locks > Create lock.
5. Add a name and description to easily identify the lock.
6. From the list of versions to lock, select Current.
7. Optional: Attach JSON attributes to your lock.

You can include a JSON object with each lock to hold any information that you might need for an automated flow. For example, a key-value pair that identifies the resource that you want to associate with this lock.
8. Optional: Make the lock exclusive.

Choose this option to remove any other locks that match the name that you provided. If any matching locks are found in the previous version of the secret, those locks are deleted when your new lock is created.
9. Optional: Delete previous version data.
Referencing secrets with the CLI 

To use secrets with apps and jobs, you can set environment variables that fully reference a secret or reference individual keys in a secret with the CLI.



 Referencing existing secrets with the CLI 

The following examples reference a generic secret, which is the default secret when the --format option is not specified. Use the --format option to specify the category of secret, such as basic_auth, generic, ssh, tls, or registry.

To use a secret with an app with the CLI, specify the --env-from-secret option on the [app create](https://cloud.ibm.com/docs/codeengine?topic=codeengine-clicli-application-create) or [app update](https://cloud.ibm.com/docs/codeengine?topic=codeengine-clicli-application-update) commands. Similarly, to reference a secret from a job with the CLI, specify the --env-from-secret option on the [job create](https://cloud.ibm.com/docs/codeengine?topic=codeengine-clicli-job-create), [job update](https://cloud.ibm.com/docs/codeengine?topic=codeengine-clicli-job-update), [jobrun submit](https://cloud.ibm.com/docs/codeengine?topic=codeengine-clicli-jobrun-submit), or [jobrun resubmit](https://cloud.ibm.com/docs/codeengine?topic=codeengine-clicli-jobrun-resubmit) commands.

The following example describes how to reference an existing generic secret with a job by using the CLI.



1. Use the secret create command to create the following two generic secrets for this scenario. By default, a generic secret is created when the --format option is not specified.

ibmcloud ce secret create --name myliteralsecret --from-literal "TARGET=My big literal secret"
Getting generic secret 'mydatabasesec-writer'...
OK

Name: mydatabasesec-writer
ID: abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name: myproject
Project ID: 01234567-abcd-abcd-abcd-abcdabcd1111
Age: 14s
Created: 2020-10-14 13:44:16 -0400 EDT

Data:
---
password: d3h5eg==
username: d3JpdGVy
7. Update the writerjob job to reference the full mydatabasesec-writer secret and use the write_ prefix.

ibmcloud ce job update --name writerjob --env-from-secret write_=mydatabasesec-writer
8. (Optional) View details of the updated writerjob job. The job fully references the mydatabasesec and the mydatabase-writer secrets.

ibmcloud ce job get -n writerjob

Example output

Getting job 'writerjob'...
OK

Name: writerjob
ID: abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name: myproject
Project ID: 01234567-abcd-abcd-abcd-abcdabcd1111
Age: 4m2s
Created: 2021-02-12T07:12:08-06:00
[...]

Commands:
env
Environment Variables:
Type Name Value
Secret full reference mydatabasesec
Secret full reference write_=mydatabasesec-writer
Image: busybox
Resource Allocation:
CPU: 1
Memory: 4G

Runtime:
Array Indices: 0
Max Execution Time: 7200
Retry Limit: 3
9. Run a job that uses the writerjob job.
* Create a secret by using the --from-env-file option to point to a file that contains one or more lines that match the format KEY=VALUE. Each line from the specified file is added as a key-value pair. Any lines in the specified file that are empty or begin with are ignored. For this example, use a file that is named secrets_multi.txt, which contains the key-value pairs: sec1=mysec1, sec2=mysec2, and sec3=mysec3.

ibmcloud ce secret create --name mysecretmulti --from-env-file secrets_multi.txt



If you want to create (or update) a generic secret from a file, use the --from-file option with one of the following formats: --from-file FILE or --from-file KEY=FILE In Code Engine, when you use the --from-file option to specify secret values, all the contents within the file is the value for the key-value pair. When you use the option format of --from-file KEY=FILE, the KEY is name of the environment variable that is known to your job or app. When you use the option format of --from-file FILE, FILE is the name of the environment variable that is known to your job or app. If your file contains one or more key-value pairs, use the --from-env-file option to add an environment variable for each key-value pair in the specified file. Any lines in the specified file that are empty or begin with are ignored.

To display the details of the generic secret, myliteralsecret,

ibmcloud ce secret get --name myliteralsecret

Example output

Getting secret 'myliteralsecret'...
OK

Name: myliteralsecret
ID: abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Format: generic
Project Name: myproject
Project ID: 01234567-abcd-abcd-abcd-abcdabcd1111
Age: 66s
Best practices for organizing secrets and assigning access 

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



 Review the hierarchy of resources in your account 

As you use Secrets Manager to design your secrets management strategy, consider the hierarchy of resources in your IBM Cloud account and how they inherit the access policies that you assign to them. Determine ahead of time which users or service IDs require access to manage secrets. By defining a circle of trust, you help to reduce the risk of compromised credentials.



1. Use resource groups to organize the Secrets Manager instances that you want a group of developers in your account to use. To create a resource group, go to Manage > Account > Account resources > Resource groups.

If the resource groups in your account are organized by project environment level, for example development, test, and production, create a Secrets Manager instance for each resource group so that you can separate your secrets according to each phase of development. For more information about using resource groups, see [What makes a good resource group strategy?](https://cloud.ibm.com/docs/account?topic=account-account_setupresource-group-strategy)
2. Use access groups to organize the users and services IDs that require the same level of access to a Secrets Manager instance. To create an access group, go to Manage > Access (IAM) > Access groups.

For example, you can create a single access group, such as Admin-Group, for the users or service IDs that require administrator access to resources in a resource group, including your Secrets Manager instance. This way, you can assign a single policy to the access group rather than an individual policy for each user or service ID. For more information about using access groups, see [What makes a good access group strategy?](https://cloud.ibm.com/docs/account?topic=account-account_setupaccessgroup_strategy)







 Organize secrets in your Secrets Manager instance by using secret groups 

Use secret groups to narrow the scope of access to specific secrets at an instance level.



1.
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.

--search (string)
: Filter secrets that contain the specified string. The fields that are searched include: id, name, description, labels, secret_type.

Usage: If you want to list only the secrets that contain the string "text", use ../secrets/{secret_type}?search=text.

The maximum length is 128 characters.

--sort-by (string)
: Sort a list of secrets by the specified field.

Usage: To sort a list of secrets by their creation date, use ../secrets/{secret_type}?sort_by=creation_date.

Allowable values are: id, creation_date, expiration_date, secret_type, name.

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

You can apply multiple filters by using a comma-separated list of secret group IDs. If you need to filter secrets that are in the default secret group, use the default keyword.

Usage: To retrieve a list of secrets that are associated with an existing secret group or the default group, use ..?groups={secret_group_ID},default.

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





 Examples 

ibmcloud secrets-manager all-secrets --limit=1 --offset=0 --search=exampleString --sort-by=id --groups=exampleString







 ibmcloud secrets-manager secret 

Get a secret and its details by specifying the ID of the secret.

A successful request returns the secret data that is associated with your secret, along with other metadata.
Are community plug-ins for Vault supported by Secrets Manager? 

Currently, Secrets Manager offers foundational capabilities that don't exist in upstream Vault but are required to support operations for Secrets Manager as a managed service. These capabilities include a set of secrets engines to support secrets of various types in Secrets Manager, and an IBM Cloud Auth method that handles authentication between Vault and your IBM Cloud account.

Secrets Manager will continue to align with upstream Vault capabilities and plug-ins as it extends its support for more secrets engines in coming quarters. Keep in mind that plug-ins or components that are offered by the open source Vault community might not work with Secrets Manager, unless they are written against a [secret type](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secretsecret-types) that Secrets Manager currently supports.





 Can I manage IBM Cloud secrets by using an on-premises Vault? 

If you're looking to manage IBM Cloud secrets through the full Vault native experience, you can use the stand-alone IBM Cloud plug-ins for Vault. These open source plug-ins can be used independently from each other so that you can manage IBM Cloud secrets through your on-premises Vault server.



* To set up authentication between Vault and your IBM Cloud account, you can use the [IBM Cloud Auth Method plug-in for Vault](https://github.com/ibm-cloud-security/vault-plugin-auth-ibmcloud).
* To dynamically create API keys for IBM Cloud service IDs, you can use the [IBM Cloud Secrets Backend plug-in for Vault](https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud).







 I'm not familiar with Vault. Can I still use Secrets Manager? 

Yes. To use Secrets Manager, you don't need to install Vault or the IBM Cloud plug-ins for Vault. You can try Secrets Manager for free, without needing an extensive background on how to use Vault. To get started, [choose the type of secret](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secret) that you want to create.
For more information on how to create a Secrets Manager object, see [here](https://cloud.ibm.com/apidocs/secrets-manager?code=go).







 Evaluate a secret property 

Use the secretPropertyObject.GetCurrentValue(entityId, entityAttributes) method to evaluate the value of the secret property. GetCurrentValue returns the secret value based on the evaluation.

entityId := "john_doe"
entityAttributes := make(map[string]interface{})
entityAttributes["city"] = "Bangalore"
entityAttributes["country"] = "India"

getSecretRes, detailedResponse, err := secretPropertyObject.GetCurrentValue(entityId, entityAttributes)



* entityId: entityId is a string identifier related to the Entity against which the property will be evaluated. For example, an entity might be an instance of an app that runs on a mobile device, a microservice that runs on the cloud, or a component of infrastructure that runs that microservice. For any entity to interact with App Configuration, it must provide a unique entity ID.
* entityAttributes: entityAttributes is a map of type map[string]interface{} consisting of the attribute name and their values that defines the specified entity. This is an optional parameter if the property is not configured with any targeting definition. If the targeting is configured, then entityAttributes must be provided for the rule evaluation. An attribute is a parameter that is used to define a segment. The SDK uses the attribute values to determine if the specified entity satisfies the targeting rules, and returns the appropriate property value.







 How to access the payload secret data from the response 

//make sure this import statement is added
import (sm "github.com/IBM/secrets-manager-go-sdk/secretsmanagerv1")

secret := getSecretRes.Resources[0].(sm.SecretResource)
secretData := secret.SecretData.
Managing key-value secrets with Vault CLI 

If you already use HashiCorp Vault, you can use the command-line interface (CLI) to interact with IBM Cloud® Secrets Manager to manage your [key-value secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-key-value&interface=ui). All operations follow the guidelines that are available for the Vault CLI.

Before you get started, [configure the Vault CLI](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-configure-vault-cli) so that you're able to access your Secrets Manager instance by using Vault commands. To learn more about using the Vault CLI, check out the Vault documentation.

To use the standard CLI for Secrets Manager, check out the [Secrets Manager CLI reference](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-cli).



 Create or update a key-value secret 

Create a version of a key-value secret.

vault kv put [-format=FORMAT] ibmcloud/kv/SECRET_NAME [KEY_VALUE_PAIRS]

Create a version of a key-value secret in a custom group.

vault kv put [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME [KEY_VALUE_PAIRS]



 Prerequisites 

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





 Command options 

-format
: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.





 Example 

Create or update the payload of a key-value secret.

vault kv put ibmcloud/kv/example-kv-secret key1=value1 key2=value2
Release notes for Secrets Manager 

Use these release notes to learn about the latest changes to IBM Cloud® Secrets Manager that are grouped by date.

For the latest changes to the APIs, check out the [Secrets Manager API change log](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-api-change-log).



 19 April 2023 

Now available: CLI v2.0.1
: A new version of the Secrets Manager CLI is now available. In this release, the CLI was updated to address an error that Windows users faced when they attempted to download the plug-in.





 17 April 2023 

Now available: API, SDK, CLI, and Terraform v2.0
: A new version of the Secrets Manager API and SDKs is now available. The following updates are included in this release.



* You no longer need to include secret_type in the API URL to identify a secret.
* The secret group name must be unique per Secrets Manager instance.
* Resources updates are defined as HTTP patch operations.
* The configurations API follows the pattern of the Secrets Manager API. config_type acts as the API discriminator, similarly to secret_type.
* Configurations are modeled as openAPI composites with metadata and data parts, similarly to the Secrets Manager model. Mappings between IAM roles and configurations API follow the same pattern for the Secrets Manager API. For example, an IAM viewer can list configurations to view their metadata.
* List operations return metadata only for secret, secret version, and config resources.
* The action to rotate a secret is now the create a new secret version API: POST/v2/secrets/{id}/versions.
* The action to restore secret version is now the create a new secret version API with the restored_from_version body parameter.
* The action to delete IAM credentials is now the delete a secret version data API: DELETE /v2/secrets/{id}/versions/{version_id}/secret_data.
* Policies API is now embedded into the metadata API in version 2.0.
"data": {
"secret_group_id": "d2e98a96-18ed-f13c-8dee-db955fb94122",
"secret_id": "c86946e6-b392-2613-159d-aff5a3f095b3",
"versions": [
{
"alias": "current",
"id": "ad6aa6d9-b43c-4bc3-597d-15c376622e64",
"locks":
"lock-for-app-1"
],
"payload_available": true
}
]
},
"wrap_info": null,
"warnings": null,
"auth": null
}







 Unlock a secret 

Delete one or more locks that are associated with the current version of a secret.

A successful request deletes the locks that you specify. To remove all locks, you can pass {"locks": [""]} in the request body. Otherwise, specify the names of the locks that you want to delete. For example, {"locks": ["lock1", "lock2"]}.

A secret is considered unlocked and able to be revoked or deleted only after all of its locks are removed. To understand whether a secret contains locks, check the locks_total field that is returned as part of the metadata of your secret.



 Example request 

Remove all locks that are associated with a secret.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/{secret_type}/locks/{secret_id}/unlock" -H 'X-Vault-Token: {Vault-Token}'
-H 'Content-Type: application/json' -D '{
"locks": [""]
}'

Remove two locks from a secret in an existing secret group.
Allowable values for SECRET_TYPE are: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, and username_password.

Get a secret.

vault read [-format=FORMAT] ibmcloud/SECRET_TYPE/secrets/SECRET_ID

Get a secret that is assigned to a specified secret group.

vault read [-format=FORMAT] ibmcloud/SECRET_TYPE/secrets/groups/SECRET_GROUP_ID/SECRET_ID



 Prerequisites 

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





 Command options 

-format
: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.





 Examples 

Retrieve an arbitrary secret, including its payload.

vault read -format=json ibmcloud/arbitrary/secrets/71539dff-9e84-804a-debb-ab3eb3d8afce





 Output 

The command returns the following output:

{
"request_id": "025df8ac-b926-6153-3f5b-cd2364b5f85e",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"created_by": "iam-ServiceId-b7ebcf90-c7a9-495b-8ce8-bbf33cb95ca0",
"creation_date": "2020-10-20T16:55:41Z",
You can include a JSON object with each lock to hold any information that you might need for an automated flow. For example, a key-value pair that identifies the resource that you want to associate with this lock.
8. Optional: Make the lock exclusive.

Choose this option to remove any other locks that match the name that you provided. If any matching locks are found in the previous version of the secret, those locks are deleted when your new lock is created.
9. Optional: Delete previous version data.

Choose this option to also permanently delete the data of the previous secret version if it doesn't have any locks that are associated with it.
10. Click Create.

A new lock is created for your selected secret version.







 Creating a lock on the previous secret version 

You can lock the previous version of a secret by using the Secrets Manager UI. A successful request attaches a new lock to the previous version of your selected secret, or replaces a lock of the same name if it already exists.



3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to lock, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Locks > Create lock.
5. Add a name and description to easily identify the lock.
6. From the list of versions to lock, select Previous.
7. Optional: Attach JSON attributes to your lock.

You can include a JSON object with each lock to hold any information that you might need for an automated flow. For example, a key-value pair that identifies the resource that you want to associate with this lock.
8. Click Create.

A new lock is created for your selected secret version.









 Creating locks from the CLI 

You can create up to 1000 locks on a secret by using the Secrets Manager CLI.