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.

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

Scopes

You can create aliases in the globalor 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. An engineering org might use the suffix eng and suffixes frontend and backend for projects within the org scope to create the following alias combinations:

• postgres-db - Alias in the global scope
• postgres-db.backend.eng - Alias in the project scope with org and project suffixes
• postgres-db.frontend.eng - Alias in the project scope with org and project suffixes

Refer to the Create an alias suffix for a scope topic to learn more.

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

• To change the name of a suffix or to delete it, refer to Manage alias suffixes.
• To associate a target with an alias, or to update name, description, or host ID information, refer to Manage target aliases.