vania-janet/multiturn-rag-retrieval-data huggingface dataset:
This release includes the following updates:



* Added options for setting the SECRETS_MANAGER_URL. You can now either define your Secrets Manager service endpoint URL once by setting an environment variable (for example export SECRETS_MANAGER_URL), or you can override the value on the command-level by using the --service-url INSTANCE flag.
* Added support for using the Secrets Manager CLI plug-in to interact with a service instance over a private network connection.
* Fixed an issue in the [config-update](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-configuration-update-command) command for IAM credential secrets.
* Updated command descriptions.







 Version 0.1.12 

Version 0.1.12 was released on 20 September 2021. This release includes the following updates:



* Added support for the public_cert secret type.
: The legacy credentials password that is required for applications to access the service instance. This field displays only if the Use both legacy credentials and IAM option is chosen.

host
: The hostname that is used by applications to locate the service instance. This field displays only if the Use both legacy credentials and IAM option is chosen.

port
: The HTTPS port number for accessing the service instance on the host. It's 443 as only HTTPS access is allowed by IBM Cloudant. This field displays only if the Use both legacy credentials and IAM option is chosen.

url
: The HTTPS URL to access the IBM Cloudant instance. If the Use both legacy credentials and IAM option is chosen, it also includes the embedded legacy username and password.

apikey
: The IAM API key.

iam_apikey_description
: Description of the IAM API key.

iam_apikey_name
: ID of the IAM API key.

iam_role_crn
: The IAM role that the IAM API key has.

iam_serviceid_crn
: The CRN of the service ID.





 Authentication 

IBM Cloudant has two authentication methods available at provisioning time, either Use only IAM or Use both legacy credentials and IAM. You can see the details about your legacy credentials in the service credentials only if the Use both legacy credentials and IAM authentication method is chosen. The credentials display on the Service credentials tab for your instance. For more information, see the [IAM guide](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-managing-access-for-cloudant) and [legacy authentication](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-work-with-your-accountauthentication) document for details about using either style of authentication.

The IBM Cloudant team recommends you use IAM access controls for authentication whenever possible.
"version_id" : "7bf3814d-58f8-4df8-9cbd-f6860e4ca973",
"version_alias" : "current",
"locks" : "lock-3", "lock-4" ],
"payload_available" : true
}, {
"version_id" : "5bf89b0c-df55-c8d5-7ad6-8816951c6784",
"version_alias" : "previous",
"locks" : "lock-example-1", "lock-example-2" ],
"payload_available" : true
} ]
}









 Configurations 

Create and manage configurations so that you can work with specific types of secrets.



 ibmcloud secrets-manager configuration-create 

Add a configuration to the specified secret type.

Use this operation to define the configurations that are required to create public certificates (public_cert), private certificates (private_cert) and IAM Credentials secrets (iam_credentials).

You can add multiple configurations for your instance as follows:



* A single configuration for IAM Credentials.
* Up to 10 CA configurations for public certificates.
* Up to 10 DNS configurations for public certificates.
* Up to 10 Root CA configurations for private certificates.
* Up to 10 Intermediate CA configurations for private certificates.
* Up to 10 Certificate Template configurations for private certificates.



ibmcloud secrets-manager configuration-create --configuration-prototype CONFIGURATION-PROTOTYPE



 Command options 

--configuration-prototype ([ConfigurationPrototype](https://cloud.ibm.com/docs/secrets-manager-cli-plugin?topic=secrets-manager-cli-plugin-secrets-manager-clicli-configuration-prototype-example-schema))
: The details of your configuration. Required.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --configuration-prototype=@path/to/file.json.





 Example
"iam_serviceid_crn": "crn:v1:staging:public:iam-identity::a/abcdabcd719f45b98a931f6e20db1bd8::serviceid:ServiceId-ee6394cb-f203-4c3c-9152-ac886a3f66bb",
"resource_instance_id": "crn:v1:staging:public:cloud-object-storage:global:a/abcdabcd719f45b98a931f6e20db1bd8:abcdabcd-34b3-4edf-95b7-abcdabcdabcd::"
},
"name": "Cloud Object Storage-56",
"plan": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
"resourcekey_name": "ce-service-access-c5yn1",
"resourcekey_id": "abcdabcd-96e0-46ef-b805-31288524f194"
}
]
}





 Prefix method 

With the prefix method, for each credential variable in a service credential object, that variable is provided individually to your environment by using the common environment variable syntax of capital letters that are separated by underscores, such as VARIABLE_NAME.

By default, the variable name is the name of the service, followed by the name of credential variable. For example, an IBM Cloud Object Storage service credential variable that is named apikey is available in an environment variable that is called CLOUD_OBJECT_STORAGE_APIKEY. The following example shows the environment variables that are created for an IBM Cloud Object Storage service instance binding.

CLOUD_OBJECT_STORAGE_APIKEY=xxxxxx
CLOUD_OBJECT_STORAGE_ENDPOINTS=https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints
Example 

ibmcloud secrets-manager configuration --name=configuration-name --x-sm-accept-configuration-type=private_cert_configuration_root_ca







 ibmcloud secrets-manager configuration-update 

Update a configuration.

ibmcloud secrets-manager configuration-update --name NAME [--api-key API-KEY] [--lets-encrypt-environment LETS-ENCRYPT-ENVIRONMENT] [--lets-encrypt-private-key LETS-ENCRYPT-PRIVATE-KEY] [--lets-encrypt-preferred-chain LETS-ENCRYPT-PREFERRED-CHAIN] [--cloud-internet-services-apikey CLOUD-INTERNET-SERVICES-APIKEY] [--cloud-internet-services-crn CLOUD-INTERNET-SERVICES-CRN] [--classic-infrastructure-username CLASSIC-INFRASTRUCTURE-USERNAME] [--classic-infrastructure-password CLASSIC-INFRASTRUCTURE-PASSWORD] [--max-ttl MAX-TTL] [--crl-expiry CRL-EXPIRY] [--crl-disable CRL-DISABLE] [--crl-distribution-points-encoded CRL-DISTRIBUTION-POINTS-ENCODED] [--issuing-certificates-urls-encoded ISSUING-CERTIFICATES-URLS-ENCODED] [--allowed-secret-groups ALLOWED-SECRET-GROUPS] [--ttl TTL] [--allow-localhost ALLOW-LOCALHOST] [--allowed-domains ALLOWED-DOMAINS] [--allowed-domains-template ALLOWED-DOMAINS-TEMPLATE] [--allow-bare-domains ALLOW-BARE-DOMAINS] [--allow-subdomains ALLOW-SUBDOMAINS] [--allow-glob-domains ALLOW-GLOB-DOMAINS] [--allow-any-name ALLOW-ANY-NAME] [--enforce-hostnames ENFORCE-HOSTNAMES] [--allow
You must add a depends_on Terraform meta-argument and refer it to your IAM configuration resource. The depends_on meta-argument instructs Terraform to complete all actions on the IAM configuration before you perform actions on the IAM credentials secrets.

The following example shows a configuration that you can use to create IAM credentials.

resource "ibm_sm_iam_credentials_secret" "test_iam_credentials_secret" {
instance_id = local.instance_id
region = local.region
service_id = "ServiceId-f4b2deac-fbb5-4bf7-85de-88426701db97"
ttl = "1800"
name = "test-iam-credentials-secret"
reuse_api_key = true
secret_group_id = ibm_sm_secret_group.sm_secret_group_test.secret_group_id
depends_on = [
ibm_sm_iam_credentials_configuration.iam_credentials_configuration
]
}





 Deleting IAM credentials 

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. For more information, see [Managing user API keys](https://cloud.ibm.com/docs/account?topic=account-userapikey).
Reusing the same API key until the lease expires 

IAM credentials consist of a service ID and an API key. By default, the service ID and API key are single-use, ephemeral values that are generated and deleted each time that an IAM credentials secret is read or accessed.

If you'd like to continue to use those credentials through the end of the lease of your secret, you can use the reuse_api_key field. If set to true, your secret retains its current service ID and API key values and reuses them on each read while the secret remains valid. For example, the following example command creates IAM credentials that can be reused until they expire.

ibmcloud secrets-manager secret-create 
--secret-prototype='{"name": "example-iam-credentials-secret","description": "Description of my IAM credentials secret","secret_type": "iam_credentials","secret_group_id": "<secret_group_id>","labels": ["dev","us-south"],"ttl": "30m","access_groups": ["<access_group_id>"],"reuse_api_key": true, "custom_metadata": {"metadata_custom_key": "metadata_custom_value"},"version_custom_metadata": { "custom_version_key": "custom_version_value"}}'

The command outputs 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 about the command options, see [ibmcloud secrets-manager secret-create](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-create-command).

If reuse_api_key is false for IAM credentials, manual rotation for the secret isn't supported.
Integrating with Ansible 

Do you store secrets by using Ansible? Migrate to the IBM Cloud® Secrets Manager Standard plan to maintain any required secrets before you can migrate your operations to use Secrets Manager.



 Before you begin 



1. Create a Standard plan Secrets Manager instance.
2. Create an IAM API key by using a service ID that has SecretReader permissions.







 Retrieving credentials 

By following these steps, you can retrieve Secrets Manager secrets by using Ansible.



1. Create your secrets. The following code samples use key-value and user credentials secrets as examples to demonstrate the retrieval process.
2. Get the ID of the secrets from the secret details panel.
3. Run the following Ansible playbook and set the values of your SM_INSTANCE and IBMCLOUD_API_KEY as extra-vars.
4. Set your user credentials secret ID as the value in the lookup and parsing tasks.



- name: IBM Secrets Manager Standard Example
gather_facts: false
hosts: localhost
connection: local
vars:
api_key: "{{ IBMCLOUD_API_KEY }}"
secret_manager_instance_id: "{{ SM_INSTANCE }}"
region: "us-south"
hostname_vault: "https://{{ secret_manager_instance_id }}.{{ region }}.secrets-manager.appdomain.cloud"
tasks:
- name: Create IAM Token
uri:
url: https://iam.cloud.ibm.com/identity/token
headers:
Content-Type: application/x-www-form-urlencoded
Accept: application/json
body_format: form-urlencoded
method: POST
body:
grant_type: "urn:ibm:params:oauth:grant-type:apikey"
apikey: "{{ api_key }}"
register: login

- block:
- name: Setting IAMtoken
set_fact:
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 

Generate an IAM credential for a secret that is assigned to the default secret group.

vault read -format=json ibmcloud/iam_credentials/creds/test-iam-credentials

Generate an IAM credential for a secret that is assigned to a specified secret group.

vault read -format=json ibmcloud/iam_credentials/creds/groups/9ab2250f-a369-4e07-ade7-d417d63ad587/test-iam-credential-in-group





 Output 

The command returns the following output:

{
"request_id": "48d14d52-ce92-6efc-aeaa-b49cc11eabd6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"access_groups": [
"AccessGroupId-985dc0a3-857b-48bd-b6d6-33819da7ba42"
],
"api_key": "Cg7l3kJveurEry_P7_fLPIBR....(truncated)",
"created_by": "iam-ServiceId-b7ebcf90-c7a9-495b-8ce8-bbf33cb95ca0",
"creation_date": "2020-10-09T17:13:47Z",
"crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/791f5fb10986423e97aa8512f18b7e65:e415e570-f073-423a-abdc-55de9b58f54e::",
* To use the IBM Cloud Secrets Manager secret as the prefix, use the prefixed field option: --field prefix=<crn>. This option is available for IAM credential, username and password, and key value secret types.



--namespace NAMESPACE
: Required. The namespace that the secret is deployed to.

-q
: Optional: Do not show the message of the day or update reminders.

Example to add default, named, and prefixed fields to a set of IAM credentials:

ibmcloud oc ingress secret field add --cluster example-cluster --name example-iam-secret --namespace default --field crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa1a11111aaa1a1111aa1aa111:111a1111-11a1 --field unique_iam_name=crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa1a11111aaa1a1111aa1aa111:111a1111-11a1 --field prefix=crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa1a11111aaa1a1111aa1aa111:111a1111-11a1





 ibmcloud oc ingress secret field ls 

Virtual Private Cloud

Classic infrastructure

View the CRN fields of an Ingress secret. This command applies only to Opaque secrets.

ibmcloud oc ingress secret field ls --cluster CLUSTER --name SECRET_NAME --namespace NAMESPACE [--output OUTPUT] [-q]

Minimum required permissions
: Administrator platform access role for the cluster in IBM Cloud Kubernetes Service

Command options:

--c, --cluster CLUSTER
: Required. The name or ID of the cluster.

--name NAME
: Required. The name of the secret to add the field to.

--namespace NAMESPACE
: Required. The namespace that the secret is deployed to.

--output json
"iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
"iam_serviceid_crn": "crn:v1:staging:public:iam-identity::[...]",
"url": "https://76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
"username": "76838001-b883-444d-90d0-46f89e942a15-bluemix"
}

Each value in the previous JSON example must be interpreted by using the following definitions:

apikey
: IAM API key.

iam_apikey_description
: Description of IAM API key.

iam_apikey_name
: ID of IAM API key.

iam_role_crn
: The IAM role that the IAM API key has.

iam_serviceid_crn
: The CRN of service ID.

url
: IBM Cloudant service URL.

username
: The internal IBM Cloudant account name.

When you select Use both legacy credentials and IAM, the service credentials that are generated contain both IAM and legacy credentials, and look like the values in the following example.

{
"apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
"host": "76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
"iam_apikey_description": "Auto generated apikey during resource-key [...]",
"iam_apikey_name": "auto-generated-apikey-050d21b5-5f[...]",
}

A request to create IAM credentials in an existing secret group returns the following response:

{
"request_id": "2278a441-6dbe-5ee8-4a4b-3b5b1e814231",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"access_groups": [
"AccessGroupId-0529f490-129c-4877-a2a0-b57f50d3e53b"
],
"created_by": "iam-ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0",
"creation_date": "2020-12-16T21:57:13Z",
"crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/a5ebf2570dcaedf18d7ed78e216c263a:0f4c764e-dc3d-44d1-bd60-a2f7cd91e0c0:secret:99425779-0707-4877-81CB-ca11e28b6ef1",
"description": "Extended description for my secret.",
"id": "99425779-0707-4877-81CB-ca11e28b6ef1",
"labels": [
"dev",
"us-south"
],
"last_update_date": "2020-12-16T21:57:13Z",
"name": "test-iam-credentials-in-group",
"secret_group_id": "714e070d-8122-6270-198c-fef9166729e3",
"secret_type": "iam_credentials",
"state": 1,
For example, if you define [certificate authority (CA) and DNS provider configurations](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-add-certificate-authority) for your instance, you can use Secrets Manager to order public certificates (public_cert).

Check out the following image to see how a configuration is structured.

Zoom

![This image shows the components of a secrets engine configuration. The information in the image is detailed in the surrounding content.](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/secrets-manager//images/example-config.svg)

Figure 1. JSON representation of Secrets Manager engine configuration



1. The name and type fields hold identifying information about a configuration.
2. The config object contains the actual configuration details.

When you use the Secrets Manager API to set the configuration of a secret type, the properties that you add to the config object differ depending on the type of configuration that you are adding. For example, the following truncated example shows how the configuration model is represented for a certificate authority (CA) configuration.

{
"name": "my-lets-encrypt-config",
"type": "letsencrypt",
"config": {
"private_key": "-----BEGIN PRIVATE KEY-----nMIICdgIBADANB...(redacted)"
}
}







 How do I get started? 

To get started with secrets, you can go to the Secrets engines page of the Secrets Manager UI, or check out the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2) to learn more about managing secret types programmatically.
Migrating an instance with legacy credentials and IAM Authentication to IAM Only Authentication 

When you create a new service credential by using the IBM Cloud Dashboard or the IBM Cloud CLI, it always produces a new username and password combination. This method applies to legacy credentials as well as a new IAM API key. This tutorial guides you through migrating your instance from generating new legacy credentials and IAM API keys to generating new IAM API keys only.

This tutorial is only applicable to IBM Cloudant instances within resource groups with legacy credentials that are enabled.

See the effects of this tutorial on existing legacy credentials:



* New format legacy credentials (usernames that start with apikey-v2-) continue to function until the service credential is deleted.
* URL style legacy credentials if still active are revoked. If you would like to revoke them separately, follow the [Revoking credential that is tied to your instance URL](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-revoke-instance-url-style-credential) steps before you complete this tutorial.





 Objectives 



1. Update your applications to use IAM credentials instead of legacy credentials.
2. Disable creation of new legacy credentials.







 Step 1: Generating new IBM Cloudant IAM Credentials 



1. Use the IBM Cloud Dashboard or the IBM Cloud CLI to [generate new service credentials](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudantcreating-service-credentials) for your IBM Cloudant instance. For more information, see [Creating service credentials](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-migrating-to-iam-onlycreating-service-credentials) for further instructions.







 Step 2: Updating applications 



1. Update all applications to use IAM access tokens when you authenticate with the IBM Cloudant instance.







 Step 3: Migrating to IAM only 

This operation cannot be undone. Make sure all applications that access the instance are using IAM to authenticate before you start this step.



1.
: 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"}}'







 ibmcloud secrets-manager secret-delete 

Delete a secret by specifying the ID of the secret.

ibmcloud secrets-manager secret-delete --secret-type SECRET-TYPE --id 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}/.





 Examples 

ibmcloud secrets-manager secret-delete --secret-type=arbitrary --id=exampleString







 ibmcloud secrets-manager secret-versions 

List the versions of a secret.

A successful request returns the list of the versions along with the metadata of each version.

ibmcloud secrets-manager secret-versions --secret-type SECRET-TYPE --id 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.
IAM overview 

IBM Cloud Identity and Access Management (IAM) service securely authenticates users and controls access to all resources consistently in the IBM Cloud Platform.

For more information, see the [IAM account overview](https://cloud.ibm.com/docs/account?topic=account-overview).



 Identity Management 

Identity Management includes the interaction of users, services, and resources. Users are identified by their IBMid. Services are identified by their service IDs. And, resources are identified and addressed by using CRNs.

The IBM Cloud IAM Token Service is used to create, update, delete, and use API keys for users and services. Those API keys are created either with API calls or the Identity & Access section of the IBM Cloud® Platform Console. The same key can be used across services. Each user has any number of API keys to support key rotation scenarios, as well as scenarios by using different keys for different purposes to limit the exposure of a single key.

For more information, see [the IAM documentation](https://cloud.ibm.com/docs/account?topic=account-iamoverviewiamoverview).



 Users and API keys 

API keys can be created and used by IBM Cloud users for automation and scripting purposes. API keys can be created in the Identity and Access Management UI or by using the ibmcloud CLI.





 Service IDs and API keys 

Users also can create Service IDs and API keys for Service IDs. A Service ID is similar to a "functional ID" or an "application ID" and is used to authenticate services, and not to represent a user.

Users create Service IDs and bind them to scopes, like a IBM Cloud Platform account, a CloudFoundry organization, or a CloudFoundry space. It is best to bind Service IDs to a IBM Cloud Platform account. This binding is done to give the Service ID a container to live in. This container also defines who can update and delete the Service ID and who can create, update, read, and delete API Keys that are associated to that Service ID. It is important to note that a Service ID is NOT related to a user.





 Key rotation