[+] expand all

Application Packages

An application package is a set of files in a specific structure that defines a deployable application. It contains all the configuration, components and machine-learned models that is necessary to deploy and run the application: No configuration is ever done locally on Vespa nodes or over remote APIs.

The application package is a directory, containing at minimum services.xml. Additionally, services.xml might consume other files or directories from the application package - see the reference for a full list.

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. With this code/config discrepancies will make the build fail - this is better than production errors. Read more in configuring components.

Note: See automated deployments for how to build a pipeline including tests to fully safeguard a new deployment.

Deploy

Deploy the application package using vespa deploy:

# Deploy an application package from cwd
$ vespa deploy

# Deploy an application package from cwd to a prod zone with CD pipeline in Vespa Cloud using deployment.xml
$ vespa prod deploy

At deployment, the application package is validated, and destructive changes rejected. Read more on how to handle application package changes in validation overrides.

Make changes to schemas, like adding a field, then deploy. Most such changes do not require restarts or re-indexing, if they do, deployment fails, and a validation override might be required - read more.

Convergence

Refer to the deploy reference for detailed steps run when deploying an application. Use the /application/v2/tenant API to validate that the configuration is deployed and activated on all nodes, like http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/serviceconverge - example output:

{
    "services": [
    ],
    "url": "https://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/serviceconverge",
    "currentGeneration": 2,
    "wantedGeneration": 2,
    "converged": true
}

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.

Nodes get config from a config server cluster

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

Deploying remote models

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 models or an FSA.

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 (see example):

<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).

Also see the url config type to download resources to container nodes.

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/>          <!-- Searchers go here. -->
        <docproc/>         <!-- 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="index"/>
        </documents>
        <nodes>             <!-- # nodes in the content cluster -->
            <node hostalias="node4" distribution-key="0" />
            <node hostalias="node5" distribution-key="1" />
            <node hostalias="node6" distribution-key="2" />
        </nodes/>
    </content>

</services>

Refer to the services.xml reference for different service types and configuration.

Component configuration

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

    <container id="default" version="1.0">
        <handler id="com.myapp.vespatest.ConfiguredHandler">
            <config name="vespatest.port">
                <port>12345</port>
            </config>

Further reads

Refer to the bundle plugin for how to build an application package with Java components.
Find more details in the config introduction.
During development on a local instance it can be handy to just wipe the state completely and start over:
1. Delete all config server state on all config servers
2. Run vespa-remove-index to wipe content nodes
See vespa-deploy for an alternative debug tool for local deployments - use it to:
1. prepare: Upload, validate and distribute to nodes
2. activate: Activate on all nodes - this reloads the application bundles, while serving. It waits for prepare to complete before running activation.
Find more details in the reference.

Important: The prepare step does not validate all changes. E.g., the container itself is not started with the bundles and bundle configuration at prepare-time.