APIM
gravitee-io/apim
Gravitee API Management with your choice of datasource and analytics backend, licensed or not
Deploys a full Gravitee API Management stack (Console, Portal, Gateway, and
Management API). APIM stores its data in PostgreSQL over JDBC and its
analytics in Elasticsearch unless you pick another backend with a --use-*
flag. When a Gravitee license is present it is mounted automatically, and
licensed features such as the Kafka Gateway are one flag away.
Install gck#
go install github.com/gravitee-io-labs/gck@latest
For other installation methods, see Installation .
Usage#
Create#
gck create --from gravitee-io/apim
Each --use-* flag picks one implementation in its group: the datasource
(--use-jdbc-postgres, --use-jdbc-mysql, --use-jdbc-mssql, --use-mongodb)
and the analytics backend (--use-elasticsearch, --use-opensearch). The
Context flags table lists every option and its default. For example, APIM on
MongoDB with OpenSearch:
gck create --from gravitee-io/apim --use-mongodb --use-opensearch
To run without analytics at all, pass --disable-analytics.
To run the gateway alone, without a database, pass --use-dbless. The gateway
is then configured from Kubernetes resources through the Gravitee Kubernetes
Operator, and no console, portal, management API or analytics backend is
deployed:
gck create --from gravitee-io/apim --use-dbless
Kafka Gateway#
The Kafka Gateway is a licensed feature (see License
).
--enable-kafka-gateway deploys a Kafka broker and makes the APIM gateway
its Kafka proxy: clients connect with the Kafka protocol through
*.kafka.gck.local:9092 over TLS.
gck create --from gravitee-io/apim --enable-kafka-gateway
This uses DNS for host-based Kafka routing (*.kafka.gck.local). After
creating the cluster, run the one-time OS setup so these hostnames resolve
on your machine:
gck setup dns
The setup command requires
sudobecause it writes to system directories:/etc/resolver/on macOS, andsystemd-resolvedconfiguration on Linux. Once done, day-to-daygck createandgck deletecommands run without elevated privileges.
See the Networking guide for details.
Cleanup#
gck delete
Quick Start#
Sign in to the Console at http://localhost:30080
with the default admin account (admin / admin).
gck create ends by printing how to reach the datasource you picked. With
the default PostgreSQL:
PGPASSWORD=postgres psql -h localhost -p 30432 -U postgres -d gravitee
To create your first API, follow the Gravitee APIM quick start guide .
With --use-dbless, the gateway is available at
http://localhost:30082
. Define APIs with GKO custom
resources (ApiV4Definition, ApiDefinition), following the
GKO documentation
:
kubectl apply -f my-api.yaml -n gravitee
Connecting a Kafka client#
With --enable-kafka-gateway, extract the TLS certificate from the running
cluster:
kubectl get secret kafka-tls -n gravitee -o jsonpath='{.data.tls\.crt}' | base64 -d > kafka-tls.crt
Then configure your Kafka client properties:
security.protocol=SSL
ssl.truststore.type=PEM
ssl.truststore.location=/path/to/kafka-tls.crt
ssl.endpoint.identification.algorithm=
The ssl.endpoint.identification.algorithm must be set to empty because the
self-signed certificate covers *.kafka.gck.local but broker metadata
addresses use two-level subdomains (e.g. broker-0-acr.kafka.gck.local)
that don’t match the single-level wildcard.
License#
Place your Gravitee license key at $HOME/opt/gravitee/license.key and gck
mounts it into the cluster; without it, everything that does not need a
license runs as usual. Licensed features (flags marked as such) refuse to
start without the file. To use another path, set it at creation time:
gck create --from gravitee-io/apim --set licenseFile=/path/to/license.key
Endpoints
Services this context exposes on your machine after gck create, including the ones it inherits from the contexts it composes. Rows marked with a flag only exist when you pass it; rows marked with an alternative only exist when it is selected, and rows marked not with one disappear when it is.
| Service | URL | Notes | From |
|---|---|---|---|
| APIM Gateway | http://localhost:30082 | gravitee-io/apim/base | |
| Elasticsearch | http://localhost:30920 | with --use-elasticsearch
not with --use-dbless
security disabled | elastic/elasticsearch/standalone |
| PostgreSQL | localhost:30432 | with --use-jdbc-postgres | postgresql/standalone |
| APIM Console | http://localhost:30080 | not with --use-dbless | gravitee-io/apim/base |
| APIM Portal | http://localhost:30081 | not with --use-dbless | gravitee-io/apim/base |
| APIM Gateway (TLS) | https://localhost:30084 | not with --use-dbless | gravitee-io/apim/base |
| APIM API | http://localhost:30083 | not with --use-dbless | gravitee-io/apim/base |
| OpenSearch | http://localhost:30921 | with --use-opensearch
security disabled | opensearch/standalone |
| MSSQL Server | localhost:31433 | with --use-jdbc-mssql | mssql/standalone |
| MySQL | localhost:30306 | with --use-jdbc-mysql | mysql/standalone |
| MongoDB | localhost:30017 | with --use-mongodb
no authentication | mongodb/standalone |
| Kafka Gateway | *.kafka.gck.local:9092 | needs --enable-kafka-gateway
TLS | gravitee-io/apim/kafka-gateway |
| APIM Bridge API | http://localhost:30085 | needs --enable-bridge | gravitee-io/apim/base |
| Alert Engine | ws://alert-engine:8072 | needs --enable-alert-engine
in-cluster only | gravitee-io/apim/base |
Components
What gck create deploys, and which context flags change it.
| Component | Deployed |
|---|---|
elasticsearch | with --use-elasticsearch, not with --use-dbless |
postgresql | with --use-jdbc-postgres |
license | |
tls-server | not with --use-dbless |
apim | |
opensearch | with --use-opensearch |
gko | with --use-dbless |
mssql | with --use-jdbc-mssql |
mssql-init | with --use-jdbc-mssql |
mysql | with --use-jdbc-mysql |
mongodb | with --use-mongodb |
Context flags
Flags you can pass to gck create to customize this context. Flags tagged with a group are mutually exclusive: pass at most one per group, the default applies otherwise.
| Flag | Description |
|---|---|
--use-elasticsearch | Store analytics in Elasticsearch |
--use-opensearch | Store analytics in OpenSearch |
--use-dbless | No datasource: the gateway runs DB-less, configured from Kubernetes resources through GKO implies --disable-ui, --disable-analytics |
--use-jdbc-mssql | Store APIM data in Microsoft SQL Server over JDBC |
--use-jdbc-mysql | Store APIM data in MySQL over JDBC |
--use-jdbc-postgres | Store APIM data in PostgreSQL over JDBC |
--use-mongodb | Store APIM data in MongoDB |
--disable-portal | Disable the developer portal UI |
--disable-ui | Disable both Console and Portal UIs |
--enable-bridge | Enable bridge architecture: management API serves as bridge, gateway syncs through it not with --use-dbless |
--enable-consul | Deploy Consul and configure APIM service discovery |
--enable-distributed-sync | Deploy Redis and enable distributed sync with multiple gateway replicas not with --use-dbless |
--enable-gko | Deploy the Gravitee Kubernetes Operator (GKO) alongside APIM not with --use-dbless |
--enable-hc-vault | Deploy HashiCorp Vault and configure it as a secret provider |
--enable-keycloak | Deploy Keycloak and configure APIM OIDC security provider not with --use-dbless |
--enable-mailhog | Deploy MailHog and configure APIM email settings not with --use-dbless |
--enable-opentelemetry-jaeger | Deploy Jaeger and enable OpenTelemetry tracing on the gateway |
--enable-otel-collector | Export gateway OpenTelemetry traces to a composed otel-collector |
--enable-prometheus | Deploy Prometheus and enable APIM metrics |
--enable-redis | Deploy Redis and use it for gateway rate limiting |
--enable-system-proxy | Deploy mitmproxy and configure APIM HTTP client proxy |
--enable-tags | Configure gateway with sharding tags (internal/external) |
--enable-tcp | Add a TCP protocol listener on the gateway |
--enable-tls | Enable TLS termination on the gateway |
--disable-analytics | Disable analytics: no Elasticsearch or OpenSearch, no analytics reporters |
--enable-alert-engine | Deploy Alert Engine and wire APIM gateway + management API to send alerts (licensed feature, needs the license file) |
--enable-kafka-gateway | Deploy a Kafka broker fronted by the APIM Kafka Gateway (licensed feature, needs the license file) |
--enable-kibana | Deploy Kibana alongside Elasticsearch needs --use-elasticsearch |
--enable-opensearch-dashboards | Deploy OpenSearch Dashboards alongside OpenSearch needs --use-opensearch |
Variables
Template variables overridable with --set. Use --set path.segments.var=value to target a specific context in the composition chain.
| Variable | Default | Origin | Description |
|---|---|---|---|
clusterName | gravitee | gravitee-io/apim/base | Name of the Kind cluster |
imageRepository | postgres | postgresql/standalone | with --use-jdbc-postgres
PostgreSQL Docker image repository |
imageTag | latest | gravitee-io/apim/base | Docker image tag for all APIM components |
postgresDatabase | gravitee | postgresql/standalone | with --use-jdbc-postgres
Database to create on first startup |
imagePrefix | graviteeio | gravitee-io/apim/base | Docker image prefix for all APIM components |
helmVersion | (empty) | gravitee-io/apim/base | Helm chart version constraint |
helmChartLocator | graviteeio/apim | gravitee-io/apim/base | Helm chart reference: repo/chart, oci://registry/path/chart, a path or a URL. An OCI chart needs an explicit helmVersion |
licenseFile | {{ env "HOME" }}/opt/gravitee/license.key | gravitee-io/apim/base | Gravitee license key file, mounted into the gateway and management API when it exists |
jdbcUrl | jdbc:postgresql://postgresql:5432/gravitee | gravitee-io/apim | with --use-jdbc-postgres
JDBC connection URL |
jdbcDriver | https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.4/postgresql-42.7.4.jar | gravitee-io/apim | with --use-jdbc-postgres
JDBC driver download URL |
jdbcUsername | postgres | gravitee-io/apim | with --use-jdbc-postgres
JDBC username |
jdbcPassword | postgres | gravitee-io/apim | with --use-jdbc-postgres
JDBC password |
imageRepository | graviteeio/kubernetes-operator | gravitee-io/gko | with --use-dbless
GKO Docker image repository |
imageRepository | mcr.microsoft.com/mssql/server | mssql/standalone | with --use-jdbc-mssql
MSSQL Server Docker image repository |
saPassword | Password1! | mssql/standalone | with --use-jdbc-mssql
SA account password (must meet MSSQL complexity requirements) |
jdbcUrl | jdbc:sqlserver://mssql:1433;databaseName=gravitee;encrypt=false | gravitee-io/apim | with --use-jdbc-mssql
JDBC connection URL |
jdbcDriver | https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.8.1.jre11/mssql-jdbc-12.8.1.jre11.jar | gravitee-io/apim | with --use-jdbc-mssql
JDBC driver download URL |
jdbcUsername | SA | gravitee-io/apim | with --use-jdbc-mssql
JDBC username |
jdbcPassword | Password1! | gravitee-io/apim | with --use-jdbc-mssql
JDBC password |
imageRepository | mysql | mysql/standalone | with --use-jdbc-mysql
MySQL Docker image repository |
mysqlDatabase | gravitee | mysql/standalone | with --use-jdbc-mysql
Database to create on first startup |
jdbcUrl | jdbc:mysql://mysql:3306/gravitee | gravitee-io/apim | with --use-jdbc-mysql
JDBC connection URL |
jdbcDriver | https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/9.2.0/mysql-connector-j-9.2.0.jar | gravitee-io/apim | with --use-jdbc-mysql
JDBC driver download URL |
jdbcUsername | root | gravitee-io/apim | with --use-jdbc-mysql
JDBC username |
jdbcPassword | mysql | gravitee-io/apim | with --use-jdbc-mysql
JDBC password |
imageRepository | mongo | mongodb/standalone | with --use-mongodb
MongoDB Docker image repository |