From 2455445d164a6048d3064de98754cae962a66b78 Mon Sep 17 00:00:00 2001 From: NoahMundahl <37671164+NoahMundahl@users.noreply.github.com> Date: Mon, 26 Apr 2021 09:37:50 -0500 Subject: [PATCH] website: minor edits to "Installing" pages and "Go SDK" page (#1139) --- website/content/docs/api-clients/go-sdk.mdx | 26 +++++++++---------- .../docs/installing/high-availability.mdx | 17 +++++------- .../docs/installing/no-gen-resources.mdx | 7 +++-- website/content/docs/installing/postgres.mdx | 2 +- website/content/docs/installing/systemd.mdx | 16 +++++------- 5 files changed, 29 insertions(+), 39 deletions(-) diff --git a/website/content/docs/api-clients/go-sdk.mdx b/website/content/docs/api-clients/go-sdk.mdx index 0315147cd..ef3974a3b 100644 --- a/website/content/docs/api-clients/go-sdk.mdx +++ b/website/content/docs/api-clients/go-sdk.mdx @@ -7,7 +7,7 @@ description: |- # Go SDK -Boundary has a Go SDK that sports full coverage of Boundary's API. This SDK is mostly auto-generated so the patterns are predictable from package to package; for the most part, browsing [pkg.go.dev](https://pkg.go.dev/github.com/hashicorp/boundary/api) is a great way to get started. +Boundary has a Go SDK that sports full coverage of Boundary's API. This SDK is mostly auto-generated, so the patterns are predictable from package to package. For the most part, browsing [pkg.go.dev](https://pkg.go.dev/github.com/hashicorp/boundary/api) is a great way to get started. Below, an example walks through using the SDK to authenticate against an auth method or perform recovery workflows. The patterns for creating a resource-typed client are the same across packages. @@ -28,7 +28,7 @@ This is the most common way for a client to authenticate to Boundary. To demonst use the [authmethods](https://github.com/hashicorp/boundary/tree/main/api/authmethods) library to generate a valid token for a client in Go. -For this example, we're going to use the Password auth method. This example +For this example, we're going to use the [password auth method](/docs/concepts/domain-model/auth-methods#password-auth-method-attributes). This example assumes there's already a valid user and an associated account in Boundary against which the client can authenticate. To simplify this example, we're assuming you're running a Boundary instance in dev mode, where the default auth @@ -37,8 +37,6 @@ method, login name, and password are pre-configured. First, we need to create a client from the Boundary API and set the address to reach Boundary: ```go -import "github.com/hashicorp/boundary/api" - // The default address points to the default dev mode address client, err := api.NewClient(nil) if err != nil { @@ -50,8 +48,8 @@ The [authenticate method](https://github.com/hashicorp/boundary/blob/main/api/authmethods/authenticate.go) uses a basic `map[string]interface{}` to pass credential information, in order to eventually support multiple auth method types. For this example, we assume -you're using the password auth method and so we're going to tailor a credentials -object to pass this data as: +you're using the password auth method, and so we create an attributes +map to pass this data: ```go credentials := map[string]interface{}{ @@ -63,9 +61,7 @@ credentials := map[string]interface{}{ Now let's create an auth method client using the base client from above: ```go -import "github.com/hashicorp/boundary/api/authmethods" - -am := authmethods.NewClient(client) +amClient := authmethods.NewClient(client)) ``` ~> This creates a shallow copy of the base client. Modifications made to the client via `am.ApiClient()` will not be reflected in the base client. @@ -89,7 +85,7 @@ Note the ID in the output above, we're going to use that in the next step. We can use the credentials object we created to execute `Authenticate()` on this client: ```go -at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials) +authenticationResult, err := amClient.Authenticate(context.Background(), "ampw_1234567890", "login", credentials) if err != nil { return err } @@ -99,13 +95,15 @@ Lastly, let's update the original client with the token we got from the `Authent ```go // pass this client to any other resource specific API resources -client.SetToken(at.Item.Token) +client.SetToken(fmt.Sprint(authenticationResult.Attributes["token"])) ``` Putting this all together: ```go import ( + "context" + "github.com/hashicorp/boundary/api" "github.com/hashicorp/boundary/api/authmethods" ) @@ -121,14 +119,14 @@ if err != nil { return err } -am := authmethods.NewClient(client) -at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials) +amClient := authmethods.NewClient(client) +authenticationResult, err := amClient.Authenticate(context.Background(), "ampw_1234567890", "login", credentials) if err != nil { return err } // pass this client to any other resource specific API resources -client.SetToken(at.Item.Token) +client.SetToken(fmt.Sprint(authenticationResult.Attributes["token"])) ``` ### Recovery KMS Workflow diff --git a/website/content/docs/installing/high-availability.mdx b/website/content/docs/installing/high-availability.mdx index d68655491..a7815dc16 100644 --- a/website/content/docs/installing/high-availability.mdx +++ b/website/content/docs/installing/high-availability.mdx @@ -7,7 +7,7 @@ description: |- # High Availability Installation -Installing Boundary as a high availability service requires certain infrastructure considerations. At the most basic level, running 3 controller and 3 worker instances gives a fundamental level of high availability for the control plane (controller), as well as bandwidth for a number of sessions on the data plane (worker). Both server types should be run in a fault-tolerant setting, that is, in a self-healing environment 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. +Installing Boundary as a high availability service requires certain infrastructure considerations. At the most basic level, running 3 controller and 3 worker instances gives a fundamental level of high availability for the control plane (controller), as well as bandwidth for a number of sessions on the data plane (worker). Both server types should be run in a fault-tolerant configuration, that is, in a self-healing environment 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 @@ -16,21 +16,16 @@ The following ports should be available: - Clients must have access to the Controller's port (default 9200) - Clients must have access to the Worker's port (default 9202) - Workers must have access to the Controller's port (default 9201) -- Workers must have a route and port access to the hosts defined within the system, in order to provide connectivity +- Workers must have a route and port access to the hosts defined within the system in order to provide connectivity ## Architecture -The general architecture for the server infrastructure requires 3 controllers -and 3 workers. Note that it is possible to run a controller and worker within the -same process, but the guide here assumes separate deployments. 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: +The general architecture for the server infrastructure requires 3 controllers and 3 workers. Note that it is possible to run a controller and worker within the same process, but the guide here assumes separate deployments. 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 independent [auto-scaling groups](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/autoscaling_group), allowing them to maintain their exact capacity. +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 independent [auto-scaling groups](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/autoscaling_group), allowing them to maintain their exact capacity. The workers must be able to establish a connection to the hosts with which they interact. In the architecture above, we place them in the public subnet so our remote client can establish a session between them and the target VM. @@ -40,12 +35,12 @@ Boundary requires an external [Postgres](https://www.postgresql.org/) and [KMS]( ### 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 techniques to expose services such as the API and administrative console to public networks. In the high availability 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). +Load balancing the controller allows operators to secure the ingress to the Boundary system. We recommend placing all Boundary servers in private networks and using load balancing techniques to expose services such as the API and administrative console to public networks. In the high availability 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 +- Health checks should use TCP port 9200 ### Controller Configuration diff --git a/website/content/docs/installing/no-gen-resources.mdx b/website/content/docs/installing/no-gen-resources.mdx index 99f1d9797..8915de215 100644 --- a/website/content/docs/installing/no-gen-resources.mdx +++ b/website/content/docs/installing/no-gen-resources.mdx @@ -13,7 +13,7 @@ targets are just some of the resources Boundary will generate unless you tell it In a production or long-running environment, these resources are not necessary, but without them, managing Boundary from scratch isn't straight forward. How do you create your first user and login to administer a Boundary -deployment that has no authentication methods, users, accounts, etc? This section describes how to get your freshly +deployment that has no authentication methods, users, accounts, etc.? This section describes how to get your freshly deployed Boundary installation off the ground for non-dev environments. ## Recovery KMS Workflow @@ -276,9 +276,8 @@ resource "boundary_user" "myuser" { ### Create Roles to Manage Scopes The following describes the four baseline roles you'll need to create to manage resources within the org and project -scopes created above. These roles are similar to the roles created for you in if generation had not been skipped during `boundary database init`, but declaring them explicitly -allows you to manage them independently and fully within Terraform or on the CLI. This is useful if you want to lock -them down more or have control over them in a declarative way. +scopes created above. These roles are similar to the roles created for you if generation had not been skipped during `boundary database init` when executed with the `-skip-initial-login-role-creation` flag, Declaring roles explicitly +allows you to manage them independently and fully within Terraform or via the CLI. In doing so, you can precisely define their access. The following example creates 4 roles: diff --git a/website/content/docs/installing/postgres.mdx b/website/content/docs/installing/postgres.mdx index 9f120a38c..9a67d1bdc 100644 --- a/website/content/docs/installing/postgres.mdx +++ b/website/content/docs/installing/postgres.mdx @@ -24,7 +24,7 @@ Worker nodes never need access to the database. ## Users/Roles After the database has been initialized, -the database user for a Boundary Controller +the database user for a Boundary controller only requires permissions for [Data Manipulation](https://www.postgresql.org/docs/current/dml.html) (select, insert, update, and delete) operations. diff --git a/website/content/docs/installing/systemd.mdx b/website/content/docs/installing/systemd.mdx index e7911510a..55040ec12 100644 --- a/website/content/docs/installing/systemd.mdx +++ b/website/content/docs/installing/systemd.mdx @@ -7,23 +7,21 @@ description: |- # Installing Boundary under Systemd -This section covers how to install Boundary under the [Systemd](https://systemd.io/) init system on modern Linux distributions. In this section we'll cover an example of breaking out the controller and worker servers onto separate instances, though you can opt to run both on a single server. +This section covers how to install Boundary under the [systemd](https://systemd.io/) init system on modern Linux distributions. In this section, we'll cover an example of breaking out the controller and worker servers onto separate instances, though you can opt to run both on a single server. ## Filesystem Configuration `TYPE` below can be either `worker` or `controller` if you want to run them independently, e.g. for high availability. If you want to run combined nodes, modify as desired. -1. `/etc/boundary-${TYPE}.hcl`: Configuration file for the boundary service - See above example configurations. +1. `/etc/boundary-${TYPE}.hcl`: Configuration file for the boundary service. -2. `/usr/local/bin/boundary`: The Boundary binary. Can build from [GitHub repository](https://github.com/hashicorp/boundary) or download binary from our [release pages](https://www.boundaryproject.io/downloads). +2. `/usr/local/bin/boundary`: The Boundary binary, which can be built from the [source](https://github.com/hashicorp/boundary) or downloaded from our [release page](https://www.boundaryproject.io/downloads). -3. `/etc/systemd/system/boundary-${TYPE}.service`: Systemd unit file for the Boundary service - Example: +3. `/etc/systemd/system/boundary-${TYPE}.service`: Systemd unit file for the Boundary service. ## User & Group Configuration -We recommend running Boundary as a non-root user, and use this user to manage the Boundary process running under systemd. The example init files here do exactly this, and our example install script below creates a user and group on Debian-like Ubuntu systems as an example. +We recommend running Boundary as a non-root user and using this user to manage the Boundary process running under systemd. The example init files here do exactly that. Our example install script below creates a user and group on Ubuntu or Debian-like systems. ## Systemd Unit file @@ -45,8 +43,8 @@ WantedBy=multi-user.target ## Systemd All-in-One Installation Script -Here's a simple install script that creates the boundary group and user, installs the -systemd unit file and enables it at startup: +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