Skip to main content

Run Vault in stateless mode

Learn how to set up and run Piiano Vault in stateless mode using a container​

note

If you're using the hosted version of Vault, there is no set up for using stateless mode. Once you have specified your collections and IAM integration, you simply call the relevant APIs. For example, passing either fields or encrypted to the encrypt REST API.

Where you want to encrypt PII data stored in an existing infrastructure, you can run Vault in stateless mode to take advantage of its encryption and hashing features without the need to include and maintain a PostgreSQL database.

In stateless mode, Vault runs without a backing data store, removing the need to maintain a PostgreSQL database. Its operations are limited to those that provide encryption and hashing features. The lack of a backing store means you must provide the system, IAM, collection, and secrets configuration information for Vault in static files. Except for configuration environment variables, these configuration details cannot be updated while Vault is running.

When testing Vault in stateless mode, you can use the binary version. This option provides simplified set up, easy command line interaction, and simplifies testing in a CI or CD environment.

note

The container version of Vault is recommended for stateless workloads in production. The binary version is supplied mostly for testing, CI, and local development purposes. Contact us if you wish to use the binary version in production.

Register to get your license key​

Register to get a free 7-day development license, no credit card required.

Install the container version​

To start, install the container version of Vault. Follow the get started guide or appropriate instructions for your environment.

Create Vault configuration files​

In stateless mode, Vault does not include the default IAM configuration file needed to start Vault.

Either create this file and, optionally, a system configuration file manually. Alternatively, use the binary version of Vault to re-create the default IAM and system configuration files. When preparing the IAM file, remember to add your users.

Store these files as pvault.iam.toml, for the IAM configuration, and pvault.system.toml, for the system configuration, in the Docker container's /etc/pvault/conf.d directory.

Define data types, bundles, and collections,​

When Vault encrypts data, it uses information about the external files defined in collection schemas. You define these collections to Vault in a file containing PVSchemas. If you also have custom data types, you can include a file to define these too.

Name your PVSchema file pvault.collections.pvschema and, if you need it, the file containing custom data type details pvault.types.toml. Store these files in the /etc/pvault/conf.d directory.

Without the specification of at least one collection, Vault does not start.

Create secrets and tokens​

Vault uses a number of secrets to undertake encryption and provide user access to the REST API and CLI. As Vault has no storage in stateless mode, these details must be generate and store locally.

To do this, run Vault like this, setting PVAULT_DEVMODE appropriately depending on whether you want to run development or production mode:

docker run --rm \ 
    --name pvault-server \ 
    -e PVAULT_GENERATE_SECRETS=true \ 
    -e PVAULT_BACKING_STORE=none \ 
    -e PVAULT_DEVMODE=true \ 
    -e PVAULT_SERVICE_LICENSE={LICENSE_KEY} \ 
    -v $(pwd)/pvault-conf:/etc/pvault/conf.d \
    piiano/pvault-server:1.13.2

Vault starts and generates secrets and user tokens.

In development mode, the secrets are stored in a file called pvault.secrets.json and the tokens in api_tokens.txt in the /etc/pvault/conf.d directory.

In production mode, the secrets are stored in a file called pvault.secrets.json in the /etc/pvault/conf.d directory and the tokens are output to stdout.

note

Do not edit the pvault.secrets.json file. Altering the secret values could prevent Vault from starting or mean Vault cannot decrypt data.

In development mode Vault continues running after generation, whereas, in production mode, Vault shuts down after completing generation.

Vault is now available to execute any of the crypto REST API operations or CLI commands. You can also perform read operations in the control side, and set and clear configuration variables for the session.

note

For testing purposes, you might find it more convenient to use the binary version of Vault.

Starting Vault in stateless mode​

You start Vault in stateless mode like this, setting PVAULT_DEVMODE appropriately depending on whether you want to run development or production mode:

docker run --rm \ 
    --name pvault-server \ 
    -e PVAULT_BACKING_STORE=none \ 
    -e PVAULT_DEVMODE=true \ 
    -e PVAULT_SERVICE_LICENSE={LICENSE_KEY} \ 
    -v :/etc/pvault/conf.d \ 
    piiano/pvault-server:1.13.2

Updating configuration details​

Add users​

If you need to add users, update the pvault.iam.toml file with the new user details and run Vault with the -e flag set to PVAULT_GENERATE_SECRETS=true. Vault updates the secrets file with a hash of the users' tokens and outputs the users' tokens to file or stdout depending on the edition.

note

If you misplace a user's token, the recommended approach to obtaining a new token is to:

  • remove the user details from the pvault.iam.toml file.
  • run Vault with the -e flag set to PVAULT_GENERATE_SECRETS=true (which removes the hash of the user's token from the secrets file and, for developement mode, the user from the tokens file).
  • add the user's details back to the pvault.iam.toml file.
  • run Vault with the -e flag set to PVAULT_GENERATE_SECRETS=trueto update the secrets file and user tokens.

Add or updating collections​

If you need to add or update collections, update the PVSchema file with the new or updated collection details and run Vault with the -e flag set to PVAULT_GENERATE_SECRETS=true. Vault updates the secrets file with secrets relevant to the collections.

On this page