<commit_before>= Configure cache
:page-sidebar: apim_3_x_sidebar
:page-permalink: apim/3.x/apim_installguide_cache.html
:page-folder: apim/installation-guide/cache
:page-description: Gravitee.io API Management - Cache
:page-keywords: Gravitee.io, API Platform, API Management, API Gateway, oauth2, openid, documentation, manual, guide, reference, api
:page-layout: apim3x


== Overview

Caches are used to store different types of data in APIM.

They use a https://docs.hazelcast.org/docs/rn/index.html#3-12-12[Hazelcast^] implementation. You can tune the configuration in the `hazelcast.xml` file.

== Default configuration

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>

<hazelcast xmlns="http://www.hazelcast.com/schema/config"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.hazelcast.com/schema/config
           http://www.hazelcast.com/schema/config/hazelcast-config-4.1.xsd">

    <network>
        <join>
            <!-- Multicast is disabled by default to avoid latency when starting gateway -->
            <multicast enabled="false" />
        </join>
    </network>

    <map name="apikeys">
        <!-- Eviction is managed programmatically-->
        <eviction-policy>NONE</eviction-policy>
        <max-size>0</max-size>
    </map>

    <map name="subscriptions">
        <!-- Eviction is managed programmatically-->
        <eviction-policy>NONE</eviction-policy>
        <max-size>0</max-size>
    </map>

    <map name="apis">
        <!-- Eviction is managed programmatically-->
        <eviction-policy>NONE</eviction-policy>
        <!-- no restriction on the number of API to share -->
        <max-size>0</max-size>
    </map>
</hazelcast>
----

By default, the configuration contains 3 maps to cache API keys, subscriptions and APIs.

WARNING: Be careful when modifying the default configuration, it is designed with performance in mind.

== How are cache resources managed in APIM?

API publishers can create cache resources:

- to cache upstream of a response with the link:/apim/3.x/apim_policies_cache.html[Cache policy^].
- to cache access tokens with the link:/apim/3.x/apim_policies_oauth2.html[OAuth2 policy^].

Default distribution comes with link:/apim/3.x/apim_resources_cache.html[Gravitee Resource Cache].
This plugin store content in memory and is shared between nodes if your installation contains several nodes.

You can define default cache usage in the `hazelcast.xml` configuration file, as in the following example:

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>

<hazelcast xmlns="http://www.hazelcast.com/schema/config"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.hazelcast.com/schema/config
           http://www.hazelcast.com/schema/config/hazelcast-config-4.1.xsd">

    <!-- If you want to define default configuration for all resources  -->
    <map name="cache-resources_*">
        <eviction-policy>LRU</eviction-policy>
        <max-size>100</max-size>
        <time-to-live-seconds>60</time-to-live-seconds>
        <max-idle-seconds>60</max-idle-seconds>
    </map>

    <!-- If you want to define default configuration for `my-cache` resource  -->
    <map name="cache-resources_my-cache_*">
        <eviction-policy>LRU</eviction-policy>
        <max-size>100</max-size>
        <time-to-live-seconds>60</time-to-live-seconds>
        <max-idle-seconds>60</max-idle-seconds>
    </map>

</hazelcast>
----

You can find more information in the https://docs.hazelcast.org/docs[Hazelcast documentation^], also if you need to configure Hazelcast as cluster.

=== Need a persistent cache ?

Since 3.10, we provide a new link:/apim/3.x/apim_resources_cache_redis.html[Gravitee Resource Cache Redis] based on https://redis.io/documentation[Redis].
This plugin is not in distribution by default, but you can https://download.gravitee.io/#graviteeio-apim/plugins/resources/gravitee-resource-cache-redis/[download] plugin and follow link:/apim/3.x/apim_installguide_docker_customize.html#install_an_additional_plugin[instructions] to install it.
<commit_msg>docs(cache): improve doc on hazelcast cache<commit_after>= Configure cache
:page-sidebar: apim_3_x_sidebar
:page-permalink: apim/3.x/apim_installguide_cache.html
:page-folder: apim/installation-guide/cache
:page-description: Gravitee.io API Management - Cache
:page-keywords: Gravitee.io, API Platform, API Management, API Gateway, oauth2, openid, documentation, manual, guide, reference, api
:page-layout: apim3x


== Overview

Caches are used to store different types of data in APIM.

They use a https://docs.hazelcast.org/docs/rn/index.html#3-12-12[Hazelcast^] implementation. You can tune the configuration in the `hazelcast.xml` file.

== Default configuration

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>

<hazelcast xmlns="http://www.hazelcast.com/schema/config"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.hazelcast.com/schema/config
           http://www.hazelcast.com/schema/config/hazelcast-config-4.1.xsd">

    <network>
        <join>
            <!-- Auto-detection and multicast are disabled by default to avoid latency when starting local / standalone  gateway -->
            <auto-detection enabled="false"/>
            <multicast enabled="false" />
        </join>
    </network>

    <map name="apikeys">
        <!-- Eviction is managed programmatically-->
        <eviction eviction-policy="NONE" size="0"></eviction>
    </map>

    <map name="subscriptions">
        <!-- Eviction is managed programmatically-->
        <eviction eviction-policy="NONE" size="0"></eviction>
    </map>

    <map name="apis">
        <!-- Eviction is managed programmatically-->
        <eviction eviction-policy="NONE" size="0"></eviction>
    </map>
</hazelcast>
----

WARNING: Be careful when modifying the default configuration, it is designed with performance in mind.

By default, the configuration contains 3 maps to cache API keys, subscriptions and APIs.
These caches can be shared between nodes if you configure hazelcast to be able to contact the other nodes.
There are multiple ways to configure hazelcast networking depending on your installation (regular VMs, Kubernetes, AWS, ...).
The simplest way is enabling multicast:

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>

<hazelcast xmlns="http://www.hazelcast.com/schema/config"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.hazelcast.com/schema/config
           http://www.hazelcast.com/schema/config/hazelcast-config-4.1.xsd">

    <network>
        <join>
            <auto-detection enabled="false"/>
            <!-- Enable multicast to allow hazelcast discovers other nodes -->
            <multicast enabled="true" />
        </join>
    </network>
</hazelcast>
----

NOTE: You can find more information in the https://docs.hazelcast.org/docs[Hazelcast documentation^], also if you need to configure Hazelcast as cluster.

== How are cache resources managed in APIM?

API publishers can create cache resources:

- to cache upstream of a response with the link:/apim/3.x/apim_policies_cache.html[Cache policy^].
- to cache access tokens with the link:/apim/3.x/apim_policies_oauth2.html[OAuth2 policy^].

Default distribution comes with link:/apim/3.x/apim_resources_cache.html[Gravitee Resource Cache].
This plugin stores content in memory and is locally managed on each gateway node of the installation.

Configuration of cache resources cannot be managed using the `hazelcast.xml` file. The configuration is directly defined on the cache resource. See link:/apim/3.x/apim_resources_cache.html[Resource Cache^].

=== Need a persistent cache ?

Since 3.10, we provide a new link:/apim/3.x/apim_resources_cache_redis.html[Gravitee Resource Cache Redis] based on https://redis.io/documentation[Redis].
This plugin is not in distribution by default, but you can https://download.gravitee.io/#graviteeio-apim/plugins/resources/gravitee-resource-cache-redis/[download] plugin and follow link:/apim/3.x/apim_installguide_docker_customize.html#install_an_additional_plugin[instructions] to install it.

{'fraction_non_alphanumeric': 0.12481875302078299, 'fraction_numerical': 0.01220396326727888, 'mean_word_length': 3.5155482815057284, 'pattern_counts': {'":': 0, '<': 94, '<?xml version=': 4, '>': 94, 'https://': 8, 'lorem ipsum': 0, 'www.': 16, 'xml': 20}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '832595', 'n_tokens_mistral': 2637, 'n_tokens_neox': 2519, 'n_words': 677}