Production Deployment

Production zones enable serving from various locations, with a CI/CD pipeline for safe deployments. This guide goes through the minimal steps for a production deployment - in short:

• Configure a production zone in deployment.xml.
• Configure resources for clusters in services.xml.
• Name the tenant, application, log in.
• Create or have access to the data-plane cert/key pair.
• Deploy the application to Vespa Cloud.

The sample application used in getting started is a good basis for these steps, see source files.

There are alternative ways of deploying at the end of this guide, too.

deployment.xml

Add deployment.xml to the application package root (next to services.xml):

<deployment version="1.0">
    <prod>
        <region>aws-us-east-1c</region>
    </prod>
</deployment>

services.xml

Modify services.xml - minimal example:

<services version="1.0" xmlns:deploy="vespa" xmlns:preprocess="properties">

    <container id="default" version="1.0">
        <document-api/>
        <search/>
        <nodes count="2">
            <resources vcpu="2" memory="8Gb" disk="100Gb"/>
        </nodes>
    </container>

    <content id="music" version="1.0">
        <min-redundancy>2</min-redundancy>
        <documents>
            <document type="music" mode="index" />
        </documents>
        <nodes count="2">
            <resources vcpu="2" memory="8Gb" disk="100Gb"/>
        </nodes>
    </content>

</services>

For production deployments, at least 2 nodes are required for each cluster to ensure availability during maintenance tasks and upgrades. The nodes-section is also where you specify your required resources:

        <nodes count="2">
            <resources vcpu="2" memory="8Gb" disk="100Gb"/>
        </nodes>

Also note the minimum redundancy requirement of 2:

        <min-redundancy>2</min-redundancy>

Minimum resources

To help ensure a reliable service, there is a minimum resource requirement for nodes in the production environment. The minimum is currently 0.5 vcpu, 8Gb of memory, and for disk, 2 x memory for stateless nodes, or 3 x memory for content nodes. As the disk resource is very cheap, we recommend it should be allocated generously to ensure it does not limit the use of more expensive cpu and memory resources.

Application name

Give the deployment a name and log in:

$ vespa config set target cloud
$ vespa config set application mytenant.myapp
$ vespa auth login

The tenant name is found in the console, the application is something unique within your organization - see tenants, applications and instances.

Add public certificate

Just as in the getting started guide, the application package needs the public key in the security directory. You might already have a pair, if not generate it:

$ vespa auth cert -f
Success: Certificate written to security/clients.pem
Success: Certificate written to /Users/me/.vespa/mytenant.myapp.default/data-plane-public-cert.pem
Success: Private key written to /Users/me/.vespa/mytenant.myapp.default/data-plane-private-key.pem

Observe that the files are put in $HOME/.vespa. The content from data-plane-public-cert.pem is copied to security/clients.pem. More details on data-plane access control permissions.

Deploy the application

Package the application and deploy it to a production zone:

$ vespa prod deploy

Find alternative deployment procedures in the next sections.

Use deploy-vector-search.yaml as a starting point, and see Automating with GitHub Actions for more information.

Production deployment using console

Instead of using the Vespa CLI, one can build an application package for production deployment using zip only:

• Create deployment.xml and modify services.xml as above.
• Skip the Application name step.
• Add a public certificate to security/clients.pem. See creating a self-signed certificate for how to create the key/cert pair, then copy the cert file to security/clients.pem. At this point, the files are ready for deployment.
• Create a deployable zip-file:

  $ zip -r application.zip . \
    -x application.zip "ext/*" README.md .gitignore ".idea/*"
  

• Click Create Application in the console. Select the PROD tab. Enter a name for the application and drop the application.zip file in the upload section.
• Click Create and deploy to deploy the application to the production environment.

Production deployment with components

Deploying an application with Components is a little different from above:

• The application package root is at src/main/application.
• Find the Vespa API version to compile the component.
• The application package is built into a zip artifact, before deploying it.

See Getting started java for prerequisites. Procedure:

1. Use the album-recommendation-java sample application as a starting point.
2. Make the same changes to src/main/application/deployment.xml and src/main/application/services.xml.
3. Run the same steps for Application name and Add public certificate.
4. Find the lowest Vespa version of the current deployments (if any) - details:

   $ mvn vespa:compileVersion \
     -Dtenant=mytenant \
     -Dapplication=myapp
   

5. Build target/application.zip:

   $ mvn -U package -Dvespa.compile.version="$(cat target/vespa.compile.version)"
   

6. Run the Deploy the application step. Here, the Vespa CLI command will deploy target/application.zip built in the step above.

Next steps

• Read automated deployments for automation, adding CD tests and multi-zone deployments.

• Experiment with the Vespa CLI to auto-generate some of the steps above:

  $ vespa prod init