HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Boundary Home

Overview of aliases

Target aliases simplify the connection workflow for end users by allowing them to reference targets using a globally unique DNS-like string.

Without aliases, connecting to an end target requires you to reference the target ID, or a combination of target name and scope:

$ boundary connect ssh -target-id ttcp_1234567890

$ boundary connect ssh -target-name sql-database -target-scope-name -staging

With target aliases, a single globally referenced value is assigned to a target, simplifying connection workflows and enabling transparent sessions.

$ boundary connect ssh sql-database-staging

Permissions

The existence of an alias for a Boundary resource does not change how permissions function. Anyone can attempt to use an alias to access a target, but if you do not have permission to access the target, the attempt fails. You can create an alias for a target, even if you do not have permission to access the target.

Separating the permissions from aliases and destination resources means a different set of people can manage the aliases than the people who have permission to operate on targets. For example, you may have a project with a sensitive set of targets. You can configure Boundary to allow a select few users to manage those targets, while a different group of users manage the aliases.

Naming conventions

An alias is a globally unique, DNS-like string that is associated with a destination resource. The alias value parameter does not have to be delimited by a suffix, and can be just a hostname.

Examples of valid aliases include database.boundary and webserver.boundary.

Single word aliases and transparent sessions

HashiCorp recommends that you do not use single-word aliases such as webserver as opposed to webserver.boundary, because single-word aliases do not work intuitively on Windows.

Windows DNS resolution does not support resolving unqualified single word DNS hostnames. You can make the hostname fully qualified, but is not intuitive to most users.

For example the following hostname works:

ssh mytarget.

But this hostname does not work:

ssh mytarget

For this reason, if you expect any Windows users to use an alias, it should contain a dot (.) anywhere in the value.

Refer to the transparent sessions documentation for more information.

HTTPS websites

If you create an alias for a website that uses HTTPS, the alias must match the website's hostname. You may receive connection errors if the alias does not match the website's hostname exactly. The alias is used during TLS negotiation. If the alias does not match the certificate, the TLS handshake fails.

For example, if you want to create an alias to connect to https://www.hashicorp.com, you must name the alias www.hashicorp.com.

Aliases created in project scopes automatically include project and org suffixes in the following format:

alias.projectsuffix.orgsuffix

The suffixes can cause end-to-end TLS to fail if the full alias value does not match the server certificate's Common Name or Subject Alternative Name. To maintain end-to-end TLS for a website resource, create the alias in the global scope and ensure it matches the hostname. You can create aliases in project scopes if you control the certificate and can configure it to match the full alias value, including suffixes.

For more information, refer to Suffixes.

Scopes

You can create aliases in the global or project scopes.

Creating aliases for project scopes gives your organization increased granularity and control over targets. Project-level administrators can manage their scope's aliases without relying on a global administrator. Aliases created in project scopes require suffixes.

If you delete a project, Boundary clears the destination_id parameter for any aliases that resolve to targets in that project, so that they no longer function.

Refer to the Scopes domain model topic to learn more.

Suffixes

Aliases created in project scopes require suffixes. You must create one suffix for the containing org scope and one suffix for the project scope in which the alias resides. You append the suffixes to any aliases you create in project scopes as follows:

alias.projectsuffix.orgsuffix

Suffixes ensure that aliases are globally unique across scopes, even when you use the same alias value across multiple org or project scopes.

For example, your organization might use an alias value postgres-db and differentiate between different departments using suffixes:

  • A marketing org might use the suffix mktg with suffixes for project scopes based on regions, east and west.
  • An engineering org might use the suffix eng with suffixes for project scopes based on departments, frontend and backend.

This structure would produce the following alias combinations:

To learn more about using suffixes to scale your Boundary deployment, refer to the blog post Scaling without friction.

Next steps

To use target aliases to connect to targets:

  1. Create an alias suffix for a scope if you intend to create aliases in a project scope.
  2. Create a target alias
  3. Connect to a target using an alias
  4. After you set up a target alias, you can optionally Configure transparent sessions for end users.

More information

Edit this page on GitHub