Using the Caching Service
Using the Caching Service
As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. The Caching Service makes it possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make resource sharing possible for services that cannot be made stateless in two ways:
Using VSAM to store key/value pairs for production
Using InMemory
Note: In the current implementation of the Caching service, VSAM is required for the storage of key/value pairs for production, as VSAM is a native z/OS solution for storing key/value pairs.
The Caching service is available only for internal Zowe applications, and is not exposed to the internet. The Caching service supports a hot-reload scenario in which a client service requests all available service data.
- Architecture
- Storage methods
- How to start the service
- Methods to use the Caching service API
- Configuration properties
- Authentication
#
ArchitectureA precondition to provide for High Availability of all components within Zowe is the requirement for these components to be either stateless, or for the resources of the service to be offloaded to a location accessible by all instances of the service. This condition also applies to recently started instances. Some services, however, are not, and cannot be stateless. The Caching Service is designed for these types of services.
REST APIs make it possible to create, delete, and update key-value pairs in the cache. Other APIs read a specific key-value pair or all key-value pairs in the cache.
Information from cached APIs is stored as a JSON in the following format:
{ “key”: “keyValue”, “value”: “valueValue”}
#
Storage methodsThe Caching Service supports the following storage solutions, which provide the option to add custom implementation.
#
VSAMVSAM can be used to organize records into four types of data sets: key-sequenced, entry-sequenced, linear, or relative record. Use VSAM as the storage solution for production. VSAM is used primarily for applications and is not used for source programs, JCL, or executable modules. ISPF cannot be used to display or edit VSAM files.
For more information about the VSAM storage access method, see Using VSAM as a storage solution through the Caching service.
#
RedisRedis is a common storage solution that runs outside of the z/OS platform. It can store data structures in key-value pairs, has high-availability support, and is highly performant.
For more information about the Redis storage access method, see Using Redis as a storage solution through the Caching service.
#
InfinispanInfinispan is a storage solution that can also run on the z/OS platform. It can store data structures in key-value pairs, has high-availability support, and is highly performant.
For more information about the Infinispan storage access method, see Using Infinispan as a storage solution through the Caching service.
#
InMemoryTODO (add in memory procedure) The InMemory storage method is a method suitable for testing and integration verification. Be sure not to use InMemory storage in production. The key/value pairs are stored only in the memory of a single instance of the service. As such, the key/value pairs do not persist.
#
How to start the serviceBy default, the Caching service starts along with the other Zowe components. To prevent the Caching service from starting, set
components.caching-service.enabled
to false
in zowe.yaml
.
#
Methods to use the Caching service APITo apply a method to the Caching service, use the following API path:
/cachingservice/api/v1/cache/${path-params-as-needed}
Use the following methods with the Caching Service API:
POST /cache
Creates a new key in the Cache
GET /cache
Returns all key/value pairs for specific service
PUT /cache/{key}
Updates the existing value for the given key
GET /cache/{key}
Returns the existing value for the given key
DELETE /cache/{key}
Deletes a key/value pair
#
Configuration propertiesThe Caching Service uses the standard application.yml
structure for configuration. The service is built on top of the Spring enabler. As such, it dynamically registers to the API Mediation Layer. The service appears in the API Catalog under the tile, "Zowe Applications".
caching.storage.size
This property limits the size of the Caching Service. In the VSAM and InMemory implementations, this property represents the number of records stored before the eviction strategy is initiated. The default value is
100
.Note: Different implementations may implement this property differently.
caching.storage.evictionStrategy
This parameter specifies service behavior when the limit of records is reached. The default value is
Reject
.where:
reject
rejects the new item with the HTTP status code
507
when the service reaches the configured maximum numberremoveOldest
removes the oldest item in the cache when the service reaches the configured maximum number
Notes:
- For more information about how to configure the Caching Service in the
application.yml
, see: Add API Onboarding Configuration. - When using VSAM, ensure that you set the additional configuration parameters. For more information about setting these parameters, see Using VSAM as a storage solution through the Caching service.
#
Authentication#
Direct callsCaching service requires TLS mutual authentication. This verifies authenticity of client. Calls without valid client certificate generate 403 response code: Forbidden. This requirement is disabled when VERIFY_CERTIFICATES=false
in zowe-certificates.env
configuration file.
Call must have a header X-Certificate-DistinguishedName
containing information about certificate's distinguished name. This header is added by API Gateway. It needs to be added manually for direct call. Calls without this header produce 401 response code: Unauthorized.
#
Routed calls through API GatewayCaching service registers with the following authentication scheme to Discovery service:
apiml.service.authentication.scheme: x509apiml.service.authentication.headers: X-Certificate-Public,X-Certificate-DistinguishedName,X-Certificate-CommonName
which makes Gateway to attempt mutual authentication with Client and if succesfull, propagate the Client's certificate information to X-Certificate-
headers. With this scheme, Gateway will use it's server/client certificate for the routed call to caching service.