Application Packages
edit page

An application package is a set of files in a specific structure that defines a deployable application. An application package contains all the configuration, components and auxiliary files needed to specify how a given cloud config-enabled set of subsystems should behave to run the application. The application package can also have Java components that implement parts of the application running in a Vespa container - get started developing java components.

The Vespa application is hence fully defined by its application package - all code and config is there.

A change to code and configuration is atomically deployed to running instances. To ensure code and config consistency, config definition files are compiled to Java code, discrepancies causes build failures, which is easier to manage than production errors. Read more in configuring components.

The application package is a directory with the same name as the application, containing at minimum:

application/services.xml           - mandatory specification of services required
application/hosts.xml              - mapping of host ids to physical hosts

Additionally, services.xml might consume other files or directories from the application package - a quick summary of optional content (see the reference for a full list):

application/components/            - OSGi components to be deployed to container nodes. See component types
application/searchdefinitions/     - Vespa document schemas, and optionally how to search them
application/search/query-profiles/ - Vespa query profiles; named collections of search request parameters

Most application packages are stored as source code in a code repository. However, some resources are generated and/or too large to store in a code repository, like an FSA. See below for how to use the url config type to download resources to container nodes.

See Vespa quick-start, Vespa Applications or the Blog search tutorial for examples. Also, find more details in the config introduction.

Deploy

Deploy the application package using vespa-deploy. The application package is validated at deploy, and destructive changes blocked. To allow such changes to pass the validation in deploy prepare, add validation-overrides.xml. Making changes to search definitions (e.g. add a field) is followed by a deployment to the application instance. Most such changes do not require restarts or re-indexing, if they do, deployment fails, and a validation override is required. Use deploy to:

prepare: Upload, validate and distribute to nodes
activate: Waits for prepare to complete before activation. Activate on nodes - this reloads the application bundles, while serving.

Find more details in the reference. Deploying application changes to production is hence safe, trivial, and can be easily automated.

During development it can also be handy to just wipe the state of Vespa completely and start over:

Delete all config server state on all config servers
Run vespa-remove-index to wipe content nodes

File distribution

The application package can have components and other large files. At vespa-deploy prepare, these files are distributed to the nodes:

Components (i.e bundles)
Files with type path and url in config, see Adding files to the component configuration
Constant tensors

When new components or files specified in config are distributed, the container gets a new file reference, waits for it to be available and switches to new config when all files are available.

Use vespa-status-filedistribution to check if files have been distributed to all the hosts.

Deploying remote models

Machine learned models in Vespa, either TensorFlow, ONNX, XGBoost, or LightGBM, are stored in the application package under the models directory. This might be inconvenient for some applications, for instance for models that are frequently retrained on some remote system. Also, models might be too large to fit within the constraints of the version control system.

The solution is to download the models from the remote location during the application package build. This is simply implemented by adding a step in pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>exec-maven-plugin</artifactId>
      <version>1.4.0</version>
      <executions>
        <execution>
          <id>download-model</id>
          <phase>generate-resources</phase>
          <goals>
            <goal>exec</goal>
          </goals>
          <configuration>
            <executable>bin/download_models.sh</executable>
            <arguments>
              <argument>target/application/models</argument>
              <argument>MODEL-URL</argument>
            </arguments>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

bin/download_model.sh example:

#!/bin/bash

DIR="$1"
URL="$2"

echo "[INFO] Downloading $URL into $DIR"

mkdir -p $DIR
pushd $DIR
    curl -O $URL
popd

Any necessary credentials for authentication and authorization should be added to this script, as well as any unpacking of archives (for TensorFlow models for instance).

services.xml

services.xml specifies the services that makes the application - each top-level element specifies one service. Example:

<?xml version="1.0" encoding="utf-8" ?>
<services version="1.0">

  <container id="default" version="1.0">
    <processing/>      <!-- Request-response processors go here. -->
    <search/>          <!-- Use to run the search middleware. Searchers go here. -->
    <docproc/>         <!-- Use to run the document processing middleware. DocumentProcessors go here. -->
    <nodes>            <!-- Nodes in the container cluster -->
      <node hostalias="node1"/>
      <node hostalias="node2"/>
      <node hostalias="node3"/>
    </nodes/>
  </container>

  <content id="my-content" version="1.0">
    <redundancy>1</redundancy>
    <documents>         <!-- Add document schemas here -->
      <document type="my-searchable-type" mode="index"/>
      <document type="my-other-type" mode="streaming"/>
    </documents>
    <nodes>             <!-- # nodes in the content cluster -->
      <node hostalias="node4"/>
      <node hostalias="node5"/>
      <node hostalias="node6"/>
    </nodes/>
  </content>

</services>

Refer to the services.xml reference for different service types and configuration. The application package may also specify arbitrary binaries to be started and given configuration specified explicitly in the services file, see application-specific services.

Component configuration

The application's custom Java code (in components) is configured in services.xml. E.g, a port number for a remote service: