From 199207aa60db234e8960204518bc6eb19ca4d0b1 Mon Sep 17 00:00:00 2001 From: Jeff Malnick Date: Tue, 6 Oct 2020 07:58:01 -0700 Subject: [PATCH] docs: add complete config examples to controller and worker sections (#548) --- .../content/docs/configuration/controller.mdx | 80 ++++++++++++ website/content/docs/configuration/index.mdx | 120 +----------------- website/content/docs/configuration/worker.mdx | 44 +++++++ 3 files changed, 125 insertions(+), 119 deletions(-) diff --git a/website/content/docs/configuration/controller.mdx b/website/content/docs/configuration/controller.mdx index 70ff612bdd..04bec30e9c 100644 --- a/website/content/docs/configuration/controller.mdx +++ b/website/content/docs/configuration/controller.mdx @@ -31,3 +31,83 @@ controller { 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" +} +``` + + diff --git a/website/content/docs/configuration/index.mdx b/website/content/docs/configuration/index.mdx index b9c9380ed4..ae39cd209f 100644 --- a/website/content/docs/configuration/index.mdx +++ b/website/content/docs/configuration/index.mdx @@ -72,122 +72,4 @@ After the configuration is written, use the `-config` flag to specify a local pa ## Example Configurations -The following examples are broken down for controllers and workers. If you're running an all-in-one deployment with the controller and worker on the same host via `boundary server`, then concatonate these files together. - -### Controller Configuration - -```hcl -# Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html -disable_mlock = true - -telemetry { - # TODO: prometheus is not currently implemented - prometheus_retention_time = "24h" - disable_hostname = true -} - -# Controller configuration block -controller { - # This name attr must be unique! - name = "demo-controller-${count.index}" - # Description of this controller - description = "A controller for a demo!" -} - -# API listener configuration block -listener "tcp" { - # Should be the address of the NIC that the controller server will be reached on - address = "${self.private_ip}:9200" - # The purpose of this listener block - purpose = "api" - # Should be enabled for production installs - tls_disable = true - # TODO - # proxy_protocol_behavior = "allow_authorized" - # TODO - # 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 = "${self.private_ip}:9201" - # The purpose of this listener - purpose = "cluster" - # Should be enabled for production installs - tls_disable = true - # TODO - # proxy_protocol_behavior = "allow_authorized" - # TODO - # 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" -} - -# 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" -} -``` - -### Worker Configuration - -```hcl -listener "tcp" { - purpose = "proxy" - tls_disable = true - #proxy_protocol_behavior = "allow_authorized" - #proxy_protocol_authorized_addrs = "127.0.0.1" -} - -worker { - # Name attr must be unique - name = "demo-worker-${count.index}" - description = "A default worker created demonstration" - controllers = [ - "${aws_instance.controller[0].private_ip}", - "${aws_instance.controller[1].private_ip}", - "${aws_instance.controller[2].private_ip}" - ] -} - -# must be same key as used on controller config -kms "aead" { - purpose = "worker-auth" - aead_type = "aes-gcm" - key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" - key_id = "global_worker-auth" -} -``` +For complete example configurations see the sections for [controller](/docs/configuration/controller) and [worker](/docs/configuration/worker). diff --git a/website/content/docs/configuration/worker.mdx b/website/content/docs/configuration/worker.mdx index 38b69dff8a..c9613faa59 100644 --- a/website/content/docs/configuration/worker.mdx +++ b/website/content/docs/configuration/worker.mdx @@ -23,3 +23,47 @@ worker { - `description` - Specifies a friendly description of this worker. - `public_addr` - Specifies the public IP address for the worker to be reached on. This is useful for cloud environemnts that do not bind a publically accessible IP to a NIC on the host directly, such as an Amazon EIP. + +- `controllers` - A list of IP addresses for reaching controllers on port :9202. + +- KMS block designated for `worker-auth` - This is the KMS configuration for authentication between the workers and controllers and must be present. Example: +```hcl +kms "aead" { + purpose = "worker-auth" + aead_type = "aes-gcm" + key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" + key_id = "global_worker-auth" +} +``` + +# Complete Configuration Example + +```hcl +listener "tcp" { + purpose = "proxy" + tls_disable = true + proxy_protocol_behavior = "allow_authorized" + proxy_protocol_authorized_addrs = "127.0.0.1" +} + +worker { + # Name attr must be unique across workers if running in HA mode + name = "demo-worker-1" + description = "A default worker created demonstration" + + # Workers must be able to reach controllers on :9202 + controllers = [ + "10.0.0.1", + "10.0.0.2", + "10.0.0.3", + ] +} + +# must be same key as used on controller config +kms "aead" { + purpose = "worker-auth" + aead_type = "aes-gcm" + key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" + key_id = "global_worker-auth" +} +```