Working with key value maps

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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 key/value String pairs that is either encrypted or unencrypted. Here are two examples:

To learn about other types of persistence, see Adding caching and persistence.

KVM scenarios

Here are some situations where KVMs come in handy:

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 proxy, you can have the proxy detect which environment it's in, execute the related Key Value Map Operations policy, and retrieve the correct target URL from one of the KVMs you created. And later, if one or both of your targets change, you simply update the KVMs with the new URLs. The proxy picks up the new values, and no proxy redeployment is required.
You want to store credentials, private keys, or tokens—like tokens for external services, credentials required to generate OAuth tokens, or private keys used in Java Callouts 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 (always encrypted) 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 places 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.

KVMs have scope

Scope means "where a KVM is available." KVMs can be created at the following scopes: organization, environment, and apiproxy.

For example, if only one API proxy requires data in a KVM, you can create the KVM at the apiproxy scope, where only that API proxy can access the data.

Or you may want all API proxies in your test environment to have access to a key value map, in which case you'd create a key value map at the environment scope. Proxies deployed in the "prod" environment cannot access KVMs in the "test" environment scope. If you want the same KVM keys to be available in production, create a parallel KVM scoped to the "prod" environment.

If you want all proxies in all environments to access the same KVM, create the KVM at the organization scope.

Note: When creating and managing key value maps in the management UI, which this topic covers, you're creating them at the environment scope.

See Managing and using KVMs for information on creating KVMs.

About encrypted KVMs

Encrypted KVMs are encrypted with an Apigee-generated AES-128 cipher key. The key used to encrypt a KVM is stored at the scope of the KVM. For example, within an organization, all encrypted KVMs you create at the environment scope are created using the same environment-scoped key.

Edge handles the display of encrypted values in the following ways. (See Managing and using KVMs for information on creating encrypted KVMs.)

Edge UI

Encrypted key value maps display values masked with asterisks in the UI (*****). For example:

Management API

In the management API, encrypted values are returned masked. Following is sample management API response on a Get encrypted KVM call:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Trace and debug

When you use the Key Value Map Operations policy to retrieve encrypted KVM values, you supply the name of a variable to store the value. To get an encrypted value, you need to add the "private." prefix to the variable name, which prevents the KVM keys/values from appearing in Trace and debug sessions.

Limits

In organizations with Core Persistence Services (CPS) enabled:

The KVM name/identifier is case sensitive.
Key size is limited to 2 KB.
Value size is limited to 10 KB.

For Apigee Edge for Private Cloud, each KVM should not exceed 15MB (this is the combined size of the keys and values). If you exceed this limit, Apigee Edge for Private Cloud returns an error. To determine the size of your KVMs, you can use the nodetool cfstats command.

Larger KVMs can result in performance degradation. As a result, you should split large, monolithic KVMs into smaller ones to improve performance.

Managing and using KVMs

You can create, manage, and use KVMs in a variety of ways. This section describes different options for creating, then retrieving, both encrypted and unencrypted KVMs.

Creating and updating KVMs

You can create and update KVMs in the following ways:

Key Value Map Operations policy (no encryption)

For runtime KVM creation and update by your API proxies, use the Key Value Map Operations policy. (In the policy, you specify the name of the KVM in the mapIdentifier attribute on the parent element.)

Note: The policy doesn't currently support the creation of encrypted KVMs (use the management UI or API for this), but you can update encrypted KVMs with the policy.

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 keys/values are added to the existing KVM alongside the existing keys/values.

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/values are added (or updated if the key already exists). You can use multiple <Put> elements in a KVM policy.
Management API

The management API is for working with KVMs as an administrator rather than during runtime in your API proxies. For example, you may have an internal script that uses the management API to delete and recreate KVMs in a test environment, or you may want to reset a key's value in a KVM for all proxies to pick up. (For runtime manipulation of KVMs, use the Key Value Map Operations policy in your proxies).

The Key/Value Maps management API lets you create, update, and delete encrypted KVMs and keys/values at all scopes (organization, environment, and apiproxy).

To create an encrypted KVM with the management API, add "encrypted" : "true" to the JSON payload. You can only encrypt KVMs when you create them. You cannot encrypt an existing KVM.
Management UI

In the Edge management UI, you can create and update environment-scoped KVMs, which are the only scope of KVM that appears in the UI. The management UI is a good way to manually administer KVM data for API proxies at runtime. See Creating and editing environment key value maps for more information.

Retrieving KVMs

You retrieve encrypted and unencrypted key value maps the same way, with one slight variation when retrieving with the Key Value Map Operations policy.

Policy: Use the <Get> element in the Key Value Map Operations policy to retrieve encrypted and unencrypted KVMs. The one slight difference is retrieving encrypted values with the policy, where you must add a "private." prefix to the name of the variable that will contain the retrieved value, as described in the Get operation section of the reference topic. That prefix hides the value from Trace and debug sessions while you're debugging API proxies.
Management API: For administrative management purposes, you can use the Creating and editing environment key value maps to get KVMs and keys/values. For example, if you want to back up KVMs by getting and storing the JSON definitions, use the management API. Be aware, though, that encrypted values are displayed as ***** in the API response.
Management UI: You can view your environment-scoped KVMs in the management UI by going to APIs > Environment Configuration > Key Value Maps (Classic Edge) or Admin > Environments > Key Value Maps (New Edge).

KVM example

For an example of using a KVM to populate values in a URL, see https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.