boundary/website/content/docs/configuration/controller.mdx

---
layout: docs
page_title: Controller - Configuration
sidebar_title: controller
description: |-
  The controller stanza configures controller-specifc parameters.
---

# `controller` Stanza

The `controller` stanza configures Boundary controller-specific parameters.

```hcl
controller {
  name = "example-controller"
  description = "An example controller"
  database {
    url = "postgresql://<username>:<password>@10.0.0.1:5432/<database_name>"
  }
}
```

- `name` - Specifies a unique name of this controller within the Boundary controller cluster.

- `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
    - `migration_url` - Can be used to specify a different URL for the migrations, as that 
       usually requires higher priviledges.

    Either 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://).

# Complete Configuration Example

```hcl
# Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html
disable_mlock = true

# Controller configuration block
controller {
  # 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!"

  # 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@${aws_db_instance.boundary.endpoint}/boundary"
  }
}

# API listener configuration block
listener "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"

  tls_disable = false
  proxy_protocol_behavior = "allow_authorized"
  proxy_protocol_authorized_addrs = "127.0.0.1"

  # Enable CORS for the Admin UI
  cors_enabled = true
  cors_allowed_origins = ["*"]
}

# 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"

  tls_disable = false 
  proxy_protocol_behavior = "allow_authorized"
  proxy_protocol_authorized_addrs = "127.0.0.1"
}

# Root KMS configuration block: this is the root key for Boundary
# Use a production KMS such as AWS KMS in production installs
kms "aead" {
  purpose = "root"
  aead_type = "aes-gcm"
  key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
  key_id = "global_root"
}

# Worker authorization KMS
# Use a production KMS such as AWS KMS for production installs
# This key is the same key used in the worker configuration
kms "aead" {
  purpose = "worker-auth"
  aead_type = "aes-gcm"
  key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  key_id = "global_worker-auth"
}

# Recovery KMS block: configures the recovery key for Boundary
# Use a production KMS such as AWS KMS for production installs
kms "aead" {
  purpose = "recovery"
  aead_type = "aes-gcm"
  key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
  key_id = "global_recovery"
}
```