Using key value maps

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This section discusses how to use key value maps (KVMs).

Overview

There are times when you want to store data for retrieval at runtime—non-expiring data that shouldn't be hard-coded in your API proxy logic. Key value maps (KVMs) are ideal for this. A KVM is a custom collection of encrypted key/value String pairs.

The following lists three broad use cases for storing data in KVMs:

  • User session data: Data that is created and deleted by the runtime only; you cannot view or manage KVM entries outside of the runtime. For example, shopping cart contents.
  • Configuration (such as routing rules and look up tables): Data that is typically created outside of the runtime but is read by the runtime. This data is configured using the UI or API, and then made available to the gateway (as variables or read-only content).

    For example: You have an API proxy that needs to call one target (or Service Callout) URL in a test environment and another target URL in a production environment. Instead of hard-coding URLs in your API proxy, you can have it detect which environment it's in, execute the related KeyValueMapOperations policy, and retrieve the correct target URL from the appropriate KVM.

    Later, if one or both of your targets change, you simply update the KVMs with the new URLs. The API proxy picks up the new values; no redeployment is required.

  • Credentials: Store credentials, private keys, or tokens—such as tokens for external services, credentials required to generate OAuth tokens, or private keys used in JavaCallout policies or JavaScript for encryption or JSON Web Token (JWT) signing. Instead of passing credentials, keys, or tokens in the request, or hard-coding them in your proxy logic, you can store them in a KVM and dynamically retrieve them in calls to targets that require them.

You'll discover other situations where storage of key/value String pairs is useful. In general, consider using KVMs when:

  • Specific sections in your code require different values at runtime.
  • Sensitive data needs to be passed without hard-coding it.
  • You want to store values that don't expire like a cache might.

In some cases, property sets are a good alternative to KVMs as they can be easier to use. For more information, see Using property sets.

About KVM scope

Scope defines where a KVM is available. KVMs can be created at the following scopes:

Scope Description
API proxy Only the API proxy can access the KVM.
Environment All API proxies in a specific environment can access the KVM. For example, you may want API proxies deployed in the prod environment to not have access to KVMs in the test environment. If you want the same KVM keys to be available in production, create a parallel KVM scoped to the prod environment.
Organization All API proxies in all environments can access the KVM.

About KVM encryption

In Apigee, all KVM entries for API proxy, organization and environment scopes are protected using the Cloud KMS key provided when an Apigee organization is provisioned (see the runtimeDatabaseEncryptionKey field in the Organization resource). Apigee uses AES256 as the encryption standard.

In Apigee hybrid, you can provide separate encryption keys for all KVM entries for API proxy, organization and environment scopes. Apigee accepts cipher sizes of AES128, AES196 or AES256 as the encryption standard.

About KVM masking

By default, KVM values are displayed as plain text. You can turn on KVM masking to mask values with asterisks (*****). To turn on or off KVM masking, use the Mask values setting in the UI or the maskedValues flag in your API request.

Values are masked at the KVM level. You can't mask individual KVM entries; either all values within a KVM are masked, or none are.

Note: KVM masking won't be automatically turned on for existing KMVs. You will need to explicitly update existing KVMs to use KVM masking.

Create KVMs

Create KVMs as described in the following sections.

Apigee in Cloud console

To create a new (empty) KVM or view a list of KVMs:

  1. In the Google Cloud console, go to the Management > Environments page.

    Go to Environments

  2. Select the environment you wish to edit from the list of available environments.
  3. Click the Key value maps tab on the Environment details page.

    The Key value maps page displays a list of existing KVMs. If you have not created any KVMs, then the list is empty.

  4. To create a new (empty) KVM, click + Create Key value map.

    The Create key value map dialog opens.

  5. Enter a name for the KVM in the Key value map name field.

    The name can contain only letters, numbers, and hyphens and cannot be longer than 255 characters. It cannot include spaces or other special characters. For example: my-kvm-1

  6. Click Mask values to mask all values. If not selected, KVM values are shown in plain text. See About KVM masking for more information.
  7. Click Create.

    The new KVM is displayed in the list.

Apigee API

Use the Apigee APIs to create, list, and delete KVMs for the following scopes:

KVM Policy

To create KVMs at runtime and update them in your API proxies, use the KeyValueMapOperations policy. In the policy, you specify the name of the KVM in the mapIdentifier attribute on the parent element.

The <InitialEntries> element lets you create and populate a baseline set of entries in a new KVM as soon as you save the policy in the UI or deploy the API proxy (if you developed it offline). If the values change in the policy, the existing values are overwritten. Any new key/value pairs are added to the existing KVM alongside the existing key/value pairs.

The <Put> element creates a new KVM if one doesn't already exist, and it creates a key with one or more values. If the KVM already exists, they key/value pairs are added (or updated if the key already exists). You can use multiple <Put> elements in a KVM policy.

Debug

When you use the KeyValueMapOperations policy to retrieve encrypted KVM values, you supply the name of a variable to store the value. Because all KVM values are encrypted, you need to add the private. prefix to the variable name, which prevents the KVM key/value pairs from appearing in Debug sessions.

Get KVMs

Use the Apigee APIs to get KVMs for the following scopes:

For example, to get an API proxy-scoped KVM, enter a GET request to the following URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Update KVMs

Use the Apigee APIs to update KVMs for the following scopes:

For example, to get an API proxy-scoped KVM, enter a GET request to the following URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Manage KVM values

You can manage KVM values using the API or the KeyValueMapOperations policy, as described in the following sections.

Manage KVM values using the API

Use the Apigee APIs to manage KVM values for the following scopes:

Manage KVM values using the KeyValueMapOperations policy

Use the KeyValueMapOperations policy to add, get, or delete values from KVMs.

Add KVM keys and values using the <Put> element of the KeyValueMapOperations policy. The <Put> element creates a new KVM if one doesn't already exist, and it creates a key with one or more values. If the KVM already exists, the key/value pairs are added (or updated if the key already exists). You can use multiple <Put> elements in a KVM policy. For more information, see <Put> element.

Get KVM values using the <Get> element of the KeyValueMapOperations policy. Because all KVM values are encrypted, add a private. prefix to the name of the variable that will contain the retrieved value. That prefix hides the value from debug sessions while you're debugging API proxies. For more information, see <Get> element.

Delete KVM values using the <Delete> element of the KeyValueMapOperations policy. For more information, see <Delete> element.

Delete KVMs

Delete KVMs as described in the following sections.

Apigee in Cloud console

To delete a KVM:

  1. In the Google Cloud console, go to the Management > Environments page.

    Go to Environments

  2. Select the environment name you wish to edit from the list of available environments.
  3. Click the Key value maps tab on the Environment details page.

    The Key value maps page displays a list of existing KVMs.

  4. Locate the row of the KVM that you want to delete.
  5. Click in the Actions column.
  6. Click Delete Key Value Map in the dialog to confirm the operation.

    The KVM is deleted and removed from the list.

Classic Apigee UI

To delete a KVM:

  1. Sign in to the Apigee UI.
  2. Select Admin > Environments > Key Value Maps.
  3. From the environment drop-down list, select the environment for which you want to delete a KVM.

    The Key Value Maps page displays a list of existing KVMs.

  4. Position your cursor over the KVM that you want to delete.
  5. Click Delete.
  6. Click Delete to confirm the operation.

    The KVM is deleted and removed from the list.

Apigee API

Use the one of the following Apigee APIs to delete a KVM based on it's scope: