deployment.xml

deployment.xml is placed in the root of the application package and specifies which environments and regions the application is deployed to during automated application deployment, as which application instances.

Deployment progresses through the test and staging environments to the prod environments listed in deployment.xml.

Example:

<deployment version="1.0">
    <instance id="beta">
        <prod>
            <region>aws-us-east-1c</region>
        </prod>
    </instance>
    <instance id="default">
        <block-change revision="false" days="mon,wed-fri" hours="16-23" time-zone="UTC" />
        <prod>
            <region>aws-us-east-1c</region>
            ...
            <delay hours="3" minutes="7" seconds="13" />
            <parallel>
                <region>aws-us-west-1c</region>
                <steps>
                    <region>aws-us-west-2d</region>
                    <delay hours="3" />
                    <test>aws-us-west-2d</test>
                </steps>
                ...
            </parallel>
        </prod>
        <endpoints>
            <endpoint container-id="my-container-service">
                <region>aws-us-east-1c</region>
                ...
            </endpoint>
        </endpoints>
    </instance>
    <endpoints>
        <endpoint id="my-weighted-endpoint" container-id="my-container-service" region="aws-us-east-1c">
          <instance weight="1">beta</instance>
          ...
        </endpoint>
    </endpoints>
</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.xml is not used for dev and perf environments, as these are deployed manually.

deployment

The root element.

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.

block-change

In <deployment>, or <instance>. This blocks changes from being deployed to production in the matching time interval. Changes are nevertheless tested while blocked.

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 and version attributes.

Any combination of the attributes below can be specified. Changes on a given date will be blocked if all conditions are met. Invalid <block-change> tags (i.e. that contains conditions that never match an actual date) are rejected by the system.

This tag must be placed after any <test> and <staging> tags, and before <prod>. It can be declared multiple times.

The below example blocks all changes on weekends, and blocks revisions outside working hours, in the PST 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"/>

The below example blocks:

• all changes on Sundays starting on 2022-03-01
• all changes in the hours 16-23 between 2022-02-10 and 2022-02-15
• all changes until 2022-01-05

<block-change days="sun" from-date="2022-03-01" time-zone="America/Los_Angeles"/>
<block-change hours="16-23" from-date="2022-02-10" to-date="2022-02-15" time-zone="America/Los_Angeles"/>
<block-change to-date="2022-01-05" time-zone="America/Los_Angeles"/>

upgrade

In <deployment>, or <instance>. Determines the strategy for upgrading the application, or one of its instances. By default, application revision changes and Vespa platform changes are deployed separately. The exception is when an upgrade fails; then, the latest application revision is deployed together with the upgrade, as these may be necessary to fix the upgrade failure.

test

Meaning depends on where it is located:

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. When specified, staging tests must be preset in the application test package. See guides for getting to production with or without Java.

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.

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 48 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>us-west-1</region>
<parallel>
    <region>us-east-3</region>
    <region>us-central-1</region>
</parallel>
<region>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>us-east-3</region>
    <steps>
        <region>us-west-1</region>
        <delay hours="1" / >
        <test>us-west-1</test>
    </steps>
    <delay hours="2" / >
</parallel>

endpoints (global)

In <deployment>, without any <instance> declared or in <instance>: This declares an global endpoint. Contains one or more <endpoint> elements.

endpoint (global)

In <endpoints>. 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-container-service"/>
    <endpoint id="us" container-id="my-container-service">
        <region>aws-us-east-1c</region>
        <region>aws-us-west-2a</region>
    </endpoint>
</endpoints>

endpoints (application)

In <deployment> and at least one <instance> declared: This declares an application endpoint. Contains one or more <endpoint> elements.

endpoint (application)

In <endpoints>. Specifies an application endpoint pointing to multiple instances of this application. This requires instances of the application to be declared explicitly in <instance> elements.

Each endpoint will point to the declared instances. At least one instance must be declared. The following example creates a default endpoint routing traffic to two instances, where one receives 25% of requests and another receives 75%, in the aws-us-east-1c zone.

<endpoints>
    <endpoint id="my-weighted-endpoint" container-id="my-container-service" region="aws-us-east-1c">
        <instance weight="1">beta</instance>
        <instance weight="3">main</instance>
    </endpoint>
</endpoints>

instance (in application endpoint)

In <endpoint>. Declares the instance to add to this endpoint and its relative weight. The portion of requests an instance receives can be calculated as follows: instance weight / sum of all weights..

A weight of 0 means that the instance will only be used as a backup, i.e. it will only receive requests when all the other instances are unhealthy.