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 sudo because it writes to system directories: /etc/resolver/ on macOS, and systemd-resolved configuration on Linux. Once done, day-to-day gck create and gck delete commands 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.

ServiceURLNotesFrom
APIM Gatewayhttp://localhost:30082gravitee-io/apim/base
Elasticsearchhttp://localhost:30920with --use-elasticsearch not with --use-dbless security disabledelastic/elasticsearch/standalone
PostgreSQLlocalhost:30432with --use-jdbc-postgrespostgresql/standalone
APIM Consolehttp://localhost:30080not with --use-dblessgravitee-io/apim/base
APIM Portalhttp://localhost:30081not with --use-dblessgravitee-io/apim/base
APIM Gateway (TLS)https://localhost:30084not with --use-dblessgravitee-io/apim/base
APIM APIhttp://localhost:30083not with --use-dblessgravitee-io/apim/base
OpenSearchhttp://localhost:30921with --use-opensearch security disabledopensearch/standalone
MSSQL Serverlocalhost:31433with --use-jdbc-mssqlmssql/standalone
MySQLlocalhost:30306with --use-jdbc-mysqlmysql/standalone
MongoDBlocalhost:30017with --use-mongodb no authenticationmongodb/standalone
Kafka Gateway*.kafka.gck.local:9092needs --enable-kafka-gateway TLSgravitee-io/apim/kafka-gateway
APIM Bridge APIhttp://localhost:30085needs --enable-bridgegravitee-io/apim/base
Alert Enginews://alert-engine:8072needs --enable-alert-engine in-cluster onlygravitee-io/apim/base

Components

What gck create deploys, and which context flags change it.

ComponentDeployed
elasticsearchwith --use-elasticsearch, not with --use-dbless
postgresqlwith --use-jdbc-postgres
licensealways
tls-servernot with --use-dbless
apimalways
opensearchwith --use-opensearch
gkowith --use-dbless
mssqlwith --use-jdbc-mssql
mssql-initwith --use-jdbc-mssql
mysqlwith --use-jdbc-mysql
mongodbwith --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.

FlagDescription
--use-elasticsearch
analytics
Store analytics in Elasticsearch default
--use-opensearch
analytics
Store analytics in OpenSearch
--use-dbless
datasource
No datasource: the gateway runs DB-less, configured from Kubernetes resources through GKO
implies --disable-ui, --disable-analytics
--use-jdbc-mssql
datasource
Store APIM data in Microsoft SQL Server over JDBC
--use-jdbc-mysql
datasource
Store APIM data in MySQL over JDBC
--use-jdbc-postgres
datasource
Store APIM data in PostgreSQL over JDBC default
--use-mongodb
datasource
Store APIM data in MongoDB
--disable-portalDisable the developer portal UI
--disable-uiDisable both Console and Portal UIs
--enable-bridgeEnable bridge architecture: management API serves as bridge, gateway syncs through it
not with --use-dbless
--enable-consulDeploy Consul and configure APIM service discovery
--enable-distributed-syncDeploy Redis and enable distributed sync with multiple gateway replicas
not with --use-dbless
--enable-gkoDeploy the Gravitee Kubernetes Operator (GKO) alongside APIM
not with --use-dbless
--enable-hc-vaultDeploy HashiCorp Vault and configure it as a secret provider
--enable-keycloakDeploy Keycloak and configure APIM OIDC security provider
not with --use-dbless
--enable-mailhogDeploy MailHog and configure APIM email settings
not with --use-dbless
--enable-opentelemetry-jaegerDeploy Jaeger and enable OpenTelemetry tracing on the gateway
--enable-otel-collectorExport gateway OpenTelemetry traces to a composed otel-collector
--enable-prometheusDeploy Prometheus and enable APIM metrics
--enable-redisDeploy Redis and use it for gateway rate limiting
--enable-system-proxyDeploy mitmproxy and configure APIM HTTP client proxy
--enable-tagsConfigure gateway with sharding tags (internal/external)
--enable-tcpAdd a TCP protocol listener on the gateway
--enable-tlsEnable TLS termination on the gateway
--disable-analyticsDisable analytics: no Elasticsearch or OpenSearch, no analytics reporters
--enable-alert-engineDeploy Alert Engine and wire APIM gateway + management API to send alerts (licensed feature, needs the license file)
--enable-kafka-gatewayDeploy a Kafka broker fronted by the APIM Kafka Gateway (licensed feature, needs the license file)
--enable-kibanaDeploy Kibana alongside Elasticsearch
needs --use-elasticsearch
--enable-opensearch-dashboardsDeploy 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.

VariableDefaultOriginDescription
clusterNamegraviteegravitee-io/apim/baseName of the Kind cluster
imageRepositorypostgrespostgresql/standalonewith --use-jdbc-postgres PostgreSQL Docker image repository
imageTaglatestgravitee-io/apim/baseDocker image tag for all APIM components
postgresDatabasegraviteepostgresql/standalonewith --use-jdbc-postgres Database to create on first startup
imagePrefixgraviteeiogravitee-io/apim/baseDocker image prefix for all APIM components
helmVersion(empty)gravitee-io/apim/baseHelm chart version constraint
helmChartLocatorgraviteeio/apimgravitee-io/apim/baseHelm 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.keygravitee-io/apim/baseGravitee license key file, mounted into the gateway and management API when it exists
jdbcUrljdbc:postgresql://postgresql:5432/graviteegravitee-io/apimwith --use-jdbc-postgres JDBC connection URL
jdbcDriverhttps://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.4/postgresql-42.7.4.jargravitee-io/apimwith --use-jdbc-postgres JDBC driver download URL
jdbcUsernamepostgresgravitee-io/apimwith --use-jdbc-postgres JDBC username
jdbcPasswordpostgresgravitee-io/apimwith --use-jdbc-postgres JDBC password
imageRepositorygraviteeio/kubernetes-operatorgravitee-io/gkowith --use-dbless GKO Docker image repository
imageRepositorymcr.microsoft.com/mssql/servermssql/standalonewith --use-jdbc-mssql MSSQL Server Docker image repository
saPasswordPassword1!mssql/standalonewith --use-jdbc-mssql SA account password (must meet MSSQL complexity requirements)
jdbcUrljdbc:sqlserver://mssql:1433;databaseName=gravitee;encrypt=falsegravitee-io/apimwith --use-jdbc-mssql JDBC connection URL
jdbcDriverhttps://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.8.1.jre11/mssql-jdbc-12.8.1.jre11.jargravitee-io/apimwith --use-jdbc-mssql JDBC driver download URL
jdbcUsernameSAgravitee-io/apimwith --use-jdbc-mssql JDBC username
jdbcPasswordPassword1!gravitee-io/apimwith --use-jdbc-mssql JDBC password
imageRepositorymysqlmysql/standalonewith --use-jdbc-mysql MySQL Docker image repository
mysqlDatabasegraviteemysql/standalonewith --use-jdbc-mysql Database to create on first startup
jdbcUrljdbc:mysql://mysql:3306/graviteegravitee-io/apimwith --use-jdbc-mysql JDBC connection URL
jdbcDriverhttps://repo1.maven.org/maven2/com/mysql/mysql-connector-j/9.2.0/mysql-connector-j-9.2.0.jargravitee-io/apimwith --use-jdbc-mysql JDBC driver download URL
jdbcUsernamerootgravitee-io/apimwith --use-jdbc-mysql JDBC username
jdbcPasswordmysqlgravitee-io/apimwith --use-jdbc-mysql JDBC password
imageRepositorymongomongodb/standalonewith --use-mongodb MongoDB Docker image repository