Storing key-value secrets

Creating key-value secrets in the UI

To add a key-value secret by using the Secrets Manager UI, complete the following steps.

1. In the IBM Cloud console, click the Menu icon > Resource List.

2. From the list of services, select your instance of Secrets Manager.

3. In the Secrets table, click Add.

4. From the list of secret types, select the Key-value tile.

5. Click Next.

6. Add a name and description to easily identify your secret.

7. Select the secret groupThe environment and constraints that contained secrets in an instance must adhere to. A user can be associated with a secret group to enable access and collaboration. that you want to assign to the secret.

   Don't have a secret group? In the Secret group field, you can click Create to provide a name and a description for a new group. Your secret is added to the new group automatically. For more information about secret groups, check out Organizing your secrets.

8. Optional: Add labels to help you to search for similar secrets in your instance.

9. Optional: Add metadata to your secret or to a specific version of your secret.

   1. Upload a file or enter the metadata and the version metadata in JSON format.

10. Click Next.

11. Select a file or enter the secret value that you want to associate with the secret.

    You must enter the key-value data as a JSON object. The maximum file size is 512 KB.

12. Click Next.

13. Review the details of your secret.

14. Click Add.

Creating key-value secrets from the CLI

To create a key-value secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command. For example, the following command creates a key-value secret and stores {"key1":"value1"} as its value.

ibmcloud secrets-manager secret-create  \
  --secret-prototype='{
  "name": "example-kv-secret","description": "Description of my key-value secret.","secret_type": "kv","secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a","labels": ["dev","us-south"],"data": {"key1": "val1","key2": "val2"},"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. For more information about the command options, see ibmcloud secrets-manager secret-create.

Creating key-value secrets with the API

You can create key-value secrets programmatically by using the Secrets Manager API.

The following example shows a query that you can use to create and store a key-value secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

curl -X POST 
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
          "name": "example-kv-secret",
          "description": "Description of my kv secret.",
          "secret_type": "kv",
          "secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
          "labels": [
            "dev",
            "us-south"
          ],
          "data": {
            "key1": "val1",
            "key2": "val2"
          },
          "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 response returns the ID value of the secret, along with other metadata. For more information about the required and optional request parameters, see Create a secret.

Creating key-value secrets with Terraform

You can create key-value secrets programmatically by using Terraform for Secrets Manager.

Follow Terraform best practices for protecting sensitive input variables such as secret credentials. For more information, see Protect sensitive input variables.

The following example shows a configuration that you can use to create a key-value secret by setting sensitive values in a terraform.tfvars file.

1. Define an input variable for the key-value secret data in a variables.tf file.

    variable "kv_secret_data" {
        description = "KV secret data"
        type        = map(any)
        sensitive   = true
    }

2. Assign a value to the kv_secret_data variable in a terraform.tfvars file.

   By setting values with a .tfvars file, you can separate sensitive values from the rest of your variable values, and ensure that your users who work with your configuration know which values are sensitive. For security purposes, you must maintain and share the .tfvars file only with your users who have the appropriate access. You must also be careful not to store .tfvars files with sensitive values into version control such as Github, in clear text.

   kv_secret_data = {
       "key1" : "value1"
   }
   

3. Create the key-value secret in the main.tf file.

The following example shows a configuration that you can use to create a key-value secret.

    resource "ibm_sm_kv_secret" "sm_kv_secret"{
        instance_id = local.instance_id
        region = local.region
        name = "kv-secret-example"
        description = "Extended description for this key-value secret."
        labels = ["my-label"]
        secret_group_id = ibm_sm_secret_group.sm_secret_group_test.secret_group_id
        data = var.kv_secret_data
    }