This is the API specification and some examples for the HTTP Deploy API that can be used to deploy applications in Vespa.
The API supports multiple tenants and applications. Each tenant may have multiple applications deployed, all of which
can be deployed using this API.
For a tenant one can
upload,
prepare and
activate applications.
The response format is JSON. Examples are found in the use-cases.
The current API version is 2. The API port is 19071 - use
vespa-model-inspect service configserver
to find config server hosts. Example:
http://myconfigserver.mydomain.com:19071/application/v2/tenant/mytenant/session.
All operations are synchronous across the cluster of config servers,
meaning that requests return after the operations complete on all servers.
Note: An application file path in a request URL or parameter refers to a
relative path in the application package. A path ending with '/' refers to a directory.
Entities:
Tenant
The tenant used in this API is created using the tenant REST API.
The tenant name is required for all operations.
Tenant names may only contain word characters and dash: [a-zA-Z_0-9-].
Application
The application is the name of the application taken from the application package
or given during prepare.
Application names may only contain word characters: [a-zA-Z_0-9].
Environment
Multiple environments are not yet supported. prod is used by default.
Region
Multiple regions are not yet supported. default is used by default.
Instance
Multiple instances are not yet supported. default is used by default.
Session-id
The session id used in this API is generated by the server and is required
for all operations after creating a session.
The session is valid as long as it is one of the last 10 session ids created.
Path
For deploying to Vespa on the command line one can use the
vespa-deploy tool, which uses this API to deploy applications.
POST /application/v2/tenant/[tenant name]/prepareandactivate
Creates a new session with the application package that is included in the request,
prepares it and then activates it.
See details in the steps later in this document
{"log":[{"time":1619448107299,"level":"WARNING","message":"Host named 'vespa-container' may not receive any config since it is not a canonical hostname. Disregard this warning when testing in a Docker container."}],"tenant":"default","session-id":"3","url":"http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default","message":"Session 3 for tenant 'default' prepared and activated.","configChangeActions":{"restart":[],"refeed":[],"reindex":[]}}
Creates a new session with the application package that is included in the request.
Parameters
Name
Default
Description
from
N/A
Should only be used when you want to create a session based on an active application.
Valid values are a URL to an active application.
A new session will be created based on the corresponding application.
Examples (both requests return the same response):
POST /application/v2/tenant/mytenant/session
POST /application/v2/tenant/mytenant/session?from=http://myconfigserver.mydomain.com:19071/application/v2/tenant/mytenant/application/myapp/environment/default/region/default/instance/default
Prepares an application with the session id given.
Parameters
Parameter
Default
Description
applicationName
N/A
Name of the application to be deployed
environment
default
Environment where application should be deployed
region
default
Region where application should be deployed
instance
default
Name of application instance
debug
false
If true, include stack trace in response if prepare fails.
timeout
300 seconds
Timeout in seconds to wait for session to be prepared.
Request body
None
Response
Returns a session id and a link to activate the session.
Log with any errors or warnings from preparing the application.
An activate URL for activating
the application with this session id, if there were no errors.
A list of actions (possibly empty) that must be performed in order to apply some config changes
between the current active application and this next prepared application.
These actions are organized into three categories; restart, reindex, and refeed:
Restart actions are done after the application has been activated
and are handled by restarting all listed services.
See
schemas for details.
Reindex actions are special refeed actions that Vespa
handles automatically, if the
reindex endpoint below is used.
Refeed actions require several steps to handle.
See schemas for details.
Example:
PUT /application/v2/tenant/mytenant/session/3/prepared
{"tenant":"mytenant","session-id":"3","activate":"http://myconfigserver.mydomain.com:19071/application/v2/tenant/mytenant/session/3/active","message":"Session 3 for tenant 'mytenant' prepared.","log":[{"level":"WARNING","message":"Warning message 1","time":1430134091319},{"level":"WARNING","message":"Warning message 2","time":1430134091320}],"configChangeActions":{"restart":[{"clusterName":"mycluster","clusterType":"search","serviceType":"searchnode","messages":["Document type 'test': Field 'f1' changed: add attribute aspect"],"services":[{"serviceName":"searchnode","serviceType":"searchnode","configId":"mycluster/search/cluster.mycluster/0","hostName":"myhost.mydomain.com"}]}],"reindex":[{"documentType":"test","clusterName":"mycluster","messages":["Document type 'test': Field 'f1' changed: add index aspect"],"services":[{"serviceName":"searchnode","serviceType":"searchnode","configId":"mycluster/search/cluster.mycluster/0","hostName":"myhost.mydomain.com"}]}]}}
GET /application/v2/tenant/mytenant/session/[session id]/prepared
Returns the state of a prepared session.
The response is the same as a successful prepare operation (above),
however the configChangeActions element will be empty.
Activates an application with the session id given.
The session id must be for a prepared session.
The operation will make sure the session is activated on all config servers.
Parameters
Parameter
Default
Description
timeout
60 seconds
Timeout in seconds to wait for session to be activated (when
several config servers are used, they might need to sync
before activate can be done).
Request body
None
Response
Returns a session id, a message and a URL to the activated application.
POST /application/v2/tenant/[tenant name]/application/[application name]/environment/prod/region/default/instance/default/reindex
Triggers reindexing of specified document types in
specified clusters of an application.
Reindexing starts with the next redeployment of the application.
All document types in all clusters are reindexed unless restricted, using parameters as specified:
Parameters
Name
Description
clusterId
A comma-separated list of content clusters to limit reindexing to.
All clusters are reindexed if this is not present.
documentType
A comma-separated list of document types to limit reindexing to.
All document types are reindexed if this is not present.
indexedOnly
Boolean: whether to trigger reindexing only for document types with indexing
mode index and at least one with field the indexing statement
index. Default is false.
speed
Number (0-10], default 1: Relative indexing speed -
balance speed vs. resource use. Example: speed=0.1
Request body
N/A
Response
A human-readable message indicating what reindexing was triggered.
Example:
POST /application/v2/tenant/mytenant/application/foo/environment/prod/region/default/instance/default/reindex?clusterId=foo,bar&documentType=moo,baz&indexedOnly=true
{"message":"Reindexing document types [moo, baz] in 'foo', [moo] in 'bar' of application mytenant.foo"}
GET /application/v2/tenant/[tenant name]/application/[application name]/environment/prod/region/default/instance/default/content/[path]
Returns content at the given path for an application.
See getting content for usage and response.
Errors are returned using standard HTTP status codes.
Any additional info is included in the body of the return call, JSON-formatted.
The general format for an error response is:
Bad request. Client error. The error message should indicate the cause.
400
INVALID_APPLICATION_PACKAGE
There is an error in the application package. The error message should indicate the cause.
400
OUT_OF_CAPACITY
Not enough nodes available for the request to be fulfilled.
401
Not authorized. The error message should indicate the cause.
404
NOT_FOUND
Not found. E.g. when using a session id that doesn't exist.
405
METHOD_NOT_ALLOWED
Method not implemented. E.g. using GET where only POST or PUT is allowed.
409
CONFLICT
Conflict, returned when activating an application fails due
to a conflict with other changes to the same application (in
another session). Client should retry.
500
INTERNAL_SERVER_ERROR
Internal server error. Generic error. The error message should indicate the cause.
Access log
Requests are logged in the access log which can be found at
$VESPA_HOME/logs/vespa/configserver/access-json.log, example:
To add the file files/test1.txt, first create the directory, then add the file:
$ curl -s -X PUT "http://host:19071/application/v2/tenant/mytenant/session/2/content/files/"
$ curl -s -X PUT --data-binary @app/files/test1.txt \
"http://host:19071/application/v2/tenant/mytenant/session/2/content/files/test1.txt"
Prepare and activate the session:
$ curl -s -X PUT "http://host:19071/application/v2/tenant/mytenant/session/2/prepared?applicationName=fooapp"
$ curl -s -X PUT "http://host:19071/application/v2/tenant/mytenant/session/2/active"
Rollback
If you need to roll back to a previous version of the application package
this can be achieved by creating a new session based on the previous known
working version by passing the corresponding session id in the
from argument, see creating a session