项目作者: ScaleIT-Org

项目描述 :
Kong API Gateway Sidecar Image
高级语言: Shell
项目地址: git://github.com/ScaleIT-Org/kong-sidecar.git
创建时间: 2018-01-22T16:04:16Z
项目社区:https://github.com/ScaleIT-Org/kong-sidecar

开源协议:MIT License

下载


Docker Pulls Docker Build Status" class="reference-link">Kong Sidecar Image License Docker Pulls Docker Build Status

This image uses Kong along with Kongfig and the External OAuth Plugin.

Introduction

This Image is intended to be used as a socalled sidecar image. This means a new Kong instance is created for each app using kong in contrary to using Kong as a centralized load balancer. It also means that the Kong sidecar image has its own database and therefore user, security and other configuration which guarantees a lose coupling between an infrastructure’s stacks. This is also shown as a graphical representation below:

kong-sidecar

To reduce complexity in usage when launching the stack, config files can be provided so you don’t have to make API calls (or write your own scripts to do so).

Check out the example app here: https://github.com/ScaleIT-Org/sapp-example-oauth-ready-app

Use With Your App

It is recommended to use docker-compose which makes it more easy to handle configurations. Please view this docker-compose.yml snippet below:

  1. version: '2.1' # replace by any version needed (> 2.1)
  2. services:
  3. # <...> your main application/applications here
  4. kong-database:
  5. image: postgres:10.4-alpine # kong requires >9.5
  6. environment:
  7. - POSTGRES_USER=kong
  8. - POSTGRES_DB=kong
  9. - POSTGRES_PASSWORD=kong
  10. volumes:
  11. - db-data:/var/lib/postgresql/data
  12. networks:
  13. - internal
  14. healthcheck: # optional
  15. test: ["CMD", "pg_isready", "-U", "postgres"]
  16. interval: 10s
  17. timeout: 5s
  18. retries: 5
  19. kong:
  20. image: scaleit/kong-sidecar:0.14.0-0
  21. depends_on:
  22. kong-database:
  23. condition: service_healthy # only if healthcheck is enabled
  24. restart: always
  25. ports:
  26. - 8000:8000
  27. - 8001:8001
  28. environment:
  29. - KONG_DATABASE=postgres
  30. - KONG_PG_HOST=kong-database
  31. - KONG_PG_DATABASE=kong
  32. - KONG_PG_PASSWORD=kong
  33. links:
  34. - kong-database:kong-database
  35. volumes:
  36. - "./config:/config/apis"
  37. networks:
  38. - internal
  39. healthcheck: # optional
  40. test: ["CMD-SHELL", "curl -I -s -L http://127.0.0.1:8000 || exit 1"]
  41. interval: 5s
  42. retries: 10
  43. volumes:
  44. db-data:
  45. networks:
  46. internal:
  47. # <...>

Consider replacing internal by your main application’s internal network and set the newest version for scaleit/kong-sidecar (latest should not be used in production). There is also an alpine variant of this image.

It is recommended to replace KONG_PG_PASSWORD and POSTGRES_PASSWORD by a more secure passphrase.

API Settings

APIs

API Settings have the following format:

  1. apis:
  2. - name: MyApp # unique api name
  3. attributes:
  4. upstream_url: http://<your_app_url>
  5. hosts:
  6. - app.example.com
  7. uris:
  8. - /app
  9. preserve_host: true
  10. plugins:
  11. - name: rate-limiting # kong plugin name
  12. attributes: # the plugin attributes
  13. username: # optional, to reference a consumer, same as consumer_id in kong documentation
  14. config:
  • “name”: Specify your app’s name.
  • “host” and “uris”: Set one of these (or both) to point to your app.
  • “upstream_url”: Your app’s actual URL to be reachable from Kong.
  • “preserve_host”: Set this to forward the hostname entered by the client to your app.
  • “plugins”: Apply Kong-Plugins.

Example for using the External OAuth Plugin:

  1. # <...> API config
  2. plugins:
  3. - name: external-oauth
  4. attributes:
  5. config.authorize_url: https://oauth.something.net/openid-connect/authorize
  6. config.scope: openid+profile+email
  7. config.token_url: https://oauth.something.net/openid-connect/token
  8. config.client_id: SOME_CLEINT_ID
  9. config.client_secret: SOME_SECRET_KEY
  10. config.user_url: https://oauth.something.net/openid-connect/userinfo
  11. config.user_keys: email,name,s
  12. config.hosted_domain: mycompany.c
  13. config.email_key: email

Consumers

You can also add consumers to your Kong-sidecar instance:

  1. consumers:
  2. - username: client-app
  3. credentials:
  4. - name: key-auth # name of a specific credentials plugin
  5. attributes: # credential config attributes

Applying the config

You can create YAML files with names ending with .yml within any directory and define the settings to the container by defining a bind mount for the folder:

  1. volumes:
  2. - "./<your_config_dir>:/config/apis"

Kong-sidecar will look for all YAML-files, like apis.yml or consumers.yml, in /config/apis and apply them.

Optionally you can also define JSON files, however YAML is recommended for a better readability.

After starting the stack, you should be able to reach your app by accessing http://localhost:8000/app.
API Settings should be edited in your apis.yaml file (or however you named it), so the settings are persistent even after container recreation and volume removal.

For a more advanced example go to Kongfig on Github.

Building the image

Building the image is as easy as running docker build -t teco/kong-sidecar:0.12.1-0 . inside the directory where this repository is cloned. Be free to replace “0.12.1-0” with any tag that fits your needs.

Versioning

Kong sidecar image version declarations follow the pattern <kong-version>-<kong_sidecar_image-patch> where <kong-version> is the semantic version of kong that is used and <kong_sidecar_image-patch> is a single number suggesting a patch respectively a fix for this image.

Troubleshooting

  • standard_init_linux.go:185: exec user process caused "no such file or directory": Common problem on windows. Convert line endings in the entrypoint.sh and apply-config.sh file to LF and the error will disappear.

  • “No kong-apis file found, skipping configuration.” although file provided:
    Occurs on docker for Windows or docker for Mac. Sometimes files are mounted as empty directories. A restart of the daemon can help. Otherwise provide it via volume.

  • Nginx Logs show upstream sent too big header while reading response header from upstream even if proxy buffer is disabled:
    Occurs if the external-oauth plugin is enabled and the user is redirected to the OAuth provider (or vice versa). OAuth2 fills the HTTP-header resulting in a header size which is too big to handle by the reverse proxy. Try to increase your proxy buffer as following:

    1. proxy_buffer_size 16k;
    2. proxy_buffers 8 8k;
    3. proxy_busy_buffers_size 16k;