diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 99f8b9c5a..8cb50e028 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -8,12 +8,19 @@ export default [ { - category: 'introduction', + category: 'getting-started', + content: ['building', 'run-and-login', 'connect-to-target'], + }, + { + category: 'installing', + content: ['production'], + }, + { + category: 'concepts', content: [ 'security-model', - 'reference-architecture', { - category: 'concepts', + category: 'domain-model', content: [ 'actions', 'auth-methods', @@ -34,10 +41,6 @@ export default [ }, ], }, - { - category: 'installing', - content: ['dev-mode', 'production'], - }, { category: 'configuration', content: [ diff --git a/website/package-lock.json b/website/package-lock.json index 87da21474..f12c99552 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -1,5 +1,5 @@ { - "name": "example-docs", + "name": "boundary-docs", "version": "1.0.0", "lockfileVersion": 1, "requires": true, diff --git a/website/pages/docs/introduction/concepts/actions.mdx b/website/pages/docs/concepts/domain-model/actions.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/actions.mdx rename to website/pages/docs/concepts/domain-model/actions.mdx diff --git a/website/pages/docs/introduction/concepts/auth-methods.mdx b/website/pages/docs/concepts/domain-model/auth-methods.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/auth-methods.mdx rename to website/pages/docs/concepts/domain-model/auth-methods.mdx diff --git a/website/pages/docs/introduction/concepts/grants.mdx b/website/pages/docs/concepts/domain-model/grants.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/grants.mdx rename to website/pages/docs/concepts/domain-model/grants.mdx diff --git a/website/pages/docs/introduction/concepts/groups.mdx b/website/pages/docs/concepts/domain-model/groups.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/groups.mdx rename to website/pages/docs/concepts/domain-model/groups.mdx diff --git a/website/pages/docs/introduction/concepts/host-catalogs.mdx b/website/pages/docs/concepts/domain-model/host-catalogs.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/host-catalogs.mdx rename to website/pages/docs/concepts/domain-model/host-catalogs.mdx diff --git a/website/pages/docs/introduction/concepts/host-sets.mdx b/website/pages/docs/concepts/domain-model/host-sets.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/host-sets.mdx rename to website/pages/docs/concepts/domain-model/host-sets.mdx diff --git a/website/pages/docs/introduction/concepts/hosts.mdx b/website/pages/docs/concepts/domain-model/hosts.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/hosts.mdx rename to website/pages/docs/concepts/domain-model/hosts.mdx diff --git a/website/pages/docs/introduction/concepts/index.mdx b/website/pages/docs/concepts/domain-model/index.mdx similarity index 87% rename from website/pages/docs/introduction/concepts/index.mdx rename to website/pages/docs/concepts/domain-model/index.mdx index b50228d1d..c46649f2f 100644 --- a/website/pages/docs/introduction/concepts/index.mdx +++ b/website/pages/docs/concepts/domain-model/index.mdx @@ -3,7 +3,7 @@ layout: docs page_title: Domain Model Index sidebar_title: Domain Model description: |- - Reference documentation for configuring Boundary + Reference documentation for Boundary's domain model. --- # Overview diff --git a/website/pages/docs/introduction/concepts/organization.mdx b/website/pages/docs/concepts/domain-model/organization.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/organization.mdx rename to website/pages/docs/concepts/domain-model/organization.mdx diff --git a/website/pages/docs/introduction/concepts/principals.mdx b/website/pages/docs/concepts/domain-model/principals.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/principals.mdx rename to website/pages/docs/concepts/domain-model/principals.mdx diff --git a/website/pages/docs/introduction/concepts/projects.mdx b/website/pages/docs/concepts/domain-model/projects.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/projects.mdx rename to website/pages/docs/concepts/domain-model/projects.mdx diff --git a/website/pages/docs/introduction/concepts/resources.mdx b/website/pages/docs/concepts/domain-model/resources.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/resources.mdx rename to website/pages/docs/concepts/domain-model/resources.mdx diff --git a/website/pages/docs/introduction/concepts/roles.mdx b/website/pages/docs/concepts/domain-model/roles.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/roles.mdx rename to website/pages/docs/concepts/domain-model/roles.mdx diff --git a/website/pages/docs/introduction/concepts/scopes.mdx b/website/pages/docs/concepts/domain-model/scopes.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/scopes.mdx rename to website/pages/docs/concepts/domain-model/scopes.mdx diff --git a/website/pages/docs/introduction/concepts/targets.mdx b/website/pages/docs/concepts/domain-model/targets.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/targets.mdx rename to website/pages/docs/concepts/domain-model/targets.mdx diff --git a/website/pages/docs/introduction/concepts/users.mdx b/website/pages/docs/concepts/domain-model/users.mdx similarity index 100% rename from website/pages/docs/introduction/concepts/users.mdx rename to website/pages/docs/concepts/domain-model/users.mdx diff --git a/website/pages/docs/concepts/index.mdx b/website/pages/docs/concepts/index.mdx new file mode 100644 index 000000000..a14054791 --- /dev/null +++ b/website/pages/docs/concepts/index.mdx @@ -0,0 +1,12 @@ +--- +layout: docs +page_title: Concepts +sidebar_title: Concepts +description: |- + An introduction to Boundary concepts and architecture. +--- + +# Concepts + +There are several concepts in Boundary that are important to understand. These concepts include our [security model](/docs/concepts/security-model), our [domain model](/docs/concepts/domain-model), and +our general recommendations for [deployment architecture](/docs/installing/production). diff --git a/website/pages/docs/introduction/security-model.mdx b/website/pages/docs/concepts/security-model.mdx similarity index 100% rename from website/pages/docs/introduction/security-model.mdx rename to website/pages/docs/concepts/security-model.mdx diff --git a/website/pages/docs/getting-started/building.mdx b/website/pages/docs/getting-started/building.mdx new file mode 100644 index 000000000..1f368aa79 --- /dev/null +++ b/website/pages/docs/getting-started/building.mdx @@ -0,0 +1,30 @@ +--- +layout: docs +page_title: Documentation +sidebar_title: Building +description: Building Boundary +--- + +# Building Boundary + +Building Boundary from source has a few requirements: + +- [Golang](https://golang.org/dl/) 1.15 or greater +- `make` installed +- [Docker](https://docs.docker.com/get-docker/) installed +- Basic development environment (git, xcode if you're on Mac, etc) + +1. `git clone https://github.com/hashicorp/boundary` or if you're using SSH auth for + github, `git clone git@github.com:hashicorp/boundary` +2. `cd boundary` +3. `make dev` + +Once you've built Boundary, the binary will be available at `/bin/boundary`. Move this +binary to somewhere in your `$PATH` such as `/usr/local/bin`. + +## Cross Platform Build + +If you need to cross compile boundary for another OS or architecture, use the [XC_OSARCH](https://github.com/hashicorp/boundary/blob/master/scripts/build.sh#L26) +environment variable to set this. Example: `XC_OSARCH=linux/amd64 make dev` + +For more details, please consult the [Boundary project on GitHub](https://github.com/hashicorp/boundary#build-and-start-boundary-in-dev-mode). diff --git a/website/pages/docs/getting-started/connect-to-target.mdx b/website/pages/docs/getting-started/connect-to-target.mdx new file mode 100644 index 000000000..f6152fd01 --- /dev/null +++ b/website/pages/docs/getting-started/connect-to-target.mdx @@ -0,0 +1,8 @@ +--- +layout: docs +page_title: Documentation +sidebar_title: Connect to Target +description: Connecting to your first target +--- + +# Connect to Your First Target diff --git a/website/pages/docs/getting-started/index.mdx b/website/pages/docs/getting-started/index.mdx new file mode 100644 index 000000000..c7d0c7c2b --- /dev/null +++ b/website/pages/docs/getting-started/index.mdx @@ -0,0 +1,10 @@ +--- +layout: docs +page_title: Documentation +sidebar_title: Getting Started +description: Getting started with Boundary +--- + +# Getting Started + +Before getting started with Boundary, it's important to understand a few key concepts. Please consult our [Boundary concepts](/docs/concepts) page to familiarize yourself with Boundary's architecture, and terminology. diff --git a/website/pages/docs/getting-started/installing/index.mdx b/website/pages/docs/getting-started/installing/index.mdx new file mode 100644 index 000000000..233d53327 --- /dev/null +++ b/website/pages/docs/getting-started/installing/index.mdx @@ -0,0 +1,11 @@ +--- +layout: docs +page_title: Installing Boundary +sidebar_title: Installing +description: |- + How to install boundary. +--- + +# Overview + +This section covers installing Boundary for development and production modes of operation. diff --git a/website/pages/docs/getting-started/installing/production.mdx b/website/pages/docs/getting-started/installing/production.mdx new file mode 100644 index 000000000..92c6756cc --- /dev/null +++ b/website/pages/docs/getting-started/installing/production.mdx @@ -0,0 +1,246 @@ +--- +layout: docs +page_title: Production Installation +sidebar_title: Production Install +description: |- + How to install Boundary in a production environment +--- + +# Production Installation + +Installing Boundary in a production setting requires prerequisits for infrastructure. At the most basic level, Boundary operators should run a minimum of 3 controllers and 3 workers. Running 3 of each server type gives a fundamental level of high availability for the control plane (controller), as well as bandwith for number of sessions on the data plane (worker). Both server type should be ran in a fault tolerant setting, that is, in a self-healing environmnet such as an auto-scaling group. The documentation here does not cover self-healing infrastructure and assumes the operator has their preferred scheduling methods for these environments. + +## Network Requirements + +- Client -> Controller port is :9200 +- Controller -> Worker port is :9201 +- Client must have access to Controller on :9200 +- :9201 must be open between Worker and Controller +- Workers must have a route and port access to the targets which they service + +## Architecture + +The general architecture for the server infrastructure requires 3 controllers and 3 workers. The documentation here uses virtual machines running on Amazon EC2 as the example environment, but this use +case can be extrapolated to almost any cloud platform to suit operator needs: + +![](/img/production.png) + +As shown above, Boundary is broken up into its controller and worker server components across 3 [EC2 instances](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance), in +3 separate [subnets](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/subnet), in three separate [availability zones](), with the controller API and UI being publically exposed by an [application load balancer (ALB)](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb). The worker and controller VM's are in independant [auto-scaling groups](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/autoscaling_group), allowing them to maintain their exact capacity. + +Boundary requires an external [Postgres](https://www.postgresql.org/) and [KMS](https://aws.amazon.com/kms/). In the example above, we're using AWS managed services for these components. For Postgres, we're using [RDS](https://aws.amazon.com/rds/) and for KMS we're using Amazon's [Key Management Service](https://aws.amazon.com/kms/). + +## Architecture Breakdown + +### API and Console Load Balancer + +Load balancing the controller allows operators to secure the ingress to the Boundary system. We recommend placing all Boundary server's in private networks and using load balancing tecniques to expose services such as the API and administrative console to public networks. In the production architecture, we recommend load balancing using a layer 7 load balancer and further constraining ingress to that load balancer with layer 4 constraints such as [security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) or [IP tables](https://wiki.archlinux.org/index.php/Iptables). + +For general configuration, we recommend the following: + +- HTTPS listener with valid TLS certificate for the domain it's serving or TLS passthrough +- Health check port should use :9200 with TCP protocol + +### Controller Configuration + +When running Boundary controller as a service we recommend storing the file at `/etc/boundary-controller.hcl`. A `boundary` user and group should exist to manage this configuration file and to further restrict who can read and modify it. + +Example 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, can be overridden with PG_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" +} +``` + +name must be unique! + +### Installation + +`TYPE` below can be either `worker` or `controller`. + +1. `/etc/boundary-${TYPE}.hcl`: Configuration file for the boundary service + See above example configurations. + +2. `/usr/local/bin/boundary`: The Boundary binary + Can build from https://github.com/hashicorp/boundary or download binary from our release pages. + +3. `/etc/systemd/system/boundary-${TYPE}.service`: Systemd unit file for the Boundary service + Example: + +``` +[Unit] +Description=${NAME} ${TYPE} + +[Service] +ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl +User=boundary +Group=boundary +LimitMEMLOCK=infinity +Capabilities=CAP_IPC_LOCK+ep +CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK + +[Install] +WantedBy=multi-user.target +``` + +Here's a simple install script that creates the boundary group and user, installs the +systemd unit file and enables it at startup: + +``` +#!/bin/bash +# Installs the boundary as a service for systemd on linux +# Usage: ./install.sh + +TYPE=$1 +NAME=boundary + +sudo cat << EOF > /etc/systemd/system/${NAME}-${TYPE}.service +[Unit] +Description=${NAME} ${TYPE} + +[Service] +ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl +User=boundary +Group=boundary +LimitMEMLOCK=infinity +Capabilities=CAP_IPC_LOCK+ep +CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK + +[Install] +WantedBy=multi-user.target +EOF + +# Add the boundary system user and group to ensure we have a no-login +# user capable of owning and running Boundary +sudo adduser --system --group boundary || true +sudo chown boundary:boundary /etc/${NAME}-${TYPE}.hcl +sudo chown boundary:boundary /usr/local/bin/boundary + +# Make sure to initialize the DB before starting the service. This will result in +# a database already initizalized warning if another controller or worker has done this +# already, making it a lazy, best effort initialization +if [ "${TYPE}" = "controller" ]; then + sudo /usr/local/bin/boundary database init -config /etc/${NAME}-${TYPE}.hcl || true +fi + +sudo chmod 664 /etc/systemd/system/${NAME}-${TYPE}.service +sudo systemctl daemon-reload +sudo systemctl enable ${NAME}-${TYPE} +sudo systemctl start ${NAME}-${TYPE} +``` + +### Postgres Configuration + +TBD + +### KMS Configuration + +TBD diff --git a/website/pages/docs/installing/dev-mode.mdx b/website/pages/docs/getting-started/run-and-login.mdx similarity index 57% rename from website/pages/docs/installing/dev-mode.mdx rename to website/pages/docs/getting-started/run-and-login.mdx index e63f6958d..992585117 100644 --- a/website/pages/docs/installing/dev-mode.mdx +++ b/website/pages/docs/getting-started/run-and-login.mdx @@ -1,16 +1,18 @@ --- layout: docs -page_title: Development Mode -sidebar_title: Dev Mode +page_title: Run and Login +sidebar_title: Run and Login description: |- - How to install Boundary in development mode + How to run Boundary services in dev mode and login for the first time. --- -# Development Mode +# Run and Login to Boundary + +Before you can do anything with Boundary, you need to get the Boundary services up and running for the first time. To do this, we're going to run Boundary in `dev` mode. Dev mode is an all-in-one installation method for getting started with Boundary quickly. As the name implies, dev mode is not a production installation method, but instead a way to get Boundary running with a Postgres -database easily. Do not use dev mode in a production environment, see our "Production Installation" section for +database easily. Do not use dev mode in a production environment, see [Poduction Installation](/docs/installing/production) section for production ready deployment methods. Dev mode brings up a fully functioning instance of Boundary, including: @@ -23,19 +25,19 @@ These components should all be considered ephemeral - no data persistence occurs strongly recommended that users leverage our [Terraform Provider for Boundary](https://github.com/hashicorp/terraform-provider-boundary) for managing configuration of Boundary. This will simplify starting up and shutting down your Boundary dev instance. -## Assumptions +## Requiements There are a few requirements for running dev mode: 1. Docker is installed 2. A route to download the [Postgres Docker image](https://hub.docker.com/_/postgres) is available or a local image cache is available -## Run +## Start Boundary Services To start Boundary in dev mode: ```bash -./boundary dev +boundary dev ``` The above is the most simple way to start the Boundary server in dev mode. However, there are likely some overrides you'll want to configure when @@ -48,13 +50,31 @@ doing so, these include: To use these overrides, set the following flags: ```bash -./boundary dev -dev-auth-method-id=ampw_0000000000 -dev-password=foofoofoo -dev-login-name=foo +boundary dev -dev-auth-method-id=ampw_0000000000 -dev-password=foofoofoo -dev-login-name=foo ``` Setting these allows you to configure hardcoded auth method ID, password, and login name. You can then use these hardcoded values when configuring clients such as the Terraform Provider, or when logging into the admin console. -An example using these values to configure your Terraform provider instance for Boundary: +## Login to Boundary + +You can use the values from the above example to authenticate. + +For CLI users, you can override using flags: + +``` +# Boundary uses http not https in dev mode +export BOUNDARY_ADDR=http://127.0.0.1:9200 +boundary authenticate password -login-name=foo -password foofoofoo -auth-method-id=ampw_0000000000 +``` + +The authenticate to the Admin UI, open [http://127.0.0.1:9200](http://127.0.0.1:9200) in a browser and enter the hard coded login name and password: + +![](/img/login-dev-mode.png) + +Note: Opening `127.0.0.1:9200` will redirect you to the auth method set in the global scope, which is shown in the image above. + +And of course, you can also use these overrides to configure the [Terraform provider for Boundary](https://github.com/hashicorp/terraform-provider-boundary): ```hcl provider "boundary" { @@ -69,12 +89,14 @@ Note in the example above we're setting `base_url` to `http` and not `https` as ## User Interface +If you want to develop the Admin UI locally: + The UI is normally compiled into the Boundary binary at build time. However, it would be impractical to rebuild the binary on every change when -actively developing the UI. To make UI development more convenient, the binary -supports a _passthrough directory_. This is an arbitrary local -directory from which UI assets are served. Note this option is only available -in dev mode. For example: +actively developing the UI. To make UI development more convenient, the binary +supports a _passthrough directory_. This is an arbitrary local +directory from which UI assets are served. Note this option is only available +in dev mode. For example: ```bash BOUNDARY_DEV_PASSTHROUGH_DIRECTORY=../boundary-ui/ui/core/dist ./boundary dev diff --git a/website/pages/docs/introduction/index.mdx b/website/pages/docs/introduction/index.mdx deleted file mode 100644 index 0ef1121ea..000000000 --- a/website/pages/docs/introduction/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: docs -page_title: Introduction Index -sidebar_title: Introduction -description: |- - An introduction to Boundary including concepts and architecture. ---- - -# Introduction - -Lorum ipsum diff --git a/website/pages/docs/introduction/reference-architecture.mdx b/website/pages/docs/introduction/reference-architecture.mdx deleted file mode 100644 index 0a9d21b61..000000000 --- a/website/pages/docs/introduction/reference-architecture.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: docs -page_title: Architecture -sidebar_title: Reference Architecture -description: |- - Boundary reference architecture and considerations ---- - -# Overview - -When deploying Boundary in an on premise environment some considerations should be taken. The aim of this document is to provide minimum requirements for deploying Boundary and a reference architecture model to follow in doing so. diff --git a/website/public/img/login-dev-mode.png b/website/public/img/login-dev-mode.png new file mode 100644 index 000000000..44756f759 Binary files /dev/null and b/website/public/img/login-dev-mode.png differ