Container Hooks

This page describes the configuration of HTTP hooks that can be wired into your container orchestration framework to facilitate container lifecycle events (such as shutdown).

Lifecycle Hooks

Your container orchestration framework likely supports the ability to signal a running API container when one of the following occurs:

  • A container has finished starting up.
  • A container is about to be shut down.

In the Kubernetes world, there are two lifecycle hooks (postStart and preStop). These describe the two lifecycle events listed above.

  • postStart - the container has finished starting up
  • preStop - the container is about to be shut down

For reference, please see Kubernetes Container Lifecycle Hooks: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/

Container Routes

Shutdown

The Cloud CMS API containers currently provide support for a single container route to handle the case for when a container is about to be shut down. You can wire this route to your preStop lifecycle. That way, when your container is about to shut down, the API container can learn about this and can be given time to complete a few maintenance steps that will help your system to scale down gracefully.

The shutdown route is:

POST /container/hooks/shutdown

There are no arguments to this method. You simply invoke it and the API container will do the following:

  1. Disable any job processing on the container. This makes it so the container will not pick up any new jobs.
  2. Any currently executing jobs will be bounced.

The currently executing jobs are, in effect, paused and then resumed on another server in the cluster. These jobs are scheduled and will resume as soon as possible with due consideration for other jobs and their scheduling specifications.

Within Kubernetes, you may opt to configure the usage of this shutdown hook to work something like this:

lifecycle:
  preStop:
    exec:
      command: ["curl", "-XPOST", "http://localhost:8080/container/hooks/shutdown", "-u", "username:password"]

Where username and password are the credentials for the container user configured below.

Configuration

The container routes are configured within Spring Security to use a different security context than your normal, client-facing API routes. These functions are only intended to be invoked by your DevOps or container framework software. You should not expose these routes to the outside world.

In your docker.properties file, you may configure the following:

gitana.container.enabled=true
gitana.container.username=
gitana.container.password=

Plug in the username and password that should be used by your container routes. You may also opt to disable container routes altogether if you wish.

Block Container Routes

In addition to the routes having their own security credentials (described above), we further advise that you block any routes beginning with /container/ on your externally facing load balancer. You container framework should still be able to connect to them (since they're using localhost or an internal/local IP).

However, you should prevent your public-facing load balancer from routing any traffic prefixed with /container/.