Migrate from HCP Vault Secrets to HCP Vault Dedicated

HCP Vault Secrets and HCP Vault Dedicated are different HCP services, but share similar concepts for enabling, managing, and retrieving secrets.

The following are conceptual differences between Vault Dedicated and Vault Secrets:

What is HCP Vault Dedicated?

HCP Vault Dedicated (HVD) is a hosted version of Vault Enterprise running on the HashiCorp Cloud Platform (HCP).

Vault Dedicated, and Vault Enterprise, offer a rich set of features compared to HCP Vault Secrets. The key/value (K/V) version 2 secrets engine operates similarly to how HCP Vault Secrets stores secrets. You can update secrets, while retaining version history for each secret.

Each Vault Dedicated cluster is isolated from other clusters. You deploy each cluster to a specific cloud provider, and preferred region. You have the option to make the cluster public or private. The recommended practice is making the cluster private, and connect it to your cloud provider using a peering connection, transit gateway, or transit network, using a virtual private network (VPN). For scenarios where you need the cluster to be publicly accessible, you can configure the IP allow list to limit access to specific IP addresses, or CIDR ranges.

You can also migrate to a self-hosted version of Vault using either Vault Community edition, or Vault Enterprise edition. The community edition does not support namespaces.

This document focuses on the Vault K/V v2 secrets engine, and how to map your Vault Secrets implementation to HCP Vault Dedicated.

Recommended resources:

• Get started with HCP Vault Dedicated tutorials
• HashiCorp Virtual Network documentation
• VPN access over a transit network
• Manage public network access with IP allow lists

If you are new to Vault, follow the Vault foundations tutorials to learn the basics of Vault Community edition.

Superuser access

Every HCP organization starts with an owner. The owner role can perform any action in the organization, including adding new users, setting up services, or creating additional projects. The account owner, like the root user in Unix based systems, uses this account for initial setup. After initial setup is complete, log in with a user account that matches the level of access you need for day-to-day tasks.

In Vault Dedicated, you initially access the cluster with the admin token. The admin token, similar to the HCP organization owner, has the capabilities to perform almost any action in the cluster, including creating new namespaces, enabling auth methods, and creating policies.

When you migrate from Vault Secrets to Vault Dedicated, your workflow will look similar to:

• Generate an admin token in the HCP Portal.
• Enable an auth method to allow users to authenticate to Vault.
• Create a policy to allow common administrative tasks like enabling a secrets engine or creating policies.

Recommended resources:

• Generate an admin token documentation
• Enable an auth method tutorial
• OIDC authentication with Okta tutorial
• AppRole authentication tutorial

Client access

In HCP Vault Secrets, you access secrets through the HCP API, CLI, or UI. Workloads most commonly access through the API or CLI.

Vault Dedicated supports the same access methods, and like Vault Secrets, your workloads are going to access secrets through the Vault API or CLI.

Since Vault Dedicated is a hosted version of Vault Enterprise, all client interactions start in a namespace called admin. You can enable all auth methods and secrets engines in the admin namespace, or you can create separate namespaces, like HCP projects, to isolate resources. The admin namespace is an important concept to understand - client access through the API or CLI requires specifying the namespace parameter.

When using the Vault API, you pass the X-Vault-Namespace header to the API endpoint. When using the CLI, you pass the -namespace flag with the command or set the VAULT_NAMESPACE environment variable.

Recommended resources:

• Install the Vault binary tutorial
• Learn to use the Vault CLI tutorial
• Learn to use the Vault UI tutorial
• Learn to use the Vault API tutorial
• Learn to use the Terraform Vault provider tutorial
• Vault API documentation
• Vault CLI commands documentation

Store secrets

Vault Dedicated uses a plugin known as the Key/Value (K/V) secrets engine. The K/V version 2 secrets engine operates similarly to how HCP Vault Secrets stores secrets. You can write, read, and update secrets, while retaining version history for each secret. In addition to the K/V secrets engine, Vault Dedicated also supports other secrets engines. You can use secrets engines for dynamic secrets with the AWS, Azure, or database secrets engine.

When you migrate from Vault Secrets to Vault Dedicated, your workflow to store secrets will look similar to:

• Authenticate to Vault with a user that can enable a secrets engine.
• Enable the K/V v2 secrets engine in the admin namespace.

Recommended resources:

• Understand static and dynamic secrets tutorial
• Store versioned key/value secrets tutorial

Manage permissions

When using HCP services, you assign a user or service principal to a role. That role defines the capabilities the user is able to perform in Vault Secrets.

In Vault Dedicated, you write policies that define the specific capabilities a client is able to perform. This allows you to follow the principle of least privilege and assign the specific capabilities needed to access Vault.

After you write a policy, you assign it to a role (or in the case of the userpass auth method, a user). A role is a collection of settings and policies that define the client's capabilities (policies) and how long the client remains authenticated before needing to re-authenticate (TTL).

When you migrate from Vault Secrets to Vault Dedicated, your workflow to write and assign policies will look similar to:

• Authenticate to Vault with a user that can write policies.
• Write a policy to define the required access to each secrets engine for users and workloads.
• Attach the policy to a user or role.
• Authenticate to Vault with a user that can write secrets.
• Authenticate to Vault with a user that can read secrets.

Recommended resources:

• Introduction to Vault policies tutorial
• Access control with Vault policies tutorial
• Simplify management of policies with ACL policy templating tutorial

Enable multi-tenancy

With HCP Vault Secrets, you use HCP projects for strict isolation of secrets. Clients are able to access a Vault Secrets app or secret if they have permission to the HCP project (or organization-wide role).

In Vault Dedicated, namespaces allow you to create isolated environments within a single Vault cluster. You can also delegate management of namespaces to individual lines of business or teams, while allowing the security team to maintain control over the entire cluster. Using policies, you define the specific capabilities a namespace administrator can perform. You can allow the namespace administrator to enable new secrets engines, but not enable new auth methods.

When you migrate from Vault Secrets to Vault Dedicated, your workflow to create new namespaces will look similar to:

• Authenticate to Vault with a user that can create namespaces.
• Create a namespace to match your desired consumption and security model.
• Write a policy to delegate the desired management capabilities to the namespace administrator.
• Configure the namespace with the desired auth methods, secrets engines, and policies.
• Authenticate to Vault with a client that has access to the namespace.

Recommended resources:

• Enable multi-tenancy in Vault Dedicated tutorial
• Manage namespaces in Vault Dedicated documentation

Integrate with external systems

HCP Vault Secrets integrates with different platforms to support workloads that require access secrets, but do not have the ability to authenticate with, or read directly from Vault Secrets.

HCP Vault Dedicated supports the same type of integrations. This allows you to use Vault Dedicated with minimal changes to your existing workflows.

Kubernetes integrations

For Kubernetes workloads, you can use the Vault Secrets Operator to create Kubernetes secrets from Vault secrets. VSO supports both static and dynamic secrets.

For environments that do not support using Kubernetes Secrets, you can use Vault Agent. Vault Agent allows you to write secrets from Vault to a format supported by your workload such as local files, or environment variables.

Cloud provider integrations

Vault secrets sync allows you to sync a secret from Vault to a supported cloud provider. With secrets sync, you can centrally manage secrets in Vault, while allowing workloads to access secrets from the cloud provider's secret management service. Using secrets sync is useful when workloads already retrieve secrets from native solutions, but the security team wants to centrally manage all secrets in Vault.

Application integrations

For workloads that operate outside Kubernetes, or public cloud providers, you can use Vault Agent to write secrets from Vault to local files, or environment variables. You can also choose to update your application to use the Vault SDK, or your programming language's native API/secrets management library. Using an SDK, however, may require significant changes to your application code and time from engineering teams.

Recommended resources:

• Create Kubernetes Secrets from HCP Vault Dedicated with VSO tutorial
• Vault Agent and Vault Proxy quickstart
• Inject secrets using the Vault Agent as a sidecar tutorial
• Sync secrets to cloud native solutions tutorial

Example migration process

Migration from HCP Vault Secrets to HCP Vault Dedicated is highly dependent on your Vault Secrets configuration and consumption patterns. There are design decisions on how you want to configure Vault Dedicated.

The following considerations are common for most use cases:

• Who will manage the Vault Dedicated cluster or namespaces? Select users that manage the Vault cluster and any namespaces you create. Create separate accounts with policies that allow them to perform administrative tasks, and accounts for day-to-day operations.
• How many Vault Dedicated clusters do you need? If your clients access from multiple regions, consider using performance replication.
• Should you use separate namespaces or manage everything in the admin namespace? If you use multiple HCP projects to isolate secrets, consider using Vault namespaces to isolate access to Vault.
• Does restricting access to secrets with policies meet your security requirements? Decide whether you need to enable multiple K/V v2 secrets engines at different paths to match Vault Secrets apps, or if you can use a single K/V v2 secrets engine and restrict access to secrets using policies.
• What type of clients connect, and how do they authenticate? Document the types of clients that access Vault (workloads or users) and select auth methods that match their use case.

Example migration script

This script is an example of how you might migrate apps and secrets from Vault Secrets to Vault Dedicated. The script runs within the context of a single HCP project and single Vault Dedicated namespace. It gets a list of each Vault Secrets app and creates a Vault Dedicated K/V v2 secrets engine mounted at the same path as the app name. Once the script enables the secrets engine, it retrieves the secrets from the Vault Secrets app and writes it to the K/V v2 secrets engine.

You can run the script multiple times, changing the project of the authenticated user, and namespace of the Vault Dedicated cluster. The script assumes each app name is unique within the project and the target namespace.

#!/usr/bin/env bash
set -euo
set -o pipefail

###############################################################################
# .SYNOPSIS
# This script is an example of how you can migrate secrets from HCP Vault Secrets
# to HCP Vault Dedicated. It retrieves a list of HVS apps, and mounts a KV v2
# secrets engine for each app in HCP Vault Dedicated. It then retrieves the
# secrets from HCP Vault Secrets, encrypts them using a secure passphrase, and
# writes them to the corresponding KV v2 path in HCP Vault Dedicated.
#
# .REQUIREMENTS:
# - shred must be installed (brew install coreutils on macOS)
# - jq must be installed (brew install jq on macOS)
# - openssl must be installed (usually pre-installed on most systems)
# - hcp CLI must be installed
# - vault CLI must be installed
# - You must have the necessary permissions in HCP Vault Secrets to list apps and secrets
# - You must have the necessary permissions in Vault to mount secrets engines and write to KV v2
# - You must be authenticated with the HCP CLI using: `hcp auth login`
# - The following environment variables must be set for Vault CLI access:
#     VAULT_ADDR       (e.g. https://vault.yourdomain.com)
#     VAULT_TOKEN      (token with permission to mount secrets engines and write)
#     VAULT_NAMESPACE  (set to admin for HCP Vault Dedicated)
#
# .EXAMPLE
# No parameters are required to run this script.
# ./migrate.sh
###############################################################################

# Disable history to prevent secrets from being stored in shell history
if [ -n "${BASH_VERSION:-}" ]; then
  echo "🔒 Disabling bash history..."
  set +o history
  HISTFILE=
elif [ -n "${ZSH_VERSION:-}" ]; then
  echo "🔒 Disabling zsh history..."
  unsetopt HIST_SAVE_NO_DUPS
  unsetopt INC_APPEND_HISTORY
  HISTFILE=
else
  echo "⚠️  Unknown shell. Unable to disable shell history safely."
fi

### 1. CHECK HCP AUTHENTICATION ###############################################
echo "🔍 Checking HCP CLI authentication..."
if ! hcp vault-secrets apps list --format json >/dev/null 2>&1; then
  echo "❌ ERROR: Failed to list HCP Vault Secrets apps."
  echo "➡️  Run 'hcp auth login' and try again."
  exit 1
fi

### 2. CHECK VAULT CLI AUTH & PERMISSIONS #####################################
echo "🔍 Checking Vault CLI authentication and permissions..."
# Attempt a dry-run mount to a test path (will be disabled later)
TEST_MOUNT="hcp-check-$$"
if vault secrets enable -path="$TEST_MOUNT" -version=2 kv >/dev/null 2>&1; then
  vault secrets disable "$TEST_MOUNT" >/dev/null 2>&1 || true
else
  echo "❌ ERROR: Vault CLI cannot mount secrets engines."
  echo "➡️  Check that VAULT_TOKEN is set and has the 'sudo' capability or 'update' on sys/mounts/*."
  echo "➡️  You can also test manually: vault secrets enable -path=test-mount -version=2 kv"
  exit 1
fi

# Generate secure, random passphrase for file encryption (stored only in memory)
PASSPHRASE=$(openssl rand -hex 32)

# Fetch all HCP Vault Secrets apps
echo "📦 Fetching HCP Vault Secrets apps..."
apps=$(hcp vault-secrets apps list --format json | jq -r '.[].name')

for app in $apps; do
  echo "🔧 Processing app: $app"

  # Enable Vault KV v2 if not already mounted
  if ! vault secrets list -format=json | jq -e --arg app "$app/" 'has($app)'; then
    echo "🔐 Mounting KV v2 at path: $app"
    vault secrets enable -path="$app" -version=2 kv
  else
    echo "✅ KV already mounted at $app"
  fi

  # List secrets from HCP app
  secrets=$(hcp vault-secrets secrets list --app "$app" --format json)

  # Handle both single object and NDJSON (newline-delimited JSON objects)
  echo "$secrets" | jq -c '.' | while read -r secret_entry; do
    key=$(echo "$secret_entry" | jq -r '.name')

    # Read secret value securely from HCP
    secret_value=$(hcp vault-secrets secrets open --app "$app" "$key" --format json | jq -r '.static_version.value')

    # Encrypt secret value to a temp file
    TMP_ENC_FILE=$(mktemp)
    echo "$secret_value" | openssl enc -aes-256-cbc -pbkdf2 -salt -pass pass:"$PASSPHRASE" -out "$TMP_ENC_FILE"

    # Decrypt just before writing to Vault
    TMP_DEC_FILE=$(mktemp)
    openssl enc -d -aes-256-cbc -pbkdf2 -pass pass:"$PASSPHRASE" -in "$TMP_ENC_FILE" -out "$TMP_DEC_FILE"

    echo "➡️ Writing $key to Vault at $app/$key"
    secret_dec_value=$(cat "$TMP_DEC_FILE")
    vault kv put "$app/$key" value="$secret_dec_value"

    # Securely remove temp files
    shred -u "$TMP_ENC_FILE"
    shred -u "$TMP_DEC_FILE"
  done
done

# Cleanup
unset PASSPHRASE

# Re-enable shell history if possible
if [ -n "${BASH_VERSION:-}" ]; then
  echo "🔓 Re-enabling Bash history..."
  set -o history
elif [ -n "${ZSH_VERSION:-}" ]; then
  echo "🔓 Re-enabling Zsh history..."
  setopt INC_APPEND_HISTORY
  setopt HIST_SAVE_NO_DUPS
fi

echo "✅ All HCP secrets securely synced to Vault KV v2."

Vault Community edition

The Vault Community edition is a self-hosted version of Vault. While it does not require a license to operate, it does require platform teams to maintain the infrastructure to run Vault, and keep up with upgrades. Vault Community edition does not allow the creation of additional namespaces. To isolate secrets between lines of business, or teams, use separate secret engines mounted at different paths, and policies to restrict access to secrets.

Next steps

Now that you have an understanding of how HCP Vault Dedicated works, begin testing your workloads with HCP Vault Dedicated.

• Create a HVN
• Create a Vault Dedicated cluster
• Generate an admin token
• Access a cluster