vania-janet/multiturn-rag-retrieval-data huggingface dataset:
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.

ibmcloud ce secret create --name SECRET_NAME (--from-env-file FILE | --from-file FILE | --from-file KEY=FILE | --from-literal KEY=VALUE) [--cert-chain-file CERT_CHAIN_FILE] [--email EMAIL] [--format FORMAT] [--key-path KEY_PATH] [--known-hosts-path KNOWN_HOSTS_PATH] [--output OUTPUT] [--password PASSWORD] [--password-from-file PASSWORD_FROM_FILE] [--password-from-json-file PASSWORD_FROM_JSON_FILE] [--private-key-file PRIVATE_KEY_FILE] [--quiet] [--server SERVER] [--username USERNAME]



 Command Options 

--cert-chain-file, --ccf
: Specify a file containing the certificate chain provided by your certificate authority for a TLS secret. You must provide the path to the file as a value. This value is required for tls secrets. This value is optional.

--email, --em
: The email address to access the registry server for a registry secret. This value applies only for registry secrets. This value is optional.

--format, --fo
: The format of the secret. Valid values are basic_auth, generic, registry, ssh, or tls. This value is optional. The default value is generic.

--from-env-file, -e
: Create a generic secret from a file which contains one or more lines that match the format KEY=VALUE.
Migrating to Secrets Manager API v2 

A new version of the IBM Cloud® Secrets Manager API is available. Review the following sections to migrate your services and resources to v2. To learn more, see the [API docs](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2).



 General changes in v2 

Review the following list for the biggest changes that you can expect in v2.



* You must use the [create secret version API](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-secret-version) to rotate secrets.
* Define policies as part of the secret instead of as their own entity.
* You can update the resource metadata by changing only the fields that you want to modify.
* To create and delete locks, you must use locks_bulk.
* Use the lock modes remove_previous and remove_previous_and_delete instead of exclusive and exclusive_delete.
* With the Reader role, you can list configurations of IAM permissions.
* Review the response structure, as it might not be the same as v1.
* For those who created custom roles in IAM - some action names were changed.







 Migrating Curl applications 

If you use curl, review the following steps and examples to migrate to the Secrets Manager API v2.



1. Review the documentation.
2. Replace v1 with v2 and remove the secret type.
3. If the secret or configuration resource has a body, you must add the type of secret into the body.
4. Remove the metadata and resources wrapper from the resource JSON object.
5. If you are using jq or other tools, review the difference in the response structure.



The secret data is at the root of the secret and not under the secret_data field.



 Comparing v1 and v2 Curl examples 

Compare the following examples to see the changes between the v1 Curl code snippet and how the code must look like in v2.

v1 example

curl -X POST --location --header "Authorization: Bearer ${iam_token}"
For more information about how your information is protected, see [Securing your data](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-mng-data).
* What are differences between the Reader and SecretsReader roles?

Both the Reader and SecretsReader roles help you to assign read-only access to Secrets Manager resources.



* As a reader, you can browse a high-level view of secrets in your instance. Readers can't access the payload of a secret.
* As a secrets reader, you can browse a high-level view of secrets, and you can access the payload of a secret. A secrets reader can't create secrets or modify the value of an existing secret.



* How is Secrets Manager different from Key Protect?

There are a few key differences between using Key Protect and Secrets Manager to store your sensitive data. Secrets Manager offers flexibility with the types of secrets that you can create and lease to applications and services on-demand. Whereas, Key Protect delivers on encryption keys that are rooted in FIPS 140-2 Level 3 hardware security modules (HSMs) A physical appliance that provides on-demand encryption, key management, and key storage as a managed service..

For more information, see [Managing secrets in IBM Cloud](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manage-secrets-ibm-cloud).
* How is Secrets Manager different from Vault?

With Secrets Manager, you can centrally manage secrets for your services or apps in a dedicated, single tenant instance. To control who on your team has access to specific secrets, you can create secret groups that map to [Identity and Access Management (IAM)](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam) access policies in your IBM Cloud account. And, you can use [IBM Cloud Activity Tracker](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-at-events) to track how users and applications interact with your Secrets Manager instance.
* Are community plug-ins for Vault supported by Secrets Manager?
"description": "Description of my IAM Credentials secret",
"secret_type": "iam_credentials",
"secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
"labels": [
"dev",
"us-south"
],
"ttl": "30m",
"access_groups": [
"AccessGroupId-45884031-54be-4dd7-86ff-112511e92699",
"AccessGroupId-8c0ed733-dfee-4a94-992b-e2247b86e2a2"
],
"reuse_api_key": true,
"custom_metadata": {
"metadata_custom_key": "metadata_custom_value"
},
"version_custom_metadata": {
"custom_version_key": "custom_version_value"
}
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful request returns the ID value of the secret, along with other metadata. After the secret reaches the end of its lease, the credentials are revoked automatically. For more information, check out the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2).

If reuse_api_key is false for IAM credentials, manual rotation for the secret isn't supported. For more information, see [Manually rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manual-rotation).





 Using an existing service ID in your account 

You might already have a service ID in your account that you want to use to dynamically generate an API key. In this scenario, you can choose to create an IAM credentials secret by bringing your own service ID.
For more information about using Event Notifications to enable lifecycle notifications for your Secrets Manager instance, see [Enabling event notifications](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-event-notifications).





 1 August 2022 

Improved authorization flow
: The documentation for granting service access to domains is now updated to simplify the required flow. To try out the latest updates, see [Granting service access to CIS](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-prepare-order-certificatesauthorize-domains).





 27 July 2022 

CLI plug-in version 0.1.21
: Version 0.1.21 of the Secrets Manager CLI is now available for download. To learn about the latest updates, see the [CLI change log](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-change-log).





 10 July 2022 

Lock secrets to prevent them from being deleted
: You can now attach locks to secrets to indicate that they're in use by one or more consumers. When a secret is locked, it can't be modified or deleted. For more information, check out the following resources:



* [Locking secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secret-locks)
* [Best practices for rotating and locking secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-best-practices-rotate-secrets)



CLI plug-in version 0.1.20
: Version 0.1.20 of the Secrets Manager CLI is now available for download. To learn about the latest updates, see the [CLI change log](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-change-log).





 8 June 2022 

Allow access to Secrets Manager in a restricted account
--quiet, -q
: Specify this option to reduce the output of the command. This value is optional. The default value is false.





 Example 

ibmcloud ce secret delete --name mysecret-genericfromfile -f





 Example output 

Deleting secret mysecret-genericfromfile...
OK







 ibmcloud ce secret get 

Display the details of a secret.

ibmcloud ce secret get --name SECRET_NAME [--decode] [--output OUTPUT] [--quiet]



 Command Options 

--name, -n
: The name of the secret. This value is required.

--decode, -d
: Show the Data output as decoded in the details. If this option is not specified, the Data details are base64-encoded. This value is optional. The default value is false.

--output, -o
: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.

--quiet, -q
: Specify this option to reduce the output of the command. This value is optional. The default value is false.





 Example 

ibmcloud ce secret get --name mysecret-basicauth





 Example output 

Getting secret 'mysecret-basicauth'...
OK

Name: mysecret-basicauth
ID: abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Format: basic_auth
Project Name: myproject
Project ID: 01234567-abcd-abcd-abcd-abcdabcd1111
Age: 66s
Created: 2021-03-10T18:44:18-05:00

Data:
---
password: REDACTED
"type" : "application/vnd.ibm.secrets-manager.secret.policy+json",
"rotation" : {
"interval" : 1,
"unit" : "day"
}
} ]





 SecretResource[] 

The following example shows the format of the SecretResource[] object.

[ {
"name" : "example-arbitrary-secret",
"description" : "Extended description for this secret.",
"secret_group_id" : "bc656587-8fda-4d05-9ad8-b1de1ec7e712",
"labels" : "dev", "us-south" ],
"custom_metadata" : {
"anyKey" : "anyValue"
},
"version_custom_metadata" : {
"anyKey" : "anyValue"
},
"expiration_date" : "2030-01-01T00:00:00Z",
"payload" : "secret-data"
} ]





 UpdateSecretVersionMetadata[] 

The following example shows the format of the UpdateSecretVersionMetadata[] object.

[ {
"version_custom_metadata" : {
"anyKey" : "anyValue"
}
} ]
"description": "Extended description for my secret.",
"payload": "secret-data",
"labels": [
"dev",
"us-south"
],
"expiration_date": "2030-04-01T09:30:00Z"
}'

Create IAM credentials in the default secret group.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/iam_credentials/roles/{secret_name}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -H 'Content-Type: application/json' -d '{
"name": "test-iam-credentials",
"description": "Extended description for my secret.",
"access_groups": [
"AccessGroupId-0529f490-129c-4877-a2a0-b57f50d3e53b"
],
"labels": [
"dev",
"us-south"
],
"ttl": "30m"
}'
Show more

Create IAM credentials in an existing group.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/iam_credentials/roles/groups/{group_id}/{secret_name}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -H 'Content-Type: application/json' -d '{
"name": "test-iam-credentials-in-group",
"description": "Extended description for my secret.",
"access_groups": [
"AccessGroupId-0529f490-129c-4877-a2a0-b57f50d3e53b"
],
As a workaround, during the certificate order process, you can configure a shorter domain name so that it can be used as the certificate CN in your DNS provider. Then, you can order a multi-domain SAN certificate that uses the same shortened domain as the CN, along with longer application domains that are specified as Subject Alternative Names (SANs). 
 Users that have Writer or Manager service access that is scoped to secret groups are unable to create some types of secrets when they use the Secrets Manager UI. If you have Viewer platform access and Writer or Manager service access that is scoped to a Secrets Manager service secret group, it might not be possible to create secrets in the Secrets Manager dashboard that require an engine configuration, for example, IAM credentials, public certificates, or private certificates. As a workaround, you can use the Secrets Manager CLI, APIs, or SDKs to manage those secret types. 
 Community plug-ins for Vault are not supported. It is not possible to integrate a community plug-in for Vault with Secrets Manager, unless it is written against a secrets engine that Secrets Manager supports. To manage IBM Cloud secrets by using the full Vault native experience, use the [stand-alone IBM Cloud plug-ins for Vault](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-faqsfaq-vault-community-plugins). 
 When you delete an instance of the service, your API keys are not deleted from IAM. If you have a service ID or API key that was generated by the IAM credentials secret engine and delete your instance of Secrets Manager, you must also delete the secret from IAM. 







 Limits 

Consider the following service limits as you use Secrets Manager.



 Account limits 

The following limits apply per IBM Cloud account.



Table 1. Secrets Manager limits per account

 Resource Limit 

 Secrets Manager service instances Trial plan: 1 per IBM Cloud account at any time <br>Standard plan: No limit on number of instances per account 







 Instance limits 

The following limits apply to Secrets Manager service instances.



Table 2. Secrets Manager limits per instance

 Resource Limit
Public endpoints for interacting with Secrets Manager by using the native Vault APIs

 Region Endpoint URL 

 Dallas https://{instance_ID}.us-south.secrets-manager.appdomain.cloud 
 Frankfurt https://{instance_ID}.eu-de.secrets-manager.appdomain.cloud 
 London https://{instance_ID}.eu-gb.secrets-manager.appdomain.cloud 
 Osaka https://{instance_ID}.jp-osa.secrets-manager.appdomain.cloud 
 Sao Paulo https://{instance_ID}.br-sao.secrets-manager.appdomain.cloud 
 Sydney https://{instance_ID}.au-syd.secrets-manager.appdomain.cloud 
 Tokyo https://{instance_ID}.jp-tok.secrets-manager.appdomain.cloud 
 Toronto https://{instance_ID}.ca-tor.secrets-manager.appdomain.cloud 
 Washington DC https://{instance_ID}.us-east.secrets-manager.appdomain.cloud 



Ready to try the APIs? To interact with a Swagger UI from your browser, add api/v2/swagger-ui to your service endpoint URL. For example, https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/swagger-ui.





 Private endpoints 

If you need to manage your Secrets Manager resources over a private network, see the following table to determine the API endpoints to use when you connect to the Secrets Manager API.

To learn how to configure your Secrets Manager instance to use private endpoints, see [Securing your connection to Secrets Manager](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-service-connection).



Table 2. Private endpoints for interacting with Secrets Manager by using the native Vault APIs

 Region Endpoint URL 

 Dallas https://{instance_ID}.private.us-south.secrets-manager.appdomain.cloud
* {vault::SECRET_STORE_INTEGRATION_NAME.SECRET_NAME} when you reference secrets that are contained within Key Protect.
* {vault::SECRET_STORE_INTEGRATION_NAME.SECRET_GROUP_NAME.SECRET_NAME} when you reference secrets that are contained within Secrets Manager.
* {vault::SECRET_STORE_INTEGRATION_NAME.SECRET_NAME.FIELD_NAME} when you reference secrets that are contained within HashiCorp Vault.



where:



* SECRET_STORE_INTEGRATION_NAME is the name of the secrets store integration in the toolchain, not the name of the secrets store service instance.
* SECRET_GROUP_NAME is the name of the group that contains the secret within Secrets Manager.
* SECRET_NAME is the name of the secret in the secrets store.
* FIELD_NAME is the name of the field within the HashiCorp Vault secret.



To use a CRN secrets reference, obtain the secret CRN directly from the Secrets Manager UI or programmatically by using the CLI, API, or SDKs.

For more information about managing secrets, see [Managing secrets in your toolchains](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-toolchains-secrets).



 Specifying secrets references by using the console 

When you use the console, the fields for tool integration configuration properties and Delivery Pipeline properties that are classified as secure are annotated with a key icon. Click this icon to open a dialog from which you can select a secrets store and secret. Alternatively, for secrets references by CRN, paste the CRN value directly into the property.





 Specifying secrets references with the API 

You can work with secure properties with secrets reference values in calls to the API, which requires an [IAM bearer token](https://cloud.ibm.com/apidocs/toolchainauthentication). Alternatively, if you are using an SDK, [obtain an IAM API key](https://cloud.ibm.com/iam/apikeys) and set the client options by using environment variables.
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
Project Name: myproject
Project ID: 01234567-abcd-abcd-abcd-abcdabcd1111
Age: 17s
Created: 2020-10-14 14:07:59 -0400 EDT

Data:
---
password: YWJjZA==
username: cmVhZGVy
3. Set an environment variable on a job to reference the full mydatabasesec secret. In this example, let's use the --env-from-secret PREFIX=NAME option where PREFIX=NAME specifies to reference the full configmap where each key is prefixed with PREFIX. By using the read_ prefix, each key is prefixed with read_. Because the busybox image does not print any output by default, the -c env option specifies to print all the environment variables in the container.

ibmcloud ce job create -n demo -i busybox -c env --env-from-secret read_=mydatabasesec

Consider using a prefix to help make sure that all your environment variables in your job or app are unique. For example, if you have a secret with keys, a, b, and c, these environment variables display as a, b, and c. However, if you add a prefix such as read_, then the keys display with the prefix, such as read_a, read_b, and read_c. Using a prefix also groups your environment variables in the referencing app, job, or jobrun, and helps you avoid duplicates of keys in configmaps or secrets.
4. (Optional) View the details of the demo job.
If you accidentally assign a secret to the wrong secret group, or if you don't want a secret to belong to the default secret group, delete the secret and create a new one.
2. Optionally, use secret groups to allow privileged access to specific resources in your account.

Secret groups can be used to grant direct access to resources that otherwise wouldn't be possible through IAM. For example, assume that User A has no access to Service A in IAM. If you create an IAM access policy that assigns User A to Secret Group A, and Secret Group A contains an [IAM credential](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials) with a service ID that gives access to Service A, then you grant User A access to Service A. In this scenario, Secret Group A becomes a gateway to Service A, even if a restriction exists in IAM. Keep in mind that with this scenario it is possible to grant access to a resource unintentionally. Review your configuration carefully to ensure that your secret group assignments do not override your IAM access policies accidentally.
3. Audit your secret groups regularly and remove them when they're no longer needed.

Grant only the minimum access that is required, and delete a secret group when it is no longer needed.

To delete a secret group, it must be empty. If you need to remove a secret group that contains secrets, you must first [delete the secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-delete-secrets) that are part of the group.







 Track your related secrets by adding labels 

Add labels so that you can further search by and categorize the secrets in your instance. When you use a consistent labeling schema, you can easily group similar secrets together.



1. Label your secrets by using a consistent schema, such as creating labels to differentiate which secrets are used for a specific purpose. To add labels by using the Secrets Manager UI, go to the Secrets page, and then select a secret to edits its details.
To set an automatic rotation policy for a secret, see [Set secret policies](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-vault-apivault-set-secret-policies).



Table 8. Rotate secret request parameters

 Request parameters Description 

 payload The new secret data to assign to an arbitrary or a kv secret. 
 password The new password to assign to a username_password secret. 
 certificate The new certificate to assign to an imported_cert secret. 
 private_key The new private key to assign to an imported_cert secret. 
 intermediate The new intermediate certificate data to assign to an import_cert secret. 





 Example requests 

Rotate an arbitrary secret in the default secret group.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/arbitrary/secrets/{secret_id}/rotate" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -d '{
"payload": "new-secret-data"
}'

Rotate an arbitrary secret in an existing secret group.

curl -X POST "https://{instance_id}.{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}.
For more information about adding and removing vault integrations, including prerequisites and by using hints, see [Managing IBM Cloud secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manage-secrets-ibm-cloud).

By using hints within a template, a toolchain is automatically populated with preconfigured secrets; you don't need to manually select secrets from vault integrations that are attached to the toolchain.

This tutorial uses the [IBM Secrets Manager](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-getting-started) as the secrets vault.

Zoom

![Kubernetes secure app secrets options](https://cloud.ibm.com/docs-content/v1/content/562806c0b18119f4d21cb66f5ae6d051634b4a16/ContinuousDelivery/images/ds_kub_setup_secrets.png)

Figure 5. Kubernetes secure app secrets options

IBM Secrets Manager securely stores and applies secrets such as API keys, Image Signature, or HashiCorp credentials that are part of your toolchain.

Zoom

![Kubernetes secure app secrets options](https://cloud.ibm.com/docs-content/v1/content/562806c0b18119f4d21cb66f5ae6d051634b4a16/ContinuousDelivery/images/ds_kub_setup_sm.png)

Figure 6. Kubernetes Secure app secrets options