Introduction
Kong Brain (Brain) and Kong Immunity (Immunity) are installed on Kong Enterprise, either on Kubernetes or Docker, as defined below. The Collector App and Collector Plugin enable Brain and Immunity to communicate with Kong Enterprise.
Version Compatibility
Kong Brain and Kong Immunity follow a different versioning scheme from Kong Enterprise. See the table for version compatibility. Note the following:
- The Brain and Immunity version reflects the
kong-brain-immunity-base
package available in Bintray. - For Kong Enterprise 1.5.x and 2.1.x, use Brain and Immunity 3.0.0.
- Do not use Brain and Immunity 2.x.x, as it is end-of-life (EOL).
Brain and Immunity Version | Kong Enterprise Version |
---|---|
3.0.0 | 1.5.x, 2.1.x |
2.x.x is EOL. Use 3.0.0 instead. | 1.5.x |
1.x.x | 1.3.x |
Install Brain and Immunity on Kubernetes
Set up the Collector App via Helm. Use the public helm chart for setting up the Collector App and all its dependencies on Kubernetes. Setup instructions can be found on the public repo at: https://github.com/Kong/kong-collector-helm/blob/master/README.md.
Install Brain and Immunity on Docker
Install Brain and Immunity by downloading, installing and starting the Collector App on Docker, as defined in this section. After installing the Collector App, you will enable the Collector Plugin to access Brain and Immunity on Kong Enterprise.
Prerequisites
To complete this installation you will need:
- A valid Bintray account. You will need your username, account password and account API Key.
- Example:
- Bintray Access key =
john-company
- Bintray username =
john-company@kong
- Bintray password =
12345678
- Bintray API key =
12234e314356291a2b11058591bba195830
- Bintray Access key =
- The API Key can be obtained by visiting https://bintray.com/profile/edit and selecting API Key
- Example:
-
A Docker-enabled system with proper Docker access.
-
Kong Enterprise 2.1.x or later is installed on Docker.
- A valid Kong Enterprise License JSON file, including a license for Kong Brain and Kong Immunity. Note: You should receive your Bintray credentials with your purchase of Kong Enterprise. If you need Bintray credentials, contact Kong Support.
Step 1. Add the Kong Docker Repository and Pull the Kong Brain and Kong Immunity Docker Image
- In a terminal window, add the Kong Docker Repository.
Note: Be sure to replace the variables with your bintray username and bintray apikey.
$ docker login -u <your_username_from_bintray> -p <your_apikey_from_bintray> kong-docker-kong-brain-immunity-base.bintray.io
- Pull the Kong Brain and Kong Immunity Docker image.
$ docker pull kong-docker-kong-brain-immunity-base.bintray.io/kong-brain-immunity:3.0.0
You should now have your Kong Brain and Kong Immunity image locally.
- Verify that you have the Docker image. Find the image ID matching your repository:
$ docker images
- Tag the image ID as
kong-bi
for easier use. Replace<IMAGE_ID>
with the image ID matching your repository.$ docker tag <IMAGE_ID> kong-bi
Step 2. Confirm the Kong EE Docker Network is available
Confirm the Kong Enterprise network is available, which is the network you set up when installing Kong Enterprise on Docker named kong-ee-net
.
- Run the the Docker
ls
command to list available networks. The list should showkong-ee-net
.$ docker network ls
Note: If the results do not show kong-ee-net
, create the network:
$ docker network create kong-ee-net
Step 3. Start a Postgres Database
Start a PostgreSQL database:
$ docker run -d --name collector-database \
--hostname collector-database \
--network=kong-ee-net \
-e "POSTGRES_USER=collector" \
-e "POSTGRES_DB=collector" \
-e "POSTGRES_PASSWORD=collector" \
postgres:12
Step 4. Start a Redis Database
Start a Redis database:
$ docker run -d --name redis \
--hostname redis \
--network=kong-ee-net \
-p 6379 \
redis:5.0-alpine
Step 5. Prepare the Collector Database
Prepare the Collector database:
docker run --rm --network=kong-ee-net \
-e "SQLALCHEMY_DATABASE_URI=postgres://collector:collector@collector-database:5432/collector" \
kong-bi \
flask db upgrade
Step 6. Start Kong Collector App
Start Kong Collector.
$ docker run -d --name collector \
--hostname collector \
--network=kong-ee-net \
-p 5000:5000 \
-e "CELERY_BROKER_URL=redis://redis:6379/0" \
-e "SQLALCHEMY_DATABASE_URI=postgres://collector:collector@collector-database:5432/collector" \
-e "KONG_HOST=kong-ee" \
-e "KONG_PORT=8001" \
kong-bi
Step 7. Start the Scheduler and Worker
Start the scheduler and worker.
- Start celery-beat
$ docker run -d --name celery-beat \ --network=kong-ee-net \ -e "CELERY_BROKER_URL=redis://redis:6379/0" \ kong-bi \ celery beat -l info -A collector.scheduler.celery
- Start celery-worker
$ docker run -d --name celery-worker \ --network=kong-ee-net \ -e "CELERY_BROKER_URL=redis://redis:6379/0" \ -e "SQLALCHEMY_DATABASE_URI=postgres://collector:collector@collector-database:5432/collector" \ -e "KONG_HOST=kong-ee" \ -e "KONG_PORT=8001" \ kong-bi \ celery worker -l info -A collector.scheduler.celery --concurrency=1
Step 8. Validate the Collector App Installation
To complete the Collector App installation, validate the Collector App is working:
curl -i -X GET --url http://localhost:5000/status
You should receive an HTTP/1.1 200 OK message.
Step 9. Enable and Configure the Collector Plugin using Kong Manager
Using Kong Manager, enable the Collector Plugin. To enable the plugin:
- Navigate to the Workspaces page.
- Click the workspace you want to use. For example, the default workspace.
- Click Plugins in the API Gateway section of the left navigation bar.
- Click New Plugin which opens a page of plugin options.
- Scroll to the Analytics and Monitoring section, and click Enable on the Collector tile.
- The Create new collector plugin dialog displays. To minimally configure the Collector Plugin: ** In the Config.Http Endpoint field, enter the Collector App endpoint that Kong Enterprise can communicate with. For example, http://collector:5000. ** The default values populating the remaining fields are valid for a minimal configuration.
- Click Create. The Collector Plugin is configured.
Using a cURL command enter:
$ curl -X POST localhost:8001/default/plugins \
-d name=collector \
-d config.http_endpoint=http://collector:5000
Step 10. Confirm the Collector Plugin is Enabled and Configured
- Click Alerts in the left navigation pane, and the Alerts page should say Collector is connected.
- Click Service Map in the left navigation pane, and the Service Map should display with the Add Service button.
Using a cURL command, enter:
$ curl localhost:8001/default/collector/status
Summary
The Collector App is installed and the Collector Plugin is enabled on Kong Enterprise. You are now ready to analyze incoming traffic for alerts, auto-generate specs, and display your traffic visually in a Service Map.
For any issues encountered when setting up Collector App, Collector Plugin, or configuring other aspects of Brain and Immunity, see troubleshooting for help debugging common problems.