Elasticsearch Registry & Components

Many of the shipped configurations make use of variable substitution to reduce repetition.

Apiman components for Elasticsearch.

Global Required Parameters

Name Type Description

client.type

String

The Elasticsearch client type:

  • Default Value: es

client.protocol

Enum

The Elasticsearch protocol to use

  • Default Value: http

  • Allowed Values: http, https

client.indexPrefix

String

Elasticsearch index prefix

  • Default Value: name of component

client.host

String

The ES host

client.port

Integer

The ES port

client.timeout

Integer

Client timeout (milliseconds)

  • Default Value: 10000

  • Allowed Values: 0 infinite timeout or any positive int

Global Optional Parameters

Name Type Description

client.index

String

An alternative Elasticsearch index name.

client.initialize

Boolean

Initialise the storage

client.username

String

Username if using an auth mechanism like SearchGuard, Shield, etc

client.password

String

Password if using an auth mechanism like SearchGuard, Shield, etc

client.keystore.path

String

Path to the client KeyStore

client.keystore.format

Enum

Format of keystore

  • Default Value: jks

  • Allowed Values: pkcs12, jks

client.keystore.password

String

Password for the client KeyStore

client.truststore.path

String

Path to the TrustStore

client.truststore.format

Enum

Format of truststore

  • Default Value: jks

  • Allowed Values: pkcs12, jks

client.truststore.password

String

Password for the TrustStore

client.allowSelfSigned / client.trust.certificate

Boolean

Trust self-signed certificates

  • Default Value: false

client.allowAnyHost / client.trust.host

Boolean

Disable hostname verification checks

  • Default Value: false

client.trustAll

Boolean

Trust all SSL endpoints without any checks (use with great care)

  • Default Value: false

client.pollingTime / client.polling.time

String

Polling frequency for client attempting connection to Elasticsearch (milliseconds). This is only relevant if the client is unable to connect on first attempt.

  • Default Value: 600

Registry

Assign your chosen implementation as shown in the example, providing configuration.

  • Properties (Servlet)

  • JSON (Vert.x)

apiman-gateway.registry=io.apiman.gateway.engine.es.PollCachingESRegistry
{
  "registry": {
    "class": "io.apiman.gateway.engine.es.PollCachingESRegistry",
    "config": {
      // <registry configuration>
    }
  }
}
Table 1. Available implementations:
Implementation Notes

io.apiman.gateway.engine.es.PollCachingESRegistry

Recommended. Works well in multi-node setups.

io.apiman.gateway.engine.es.CachingESRegistry

Works well in single-node setups.

io.apiman.gateway.engine.es.ESRegistry

Only recommended for very low volume or test setups; causes remote calls to be issued on every request.

Required Parameters

Refer also to Global Required Parameters.

Name Type Description

cache-polling-interval

Integer

Cache polling interval in seconds.

  • Default Value: 10

  • Implementations: PollCachingESRegistry

Optional Parameters

Refer also to Global Optional Parameters.

Name Type Description

cache-polling-startup-delay

Integer

Polling startup delay in seconds.

  • Default Value: 30

  • Implementations: PollCachingESRegistry

Metrics

Set the metrics implementation as shown.

  • Properties (Servlet)

  • JSON (Vert.x)

apiman-gateway.metrics=io.apiman.gateway.engine.es.ESMetrics
{
  "metrics": {
    "class": "io.apiman.gateway.engine.es.ESMetrics",
    "config": {
      "client": {
         "type": "es",
         "protocol": "${apiman.es.protocol}",
         "host": "${apiman.es.host}",
         "port": "${apiman.es.port}"
         // <metrics configuration>
       }
     }
  }
}

Set the Apiman Manager metrics accessor implementation to enable Apiman Manager UI to provide some basic visualisations from your Elasticsearch data.

  • A commented-out segment should be in your apiman.properties already.

  • All the same global required and optional options are available.

 
# API Manager metrics settings.
apiman-manager.metrics.type=io.apiman.manager.api.es.EsMetricsAccessor

apiman-manager.metrics.es.client.type=es
# All options available as in global mandatory and optional
apiman-manager.metrics.es.client.protocol=${apiman.es.protocol}
apiman-manager.metrics.es.client.host=${apiman.es.host}
apiman-manager.metrics.es.client.port=${apiman.es.port}

Optional Parameters

Refer also to Global Required Parameters.

Name Type Description

queue.size

Integer

Maximum metrics queue size

  • Default Value: 10000

batch.size

Integer

Maximum metrics batching size

  • Default Value: 1000

custom.headers.request

String[]

Case-insensitive list of request headers to capture, for example X-Correlation-Id.

custom.headers.response

String[]

Case-insensitive list of response headers to capture

custom.query-params

String[]

Case-insensitive list of HTTP query parameters to capture

write-to

String[]

Case-insensitive list of destinations to write Elasticsearch logs.

Rather than solely pushing metrics directly to the Elasticsearch server, Apiman can also write the metrics to a log file as JSON (e.g. for scraping).

  • Default Value: REMOTE

  • Allowed Values: REMOTE, LOG (both permissible at once)

  • File Location:

    • WildFly: standalone/log/metrics.log

    • Tomcat: logs/apiman/metrics.log
For custom header and query param capture, we add entries into the Elasticsearch index dynamically using dynamic templates.

Components

Shared State

Set shared state implementation as shown.

  • Properties (Servlet)

  • JSON (Vert.x)

apiman-gateway.components.ISharedStateComponent=io.apiman.gateway.engine.es.ESSharedStateComponent
apiman-gateway.components.ISharedStateComponent.client.type=es
# <other configuration options>
{
  "components": {
    // Shared State Component Settings
    "ISharedStateComponent": {
      "class": "io.apiman.gateway.engine.es.ESSharedStateComponent",
      "config": {
        "client": {
          "type": "es",
          "protocol": "${apiman.es.protocol}",
          "host": "${apiman.es.host}",
          "port": "${apiman.es.port}"
          //<configuration options>
        }
      }
    }
  }
}

Required Parameters

Refer to Global Required Parameters.

Rate Limiter

Set rate limiter implementation as shown.

  • Properties (Servlet)

  • JSON (Vert.x)

apiman-gateway.components.IRateLimiterComponent=io.apiman.gateway.engine.es.ESRateLimiterComponent
apiman-gateway.components.IRateLimiterComponent.client.type=es
# <configuration options>
{
  "components": {
    // Rate Limiter Component Settings
    "IRateLimiterComponent": {
      "class": "io.apiman.gateway.engine.es.ESRateLimiterComponent",
      "config": {
        "client": {
          "type": "es",
          "protocol": "${apiman.es.protocol}",
          "host": "${apiman.es.host}",
          "port": "${apiman.es.port}"
          // <configuration options>
        }
      }
    }
  }
}

Required Parameters

Refer to Global Required Parameters.

Cache Store

Set cache store implementation as shown.

  • Properties (Servlet)

  • JSON (Vert.x)

apiman-gateway.components.ICacheStoreComponent=io.apiman.gateway.engine.es.EsCacheStoreComponent
apiman-gateway.components.ICacheStoreComponent.client.type=es
# <configuration options>
{
  "components": {
    // Cache Store Component Settings
    "ICacheStoreComponent": {
      "class": "io.apiman.gateway.engine.es.ESCacheStoreComponent",
      "config": {
        "client": {
          "type": "es",
          "protocol": "${apiman.es.protocol}",
          "host": "${apiman.es.host}",
          "port": "${apiman.es.port}"
          // <configuration options>
        }
      }
    }
  }
}

Required Parameters

Refer to Global Required Parameters.