Using the JDisc Container with VIP

There are several ways making the JDisc container interact with VIP service rotation, this document covers the default strategy used when deploying a Vespa application.

Default behavior

By default, a search application will configure an instance of com.yahoo.container.handler.VipStatusHandler to answer /status.html. If there are no Vespa search backends, it will return HTTP OK. If there are one or more Vespa clusters connected, it will require at least one search node online before it will return HTTP OK.

To disable the server using the state of Vespa search clusters to determine whether it should be included in rotation, add the following configuration override inside the jdisc tag in services.

<config name="container.core.vip-status">
  <noSearchBackendsImpliesOutOfService>false</noSearchBackendsImpliesOutOfService>
</config>

The container will then ignore the state of search backends, and always stay in rotation unless a status file is used (see below).

Taking a container out of service

To be able to remove a container from VIP rotation, it is necessary to override the config container.core.vip-status to make the status handler look at a single file on disk instead of using the hardcoded response.

<config name="container.core.vip-status">
  <accessdisk>true</accessdisk>
  <statusfile>/full-path-to/status-response.html</statusfile>
</config>

The status handler is now instructed to look at the file system by the boolean value accessdisk, the file to serve is located at the path given by statusfile. Note, this path is completely independent from the path in the URI. If the file exists, its contents will be served on the URI path /status.html, otherwise a pertinent error message will be generated. So, to remove a container from service, simply delete or rename the file to serve.

Serve a response using alternative or multiple paths

The VIP status handler only looks at a single file path, but since this is independent from the URI path, it is possible to configure multiple handler instances to serve alternative or custom messages.

<handler id="vipFreshness" class="com.yahoo.container.handler.VipStatusHandler">
  <binding>http://*:*/docproc/freshness-data.xml</binding>
  <config name="container.core.vip-status">
    <accessdisk>true</accessdisk>
    <statusfile>/full-path-to/freshness-data.xml</statusfile>
  </config>
</handler>
<handler id="vipClustering" class="com.yahoo.container.handler.VipStatusHandler">
  <binding>http://*:*/docproc/ClusteringDocproc.status</binding>
  <config name="container.core.vip-status">
    <accessdisk>true</accessdisk>
    <statusfile>/full-path-to/ClusteringDocproc.status</statusfile>
  </config>
</handler>

In this example the paths /docproc/freshness-data.xml and /docproc/ClusteringDocproc.status will serve the files located at /full-path-to/freshness-data.xml and /full-path-to/ClusteringDocproc.status, respectively. As the handler instances are completely independent of each other, a container can be taken out of one type of rotation without affecting another, for instance.