• [+] expand all

Application Packages
edit page

An application package is a set of files in a specific structure which 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 may also contain Java components that implement parts of the application running in a Vespa container.

The application package consists of one 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: 
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
See Vespa quick-start, developing applications or the Blog search tutorial for examples. For a complete list of files and directories in an application package, see the application package reference.

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 jdisc 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="store-only"/>
    </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: 

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

Deploy

Deploy the application package using the vespa-deploy tool. This tool uses the deploy API.

prepare

vespa-deploy prepare combines the upload and prepare steps in the deploy API. 

$ vespa-deploy prepare [application-path]
The prepare step:
  1. Verifies that a configuration server is up and running
  2. Uploads the application to the configuration server, which stores it in $VESPA_HOME/var/db/vespa/config_server/serverdb/tenants/[tenant]/sessions/[sessionid]. [sessionid] increases for each prepare-call. [tenant] is default in a single-tenant system. The config server also stores the application in a ZooKeeper instance at /config/v2/tenants/default/sessions/[sessionid] - this distributes the application to all config servers.
  3. Creates metadata about the deployed the applications package (which user deployed it, which directory was it deployed from and at what time was it deployed) and stores it in ...sessions/[sessionid]/.applicationMetaData
  4. Verifies that the application package contains the required files and performs a consistency check
  5. Validates the xml config files using the schema, found in $VESPA_HOME/share/vespa/schema
  6. Checks if there are config changes between the active application and this prepared application that require actions like restart or re-feed (like changes to search definitions). These actions are returned as part of the prepare step in the deployment API. This prevents breaking changes to production - also read about validation overrides
  7. Distributes bundles with components to nodes using file-distribution

activate

vespa-deploy activate invokes the activate step in the deployment API. Activate the application package: 

$ vespa-deploy activate
This activates the application package in the configuration servers, all configurations are propagated to services that subscribe to them.

Making changes to applications

Any change can be made to an application and be set live by calling deploy with the new application package. Vespa will by default prevent any destructive changes. To allow such changes to pass through the validation in deploy prepare, add a suitable validation-overrides.xml to your application package.

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