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 and JUnit5 code to communicate with the Vespa cloud API, but the configuration 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:

$ mvn test \
  -Dtest.categories=system \
  -DdataPlaneKeyFile=data-plane-private-key.pem -DdataPlaneCertificateFile=data-plane-public-cert.pem \
  -DapiKeyFile=key.pem

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.

-----BEGIN PRIVATE KEY-----
MIIEpAIBAAKCAQEA04up8hoqzS1+APIB0RhjXyObwHQnOzhAk5Bd7mhkSbPkyhP1 ...
iWlX9HNavcydATJc1f0DpzF0u4zY8PY24RVoW8vk+bJANPp1o2IAkeajCaF3w9nf
q/SyqAWVmvwYuIhDiHDaV2A==
-----END PRIVATE KEY-----

Submission properties

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

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.

Deploy properties

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

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!

Miscellaneous properties

Properties used in various other plugin goals.

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, evaluates 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 implementations 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.

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.

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",
}