Vespa cloud API

The Vespa APIs are described in detail in the general documentation. This document describes the additional APIs of the Vespa cloud that a Vespa application developer needs, in addition to the Vespa cloud console., to deploy an application to production or during development for testing purposes.

A developer will use both a dedicated Maven plugin as well as JUnit5 code to communicate with the Vespa cloud API, but the configuration for these is the same: a set of properties set in the application's pom.xml, or as command line arguments using -D<propertyName>=<propertyValue>. Some of these properties are common to all plugin goals and the test library, while others are valid only for specific actions.

Vespa Maven plugin

The com.yahoo.vespa:vespa-maven-plugin has the following goals:

Property Name Values
test If run with -Dtest.categories=system or -Dtest.categories=staging, it requires apiKeyFile for control plane access and key/certificate pair for data plane access - example:
$ mvn test \
  -Dtest.categories=system \
  -DdataPlaneKeyFile=data-plane-private-key.pem -DdataPlaneCertificateFile=data-plane-public-cert.pem \
  -DapiKeyFile=key.pem
submit Submit an application package and its accompanying set of tests, created with mvn package -Pfat-test-application, for automated deployment to production. Requires an API key.
deploy Deploy an application package, created with mvn package, to a development zone. Requires a user API key.
delete Delete a development deployment, created with mvn vespa:deploy. Requires a user API key.
compileVersion Find the latest Vespa version to compile against, which is guaranteed to be compatible with the oldest production version of the application. Requires an API key.
effectiveServices Compute the effective services.xml, based on region and environment variants. Requires no key.
This plugin, required configuration, and quite a bit more, is inherited from the common parent pom.xml of all Vespa cloud applications.

Common properties

Used to identify the application, and to authenticate against the Vespa cloud API, these properties should be set for any plugin invocation or test execution.

Property Name Mandatory Values
tenant Yes Name registered for the tenant in the cloud console, used for production submissions, developer deployments and tests.
application Yes Name registered for the application in the cloud console, used for production submissions, developer deployments and tests.
apiKey (Yes)

This or apiKeyFile must be specified. Value of the API key for the current application (for submissions) or developer (for deployments and tests).

The value is a multiline private key, like:

-----BEGIN PRIVATE KEY-----
MIIEpAIBAAKCAQEA04up8hoqzS1+APIB0RhjXyObwHQnOzhAk5Bd7mhkSbPkyhP1 ...
iWlX9HNavcydATJc1f0DpzF0u4zY8PY24RVoW8vk+bJANPp1o2IAkeajCaF3w9nf
q/SyqAWVmvwYuIhDiHDaV2A==
-----END PRIVATE KEY-----
See automated deployments for sample usage

apiKeyFile (Yes) This or apiKey must be specified. File location of the API key for the current application (for submissions) or developer (for deployments and tests).
apiCertificateFile No File location of the API certificate for the current application (for submissions) or developer (for deployments and tests). Certificates are not generally available.

Submission properties

Used when submitting an application package and tests for automated deployment to production, with mvn vespa:submit.

Property Name Mandatory Values
applicationZip No File location of the application package to submit or deploy. Defaults to target/application.zip
applicationTestZip No File location of the application tests package to submit. Defaults to target/application-test.zip
authorEmail Yes Email of the author of the commit being submitted.
sourceUrl No URL which points to the source code being submitted, the build job running the submission, or similar.
commit No Name — typically commit hash — of source code being submitted.

Deployment properties

Used to manipulate or test deployments in the dev or perf environments, with mvn vespa:deploy, mvn vespa:delete, mvn test or by running unit tests in an IDE.

Property Name Mandatory Values
instance No; defaults to $USER. Instance of the application to create, delete or test. This defaults to the user name of the current user, which lets each developer have their own development deployment by default, and is intentionally not set in the sample application's pom.xml.
environment No; defaults to dev The environment to deploy to, delete from, or run tests against. Environment list
region If environment is set to prod; otherwise has a system default The region to deploy to, delete from, or run tests against. May only be specified if environment is, and must be if that is prod. Region list

Deploy properties

Used for deployments to dev/perf, with mvn vespa:deploy.

Property Name Mandatory Values
applicationZip No File location of the application package to submit or deploy. Defaults to target/application.zip
vespa.runtime.version No Runtime Vespa version of the deployment. Defaults to the latest, normal confidence Vespa release
follow No; defaults to true Whether to follow the deployment log, or exit immediately after the deployment is accepted.
vespaLogLevel No; defaults to error Lowest log level to print from the Vespa log while deployment is ongoing.

Test properties

Used for running system, staging or production tests against an existing deployment, with mvn test -Dtest.categories=<categories>; supported categories are system staging production, as defined in the test library. Tests may also be run from an IDE, by specifying any mandatory properties not set in pom.xml as VM options. Be careful not to run destructive tests against a production deployment!

Property Name Mandatory Values
dataPlaneCertificateFile No File location of the data plane certificate for the deployment to run tests against — typically src/main/application/security/clients.pem
dataPlaneKeyFile No File location of the private key corresponding to the data plane certificate for the deployment to run tests against.

Miscellaneous properties

Properties used in various other plugin goals.

Property Name Mandatory Values
outputFile No File location where the compile version is written, when invoking mvn vepspa:compileVersion. Defaults to target/vespa.compile.version
servicesFile No File location of the services.xml for the application, when invoking mvn vespa:effectiveServices. Defaults to src/main/application/services.xml
outputDirectory No Directory location where the effective services.xml is written, when invoking mvn vespa:effectiveServices. Defaults to target