vania-janet/multiturn-rag-retrieval-data huggingface dataset:
If the role belongs to a secret group, the data.secret_group_id value is included in the response to identify the secret group assignment.







 List roles 

Use the following commands to list the roles or secrets in your Secrets Manager instance.

List roles by type.

vault read [-format=FORMAT] ibmcloud/SECRET_TYPE/roles

List roles by secret group ID.

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



 Prerequisites 

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





 Command options 

SECRET_TYPE
: The type of secret that you want to list. Currently, iam_credentials is supported.

SECRET_GROUP_ID
: The ID of the secret group.

-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 a list of IAM credentials.

vault read -format=json ibmcloud/iam_credentials/roles

Retrieve a list of IAM credentials that belong to a specified secret group.

vault read -format=json ibmcloud/iam_credentials/roles/groups/9ab2250f-a369-4e07-ade7-d417d63ad587





 Output 

The command returns the following output:

{
"request_id": "d567207f-b5e6-fc35-086e-fbc465bf3678",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"roles": [
{
"created_by": "iam-ServiceId-b7ebcf90-c7a9-495b-8ce8-bbf33cb95ca0",
"iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/3ag0e9402tyfd5d29761c3e97696b71n:d6f74k03-6k4f-4a82-b165-697354o63903::",
"iam_apikey_name": "auto-generated-apikey-f9274b63-ef0b-4b4e-a00b-b3bf9023f9dd",
"iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
"iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/3ag0e9402tyfd5d29761c3e97696b71n::serviceid:ServiceId-540a4a41-7322-4fdd-a9e7-e0cb7ab760f9",
"resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/3ag0e9402tyfd5d29761c3e97696b71n:d6f74k03-6k4f-4a82-b165-697354o63903::"
}
Show more

You can also use the IBM Cloud CLI to create a new service credential (which is a subset of something called a service key). This example extracts the credential and writes it to a file where the IBM COS SDKs can automatically source the API key and Service Instance ID. First, create the Service Key (called config-example and associated with a COS instance called cos-dev-enablement in this example):
Two ways you can generate an IAM oauth token for authenticating requests are using a curl command with an API key (described later), or from the command line by using [IBM Cloud® CLI](https://cloud.ibm.com/docs/cli?topic=cli-ibmcloud_commands_iamibmcloud_iam_oauth_tokens).



 Request an IAM token by using an API key 

Ensure that you have an API key. You can get one from [IBM Cloud® Identity and Access Management](https://cloud.ibm.com/iam/apikeys).

curl -X "POST" "https://iam.cloud.ibm.com/oidc/token" 
-H 'Accept: application/json' 
-H 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode "apikey={api-key}" 
--data-urlencode "response_type=cloud_iam" 
--data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey"









 Get your resource instance ID 

Some of the following commands require an ibm-service-instance-id parameter. To find this value, go to the Service credentials tab of your Object Storage instance in the cloud console. Create a credential if needed, then use the View credentials menu to see the JSON format. Use the value of resource_instance_id.

For use with curl APIs, you need only the UUID that starts after the last single colon and ends before the final double colon. For example, the ID crn:v1:bluemix:public:cloud-object-storage:global:a/81caa0254631ce5f9330ae427618f209:39d8d161-22c4-4b77-a856-f11db5130d7d:: can be abbreviated to 39d8d161-22c4-4b77-a856-f11db5130d7d.
},
"resources" : [ {
"created_by" : "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21",
"creation_date" : "2022-03-07T13:06:15Z",
"state" : 1,
"state_description" : "Active",
"crn" : "crn:v1:bluemix:public:secrets-manager:us-south:a/a5ebf2570dcaedf18d7ed78e216c263a:f1bc94a6-64aa-4c55-b00f-f6cd70e4b2ce:secret:24ec2c34-38ee-4038-9f1d-9a629423158d",
"description" : "Extended description for this secret.",
"expiration_date" : "2022-03-24T05:06:15Z",
"id" : "24ec2c34-38ee-4038-9f1d-9a629423158d",
"last_update_date" : "2022-03-16T09:55:32Z",
"name" : "example-private-cert-secret",
"secret_group_id" : "bc656587-8fda-4d05-9ad8-b1de1ec7e712",
"secret_type" : "private_cert",
"algorithm" : "SHA256-RSA",
"key_algorithm" : "RSA2048",
"serial_number" : "d9:be:fe:35:ba:09:42:b5",
"certificate_authority" : "test-intermediate-CA",
"certificate_template" : "test-certificate-template",
"issuer" : "example.com",
"common_name" : "localhost",
The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

You can import certificate files that are in the .pem format. Be sure to [convert your PEM files to single-line format](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-troubleshoot-pem) so that they can be parsed correctly by the Secrets Manager API.

curl -X POST
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
"name": "example-imported-certificate",
"description": "description of my imported certificate.",
"secret_type": "imported_cert",
"secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
"labels": [
"dev",
"us-south"
],
"certificate": "-----BEGIN CERTIFICATE-----nMIIE3jCCBGSgAwIBAgIUZfTbf3adn87l5J2Q2Aw+6Vk/qhowCgYIKoZIzj0EAwIwn-----END CERTIFICATE-----",
"intermediate": "-----BEGIN CERTIFICATE-----nMIIE3DCCBGKgAwIBAgIUKncnp6BdSUKAFGBcP4YVp/gTb7gwCgYIKoZIzj0EAwIwn-----END CERTIFICATE-----",
"private_key": "-----BEGIN RSA PRIVATE KEY-----nMIIEowIBAAKCAQEAqcRbzV1wp0nVrPtEpMtnWMO6Js1q3rhREZluKZfu0Q8SY4H3n-----END RSA PRIVATE KEY-----",
"custom_metadata": {
Integrating with Vault Jenkins plug-in 

Are you already using the Vault Jenkins plug-in? You can integrate this tool with IBM Cloud® Secrets Manager to minimize the changes in your setup.



 Before you begin 



1. Be sure that you have the required level of access. You need the [SecretsReader](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iamiam-roles-actions) service role to view secrets.
2. Create an IAM API key by using a service ID that has SecretsReader permissions.







 Setting up the Vault Jenkins plug-in integration 

By following these steps, you can integrate Secrets Manager with the plug-in that you use in your Jenkins job or project. For more information about the Jenkins plug-in, see [Hashicorp Vault](https://plugins.jenkins.io/hashicorp-vault-plugin/).



1. In the Jenkins dashboard, select your job or project where you're using the plug-in.
2. Click Build Environment in the configuration section.
3. Select Vault Plugin.
4. Select Vault Token Credentials from the Credential Authentication Kind field.
5. Create a placeholder value for the Token field (for example, temp).
6. Set an ID (for example, sm-vault-token).
7. Click Add.
8. In the Vault URL field, point to the URL of your Secrets Manager instance.
9. Click Advanced to display the Prefix Path.
10. Set the Prefix Path to ibmcloud/kv.
11. Make sure that the K/V Engine Version is 2.







 Updating the plug-in's Vault token 

You can configure a vault-refresh job to run periodically in order to refresh the Vault token before it expires.



1. Create a periodically repeated job to refresh the token.
export IAM_TOKEN=$(curl -X POST 'https://iam.cloud.ibm.com/identity/token' -H 'Content-Type: application/x-www-form-urlencoded' -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=${IAM_API_KEY}" | jq --raw-output '.access_token')
export NEW_VAULT_TOKEN=$(curl -X PUT -H "X-Vault-Request: true" -d "{"token":"${IAM_TOKEN}"}" ${VAULT_ADDR}/v1/auth/ibmcloud/login | jq --raw-output '.auth.client_token')

printf "<com.datapipe.jenkins.vault.credentials.VaultTokenCredential plugin="hashicorp-vault-plugin@3.8.0"><scope>GLOBAL</scope><id>sm-vault-token</id><description>Vault token for Secrets Manager</description><token>$NEW_VAULT_TOKEN</token></com.datapipe.jenkins.vault.credentials.VaultTokenCredential>" > creds.xml
java -jar jenkins-cli.jar -s https://YOUR-TAAS-JENKINS-INSTANCE-NAME.swg-devops.com/ -auth <Jenkins user>:<user token> update-credentials-by-xml system::system::jenkins '(global)' sm-vault-token < creds.xml

Jenkins user represents the user or FID that you use to run your Jenkins automation. user token is a token that belongs to the user. To obtain a Jenkins API key or token, click the username and select Configure > API token > New Token*.

Provide the values that are associated with your environment. The ID of the Vault token in the XML is the same ID that you assigned in step 2. After you run the job, the Vault token is updated with the real value.
You can also set the output format by using the VAULT_FORMAT environment variable.





 Examples 

Update the details of a role that is assigned to the default group.

vault write -format=json ibmcloud/iam_credentials/roles/091ca93f-5c99-4078-9d7e-4801143030fd/metadata name="new-credential-name"





 Output 

The command returns the following output:

{
"request_id": "cb4672e2-51d9-3a83-f8a2-717afe16e24a",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"access_groups": [
"AccessGroupId-985dc0a3-857b-48bd-b6d6-33819da7ba42"
],
"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::",
"description": "My test IAM credential.",
"id": "091ca93f-5c99-4078-9d7e-4801143030fd",
"labels": [
"test",
"us-south"
],
"last_update_date": "2020-10-09T17:13:47Z",
"name": "new-credential-name",
--H "Authorization: Bearer {iam_token}" --H "Accept: application/json" --H "Content-Type: application/json" --d '{
"config_type": "private_cert_configuration_intermediate_ca",
"name": "example-intermediate-CA",
"common_name": "example.com",
"crl_disable": false,
"crl_distribution_points_encoded": true,
"crl_expiry": "72h",
"issuer": "example-root-CA",
"issuing_certificates_urls_encoded": true,
"max_ttl": "26300h",
"signing_method": "external"
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations"

Copy the CSR from the response JSON data. The CSR value is nested within the value of the data attribute of the response. You can also use the [get configuration](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-configuration) API to get the CSR from the data of the newly created intermediate CA.





 Step 2: Sign an intermediate CA with an external CA 

Use the CSR that you copied in step 1 to sign your intermediate CA certificate. Put the CSR in a file to be used for signing.

You can choose from various tools, such as openssl, to sign a CSR file. For example, the following openssl command takes a CSR file and uses a PEM-encoded CA file and its associated private key to issue a signed CA certificate.

openssl x509 -req -in <intermediate-ca-csr-file> -CA <external-parent-ca-file> -CAkey <external-ca-key-file> -out <signed-intermediate-ca-file>

The command outputs a signed certificate file that you can import into your intermediate CA configuration to complete the signing process.
"AccessGroupId-0529f490-129c-4877-a2a0-b57f50d3e53b"
],
"created_by": "iam-ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0",
"creation_date": "2020-12-16T21:34:51Z",
"crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/a5ebf2570dcaedf18d7ed78e216c263a:0f4c764e-dc3d-44d1-bd60-a2f7cd91e0c0:secret:8bc5eae8-e5b7-9599-de8e-525d1c3e2723",
"description": "Extended description for my secret.",
"id": "8bc5eae8-e5b7-9599-de8e-525d1c3e2723",
"labels": [
"dev",
"us-south"
],
"last_update_date": "2020-12-16T21:34:51Z",
"name": "test-iam-credentials",
"secret_type": "iam_credentials",
"state": 1,
"state_description": "Active",
"ttl": 1800
},
"wrap_info": null,
"warnings": null,
"auth": null
}

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": {
If you uploaded a wildcard certificate, an asterisk is included in the domain name.
* Click the copy symbol next to the secret's ID.
* Create an environment variable pointing to the secret ID:



export SECRET_ID=<secret ID>
6. In Secrets Manager, certificates that you import to the service are imported certificates (imported_cert). Certificates that you order through Secrets Manager from a third-party certificate authority are public certificates (public_cert). This information is needed in the helm chart you will be using later on to configure the ingress. Select and run the command that is appropriate for your selection in the previous step.

export CERTIFICATE_TYPE=imported_cert

or

export CERTIFICATE_TYPE=public_cert
7. Click on Endpoints in the left navigation.
8. Locate the Public endpoint for the Service API.



* Create an environment variable pointing to the endpoint:



export SECRETS_MANAGER_URL=<public endpoint>



In order to access the Secrets Manager service instance from your cluster, we will use the [External Secrets Operator](https://external-secrets.io/) and configure a service ID and API key for it.



1. Create a service ID and set it as an environment variable:

export SERVICE_ID=ibmcloud iam service-id-create kubernetesnodeapp-tutorial --description "A service ID for scalable-webapp-kubernetes tutorial." --output json | jq -r ".id"; echo $SERVICE_ID
2. Assign the service ID permissions to read secrets from Secrets Manager:

ibmcloud iam service-policy-create $SERVICE_ID --roles "SecretsReader" --service-name secrets-manager
3. Create an API key for your service ID:

export IBM_CLOUD_API_KEY=ibmcloud iam service-api-key-create kubernetesnodeapp-tutorial $SERVICE_ID --description "An API key for scalable-webapp-kubernetes tutorial."
"created_by": "iam-ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0",
"creation_date": "2020-12-15T22:46:41Z",
"id": "a09c7a3c-13a5-7a17-fadc-e7850496d27a"
}
]
},
"wrap_info": null,
"warnings": null,
"auth": null
}

A request to import a certificate to the default secret group returns the following response:

{
"request_id": "811b893b-55c7-b6bb-4e55-26a7a8362164",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"algorithm": "RSA",
"common_name": "example.com",
"created_by": "iam-ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0",
"creation_date": "2021-06-03T20:50:11Z",
"crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/a5ebf2570dcaedf18d7ed78e216c263a:0f4c764e-dc3d-44d1-bd60-a2f7cd91e0c0:secret:be4a0846-4cb5-3bfa-bab5-10a44dfc3e85",
"description": "Extended description for my secret.",
"expiration_date": "2021-06-04T15:25:44Z",
softlayer_endpoint_url = "https://api.softlayer.com/rest/v3"
softlayer_iam_endpoint_url = "https://api.softlayer.com/mobile/v3"
softlayer_datacenter = "dal10"

The IAM API key is listed in the Bluemix.iam_api_key section of your CLI output. If the Softlayer.softlayer_api_key is empty at the same time, then the IAM API key is used to determine your infrastructure permissions. The IAM API key is automatically set by the user who runs the first action that requires the IAM Administrator platform access role in a resource group and region. If a different API key is set in Softlayer.softlayer_api_key, then this key takes precedence over the IAM API key. The Softlayer.softlayer_api_key is set when a cluster admin runs the ibmcloud oc credentials-set command.
2. If you want to change the credentials, update the API key that is used.



1. [Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.](https://cloud.ibm.com/docs/containers?topic=containers-access_cluster)
2. To update the IAM API key, use the ibmcloud oc api-key reset[command](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-clics_api_key_reset). To update the IBM Cloud infrastructure key, use the ibmcloud oc credential set[command](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-clics_credentials_set).
3. Wait about 10 - 15 minutes for the storage-secret-store Kubernetes secret to update, then verify that the key is updated.
namespace: <namespace>
resourceVersion: "6145900"
selfLink: /api/v1/namespaces/default/secrets/binding-mycloudant
uid: 33333c33-3c33-33c3-cc33-cc33333333c
type: Opaque
2. Decode the binding value.

echo "<binding>" | base64 -D

Example output

{"apikey":"<API_key>","host":"<ID_string>-bluemix.cloudant.com","iam_apikey_description":"Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloudantnosqldb:us-south:a/<ID_string>::","iam_apikey_name":"auto-generated-apikey-<ID_string>","iam_role_crn":"crn:v1:bluemix:public:iam::::serviceRole:Writer","iam_serviceid_crn":"crn:v1:bluemix:public:iam-identity::a/1234567890brasge5htn2ec098::serviceid:ServiceId-<ID_string>","password":"<ID_string>","port":443,"url":"https://<ID_string>-bluemix.cloudant.com","username":"123b45da-9ce1-4c24-ab12-rinwnwub1294-bluemix"}
3. Optional: Compare the service credentials that you decoded in the previous step with the service credentials that you find for your service instance in the IBM Cloud dashboard.



6. Now that your service is bound to your cluster, you must configure your app to [access the service credentials in the Kubernetes secret](https://cloud.ibm.com/docs/containers?topic=containers-service-bindingadding_app).
[Log in the IBM Cloud.](https://cloud.ibm.com/)
2. Click Manage > Access(IAM) > Authorizations.
3. Click Create.
4. For Source account select This account.
5. For Source service select Cloud Foundry for Custom Domain and leave How do you want to scope the access? as All resources.
6. For Target service select Secrets Manager.
7. Select Resource based on selected attributes.
8. Select Resource Type and set string equals to secret-group.
9. Select Resource and set string equals to the the group ID found in the IBM Cloud Secrets Manager instance, Secret Groups section.
10. For secret access, select SecretsReader.
11. Click Authorize.







 Mapping the SSL certificate to a custom domain 

After authorizing IBM Cloud Foundry to operate on imported certificates you can map your SSL certificate to a custom domain.



1. [Log in the IBM Cloud.](https://cloud.ibm.com/)
2. Click Manage > Account > Cloud Foundry Orgs.
3. Open your Org and switch to the Domains tab.
4. Next to the name of your custom domain, click Map to a certificate.
5. Copy the [CRN from IBM Cloud Secrets Manager](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificates) for your SSL certificate into the text field.



You can also map your SSL certificate using the CLI::

ibmcloud account domain-cert-map YOUR_CUSTOM_DOMAIN SSL_CERT_CRN -o YOUR_ORG_GUID





 Unmap an SSL certificate from a Custom domain 

If your want to have a Cloud Foundry custom domain to not use anymore a mapped SSL certificate, you can unmap it:



1. Click the More actions icon and click Unmap SSL certificate.
2. Click Confirm.
Generating an IBM Cloud IAM token by using an API key 

Generate an IBM Cloud® Identity and Access Management (IAM) token by using either your IAM API key or a service ID's API key. IBM Cloud APIs can be accessed only by users who are authorized by an assigned IAM role. Each user who is calling the API must pass credentials for the API to authenticate.



 Generating an IAM token 

You can generate an IAM token by using either your [IBM Cloud API key](https://cloud.ibm.com/docs/account?topic=account-userapikeyuserapikey) or a [service ID's API key](https://cloud.ibm.com/docs/account?topic=account-serviceidapikeys). The API key is a permanent credential that can be reused if you don't lose the API key value or delete the API key in the account. This process is also used if you are developing an application that needs to work with other IBM Cloud services. You must use a service ID API key to get an access token to be passed to each of the IBM Cloud services.

An access token is a temporary credential that expires after 1 hour at the latest. After the acquired token expires, you must generate a new token to continue calling IBM Cloud or service APIs, and you can perform only actions that are allowed by your level of assigned access within all accounts. Use the response property expires_in in the API response to identify the length of time that your specific access token is valid.





 Generate an IAM token by using an API key 

To programmatically generate an IAM token by using an API key, call the [IAM Identity Services API](https://cloud.ibm.com/apidocs/iam-identity-token-apicreate-api-key) or [SDKs](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdauthentication) as shown in the following sample request.



* Curl
* Java
* Python
* Go
* Node
If the policies are correct, continue with the next step to see if the credentials are valid.

ibmcloud iam service-policies <service_ID_name>

Example output

Policy ID: a111a111-b22b-333c-d4dd-e555555555e5
Roles: Reader
Resources:
Service Name container-registry
Service Instance
Region
Resource Type namespace
Resource <registry_namespace>
3. Check if the image pull secret credentials are valid.



1. Get the image pull secret configuration. If the pod is not in the default project, include the -n option.

oc get secret <image_pull_secret_name> -o yaml [-n <project>]
2. In the output, copy the base64 encoded value of the .dockerconfigjson field.

apiVersion: v1
kind: Secret
data:
.dockerconfigjson: eyJyZWdp...==
...
3. Decode the base64 string. For example, on OS X you can run the following command.

echo -n "<base64_string>" | base64 --decode

Example output

{"auths":{"<region>.icr.io":{"username":"iamapikey","password":"<password_string>","email":"<name@abc.com>","auth":"<auth_string>"}}}
4. Compare the image pull secret regional registry domain name with the domain name that you specified in the container image. By default, new clusters have image pull secrets for each regional registry domain name for containers that run in the default Red Hat OpenShift project. However, if you modified the default settings or are using a different Red Hat OpenShift project, you might not have an image pull secret for the regional registry.