Boundary
Aliases
An alias is a globally unique, DNS-like string that is associated with a destination resource.
You can establish a session to a target by referencing its alias, instead of having to provide a target ID or target name and scope ID.
For example, if you have an alias boundary.dev
, you can use it to connect to a target with the following command: boundary connect ssh boundary.dev
.
Background
When you create a resource in Boundary, it assigns the resource a randomly generated identifier. You must use those IDs to perform actions in Boundary.
When you connect to a target using the terminal, you must reference the target ID or target name and scope name.
As an example, to SSH to a target, you can execute the command boundary connect ssh -target-id ttcp_123456789
.
Since it can be difficult to remember the unique IDs, users frequently have to look up the identifiers for any resources they want to operate on.
Aliases simplify this process.
When you create an alias and associate it with a target, you can later use the alias value
instead of the target ID in commands.
Boundary automatically resolves to the target that the alias references.
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 webserver
and webserver.boundary
.
Scopes
You can only create aliases in the global
scope.
However, you can associate aliases with targets or hosts from any scope.
Support for additional resource types may be added in the future.
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.
Connect to a target using an alias
Whenever you could use the -id
flag or -target
flag in the CLI, you can substitute an alias.
For example, you can use the following command to connect to an SSH target with the ID ttcp_1234567890
:
$ boundary connect ssh -target -id ttcp_1234567890
If you configured an alias named example.alias.boundary
for the target, you could alternatively use the following command to connect to the target:
$ boundary connect ssh example.alias.boundary
Create aliases
There are multiple ways that you can create aliases and associate them with targets in Boundary.
You can:
- Create an alias for an existing target
- Create an alias during target creation
- Associate an existing alias with a target
Create an alias for an existing target
You can create a new alias and associate it with an existing target at the same time. Complete the following steps to create a new alias and associate it with a target:
- Log in to Boundary.
- Select Aliases in the navigation pane.
- Click New Alias.
- Complete the following fields:
- Name: (Optional) Enter an optional name for the alias to use for identification purposes.
- Description: (Optional) Enter an optional description for the alias to use for identification purposes.
- Type: Select Target. At this time, targets are the only Boundary resources that supports aliasing.
- Alias Value: Enter the string that you want to use as the alias to represent the target. An alias's value can be a hostname or a DNS-like string.
- Target ID: (Optional) Specify any targets you want to associate with the alias.
- Host ID: (Optional) Enter an optional host ID, if you would like to specify that the alias always uses the same host when you use it to connect to a target.
- Click Save.
Create an alias during target creation
You can create a new target and new alias at the same time and associate the two.
Complete the following steps to create a new target and new alias at the same time:
- Log in to Boundary.
- Select Targets in the navigation pane.
- Click New Target.
- Complete the following fields:
- Name: Enter the target name for identification purposes.
- Description: (Optional) Enter an optional description for identification purposes.
- Type: Select the target type. You can create SSH or TCP targets.
- Target Address: (Optional) Enter a valid IP address or DNS name. Alternatively, you can configure host catalogs and host sets.
- Default Port: (Optional) Enter an optional default port for the target to use for connections.
- Default Client Port: (Optional) Enter an optional local proxy port on which to listen when a session is started on a client.
- Maximum Duration: (Optional) Enter an optional maximum duration for sessions on this target, in seconds.
- Maximum Connection: (Optional) Enter the maximum number of connections allowed per session on this target.
For unlimited connections, enter
-1
. - Workers: (Optional) Select whether you want the worker to function as an ingress and/or egress worker.
- Aliases: (Optional) Enter the value fpr any aliases you want to associate with this target, and then click Add. An alias's value can be a hostname or a DNS-like string. You can associate multiple aliases with a target.
- Click Save.
Associate an existing alias with a target
If you already created an alias, you can update it with an existing target. Complete the following steps to add an alias to a target:
- Log in to Boundary.
- Select Targets in the navigation pane.
- Select the target you want to add an alias to.
- Under the Aliases heading in the right sidebar, click Add an alias.
- Complete the following fields:
- Name: (Optional) Enter an optional name for the alias to use for identification purposes.
- Description: (Optional) Enter an optional description for the alias to use for identification purposes.
- Type: Select Target. At this time, targets are the only Boundary resources that supports aliasing.
- Alias Value: Enter the alias value you want to use in commands to represent the target. An alias's value can be a hostname or a DNS-like string.
- Target ID: This field contains the ID of the target you selected to add an alias to. It is read only.
- Host ID: (Optional) Enter an optional host ID, if you would like to specify that the alias always uses the same host when you use it to connect to a target.
- Click Save.