Static host catalogs

A static host catalog allows you to manually define a collection that can include hosts or host sets.

Dynamic host catalogs allow you to sync hosts from a cloud provider.

Host catalogs: contain hosts and host sets.
Host sets: a collection of hosts. These are hosts that are considered the same from an access management perspective. Host sets can be assigned to targets.
Hosts: a computing element with a network address reachable by Boundary (often through a worker deployed in same network).

Host catalog domain model diagram - light mode

Host catalogs can contain hosts directly, host sets, or a combination of both.

After defining a host catalog, you can then create targets to connect to these hosts using a Boundary session. Targets define the port and protocol that should be used for a session. This means a single host can have multiple targets defined if it accepts connections on different ports. For example, a host can have an SSH target listening on port 22, and also accept connections on port 5432 from a postgres client. To assign a host to a target, you must add the host to a host set.

Create a static host catalog

Complete the following steps to create a static host catalog.

Log in to Boundary.
Select the org, and then select the project you want to create a host catalog for.
Select Host Catalogs.
Select New Host Catalog.
Complete the following fields:
- Name: (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
- Type: (Required) Select Static to create a static host catalog.
Click Save.

Log in to Boundary.
Set the BOUNDARY_PROJECT_ID environment variable, or provide the scope ID (such as p_1234567890) in the next step.
Use the following command to create a static host catalog named my-host-catalog:
```
$ boundary host-catalogs create static \
  -scope-id $BOUNDARY_PROJECT_ID \
  -name "my-host-catalog"
```
You must provide the scope-id field when you create a static host catalog.
Refer to the host catalogs domain model documentation for more fields that you can use when you create host catalogs.

You can define a host catalog using the Boundary Terraform provider:

resource "boundary_host_catalog_static" "my_catalog" {
  name        = "my-host-catalog"
  description = "A static host catalog"
  scope_id    = boundary_scope.project.id
}

Create hosts

Complete the following steps to create a static host within a static host catalog.

Select Host Catalogs.
Select a static host catalog.
Click the Hosts tab, and click New.
Complete the following fields:
- Name: (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
- Address: (Required) The host address, without specifying a protocol.
Click Save.

resource "boundary_host_static" "my_host" {
  name            = "my-host"
  description     = "My static host"
  address         = "10.0.0.1"
  host_catalog_id = boundary_host_catalog_static.my_catalog.id
}

Create a host set

Complete the following steps to create a static host set containing a static host.

Log in to Boundary.
Select the org, and then select the project you want to create a host set for.
Select Host Catalogs.
Select a host catalog.
Click the Host Sets tab, and then click New.
Complete the following fields:
- Name: (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
Click Save.

Create a static host set:

$ boundary host-sets create static \
  -name "my-host-set" \
  -description "My host set" \
  -host-catalog-id hcst_1234567890

Add hosts to a host set:

$ boundary host-sets add-hosts \
  -id hsst_1234567890 \
  -host hst_1234567890 \
  -host hst_0987654321

To define this host set in Terraform:

resource "boundary_host_set_static" "my_host_set" {
  type            = "static"
  name            = "my-host-set"
  description     = "My host set"
  host_catalog_id = "hcst_1234567890"
  host_ids = [ boundary_host_static.my_host.id ]
}

Example

In this example you will create three hosts for separate databases. One for a hypothetical MySQL database running on 192.168.0.10 at port 3306, a second for another MySQL database running on 192.168.0.11 at port 3306, and a third for a Postgres database running on 192.168.0.20 at port 5432.

Host catalog:

databases

Hosts:

mysql1:
- Host address is 192.168.0.10
- Availability port is 3306
mysql2:
- Host address is 192.168.0.11
- Availability port is 3306
postgres:
- Host address is 192.168.0.20
- Availability port is 5432

Host sets:

mysql-hosts
- Hosts: mysql1 and mysql2
postgres-hosts
- Hosts: postgres

The databases host catalog will contain the mysql-hosts host set and the postgres-hosts host set. The mysql-hosts host set contains the mysql1 and mysql2 hosts, and the postgres-hosts host set contains the postgres host.

Create the databases host catalog

Complete the following steps to create a static host catalog named databases.

Log in to Boundary.
Select the org, and then select the project you want to create a host catalog for.
Select Host Catalogs.
Select New Host Catalog.
Complete the following fields:
- Name: databases (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
- Type: (Required) Select Static to create a static host catalog.
Click Save.

Log in to Boundary.
Set the BOUNDARY_PROJECT_ID environment variable, or provide the scope ID (such as p_1234567890) in the next step.
Use the following command to create a static host catalog named databases:
```
$ boundary host-catalogs create static \
  -scope-id $BOUNDARY_PROJECT_ID \
  -name "databases"
```
You must provide the scope-id field when you create a static host catalog.
Refer to the host catalogs domain model documentation for more fields that you can use when you create host catalogs.

You can define a host catalog using the Boundary Terraform provider:

resource "boundary_host_catalog_static" "databases" {
  name        = "databases"
  description = "A host catalog for all database types"
  scope_id    = boundary_scope.project.id
}

Create the MySQL and Postgres host sets

Host sets allow you to group hosts that provide equivalent services together. When a target references a host set, it selects any host from the set to establish a connection, unless you configure a target alias to use a specific host ID.

You must create hosts in a host catalog. Hosts must belong to a host set to add them to a target.

Create the MySQL host set

In this example, you first create a host set named mysql-hosts for the mysql1 and mysql2 hosts.

Log in to Boundary.
Select the org, and then select the project you want to create a host set for.
Select Host Catalogs.
Select the databases host catalog.
Click the Host Sets tab, and then click New.
Complete the following fields:
- Name: mysql-hosts (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
Click Save.

$ boundary host-sets create static -name "mysql-hosts" -description "MySQL host set" -host-catalog-id hcst_1234567890

Host Set information:
  Created Time:        Mon, 28 Sep 2025 18:27:10 PDT
  Description:         MySQL host set
  Host Catalog ID:     hcst_1234567890
  ID:                  hsst_z7gDCPSig5
  Name:                mysql-hosts
  Type:                static
  Updated Time:        Mon, 28 Sep 2025 18:27:10 PDT
  Version:             1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

To define this host set in Terraform:

resource "boundary_host_set_static" "mysql" {
  type            = "static"
  name            = "mysql-hosts"
  description     = "Host set for MySQL servers"
  host_catalog_id = "hcst_1234567890"
}

Create the Postgres host set

Create a host set named postgres-hosts for the postgres host.

Log in to Boundary.
Select the org, and then select the project you want to create a host set for.
Select Host Catalogs.
Select the databases host catalog.
Click the Host Sets tab, and then click New.
Complete the following fields:
- Name: postgres-hosts (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
Click Save.

$ boundary host-sets create static -name "postgres-hosts" -description "Postgres host set" -host-catalog-id hcst_1234567890

Host Set information:
  Created Time:        Mon, 28 Sep 2025 18:27:10 PDT
  Description:         Postgres host set
  Host Catalog ID:     hcst_1234567890
  ID:                  hsst_z7gDCPSig5
  Name:                postgres-hosts
  Type:                static
  Updated Time:        Mon, 28 Sep 2025 18:27:10 PDT
  Version:             1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

To define this host set in Terraform:

resource "boundary_host_set_static" "postgres" {
  type            = "static"
  name            = "postgres-hosts"
  description     = "Postgres host set"
  host_catalog_id = "hcst_1234567890"
}

Create hosts

Hosts can belong to a host catalog without being assigned to a host set, but you must add hosts to a host set before a target can connect to them.

Create the mysql hosts

Select Host Catalogs.
Select the databases host catalog.
Click the Hosts tab, and click New.
Complete the following fields:
- Name: mysql1 (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
- Address: 192.168.0.10 (Required) The host address, without specifying the protocol.
Click Save.

Repeat this process for the mysql2 host, with an address of 192.168.0.11.

Create the mysql1 host with address 192.168.0.1 within the mysql-hosts host catalog.

$ boundary host create static -name "mysql1" -description "MySQL host 1" -host-catalog-id hcst_1234567890 -address 192.168.0.10

    Host information:
      Created Time:        Fri, 27 May 2025 10:48:29 MDT
      Description:         MySQL host 1
      Host Catalog ID:     hcst_1234567890
      ID:                  hst_U1qYKzKfXO
      Name:                mysql1
      Type:                static
      Updated Time:        Fri, 27 May 2025 10:48:29 MDT
      Version:             1

      Scope:
        ID:                p_1234567890
        Name:              Generated project scope
        Parent Scope ID:   o_1234567890
        Type:              project

      Authorized Actions:
        no-op
        read
        update
        delete

      Attributes:
        address:           192.168.0.10

Repeat this process for the mysql2 host, with an address of 192.168.0.11.

$ boundary host create static -name "mysql2" -description "MySQL host 2" -host-catalog-id hcst_1234567890 -address 192.168.0.11

Host information:
  Created Time:        Fri, 27 May 2025 10:48:29 MDT
  Description:         MySQL host 2
  Host Catalog ID:     hcst_1234567890
  ID:                  hst_U1qYKzKfXO
  Name:                mysql2
  Type:                static
  Updated Time:        Fri, 27 May 2025 10:48:29 MDT
  Version:             1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete

  Attributes:
    address:           192.168.0.11

To create the mysql1 and mysql2 hosts in Terraform:

resource "boundary_host_static" "mysql1" {
  name            = "mysql1"
  description     = "MySQL Server host"
  address         = "192.168.0.10"
  host_catalog_id = boundary_host_catalog_static.databases.id
}

resource "boundary_host_static" "mysql2" {
  name            = "mysql2"
  description     = "MySQL Server host"
  address         = "192.168.0.11"
  host_catalog_id = boundary_host_catalog_static.databases.id
}

Add the hosts to the MySQL host set

Now that you created the mysql1 and mysql2 hosts, add them to the mysql-hosts host set you created earlier.

Select Host Catalogs.
Select the databases host catalog.
Click the Host Sets tab, and select postgres-hosts.
Click the Hosts tab.
Click the Manage drop-down menu, and select Add Existing Host.
Select the checkboxes for the mysql1 and mysql2 hosts.
Click Add Hosts.

Provide the mysql1 and mysql2 host IDs to the boundary host-sets add-hosts command.

$ boundary host-sets add-hosts -id=hsst_X8gmzYXbO4 -host=hst_U1qYKzKfXO -host=hst_xoKMbUsmQw

Host Set information:
  Created Time:        Fri, 27 May 2025 10:51:02 MDT
  Description:         MySQL host set
  Host Catalog ID:     hcst_1234567890
  ID:                  hsst_X8gmzYXbO4
  Name:                mysql-hosts
  Type:                static
  Updated Time:        Fri, 27 May 2025 10:59:00 MDT
  Version:             2

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete
    add-hosts
    set-hosts
    remove-hosts

  Host IDs:
    hst_U1qYKzKfXO
    hst_xoKMbUsmQw

To add hosts to the mysql-hosts host set in Terraform:

resource "boundary_host_set_static" "mysql" {
  type            = "static"
  name            = "mysql-hosts"
  description     = "Host set for MySQL servers"
  host_catalog_id = "hcst_1234567890"

  host_ids = [ boundary_host_static.mysql1.id, boundary_host_static.mysql2.id ]
}

Create the postgres host within the postgres host set

Create the postgres host within the postgres-hosts host set.

If you're using the UI, you can create a host and add it to a host set in one operation.

Select Host Catalogs.
Select the databases host catalog.
Click the Host Sets tab, and select postgres-hosts.
Click the Manage drop-down, and select Create and Add Host.
Complete the following fields:
- Name: postgres (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
- Address: 192.168.0.20 (Required) The host address, without specifying the protocol.
Click Save.

If you're using the CLI or Terraform, you must create the host before you can add it to a host set.

Create the postgres host with address 192.168.0.20 within the postgres-hosts host catalog.

$ boundary host create static -name "postgres" -description "Postgres host" -host-catalog-id hcst_1234567890 -address 192.168.0.20

Host information:
  Created Time:        Fri, 27 May 2025 11:48:29 MDT
  Description:         Postgres host
  Host Catalog ID:     hcst_1234567890
  ID:                  hst_FrdNPd9Zm9
  Name:                postgres
  Type:                static
  Updated Time:        Fri, 27 May 2025 11:48:29 MDT
  Version:             1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete

  Attributes:
    address:           192.168.0.20

Add the postgres host to the postgres-hosts host set you created earlier.

$ boundary host-sets add-hosts -id=hsst_z7gDCPSig5 -host=hst_FrdNPd9Zm9

Host Set information:
  Created Time:        Fri, 27 May 2025 10:51:02 MDT
  Description:         Postgres host set
  Host Catalog ID:     hcst_1234567890
  ID:                  hsst_X8gmzYXbO4
  Name:                postgres-hosts
  Type:                static
  Updated Time:        Fri, 27 May 2025 10:59:00 MDT
  Version:             2

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete
    add-hosts
    set-hosts
    remove-hosts

  Host IDs:
    hst_FrdNPd9Zm9

Create the postgres hosts in Terraform:

resource "boundary_host_static" "postgres" {
  name            = "postgres"
  description     = "Postgres Server host"
  address         = "192.168.0.20"
  host_catalog_id = boundary_host_catalog_static.databases.id
}

Create the postgres-hosts host set and add the postgres host in Terraform:

resource "boundary_host_set_static" "postgres" {
  type            = "static"
  name            = "postgres-hosts"
  description     = "Host set for Postgres servers"
  host_catalog_id = "hcst_1234567890"

  host_ids = [ boundary_host_static.postgres.id ]
}

Create a target

Targets define how a client should connect to a host within a host set.

Targets can set a direct target address to avoid using host catalogs. While this is useful for testing, at scale it becomes unmanageable to create and maintain separate targets for each host within a host set.

Host sets are assigned to targets to allow clients to connect to any available host in the host set.

Targets define the protocol and port used for a session with a host.

Create the mysql target

Create the mysql target with a default port of 3306.

Select Targets and click New.
Complete the following fields:
- Name: mysql (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
- Type: Generic TCP (Required)
- Default Port: 3306 (Required)
Click Save.

Add the mysql-hosts host set as the host source for the target.

Select the Host Sources tab.
Click Add Host Sources.
Select the checkboxes for the mysql-hosts host set.
Click Add Host Sources.

Create the mysql target with a default port of 3306.

$ boundary targets create tcp -name="mysql" -description="MySQL target" -default-port=3389 -scope-id=p_1234567890 -session-connection-limit="-1" -host-source

Target information:
  Created Time:               Fri, 27 May 2025 11:02:22 MDT
  Description:                MySQL target
  ID:                         ttcp_34yV5O9cwt
  Name:                       mysql
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Fri, 27 May 2025 11:02:22 MDT
  Version:                    1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete
    add-host-sources
    set-host-sources
    remove-host-sources
    add-credential-libraries
    set-credential-libraries
    remove-credential-libraries
    add-credential-sources
    set-credential-sources
    remove-credential-sources
    authorize-session

  Attributes:
    Default Port:             3306

Add the mysql-hosts host set as the host source for the target.

$ boundary targets add-host-sources -id=ttcp_34yV5O9cwt -host-source=hsst_X8gmzYXbO4

Target information:
  Created Time:               Fri, 27 May 2025 11:02:22 MDT
  Description:                MySQL target
  ID:                         ttcp_34yV5O9cwt
  Name:                       mysql
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Fri, 27 May 2025 11:07:59 MDT
  Version:                    2

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete
    add-host-sources
    set-host-sources
    remove-host-sources
    add-credential-libraries
    set-credential-libraries
    remove-credential-libraries
    add-credential-sources
    set-credential-sources
    remove-credential-sources
    authorize-session

  Host Sources:
    Host Catalog ID:          hcst_1234567890
    ID:                       hcst_xM3iCCkf1K

  Attributes:
    Default Port:             3306

Create the mysql target with a default port of 3306 and add the mysql-hosts host set as the host source.

resource "boundary_target" "mysql" {
  type                     = "tcp"
  name                     = "mysql"
  description              = "MySQL target for mysql-hosts host catalog"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  session_max_seconds      = 300
  default_port             = 5432
  host_source_ids = [
    boundary_host_set_static.mysql.id
  ]
}

Create the postgres target

Select Targets and click New.
Complete the following fields:
- Name: postgres (Optional) An optional name for identification purposes. If you enter a name, it must be unique.
- Description: (Optional) An optional description of the host catalog for identification purposes.
- Type: Generic TCP (Required)
- Default Port: 5432 (Required)
Click Save.

Add a host source.

Select the Host Sources tab.
Click Add Host Sources.
Select the checkboxes for the postgres-hosts host set.
Click Add Host Sources.

Create the postgres target with a default port of 5432.

$ boundary targets create tcp -name="postgres" -description="Postgres target" -default-port=5432 -scope-id=p_1234567890 -session-connection-limit="-1"

Target information:
  Created Time:               Fri, 27 May 2025 11:02:22 MDT
  Description:                Postgres target
  ID:                         ttcp_ge1Mowyrej
  Name:                       mysql
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Fri, 27 May 2025 11:02:22 MDT
  Version:                    1

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete
    add-host-sources
    set-host-sources
    remove-host-sources
    add-credential-libraries
    set-credential-libraries
    remove-credential-libraries
    add-credential-sources
    set-credential-sources
    remove-credential-sources
    authorize-session

  Attributes:
    Default Port:             5432

Add the postgres-hosts host set as the host source for the target.

$ boundary targets add-host-sources -id=ttcp_ge1Mowyrej -host-source=hsst_z7gDCPSig5

Target information:
  Created Time:               Fri, 27 May 2025 11:02:22 MDT
  Description:                Postgres target
  ID:                         ttcp_ge1Mowyrej
  Name:                       postgres
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Fri, 27 May 2025 11:07:59 MDT
  Version:                    2

  Scope:
    ID:                p_1234567890
    Name:              Generated project scope
    Parent Scope ID:   o_1234567890
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete
    add-host-sources
    set-host-sources
    remove-host-sources
    add-credential-libraries
    set-credential-libraries
    remove-credential-libraries
    add-credential-sources
    set-credential-sources
    remove-credential-sources
    authorize-session

  Host Sources:
    Host Catalog ID:          hcst_1234567890
    ID:                       hsst_X8gmzYXbO4

  Attributes:
    Default Port:             5432

Create the postgres target with a default port of 5432 and add the postgres-hosts host set as the host source.

resource "boundary_target" "postgres" {
  type                     = "tcp"
  name                     = "postgres"
  description              = "Postgres target for postgres-hosts host catalog"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  session_max_seconds      = 300
  default_port             = 5432
  host_source_ids = [
    boundary_host_set_static.postgres.id
  ]
}

You should now be able to start a session for any of these targets using the CLI or Boundary Desktop Client. If these hosts actually existed at these addresses, you would be able to connect.

More information

Refer to Filtering and listing resources for more information about Boundary's filter syntax and best practices.

To learn about how to connect to a target, refer to the Connection workflows documentation.