Skip to content

APIm Hybrid Deployment Guide

Introduction

This documentation page relates to the installation of the client (On-Prem / Private Cloud) part of the API Management platform in a Hybrid architecture (SaaS + On-prem / Private cloud).

Hybrid Architecture

Hybrid Architecture

SaaS Components

Component Description
Administration Console
(for API producers)		 This web UI gives easy access to some key APIM API services. API Publishers can use it to publish APIs.
Administrators can also configure global platform settings and specific portal settings.
Dev / API Portal
(for API consumers)		 This web UI gives easy access to some key APIM API services. API Consumers can use it to search for, view, try out and subscribe to a published API.
They can also use it to manage their applications.
Management API This RESTful API exposes services to manage and configure the APIM Console and APIM Portal web UIs.
All exposed services are restricted by authentication and authorization rules. For more information, see the API Reference section.
SaaS API Gateways APIM Gateway is the core component of the APIM platform. You can think of it like a smart proxy.

Unlike a traditional HTTP proxy, APIM Gateway has the capability to apply policies (i.e., rules) to both HTTP requests and responses according to your needs. With these policies, you can enhance request and response processing by adding transformations, security, and many other exciting features.
Bridge Gateways A bridge API Gateway exposes extra HTTP services for bridging HTTP calls to the underlying repository (which can be any of our supported repositories: MongoDB, JDBC and so on)
Config Database All the API Management platform management data, such as API definitions, users, applications and plans.
S3 Bucket + Analytics Database Analytics and logs data
[Optional]
Cockpit		 Cockpit is a centralized, multi-environments / organizations tool for managing all your Gravitee API Management and Access Management installations in a single place.
[Optional]
API Designer		 Drag-and-Drop graphical (MindMap based) API designer to quickly and intuitively design your APIs (Swagger / OAS) and even deploy mocked APIs for quick testing.
[Optional]
Alert Engine		 Alert Engine (AE) provides APIM and AM users with efficient and flexible API platform monitoring, including advanced alerting configuration and notifications sent through their preferred channels, such as email, Slack and using Webhooks.
AE does not require any external components or a database as it does not store anything. It receives events and sends notifications under the conditions which have been pre-configured upstream with triggers.

On-prem / Private cloud components

Component Description
Gravitee.io APIm Gaetway APIM Gateway is the core component of the APIM platform, smartly proxing trafic applying policies.
Logstash Collect and send local Gateways logs and metrics to the Gravitee.io APIM SaaS Control Plane.
Redis Database use locally for rate limits synchronized counters (RateLimit, Quota, Spike Arrest) and optionnaly as an external cache for the Cache policy.

Hybrid Architecture Connections

Self-Hosted (Hybrid) gateway

Installation

Online documentation and assets

Prerequisites

Steps :

  1. Add the Gravitee.io Helm charts repository. 
    helm repo add graviteeio https://helm.gravitee.io
  2. Install using the values.yaml file.
    Here is the full values.yaml example, please customize it following the Configuration sections. 
    helm install graviteeio-apim3x graviteeio/apim3 -f values.yaml

Online documentation

Local file structure

.
├── config
│   ├── gateway
│   │   └── gravitee.yml # (1)
│   └── logstash
│       └── logstash.conf # (2)
├── docker-compose.yml
├── logs
│   └── apim-gateway-dev
└── plugins # (3)
    ├── gravitee-apim-repository-hazelcast-3.18.3.zip
    └── gravitee-apim-repository-redis-3.18.3.zip
  1. If you prefer to override the default gravitee.yml configuration file, instead of using the environement variables in the docker-compose.yml file.
  2. Logstash configuration file.
  3. Additional plugins location.

Download plugins

Download plugins

Online documentation

Configuration

There is at least 3 connections to configure :

  • The connection to the SaaS Management plane with the Bridge Gateway.
  • The connection to push Analytics and Logs with file or tcp reporter pushing data for logstash to send them to the SaaS storage.
  • The connection the local rate limits database.
  • [Optional] The connection to the SaaS Alert Engine.

Management

Into the values.yaml configuration file :

values.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
management:
  type: http
gateway:
  management:
    http:
      url: https://bridge-gateway-url:bridge-gateway-port
      username: kubernetes://<namespace>/secrets/<my-secret-name>/<my-secret-key>
      password: kubernetes://<namespace>/secrets/<my-secret-name>/<my-secret-key>
      # ssl:
      #   trustall: true
      #   verifyHostname: true
      #   keystore:
      #     type: jks # Supports jks, pem, pkcs12
      #     path: ${gravitee.home}/security/keystore.jks
      #     password: secret
      #   truststore:
      #     type: jks # Supports jks, pem, pkcs12
      #     path: ${gravitee.home}/security/truststore.jks
      #     password: secret
      # proxy:
      #   host:
      #   port:
      #   type: http
      #   username:
      #   password:

Online documentation

docker-compose.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
version: '3.5'

services:
  gateway:
    image: graviteeio/apim-gateway:${APIM_VERSION:-3.18.3}
    container_name: gio_apim_gateway
    restart: always
    ports:
      - "8082:8082"
    environment:
      # --- BRIDGE GATEWAYS ---
      - gravitee_management_type=http
      - gravitee_management_http_url=https://bridge-gateway-url:bridge-gateway-port
      - gravitee_management_http_authentication_basic_username=bridge-gateway-username
      - gravitee_management_http_authentication_basic_password=bridge-gateway-password

Into the gravitee.yml configuration file :

gravitee.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
management:
  type: http
  http:
    url: https://bridge-gateway-url:bridge-gateway-port
    keepAlive: true
    idleTimeout: 30000
    connectTimeout: 10000
    authentication:
      basic:
        username: bridge-gateway-username
        password: bridge-gateway-password
    ssl:
      trustAll: true
      verifyHostname: true
      keystore:
        type: # can be jks / pem / pkcs12
        path:
        password:
      trustore:
        type: # can be jks / pem / pkcs12
        path:
        password:

Online documentation

Analytics and Logs

Files

Into the values.yaml configuration file :

values.yaml
1
2
3
4
5
6
7
gateway:
  reporters:
    tcp:
      enabled: true
      host: logstash
      port: 8379
      output: elasticsearch
Direct (TCP)

Warning

Choosing the direct connection may result in a loss of data. If the connection between the gateway and logstash is broken the newly generated analytics and logs data will be lost.

Into the values.yaml configuration file :

values.yaml
1
2
3
4
5
6
7
gateway:
  reporters:
    tcp:
      enabled: true
      host: logstash
      port: 8379
      output: elasticsearch

Online documentation

docker-compose.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
version: '3.5'

services:
  gateway:
    image: graviteeio/apim-gateway:${APIM_VERSION:-3.18.3}
    container_name: gio_apim_gateway
    restart: always
    ports:
      - "8082:8082"
    environment:
      # --- LOGSTASH ---
      - gravitee_reporters_elasticsearch_enabled=false
      - gravitee_reportealert-engine-usernamers_tcp_enabled=true
      - gravitee_reporters_tcp_host=logstash
      - gravitee_reporters_tcp_port=8379
      - gravitee_reporters_tcp_output=elasticsearch
gravitee.yml
1
2
3
4
5
6
7
8
reporters:
  elasticsearch:
    enabled: false # Is the reporter enabled or not (default to true)
  tcp:
    enabled: true
    host: logstash-host
    port: logstash-port
    output: elasticsearch

Rate limits

values.yaml
1
2
3
4
5
6
7
ratelimit:
  type: redis
redis:
  host: 'redis-host'
  port: 6379
  password: 'redis-password'
  download: true

Online documentation

docker-compose.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
version: '3.5'

services:
  gateway:
    image: graviteeio/apim-gateway:${APIM_VERSION:-3.18.3}
    container_name: gio_apim_gateway
    restart: always
    ports:
      - "8082:8082"
    environment:
      # --- RATE LIMIT REPO ---
      - gravitee_ratelimit_type=redis
      - gravitee_ratelimit_redis_host=redis-host
      - gravitee_ratelimit_redis_port=6379
      - gravitee_ratelimit_redis_password=${REDIS_PASS:-redis-password}
gravitee.yml
1
2
3
4
5
6
7
ratelimit:
  # type: hazelcast
  type: redis
  redis:
    host: redis-host
    port: 6379
    password: redis-password

Alert Engine

Into the values.yaml configuration file :

values.yaml
1
2
3
4
5
6
7
8
alerts:
  enabled: true
  endpoints:
    - https://alert-engine-url:alert-engine-port
  security:
    enabled: true
    username: alert-engine-username
    password: alert-engine-password

Online documentation

docker-compose.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
version: '3.5'

services:
  gateway:
    image: graviteeio/apim-gateway:${APIM_VERSION:-3.18.3}
    container_name: gio_apim_gateway
    restart: always
    ports:
      - "8082:8082"
    environment:
      # --- ALERT ENGINE ---
      - gravitee_alerts_alertengine_enabled=true
      - gravitee_alerts_alertengine_ws_discovery=true
      - gravitee_alerts_alertengine_ws_endpoints_0=https://alert-engine-url:alert-engine-port
      - gravitee_alerts_alertengine_ws_security_username=alert-engine-username
      - gravitee_alerts_alertengine_ws_security_password=alert-engine-password
gravitee.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
alerts:
  alert-engine:
    enabled: true
    ws:
      discovery: true
      endpoints:
        - https://alert-engine-url:alert-engine-port
      security:
        username: alert-engine-username
        password: alert-engine-password

Cockpit

Follow cockpit instructions

Please follow directly the instruction you have on cockpit. https://cockpit.gravitee.io/accounts/YOUR-ACCOUNT-HRID/installations/how-to

Full example

Into the values.yaml configuration file :

values.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
management:
  type: http
gateway:
  management:
    http:
      url: https://bridge-gateway-url:bridge-gateway-port
      username: kubernetes://<namespace>/secrets/<my-secret-name>/<my-secret-key>
      password: kubernetes://<namespace>/secrets/<my-secret-name>/<my-secret-key>
  reporters:
    tcp:
      enabled: true
      host: logstash
      port: 8379
      output: elasticsearch
alerts:
  enabled: true
  endpoints:
    - https://alert-engine-url:alert-engine-port
  security:
    enabled: true
    username: alert-engine-username
    password: alert-engine-password

Online documentation

docker-compose.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
version: '3.5'

services:
  gateway:
    image: graviteeio/apim-gateway:${APIM_VERSION:-3.18.3}
    container_name: gio_apim_gateway
    restart: always
    ports:
      - "8082:8082"
    depends_on:
      - rate-limit
      - logstash
    volumes:
      # --- LOCAL LOG FILES ---
      - ./logs/apim-gateway-dev:/opt/graviteeio-gateway/logs
      # --- EE LICENSE FILE ---
      # - ${GIO_LICENSE}:/opt/graviteeio-gateway/license/license.key
      # --- ADDITIONAL PLUGINS ---
      - ./plugins:/opt/graviteeio-gateway/plugins-ext
      - ./config/gateway/gravitee.yml:/opt/graviteeio-gateway/config/gravitee.yml:ro
    environment:
      # --- PLUGINS LOCATIONS ---
      - gravitee_plugins_path_0=/opt/graviteeio-gateway/plugins
      - gravitee_plugins_path_1=/opt/graviteeio-gateway/plugins-ext
      # --- COCKPIT ORGS & ENVS ---
      - gravitee_organizations=dorian-se
      - gravitee_environments=dev
      # --- SHARDING TAGS & TENANTS ---
      - gravitee_tags=internal
      # - gravitee_tenant=xxx
      # --- BRIDGE GATEWAYS ---
      - gravitee_management_type=http
      - gravitee_management_http_url=https://bridge-gateway-url:bridge-gateway-port
      - gravitee_management_http_authentication_basic_username=bridge-gateway-username
      - gravitee_management_http_authentication_basic_password=bridge-gateway-password
      # --- RATE LIMIT REPO ---
      - gravitee_ratelimit_type=redis
      - gravitee_ratelimit_redis_host=rate-limit
      - gravitee_ratelimit_redis_port=6379
      - gravitee_ratelimit_redis_password=${REDIS_PASS:-redis-password}
      # - gravitee_ratelimit_type=hazelcast
      # --- LOGSTASH ---
      - gravitee_reporters_elasticsearch_enabled=false
      - gravitee_reportealert-engine-usernamers_tcp_enabled=true
      - gravitee_reporters_tcp_host=logstash
      - gravitee_reporters_tcp_port=8379
      - gravitee_reporters_tcp_output=elasticsearch
      # --- ALERT ENGINE ---
      # - gravitee_alerts_alertengine_enabled=true
      # - gravitee_alerts_alertengine_ws_discovery=true
      # - gravitee_alerts_alertengine_ws_endpoints_0=https://alert-engine-url:alert-engine-port
      # - gravitee_alerts_alertengine_ws_security_username=alert-engine-username
      # - gravitee_alerts_alertengine_ws_security_password=alert-engine-password
      # --- SECRETS ---
      - gravitee_api_properties_encryption_secret=your-own-api-32-caracters-secret

  rate-limit:
    # https://hub.docker.com/_/redis?tab=tags
    image: redis:${REDIS_VERSION:-7.0.4-alpine3.16}
    container_name: gio_ratelimit_redis
    hostname: redis
    restart: always
    ports:
      - '6379:6379'
    command: redis-server --requirepass ${REDIS_PASS:-redis-password}
    volumes: 
      - redis_data:/data

  logstash:
    # https://www.docker.elastic.co/r/logstash/logstash-oss 
    image: docker.elastic.co/logstash/logstash-oss:8.3.2
    ports:
      - "8379:8379"
    volumes:
      - ./config/logstash:/usr/share/logstash/pipeline:ro
    environment:
      LS_JAVA_OPTS: "-Xmx256m -Xms256m"

volumes:
  redis_data:
    driver: local
gravitee.yml
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
############################################################################################################
#################################### Gravitee.IO Gateway - Configuration ###################################
############################################################################################################

############################################################################################################
# This file is the general configuration of Gravitee.IO Gateway:
# - Properties (and respective default values) in comment are provided for information.
# - You can reference other property by using ${property.name} syntax
# - gravitee.home property is automatically set-up by launcher and refers to the installation path. Do not override it !
#
# Please have a look to http://docs.gravitee.io/ for more options and fine-grained granularity
############################################################################################################

organizations: cockpit-org-hrid
environments: cockpit-env-hrid
tags: your, sharding, tags #example: internal

plugins:
  path:
    - /opt/graviteeio-gateway/plugins
    - /opt/graviteeio-gateway/plugins-ext

management:
  type: http
  http:
    url: https://bridge-gateway-url:bridge-gateway-port
    authentication:
      basic:
        username: bridge-gateway-username
        password: bridge-gateway-password

ratelimit:
  # type: hazelcast
  type: redis
  redis:
    host: redis-host
    port: 6379
    password: redis-password

cache:
  type: ehcache

reporters:
  elasticsearch:
    enabled: false # Is the reporter enabled or not (default to true)
  tcp:
    enabled: true
    host: logstash-host
    port: logstash-port
    output: elasticsearch

services:
  core:
    http:
      enabled: true
      port: 18082
      host: localhost
      authentication:
        type: basic
        users:
          admin: internal-api-password

  sync:
    delay: 5000
    unit: MILLISECONDS
    distributed: false # By enabling this mode, data synchronization process is distributed over clustered API gateways.
    bulk_items: 100 # Defines the number of items to retrieve during synchronization (events, plans, api keys, ...).

  local:
    enabled: false
    path: ${gravitee.home}/apis # The path to API descriptors

  monitoring:
    delay: 5000
    unit: MILLISECONDS
    distributed: false # By enabling this mode, data monitoring gathering process is distributed over clustered API gateways.

  metrics:
    enabled: false
    prometheus:
      enabled: true

  tracing:
    enabled: false

api:
  properties:
    encryption:
      secret: your-own-api-32-caracters-secret

alerts:
  alert-engine:
    enabled: true
    ws:
      discovery: true
      endpoints:
        - https://alert-engine-url:alert-engine-port
      security:
        username: alert-engine-username
        password: alert-engine-password

classloader:
  legacy:
    enabled: false

Redis

Installation

docker-compose.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
version: '3.5'

services:
  rate-limit:
    # https://hub.docker.com/_/redis?tab=tags
    image: redis:${REDIS_VERSION:-7.0.4-alpine3.16}
    container_name: gio_ratelimit_redis
    hostname: redis
    restart: always
    ports:
      - '6379:6379'
    command: redis-server --requirepass ${REDIS_PASS:-redis-password}
    volumes: 
      - redis_data:/data

volumes:
  redis_data:
    driver: local

Configuration

Easy peasy

No specific configuration is needed.

Logstash

Installation

docker-compose.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
version: '3.5'

services:
  logstash:
    # https://www.docker.elastic.co/r/logstash/logstash-oss 
    image: docker.elastic.co/logstash/logstash-oss:8.3.2
    ports:
      - "8379:8379"
    volumes:
      - ./config/logstash:/usr/share/logstash/pipeline:ro
    environment:
      LS_JAVA_OPTS: "-Xmx256m -Xms256m"

Configuration

logstash.conf
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
input {
  tcp {
      port => 8379
      codec => "json"
  }
}

filter {
    if [type] != "request" {
        mutate { remove_field => ["path", "host"] }
    }
}

output {
  s3 {
    access_key_id => "${S3_ACEESS_KEY_ID}"
    secret_access_key => "${S3_SECRET_ACCESS_KEY}"
    region => "${S3_REGION}"
    bucket => "${S3_BUCKET_NAME}"
    size_file => 10485760
    codec => "json_lines"
  }
}

Online documentation