controller Stanza

The controller stanza configures Boundary controller-specific parameters.

  1. controller {
  2.   name = "example-controller"
  3.   description = "An example controller"
  4.   database {
  5.     url = "postgresql://<username>:<password>@10.0.0.1:5432/<database_name>"
  6.     max_open_connections = 5
  7.   }
  8. }
  1. controller {  name = "example-controller"  description = "An example controller"  database {    url = "postgresql://<username>:<password>@10.0.0.1:5432/<database_name>"    max_open_connections = 5  }}

  • name - Specifies a unique name of this controller within the Boundary cluster. This value can be a direct name string, can refer to a file on disk (file://) from which an name will be read; or an env var (env://) from which the name will be read.

  • description - Specifies a friendly description of this controller.

  • database - Configuration block with two valid parameters for connecting to Postgres:

    • url - Configures the URL for connecting to Postgres. If your Postgres server has TLS disabled, Boundary will not be able to connect by default. To run Boundary without a TLS connection to Postgres (not recommended for production usage), add the sslmode=disable parameter to your connection string, such as url = "postgresql://postgres:boundary@192.168.1.1:5432/boundary?sslmode=disable"
    • migration_url - Can be used to specify a different URL for migrations, as that usually requires higher privileges.
    • max_open_connections - Can be used to control the maximum number of connections that can be opened by the controller. The minimum number of connections required is 5. Setting this value to 0 will allow the controller to open as many connections as needed.

    Either URL can refer to a file on disk (file://) from which a URL will be read; an env var (env://) from which the URL will be read; or a direct database URL (postgres://).

  • public_cluster_addr - Specifies the public host or IP address (and optionally port) at which the controller can be reached by workers. This will be used by workers after initial connection to controllers via the worker’s controllers block. This defaults to the address of the listener marked for cluster purpose. This is especially useful for cloud environments that do not bind a publicly accessible IP to a NIC on the host directly, such as an Amazon EIP. This value can be a direct address string, can refer to a file on disk (file://) from which an address will be read; or an env var (env://) from which the address will be read.

  • auth_token_time_to_live - Maximum time to live (TTL) for all auth tokens globally (pertains to all tokens from all auth methods). Valid time units are anything specified by Golang’s ParseDuration() method. Default is 7 days.

  • auth_token_time_to_stale - Maximum time of inactivity for all auth tokens globally (pertains to all tokens from all auth methods). Valid time units are anything specified by Golang’s ParseDuration() method. Default is 1 day.

KMS Configuration

The controller requires two KMS stanzas for root and worker-auth purposes:

  1. # Root KMS configuration block: this is the root key for Boundary
  2. # Use a production KMS such as AWS KMS in production installs
  3. kms "aead" {
  4.   purpose = "root"
  5.   aead_type = "aes-gcm"
  6.   key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
  7.   key_id = "global_root"
  8. }
  10. # Worker authorization KMS
  11. # Use a production KMS such as AWS KMS for production installs
  12. # This key is the same key used in the worker configuration
  13. kms "aead" {
  14.   purpose = "worker-auth"
  15.   aead_type = "aes-gcm"
  16.   key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  17.   key_id = "global_worker-auth"
  18. }
  1. # Root KMS configuration block: this is the root key for Boundary# Use a production KMS such as AWS KMS in production installskms "aead" {  purpose = "root"  aead_type = "aes-gcm"  key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="  key_id = "global_root"}
  2. # Worker authorization KMS# Use a production KMS such as AWS KMS for production installs# This key is the same key used in the worker configurationkms "aead" {  purpose = "worker-auth"  aead_type = "aes-gcm"  key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="  key_id = "global_worker-auth"}

And optionally, a KMS stanza for recovery purpose:

  1. # Recovery KMS block: configures the recovery key for Boundary
  2. # Use a production KMS such as AWS KMS for production installs
  3. kms "aead" {
  4.   purpose = "recovery"
  5.   aead_type = "aes-gcm"
  6.   key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  7.   key_id = "global_recovery"
  8. }
  1. # Recovery KMS block: configures the recovery key for Boundary# Use a production KMS such as AWS KMS for production installskms "aead" {  purpose = "recovery"  aead_type = "aes-gcm"  key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="  key_id = "global_recovery"}

And optionally, a KMS stanza for configuration encryption purpose:

  1. # Configuration encryption block: decrypts sensitive values in the
  2. # configuration file. See `boundary config [encrypt|decrypt] -h`.
  3. kms "aead" {
  4.   purpose   = "config"`
  5.   aead_type = "aes-gcm"
  6.   key       = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
  7. }
  1. # Configuration encryption block: decrypts sensitive values in the# configuration file. See `boundary config [encrypt|decrypt] -h`.kms "aead" {  purpose   = "config"`  aead_type = "aes-gcm"  key       = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="}

Boundary supports many kinds of KMS integrations. For a complete guide to all available KMS types, see our KMS documentation.

Complete Configuration Example

  1. # Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html
  2. disable_mlock = true
  4. # Controller configuration block
  5. controller {
  6.   # This name attr must be unique across all controller instances if running in HA mode
  7.   name = "demo-controller-1"
  8.   description = "A controller for a demo!"
  10.   # Database URL for postgres. This can be a direct "postgres://"
  11.   # URL, or it can be "file://" to read the contents of a file to
  12.   # supply the url, or "env://" to name an environment variable
  13.   # that contains the URL.
  14.   database {
  15.       url = "postgresql://boundary:boundarydemo@postgres.yourdomain.com:5432/boundary"
  16.   }
  17. }
  19. # API listener configuration block
  20. listener "tcp" {
  21.   # Should be the address of the NIC that the controller server will be reached on
  22.   address = "10.0.0.1"
  23.   # The purpose of this listener block
  24.   purpose = "api"
  26.   tls_disable = false
  28.   # Uncomment to enable CORS for the Admin UI. Be sure to set the allowed origin(s)
  29.   # to appropriate values.
  30.   #cors_enabled = true
  31.   #cors_allowed_origins = ["https://yourcorp.yourdomain.com", "serve://boundary"]
  32. }
  34. # Data-plane listener configuration block (used for worker coordination)
  35. listener "tcp" {
  36.   # Should be the IP of the NIC that the worker will connect on
  37.   address = "10.0.0.1"
  38.   # The purpose of this listener
  39.   purpose = "cluster"
  40. }
  42. # Root KMS configuration block: this is the root key for Boundary
  43. # Use a production KMS such as AWS KMS in production installs
  44. kms "aead" {
  45.   purpose = "root"
  46.   aead_type = "aes-gcm"
  47.   key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
  48.   key_id = "global_root"
  49. }
  51. # Worker authorization KMS
  52. # Use a production KMS such as AWS KMS for production installs
  53. # This key is the same key used in the worker configuration
  54. kms "aead" {
  55.   purpose = "worker-auth"
  56.   aead_type = "aes-gcm"
  57.   key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  58.   key_id = "global_worker-auth"
  59. }
  61. # Recovery KMS block: configures the recovery key for Boundary
  62. # Use a production KMS such as AWS KMS for production installs
  63. kms "aead" {
  64.   purpose = "recovery"
  65.   aead_type = "aes-gcm"
  66.   key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  67.   key_id = "global_recovery"
  68. }
  1. # Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.htmldisable_mlock = true
  2. # Controller configuration blockcontroller {  # This name attr must be unique across all controller instances if running in HA mode  name = "demo-controller-1"  description = "A controller for a demo!"
  3.   # Database URL for postgres. This can be a direct "postgres://"  # URL, or it can be "file://" to read the contents of a file to  # supply the url, or "env://" to name an environment variable  # that contains the URL.  database {      url = "postgresql://boundary:boundarydemo@postgres.yourdomain.com:5432/boundary"  }}
  4. # API listener configuration blocklistener "tcp" {  # Should be the address of the NIC that the controller server will be reached on  address = "10.0.0.1"  # The purpose of this listener block  purpose = "api"
  5.   tls_disable = false
  6.   # Uncomment to enable CORS for the Admin UI. Be sure to set the allowed origin(s)  # to appropriate values.  #cors_enabled = true  #cors_allowed_origins = ["https://yourcorp.yourdomain.com", "serve://boundary"]}
  7. # Data-plane listener configuration block (used for worker coordination)listener "tcp" {  # Should be the IP of the NIC that the worker will connect on  address = "10.0.0.1"  # The purpose of this listener  purpose = "cluster"}
  8. # Root KMS configuration block: this is the root key for Boundary# Use a production KMS such as AWS KMS in production installskms "aead" {  purpose = "root"  aead_type = "aes-gcm"  key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="  key_id = "global_root"}
  9. # Worker authorization KMS# Use a production KMS such as AWS KMS for production installs# This key is the same key used in the worker configurationkms "aead" {  purpose = "worker-auth"  aead_type = "aes-gcm"  key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="  key_id = "global_worker-auth"}
  10. # Recovery KMS block: configures the recovery key for Boundary# Use a production KMS such as AWS KMS for production installskms "aead" {  purpose = "recovery"  aead_type = "aes-gcm"  key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="  key_id = "global_recovery"}