When working with Apigee, you'll often need to store configuration data or other values that your API proxies can access. Apigee provides two primary mechanisms for this purpose: Key Value Maps (KVMs) and Property Sets. While they share some similarities, they offer some distinct features and use cases.
Let's start off with Key Value Maps (KVMs):
- Scope: API Proxy, Environment, or Organization level
- Security: Encrypted values for sensitive data (e.g. credentials)
- Location: Only in the case of Apigee hybrid, where the runtime planes can be deployed outside of GCP, it may be important to note that KVM data is stored exclusively in the runtime plane
- Management: No direct UI support; must be managed via Apigee APIs or the Key Value Map Operations policy at runtime. Consider using apigeecli to manage KVMs
- Retrieval: Requires the use of a KeyValueMapOperations policy to access values
- Modifications: Changes are immediately available to the runtime, although KeyValueMapOperations policies may configure a cache.
Next, we can compare these same features with Property Sets:
- Scope: API Proxy or Environment level
- Security: Values are stored in plain text
- Management: API Proxy scoped Property Sets are editable within the online Apigee proxy editor and can be included in your API Proxy bundle when developing outside of the online editor. Environment scoped Property Sets require use of the API or tooling such as apigeecli
- Retrieval: Values are readily accessible within API proxies, no policy execution is needed
- Modifications: Whilst Environment scoped Property Sets are updated directly as environment resources, API Proxy scoped Property Sets require deployment of a new revision. In both cases, changes can take up to a minute to propagate to the runtime.
When to Choose Which
- Security: Select KVMs when storing sensitive data due to the encryption capabilities
- Management: If you need easy UI-based management or frequent updates to API Proxy-level data, Property Sets are a better fit. If you'd like to update values without needing to redeploy anything, KVMs are more appropriate
- Location: For Apigee hybrid deployments, KVMs may be more suitable if it's important for the values to not be persisted in the control plane on GCP
- Access: If you need values immediately available without policy execution, Property Sets are the way to go
Taking this comparison into account, we can start to realise some example use cases for each.
If your API Proxy requires a preset number of configuration variables (e.g. feature switches or parameters that change the behaviour of an API), Property Sets are suitable as they are clearly presented to an API Proxy developer who can review and make decisions on the values when they are building an API Proxy. For example, you may have a property to allow for caching to be toggled -- it's cleaner and easier to change a property instead of fiddling with conditions or trying to temporarily remove policies.
On the other hand, if your API Proxy implements a Spike Arrest policy for rate limiting, you may want to store this as a KVM entry so that it can be modified without requiring a change to any proxy deployments. It's also likely that communication with an API backend requires some static credentials that can occassionally change -- managing those credentials in a KVM would be most suitable, as the values will be encrypted and can be rotated without needing a deployment. Another great use case is to have a KVM entry that can control the availability of an API in the scenario where a backend system was to go down for scheduled maintenance -- this can allow your API Proxy to generate a well-formed response without adding unnecssary load to the unavailable backend. Just make sure you have a sensible default in place (e.g. only one specific value will cause the proxy to enter maintenance mode)
LinkedIn
Twitter