Secret store

Vespa Cloud allows you to link your AWS Systems Manager Parameter Store to your Vespa Cloud tenant. This way you can let your Java components in JDisc access secrets and authenticate against other services. This guide takes you through the necessary configuration steps.

Access to SSM Parameter Store is based on AWS's own best practices. You can read more about granting third parties access to your AWS-account in the AWS documentation.

When working through the guide you need the following pieces of information:

Item Description
Vespa Cloud IAM Role The IAM role that Vespa Cloud uses to access your AWS account. Find this value in the secrets store tab in the Console in the tenant view. (e.g.
Your IAM account number The numeric identifier for your AWS account.
Your IAM Role The IAM role in your account that Vespa Cloud will assume to access your SSM Parameter Store. You will have to come up with a name for this role.
ExternalID AWS suggests using an ExternalID as a type of credential to assume an IAM Role. This is a password-like token you have come up with on your own.

For this guide to work your JDisc container cluster must run on exclusive hosts. Add exclusive="true" as an attribute to the nodes element in the container cluster. See services.xml for details.

  1. Create an IAM role in your AWS-account with policy

    Create a role that Vespa Cloud has the privileges to assume.

    $ aws iam create-role --role-name vespa-cloud-secret-store-access \
                          --assume-role-policy-document '{
      "Version": "2012-10-17",
      "Statement": [
          "Effect": "Allow",
          "Principal": {
            "AWS": "Vespa Cloud IAM Role goes in here"
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "External ID to assume role goes here"
  2. Grant access for the role to your Parameter Store

    Here we attach the pre-defined AWS IAM policy AmazonSSMReadOnlyAccess to the role we created. You can further restrict access to SSM Parameter Store by creating a custom policy that you attach to the role.

    $ aws iam attach-role-policy --role-name vespa-cloud-secret-store-access \
                                 --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess
  3. (Optional) Grant access to Parameter Store encryption key

    If you follow AWS guidelines your parameters are encrypted using a key in KMS. For Vespa Cloud to be able to retrieve your parameters you must also grant access to the KMS key used to encrypt the parameters. Add a policy like the one below as an inline policy on the role.

        "Version": "2012-10-17",
        "Statement": [
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": "kms:Decrypt",
                "Resource": "ARN used for the KMS key used here"
  4. Register the Secret Store in Vespa Cloud

    Go to the secret store tab in the tenant view in the Vespa Management Console. There you need to register the settings for Vespa Cloud accessing your parameter store. Click the Add secret button to add a new secret store to your tenant. Fixme: the Name in the dialog is the "store id" used in services.xml below

    Screenshot of 'Add secret store' view in Vespa Cloud Console

  5. Validate the use of Secret Store from the Console

    You can test that settings work before deploying a new application, but you must have an application running with an exclusive container cluster. Click the validate button on the Secret Store you just added. Provide the region where your AWS Parameter Store is located, the name of the Parameter you want to retrieve, and which Deployment in Vespa Cloud you want to retrieve the secret. Note that validation can only be done with production deployments. An empty Deployment dropdown indicates that there are no valid deployments to use for validation.

  6. Deploy an application using your Secret Store configuration

    In your Vespa application services.xml you can configure the use of your Secret Store with the secret-store tag.

    <secret-store type="cloud">
      <store id="store">
        <aws-parameter-store account="my-secrets" aws-region="us-east-1" />

    To access the secrets from your Vespa application from JDisc components like a Searcher,declare the SecretStore as a constructor parameter.

    public class MySearcher extends  Searcher {
      public MySearcher(SecretStore secretStore) {
        var secret = secretStore.getSecret("foo");

You should now have completed the integration between Vespa Cloud and the AWS Systems Manager Parameter Store in your own AWS account!