Gateway Manager

This application is used to configure Keycloak+Kong installations, locally or as part of a cluster.

Aether Landing Page

An app that serves as a UI for accessing different running services.

Continues in Aether Landing Page README

App

An app represents an application and defines a set of public URLs. The main difference between an app and a service is that the app cannot be added to a realm.

Continues in App README

Service

A service represents an application and defines a set of public and protected URLs and the routes to access to them.

Continues in Service README

Solution

A solution gathers a set of services.

Continues in Solution README

Commands

All the commands are defined in the entrypoint.sh file.

entrypoint.sh {command-name} {rest-of-arguments}

Generic

help

Shows the help message with all the possible commands.

bash

Runs bash inside the container.

eval

Evaluates shell command inside the container.

Keycloak

keycloak_ready

Checks the Keycloak connection. Returns status 0 on success.

add_realm

Adds a new realm in Keycloak using a default realm template.

add_realm {realm} \
          {*description=abc} \
          {*login_theme=abc} \
          {*account_theme=abc} \
          {*admin_theme=abc} \
          {*email_theme=abc}

add_admin

Adds or updates an admin user to an existing realm in Keycloak.

add_user {realm} {username} {*password} {*reset_password_on_first_login}

add_user

Adds or updates a user to an existing realm in Keycloak.

add_user {realm} {username} {*password} {*reset_password_on_first_login}

add_user_group

Adds an existing user to a group on an existing realm in Keycloak.

add_user_group {realm} {username} {group_name}

add_confidential_client or add_oidc_client

Adds a confidential client to an existing realm in Keycloak. Required for any realm that will use OIDC for authentication.

add_confidential_client {realm} {client-name} {*login_theme=abc}
# or
add_oidc_client {realm} {client-name} {*login_theme=abc}

add_public_client

Adds a public client to an existing realm in Keycloak. Allows token generation.

add_public_client {realm} {client-name} {*login_theme=abc}

decode_token

Decodes a Keycloak JSON Web Token (JWT).

decode_token {token}

Kong

kong_ready

Checks the Kong connection. Returns status 0 on success.

add_app or register_app

Registers an app as a service in Kong, using the app definition in APPS_PATH directory.

add_app {app-name}
# or
register_app {app-name}

Note: The expected app file is {APPS_PATH}/{app-name}.json.

remove_app

Removes an app in Kong, using the app definition in APPS_PATH directory.

remove_app {app-name}

Note: The expected app file is {APPS_PATH}/{app-name}.json.

add_service

Adds a service to an existing realm in Kong, using the service definition in SERVICES_PATH directory.

add_service {service-name} {realm} {oidc-client}

Note: The expected service file is {SERVICES_PATH}/{service-name}.json.

remove_service

Removes a service from an existing realm in Kong, using the service definition in SERVICES_PATH directory.

remove_service {service-name} {realm}

# removes service from all realms
remove_service {service-name}
# or
remove_service {service-name} "*"

Note: The expected service file is {SERVICES_PATH}/{service-name}.json.

Note: the service will not be entirely removed if it's still used by another realm.

add_solution

Adds a package of services to an existing realm in Kong, using the solution definition in SOLUTION_PATH directory.

add_solution {solution-name} {realm} {oidc-client}

Note: The expected solution file is {SOLUTION_PATH}/{solution-name}.json.

remove_solution

Removes a package of services from an existing realm in Kong, using the solution definition in SOLUTION_PATH directory.

remove_solution {solution-name} {realm}

# removes solution from all realms
remove_solution {solution-name}
# or
remove_solution {solution-name} "*"

Note: The expected solution file is {SOLUTION_PATH}/{solution-name}.json.

Note: the solution will not be entirely removed if it's still used by another realm.

Kafka

add_kafka_su

Adds a Superuser to the Kafka Cluster.

add_kafka_su {username} {password}

grant_kafka_su

Gives an existing user superuser status.

grant_kafka_su {username}

add_kafka_tenant

Adds a kafka user for a tenant, and adds ACL to their namespace.

add_kafka_tenant {tenant}

get_kafka_creds

Gets SASL Credential for a given kafka tenant.

get_kafka_creds {tenant}

Confluent Cloud

add_ccloud_su

Adds a Superuser to the Confluent Cloud Kafka Cluster.

add_ccloud_su {username} {password}

grant_ccloud_su

Gives an existing user superuser status.

grant_ccloud_su {username}

delete_ccloud_su

Removes a Superuser and their credentials, account and permissions.

delete_ccloud_su {username}

add_ccloud_tenant

Adds a kafka user for a tenant, and adds ACL to their namespace.

add_ccloud_tenant {tenant}

delete_ccloud_tenant

Removes a tenant and their credentials, account and permissions (does not remove data / topics).

delete_ccloud_tenant {username}

add_ccloud_key

Adds a ccloud APIKey for a tenant.

add_ccloud_key {tenant} "{*description}"

list_ccloud_tenants

Lists previously registered tenants in CCloud cluster.

list_ccloud_tenants

list_ccloud_acls

Lists ACLs of CCloud tenants, or of a single tenant referenced by name.

list_ccloud_acls {*tenant}

list_ccloud_api_keys

Lists active APIKeys on the cluster (names only).

list_ccloud_api_keys

ElasticSearch

elasticsearch_ready

Checks the ElasticSearch connection. Returns status 0 on success.

setup_elasticsearch

Prepares ElasticSearch.

setup_elasticsearch

add_elasticsearch_tenant

Adds a tenant to ElasticSearch.

add_elasticsearch_tenant {tenant}

Environment variables

Generic

• DEBUG: Enables debug mode. Is false if unset or set to empty string, anything else is considered true.

• BASE_DOMAIN: Installation hostname.

• BASE_HOST: Installation hostname with protocol.

• APPS_PATH: Path to app files directory. Defaults to /code/app.

• SERVICES_PATH: Path to service files directory. Defaults to /code/service.

• SOLUTIONS_PATH: Path to solution files directory. Defaults to /code/solution.

• SERVICES_DATA_PATH: Path to the services data to be displayed in the landing page. Defaults to /code/data/services.json.

Templates

• TEMPLATES_PATH: Path to template files directory. Defaults to /code/templates.

• CORS_TEMPLATE_PATH: Path to Kong service CORS plugin template file. This template is used with the register_app command. Defaults to {TEMPLATES_PATH}/cors_template.json.

• OIDC_TEMPLATE_PATH: Path to Kong service OIDC plugin template file. This template is used with the add_service and add_solution commands. Defaults to {TEMPLATES_PATH}/oidc_template.json.

• REALM_TEMPLATE_PATH: Path to Keycloak realm template file. This template is used with the add_solution and add_service commands. Defaults to {TEMPLATES_PATH}/realm_template.json.

• CLIENT_TEMPLATE_PATH: Path to Keycloak client template file. This template is used with the add_confidential_client, add_oidc_client and add_public_client commands. Defaults to {TEMPLATES_PATH}/client_template.json.

• ES_ROLE_TEMPLATE_PATH: Path to ElasticSearch role template file. This template is used with the add_elasticsearch_tenant command. Defaults to {TEMPLATES_PATH}/es_role_template.json.

All of these templates are going to be parsed using the python template strings feature. This means that even the keys or the values can contain $-based strings that will be replaced with the environment variable or command argument values.

Some of the expected $-based strings are:

• domain: replaced with BASE_DOMAIN environment variable value.
• host: replaced with BASE_HOST environment variable value.
• realm: replaced with the realmcommand argument value.
• tenant: replaced with the tenant command argument value.
• publicRealm: replaced with PUBLIC_REALM environment variable value.
• oidc_client_id: replaced with the oidc-client command argument value.
• oidc_client_secret: replaced with oidc client secret fetched form Keycloak.

Review the code to get the expected strings in each case.

Home app (landing page)

• WEB_SERVER_PORT: Web server port. Defaults to 8007.
• WEB_SERVICE_NAME: Name of this app used by kong to serve the routes. Defaults to gateway.

Keycloak

• KEYCLOAK_INTERNAL: Keycloak internal URL. Usually http://keycloak:8080/. Note: Ending / is required to connect to admin console.
• KEYCLOAK_MASTER_REALM: Keycloak master realm name. Defaults to master.
• KEYCLOAK_GLOBAL_ADMIN: Keycloak admin user in the master realm.
• KEYCLOAK_GLOBAL_PASSWORD: Keycloak admin user's password in the master realm.

Kong

• KONG_INTERNAL: Kong internal URL. Usually http://kong:8001.
• PUBLIC_REALM: Kong public realm. Defaults to -.

Kafka & Zookeeper

• ZOOKEEPER_HOST: Zookeeper host address. Usually 127.0.0.1:32181.
• ZOOKEEPER_USER: Zookeeper user.
• ZOOKEEPER_PW: Zookeeper user's password.
• KAFKA_SECRET: Kafka registered administrative credentials.

Confluent Cloud

• CC_URL: Confluent Cloud URL. Usually https://confluent.cloud.
• CC_CLI_PATH: Confluent Cloud client path. Usually ccloud.
• CC_API_USER: Confluent Cloud permissioned user.
• CC_API_PASSWORD: Confluent Cloud user's password.
• CC_ENVIRONMENT_NAME: Confluent Cloud environment to use. Usually default.
• CC_CLUSTER_NAME: Confluent Cloud cluster to modify. Usually default.

ElasticSearch

• ELASTICSEARCH_HOST: Elasticsearch internal URL. Usually http://elasticsearch:9200.
• ELASTICSEARCH_USER: Elasticsearch user.
• ELASTICSEARCH_PW: Elasticsearch user's password.