Skip to main content

Secrets management

Since release v0.39.0, the Anapaya appliances store secrets encrypted and separate from the configuration.

The secret management architecture for Anapaya appliances is designed to safeguard sensitive information by preventing unauthorized access and disclosure.

Plain-text secrets are never stored in the configuration; instead, they are provisioned with a unique secret identifier that is used to securely reference them. This design allows configuration and observability data to be exchanged without the risk of exposing the underlying secrets.

Once the secrets are provisioned, they can no longer be retrieved in plain text, it is therefore critical that you establish a source of truth for your secrets that is outside of the Anapaya appliance. Doing so ensures that your organization can easily replace an Anapaya appliance while still having a backup of the secrets.

Establishing a source of truth for secrets​

While individual secrets are provisioned directly on the Anapaya appliance, it is critical to maintain a central, authoritative source of truth for them. This central repository is where your organization should create, store, and manage the lifecycle of secrets like BGP passwords and forwarding keys. The appliance should be seen as a destination for these secrets, not their origin.

This practice ensures consistency, simplifies secret rotation, and provides a clear audit trail. There are two primary approaches for managing your secrets' source of truth.

For a seamless and integrated experience, we recommend using the Anapaya CONSOLE as the source of truth for your secrets. The CONSOLE provides a centralized interface to:

  • Securely store and manage secrets for all your appliances.
  • Automate the provisioning and synchronization of secrets to the correct appliances.
  • Maintain a clear overview of which secrets are deployed where.

Using the CONSOLE abstracts away the manual, per-appliance commands and is the recommended best practice for managing secrets at scale.

Option 2: Third-Party secrets manager​

If your organization already uses a third-party secrets manager (e.g., HashiCorp Vault, 1Password, AWS Secrets Manager), you can continue to use it as your source of truth.

The workflow in this case is:

  • Define and store the secret in your external management tool.
  • Retrieve the plain-text secret from your tool when needed.
  • Use the manual provisioning methods described in the next section to add the secret to the Anapaya appliance.

This approach gives you flexibility but requires manual steps to keep the secrets on the appliance synchronized with your source of truth.

Provisioning secrets on the appliance​

These endpoints and CLI commands are used to manually manage secrets on an appliance. This is the necessary workflow when using a third-party secrets manager or for specific edge cases. The Management API provides the underlying endpoints.

Add a secret​

To add a secret to the Anapaya appliance, use the appliance-cli, it provides helpers to prevent leaking secret in the shell history. The different options to add a secret are explained below.

In the interactive mode, the appliance-cli will prompt you for the secret value.

appliance-cli secrets add bgp-password@1

Delete a secret​

Only in v0.40.0 and later

Deletion is only possible for appliances running v0.40.0 or newer.

Secrets can be deleted using the appliance-cli with the Management API endpoint:

appliance-cli delete secrets/bgp-password@1

Only secrets that are not currently referenced in the appliance configuration can be deleted.

Reference a secret​

After provisioning the secret, the secret identifier can be used as secret reference in the appliance configuration.

Some of the secret references in the appliance configuration require a specific format of the underlying secret. For example, the forwarding key must be base64-encoded. This is specified in the documentation for the respective secret reference field of the appliance configuration.

The configuration validation of the Anapaya appliance validates that the referenced secrets exist and have the correct format.

Secret identifier​

Secrets are referenced in the configuration via a secret identifier:

  • scheme: <name>@<version>
  • regex with permitted chars: ^[_a-zA-Z0-9:.-]+@[0-9]+$

The version must be a number and is used to manage different versions of the same secret. The version can be chosen by the user.

Versioning in v0.39.x release

In v0.39.x releases the version had the following conditions:

The initial version must be 1. Subsequent version must be incremented without any gaps. I.e., if the current highest version is x, the next version must be x+1. If you require a more elaborate versioning scheme, we recommend to encode it in the name portion of the secret identifier.