deployment.xml

deployment.xml is in the root of the application package and defines which environments and regions the application is deployed to during automated application deployment.

Deployment progresses through the test and staging environments to the prod environments listed in deployment.xml. Test steps are added if production deployments are set up, even if not explicitly listed. deployment.xml is not used for dev and perf environments, as these are deployed manually. Example:

<deployment version="1.0">
  <instance id="default">
    <block-change revision="false" days="mon,wed-fri" hours="16-23" time-zone="UTC" />
    <prod>
      <region active="true">aws-us-east-1c</region>
      ...
      <delay hours="3" minutes="7" seconds="13" />
      <parallel>
        <region active="true">aws-us-west-1c</region>
        <steps>
          <region active="true">aws-us-west-2d</region>
          <delay hours="3" />
          <test>aws-us-west-2d</test>
        </steps>
        ...
      </parallel>
    </prod>
    <endpoints>
      <endpoint container-id="my-global-query-endpoint">
        <region>aws-us-east-1c</region>
        ...
      </endpoint>
    </endpoints>
  </instance>
</deployment>
Some of the elements can be declared either under the <deployment> root, or, if one or more <instance> tags are listed, under these. These have a bold or when listing where they may be present.

deployment

The root element. Attributes:

Name Values Mandatory
version 1.0 Yes
major-version The major version number this application is valid for. Do not specify except to work around problems with a new major version. No

instance

In <deployment> or <parallel> (which must be a direct descendant of the root). An instance of the application; several of these may be simultaneously deployed in the same zone. If no <instance> is specified, all children of the root are implicitly children of an <instance> with id="default", as in the above example. Attributes:

Name Values Mandatory
id The unique name of the instance. Yes
To delete an application, remove all its instances, i.e., submit a deployment spec like
<deployment version="1.0" />
To remove an instance with production deployments (see region), add a deployment-removal validation override. Example:
<validation-overrides>
  <allow until="2019-11-23">deployment-removal</allow>
</validation-overrides>

block-change

In <deployment>, or <instance>. Blocks changes from being deployed to production in the matching time interval. Changes are nevertheless tested while blocked. This tag must be placed after any <test> and <staging> tags, and before <prod>. By default, both application revision changes and Vespa platform changes (upgrades) are blocked. It is possible to block just one kind of change using the "revision" / "version" boolean attributes.

NameValuesMandatory
revision Set to false to allow application revision changes during the block period set by this. No: Default is true
version Set to false to allow Vespa version changes during the block period set by this. No: Default is true
days A spec of the days this block is effective - a comma-separated list of single days or day intervals where the start and end day are separated by a dash and are inclusive. Each day is identified by its english name or three-letter abbreviation. Yes
hours A spec of the hours this block is effective - a comma-separated list of single hours or hour intervals where the start and end hour are separated by a dash and are inclusive. Each hour is identified by a number in the range 0 to 23. Yes
time-zone The name of the time zone used to interpret the hours attribute. Time zones are full names or short forms, when the latter is unambiguous. See ZoneId.of for the full spec of acceptable values. No: Default is UTC.
The below example blocks all changes on weekends, and blocks revisions outside working hours, in the PT time zone:
<block-change days="sat-sun" hours="0-23" time-zone="America/Los_Angeles"/>
<block-change revision="false" days="mon-fri,sat,sun" hours="0-8,16-23" time-zone="America/Los_Angeles"/>

test

Meaning depends on where it is located:

In <deployment>, or <instance>. If present, the application is deployed to the test environment, and system tested there, even if no prod zones are deployed to. If present in an <instance> element, system tests are run for that specific instance before any production deployments of the instance may proceed — otherwise, previous system tests for any instance are acceptable.

In <prod>, <parallel>, or <steps>. If present, production tests are run against the production region with id contained in this element. A test must be after a corresponding region element.

staging

In <deployment>, or <instance>. If present, the application is deployed to the staging environment, and tested there, even if no prod zones are deployed to. If present in an <instance> element, staging tests are run for that specific instance before any production deployments of the instance may proceed — otherwise, previous staging tests for any instance are acceptable.

prod

In <deployment>, or in <instance>. If present, the application is deployed to the production regions listed inside this element, under the specified instance, after deployments and tests in the test and staging environments.

region

In <prod>, <parallel>, or <steps>. The application is deployed to the production region with id contained in this element. Attributes:

NameValuesMandatory
active Whether this region should receive traffic from the global endpoint of this application. This is useful when adding a new region to an application which is not ready to receive traffic yet. Yes
To remove a deployment from a region, remove the region from the <prod> element, and add a deployment-removal validation override. Example:
<validation-overrides>
  <allow until="2019-11-23">deployment-removal</allow>
</validation-overrides>

delay

In <deployment>, <instance>, <prod>, <parallel>, or <steps>. Introduces a delay which must pass after completion of all previous steps, before subsequent steps may proceed. This may be useful to allow some grace time to discover errors before deploying a change in additional zones, or to gather higher-level metrics for a production deployment for a while, before evaluating these in a production test. The maximum total delay for the whole deployment spec is 24 hours. The delay is specified by any combination of the hours, minutes and seconds attributes.

parallel

In <deployment>, <prod>, or <steps>. Runs the contained steps in parallel: instances if in <deployment>, or primitive steps (deployments, tests or delays) or a series of these (see steps) otherwise. Multiple <parallel> elements are permitted. The following example will deploy to us-west-1 first, then to us-east-3 and us-central-1 simultaneously, and, finally to eu-west-1, once both parallel deployments have completed:

<region active="true">us-west-1</region>
<parallel>
  <region active="true">us-east-3</region>
  <region active="true">us-central-1</region>
</parallel>
<region active="true">eu-west-1</region>

steps

In <parallel>. Runs the contained parallel or primitive steps (deployments, tests or delays) serially. The following example will in parallel

  1. deploy to us-east-3,
  2. deploy to us-west-1, then delay 1 hour, and run tests for us-west-1, and
  3. delay for two hours.
Thus, the parallel block is complete when both deployments are complete, tests are successful for the second deployment, and at least two hours have passed since the block began executing.

<parallel>
  <region active="true">us-east-3</region>
  <steps>
    <region active="true">us-west-1</region>
    <delay hours="1" / >
    <test>us-west-1</test>
  </steps>
  <delay hours="2" / >
</parallel>

endpoints

In <deployment>, or in <instance>. Contains one or more <endpoint> elements that specify global endpoints that should be created for the application.

endpoint

In <deployment>. Specifies a global endpoint for this application. Each endpoint will point to the regions that are declared in the endpoint. If no regions are specified, the endpoint defaults to the regions declared in the <prod> element. The following example creates a default endpoint to all regions, and a us endpoint pointing only to US regions.

<endpoints>
  <endpoint container-id="my-global-query-endpoint"/>
  <endpoint id="us" container-id="my-global-query-endpoint">
    <region>us-east-3</region>
    <region>us-west-1</region>
  </endpoint>
</endpoints>
NameValuesMandatory
id The identifier for the endpoint. This will be part of the endpoint name that is generated. If not specified, the endpoint will be the default global endpoint for the application. No
container-id The id of the container cluster to which requests to the global endpoint is forwarded. Yes