Access a cluster

HCP Vault Dedicated clusters, like self-managed Vault Enterprise clusters, can be accessed using:

• Vault command-line interface (CLI)
• Application programming interface (API)
• Web user interface (UI)

This document assumes you have access to either a HCP Vault Dedicated admin token, or a token generated from a Vault auth method.

Before you can access the Vault cluster, you must retrieve the cluster URL. When a Vault cluster is deployed with the cluster accessibility option set to Private you can use the private URL from the HCP portal to connect from any device in a network that has a connection to the HashiCorp Virtual Network such as peering connection for Amazon Web Services or Microsoft Azure. Refer to the HashiCorp Virtual Network documentation for more information on supported connectivity options.

When the cluster accessibility option is set to Public, you can connect to any internet connected device.

Retrieve HCP Vault Dedicated cluster address

Log into the HCP Portal and navigate to the Vault cluster you wish to access.

From the Vault cluster page, click either the Private or Public link to copy the address to your clipboard.

Environment variables

For convenience, you can set the following environment variables:

• VAULT_ADDR: Set it to the target HCP Vault Dedicated cluster address
• VAULT_TOKEN: Set it to the Vault client token to access your cluster
• VAULT_NAMESPACE: Set it to the target namespace to operate on (the top-level namespace is admin)

Example: The following command sets environment variables for the admin token, cluster URL, and namespace.

$ export \
     VAULT_ADDR=https://<vault-cluster-address:8200> \
     VAULT_NAMESPACE=admin \
     VAULT_TOKEN=hvs.<foo...>

Refer to the Vault documentation for the list of Vault specific environment variables.

CLI access

You can access an HCP Vault Dedicated cluster using the Vault Community Edition, or Vault Enterprise binary. Refer to the Installing Vault documentation for more information on installing the CLI.

We recommend using the Vault Enterprise binary. If you are running the Vault Community Edition binary, some enterprise specific commands may not be available.

The Vault CLI requires the address of the Vault cluster, and a Vault namespace be passed to the CLI to authenticate with the Vault cluster. The address and namespace can be passed as a command line flag or set as environment variables.

When a new HCP Vault Dedicated cluster is created, the only auth method enabled is the token auth method. You can pass a token generated from the token auth method to the CLI interactively, or as an optional positional argument. When an auth method such as userpass is enabled, you can specify the method and interactively authenticate with Vault to retrieve a token using the -method option.

CLI flag

Pass the admin token, cluster URL, and namespace as CLI flags instead of using the environment variables.

$ vault login \
     -address=https://<vault-cluster-address:8200> \
     -namespace=admin \
     token=hvs.<foo...>

Example output:

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                hvs.<foo...>
token_accessor       aBCdEFGh4W02UEMNo7gibTLO.mWxyz
token_duration       5h56m20s
token_renewable      false
token_policies       ["default" "hcp-root"]
identity_policies    []
policies             ["default" "hcp-root"]

API access

HCP Vault Dedicated clusters can also be accessed through its API. There are a number of official as well as community maintained libraries that can be used in addition to common command line utilities such as cURL.

Like the CLI, the API requires the address of the Vault cluster, a Vault namespace, and a Vault token.

$ curl \
    --header "X-Vault-Token: <foo...>" \
    --header "X-Vault-Namespace: admin" \
    https://<vault-cluster-address:8200>/v1/sys/auth

Example output:

The example output has been formatted with jq for readability.

{
  "request_id": "24f60bfa-bf45-1fe1-67ef-4a4ba71e6ebb",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "token/": {
      "accessor": "auth_ns_token_77abcdefg",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0,
        "token_type": "default"
      },
      "description": "token based credentials",
      "external_entropy_access": false,
      "local": false,
      "options": null,
      "plugin_version": "",
      "running_plugin_version": "v1.15.5+builtin.vault",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "ns_token",
      "uuid": "d55b733d-8835-0aaf-8059-c6fe0b093f31"
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

UI access

The Vault UI is enabled by default for HCP Vault Dedicated clusters. The UI can be accessed directly using the private or public address from the HCP Portal. In addition to direct access, HCP Portal users can access a Vault cluster through the HCP Proxy.

The HCP Proxy provides access to the Vault UI from anywhere, even when public access is disabled by authenticating the HCP IAM users credentials prior to authorizing access.

Direct access

Open a web browser and paste the public address into the address bar, or the private address into the address bar from a device in a network that has a connection to the HashiCorp virtual network.

Paste the admin token into the Token textbox, or select a configured auth method.

HCP Proxy access

Log into the HCP Portal and navigate to the Vault cluster you wish to access.

From the Vault cluster page, click Launch web UI. This will launch a new browser or browser tab. Authentication through the HCP Proxy is transparent to the user.

Paste the admin token into the Token textbox, or select a configured auth method.

Tutorial

Refer to the following step-by-step tutorials to learn more:

• Access a Vault cluster on HCP