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.

It is also possible to talk directly to the Vespa Cloud HTTP APIs. The last part of this document describes the most relevant parts of these. Note that this requires message signing to be implemented on the client side.

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, 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.
suspend Suspends or resumes orchestration of a development deployment. This allows all nodes of the deployment to be down simultaneously, and can speed up upgrades of an existing deployment with node redundancy, at the cost of temporarily making the cluster inoperable. 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. Writes to target/vespa.compile.version. The property -Dvespa.compile.version is used when building the application package, see continuous deployment for an example. Requires an API key. Read more.
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.

Also see the Vespa Bundle Plugin.

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 vespa:suspend; and when running system or staging tests with mvn test or in an IDE.

Property Name Mandatory Values
instance Yes Instance of the application to create, delete, suspend or test. This 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.
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.

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
suspend Yes Used by the suspend goal. Whether to suspend (true) or resume (false) orhcestration of the relevant developement deployment.
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

Vespa Cloud HTTP API

The vespa-maven-plugin and JUnit5 test framework both talk to the Vespa Cloud HTTP APIs, and sign their HTTP requests with a private elliptic curve API key for authentication. The signature algorithm can be implemented with the following steps:

  1. The request body of the HTTP request — possibly empty — is SHA256-hashed and then base64-encoded, to form a content hash.
  2. then the HTTP method, then normalized request URL, current UTC time in ISO-8601 format (with Z to denote the UTC zone), and the content hash are concatenated with line breaks ('\n') in between to form the canonical representation of the request.
  3. The signature of the canonical message is then generated using ECDSA encryption with SHA256 hashing.
  4. Finally, the following headers are added to the HTTP request:
    • X-Authorization: <the base64-encoded canonical message signature>
    • X-Content-Hash: <the base64-encoded content hash>
    • X-Timestamp: <the timestamp used in the canonical message>
    • X-Key: <the public key info, in PEM format, of the API key>
    • X-Key-Id: <tenant:application:instance of the application — instance is unused, use default>

The Vespa Cloud API server verifies the timestamp given is no more than five minutes off from its server time, that the content hash matches the hash computed on the server side, that the given key verifies the canonical message generated by the server, and if this is OK, evalutes access control for the request with the role assigned to the key in the Vespa Cloud console, considering user keys under the key-ID's tenant, and headless keys under tenant and application.

Reference impementations are available in Java and Python. The request verification code is also available in Java, and can be used to verify custom implementations.

The relevant API paths for deploying an application package to Vespa Cloud's development environment, and deleting the deploying again, are described below.

HTTP deploy

POST /application/v4/tenant/<tenant>/application/<application>/instance/<instance>/deploy/<environment>-<region>

Starts deployments of the given application package zip to the specified zone. Only dev and perf are valid environments for these direct deployments.

Request body
RequiredContentNote
Yes A compressed application package (with zip compression) OR a multipart form with such an application package as the part with name applicationZip, and with an optional part with name deployOptions which is a JSON object that may specify vespaVersion — the runtime version of Vespa used for the deployment. The Content-Type HTTP header must be application/zip if the body is a single application package OR multipart/form-data otherwise.
Response A response includes:
  • A message intended for humans.
  • The run number of the deployment process that started as a result of the request.

Example:
POST /application/v4/tenant/my-tenant/application/my-application/instance/my-instance/deploy/dev-aws-us-east-1c

{
    "message": "Deployment started in run 34 of dev-aws-us-east-1c for my-tenant.my-application.my-instance. This may take about 15 minutes the first time.",
    "run": 34
}

The deployment process is best enjoyed through the Vespa Cloud console deployment view, but the simple Python implementation of a deployment client demonstrates how to interface with more of the APIs to monitor the deployment process.

HTTP delete

DELETE /application/v4/tenant/<tenant>/application/<application>/instance/<instance>/environment/<environment>/region/<region>

Deletes the deployment of the given application instance in the specified zone. Only dev and perf are valid environments.

Response A response contains a message intended for humans.

Example:
DELETE /application/v4/tenant/my-tenant/application/my-application/instance/my-instance/environment/dev/region/aws-us-east-1c

{
    "message": "Deactivated my-tenant.my-application.my-instance in dev.aws-us-east-1c",
}