mirror of https://github.com/hashicorp/boundary
Jeff Malnick
6 years ago
committed by
GitHub
parent
278902db1a
commit
d7731d0ce7
@ -0,0 +1,22 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Controller - Configuration
|
||||
sidebar_title: <code>controller</code>
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
- `name` - Specifies a unique name of this controller within the Boundary controller cluster.
|
||||
|
||||
- `description` - Specifies a friendly description of this controller.
|
||||
@ -0,0 +1,24 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: KMS AEAD - Configuration
|
||||
sidebar_title: <code>KMS AEAD</code>
|
||||
description: |-
|
||||
The KMS AEAD configures KMS-specifc parameters.
|
||||
---
|
||||
|
||||
```hcl
|
||||
kms "aead" {
|
||||
purpose = "worker-auth"
|
||||
aead_type = "aes-gcm"
|
||||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||||
key_id = "global_worker-auth"
|
||||
}
|
||||
```
|
||||
|
||||
- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, and `recovery`.
|
||||
|
||||
- `aead_type` - The type of encryption this KMS uses.
|
||||
|
||||
- `key` - Optional, a hard coded key if not using an external KMS.
|
||||
|
||||
- `key_id` - The unique name of this key.
|
||||
@ -0,0 +1,72 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: AliCloud KMS - KMSs - Configuration
|
||||
sidebar_title: AliCloud KMS
|
||||
description: >-
|
||||
The AliCloud KMS configures Boundary to use AliCloud KMS for key management.
|
||||
---
|
||||
|
||||
# `alicloudkms` KMS
|
||||
|
||||
The AliCloud KMS configures Boundary to use AliCloud KMS for key management.
|
||||
The AliCloud KMS is activated by one of the following:
|
||||
|
||||
- The presence of a `kms "alicloudkms"` block in Boundary's configuration file.
|
||||
|
||||
## `alicloudkms` Example
|
||||
|
||||
This example shows configuring AliCloud KMS through the Boundary configuration file
|
||||
by providing all the required values:
|
||||
|
||||
```hcl
|
||||
kms "alicloudkms" {
|
||||
region = "us-east-1"
|
||||
access_key = "0wNEpMMlzy7szvai"
|
||||
secret_key = "PupkTg8jdmau1cXxYacgE736PJj4cA"
|
||||
kms_key_id = "08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4fb73"
|
||||
}
|
||||
```
|
||||
|
||||
## `alicloudkms` Parameters
|
||||
|
||||
These parameters apply to the `kms` stanza in the Boundary configuration file:
|
||||
|
||||
- `region` `(string: <required> "us-east-1")`: The AliCloud region where the encryption key
|
||||
lives. May also be specified by the `ALICLOUD_REGION`
|
||||
environment variable.
|
||||
|
||||
- `domain` `(string: "kms.us-east-1.aliyuncs.com")`: If set, overrides the endpoint
|
||||
AliCloud would normally use for KMS for a particular region. May also be specified
|
||||
by the `ALICLOUD_DOMAIN` environment variable.
|
||||
|
||||
- `access_key` `(string: <required>)`: The AliCloud access key ID to use. May also be
|
||||
specified by the `ALICLOUD_ACCESS_KEY` environment variable or as part of the
|
||||
AliCloud profile from the AliCloud CLI or instance profile.
|
||||
|
||||
- `secret_key` `(string: <required>)`: The AliCloud secret access key to use. May
|
||||
also be specified by the `ALICLOUD_SECRET_KEY` environment variable or as
|
||||
part of the AliCloud profile from the AliCloud CLI or instance profile.
|
||||
|
||||
- `kms_key_id` `(string: <required>)`: The AliCloud KMS key ID to use for encryption
|
||||
and decryption. May also be specified by the `VAULT_ALICLOUDKMS_SEAL_KEY_ID`
|
||||
environment variable.
|
||||
|
||||
## Authentication
|
||||
|
||||
Authentication-related values must be provided, either as environment
|
||||
variables or as configuration parameters.
|
||||
|
||||
~> **Note:** Although the configuration file allows you to pass in
|
||||
`ALICLOUD_ACCESS_KEY` and `ALICLOUD_SECRET_KEY` as part of the 's parameters, it
|
||||
is _strongly_ recommended to set these values via environment variables.
|
||||
|
||||
```text
|
||||
AliCloud authentication values:
|
||||
|
||||
* `ALICLOUD_REGION`
|
||||
* `ALICLOUD_ACCESS_KEY`
|
||||
* `ALICLOUD_SECRET_KEY`
|
||||
```
|
||||
|
||||
Note: The client uses the official AliCloud SDK and will use environment credentials,
|
||||
the specified credentials, or RAM role credentials in that order.
|
||||
@ -0,0 +1,95 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: AWS KMS - KMSs - Configuration
|
||||
sidebar_title: AWS KMS
|
||||
description: |-
|
||||
The AWS KMS configures Boundary to use AWS KMS for key management.
|
||||
mechanism.
|
||||
---
|
||||
|
||||
# `awskms`
|
||||
|
||||
The AWS KMS configures Boundary to use AWS KMS for key management.
|
||||
|
||||
## `awskms` Example
|
||||
|
||||
This example shows configuring AWS KMS through the Boundary configuration file
|
||||
by providing all the required values:
|
||||
|
||||
```hcl
|
||||
kms "awskms" {
|
||||
region = "us-east-1"
|
||||
access_key = "AKIAIOSFODNN7EXAMPLE"
|
||||
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
|
||||
endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
|
||||
}
|
||||
```
|
||||
|
||||
## `awskms` Parameters
|
||||
|
||||
These parameters apply to the `kms` stanza in the Boundary configuration file:
|
||||
|
||||
- `region` `(string: "us-east-1")`: The AWS region where the encryption key
|
||||
lives. If not provided, may be populated from the `AWS_REGION` or
|
||||
`AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file,
|
||||
or from instance metadata.
|
||||
|
||||
- `access_key` `(string: <required>)`: The AWS access key ID to use. May also be
|
||||
specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the
|
||||
AWS profile from the AWS CLI or instance profile.
|
||||
|
||||
- `session_token` `(string: "")`: Specifies the AWS session token. This can
|
||||
also be provided via the environment variable `AWS_SESSION_TOKEN`.
|
||||
|
||||
- `secret_key` `(string: <required>)`: The AWS secret access key to use. May
|
||||
also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as
|
||||
part of the AWS profile from the AWS CLI or instance profile.
|
||||
|
||||
- `kms_key_id` `(string: <required>)`: The AWS KMS key ID to use for encryption
|
||||
and decryption. May also be specified by the `VAULT_AWSKMS_SEAL_KEY_ID`
|
||||
environment variable.
|
||||
|
||||
- `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS
|
||||
requests. May also be specified by the `AWS_KMS_ENDPOINT` environment
|
||||
variable. This is useful, for example, when connecting to KMS over a [VPC
|
||||
Endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html).
|
||||
If not set, Boundary will use the default API endpoint for your region.
|
||||
|
||||
## Authentication
|
||||
|
||||
Authentication-related values must be provided, either as environment
|
||||
variables or as configuration parameters.
|
||||
|
||||
~> **Note:** Although the configuration file allows you to pass in
|
||||
`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as part of the KMS's parameters, it
|
||||
is _strongly_ recommended to set these values via environment variables.
|
||||
|
||||
AWS authentication values:
|
||||
|
||||
- `AWS_REGION` or `AWS_DEFAULT_REGION`
|
||||
- `AWS_ACCESS_KEY_ID`
|
||||
- `AWS_SECRET_ACCESS_KEY`
|
||||
|
||||
Note: The client uses the official AWS SDK and will use the specified
|
||||
credentials, environment credentials, shared file credentials, or IAM role/ECS
|
||||
task credentials in that order, if the above AWS specific values are not
|
||||
provided.
|
||||
|
||||
Boundary needs the following permissions on the KMS key:
|
||||
|
||||
- `kms:Encrypt`
|
||||
- `kms:Decrypt`
|
||||
- `kms:DescribeKey`
|
||||
|
||||
These can be granted via IAM permissions on the principal that Boundary uses, on
|
||||
the KMS key policy for the KMS key, or via KMS Grants on the key.
|
||||
|
||||
## Key Rotation
|
||||
|
||||
This KMS supports rotating the master keys defined in AWS KMS
|
||||
[doc](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html). Both automatic
|
||||
rotation and manual rotation is supported for KMS since the key information is stored with the
|
||||
encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data.
|
||||
Any new or updated data will be encrypted with the current key defined in the KMS configuration
|
||||
or set to current under a key alias.
|
||||
@ -0,0 +1,63 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Azure Key Vault - Seals - Configuration
|
||||
sidebar_title: Azure Key Vault
|
||||
description: >-
|
||||
The Azure Key Vault seal configures Boundary to use Azure Key Vault for key management.
|
||||
---
|
||||
|
||||
# `azurekeyvault` KMS
|
||||
|
||||
The Azure Key Vault KMS configures Vault to use Azure Key Vault for key management.
|
||||
The Azure Key Vault KMS is activated by one of the following:
|
||||
|
||||
- The presence of a `seal "azurekeyvault"` block in Boundary's configuration file.
|
||||
|
||||
## `azurekeyvault` Example
|
||||
|
||||
This example shows configuring Azure Key Vault KMS through the Boundary
|
||||
configuration file by providing all the required values:
|
||||
|
||||
```hcl
|
||||
kms "azurekeyvault" {
|
||||
tenant_id = "46646709-b63e-4747-be42-516edeaf1e14"
|
||||
client_id = "03dc33fc-16d9-4b77-8152-3ec568f8af6e"
|
||||
client_secret = "DUJDS3..."
|
||||
vault_name = "hc-vault"
|
||||
key_name = "vault_key"
|
||||
}
|
||||
```
|
||||
|
||||
## `azurekeyvault` Parameters
|
||||
|
||||
These parameters apply to the `kms` stanza in the Vault configuration file:
|
||||
|
||||
- `tenant_id` `(string: <required>)`: The tenant id for the Azure Active Directory organization. May
|
||||
also be specified by the `AZURE_TENANT_ID` environment variable.
|
||||
|
||||
- `client_id` `(string: <required or MSI>)`: The client id for credentials to query the Azure APIs.
|
||||
May also be specified by the `AZURE_CLIENT_ID` environment variable.
|
||||
|
||||
- `client_secret` `(string: <required or MSI>)`: The client secret for credentials to query the Azure APIs.
|
||||
May also be specified by the `AZURE_CLIENT_SECRET` environment variable.
|
||||
|
||||
- `environment` `(string: "AZUREPUBLICCLOUD")`: The Azure Cloud environment API endpoints to use. May also
|
||||
be specified by the `AZURE_ENVIRONMENT` environment variable.
|
||||
|
||||
- `vault_name` `(string: <required>)`: The Key Vault vault to use the encryption keys for encryption and
|
||||
decryption. May also be specified by the `VAULT_AZUREKEYVAULT_VAULT_NAME` environment variable.
|
||||
|
||||
- `key_name` `(string: <required>)`: The Key Vault key to use for encryption and decryption. May also be specified by the
|
||||
`VAULT_AZUREKEYVAULT_KEY_NAME` environment variable.
|
||||
|
||||
## Authentication
|
||||
|
||||
Authentication-related values must be provided, either as environment
|
||||
variables or as configuration parameters.
|
||||
|
||||
Azure authentication values:
|
||||
|
||||
- `AZURE_TENANT_ID`
|
||||
- `AZURE_CLIENT_ID`
|
||||
- `AZURE_CLIENT_SECRET`
|
||||
- `AZURE_ENVIRONMENT`
|
||||
@ -0,0 +1,60 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: GCP Cloud KMS - KMSs - Configuration
|
||||
sidebar_title: GCP Cloud KMS
|
||||
description: >-
|
||||
The GCP Cloud KMS configures Boundary to use GCP Cloud KMS for key management.
|
||||
---
|
||||
|
||||
# `gcpckms` KMS
|
||||
|
||||
The GCP Cloud KMS configures Boundary to use GCP Cloud KMS for key management.
|
||||
|
||||
The GCP Cloud KMS seal is activated by the presence of a `seal "gcpckms"` block in Boundary's configuration file.
|
||||
|
||||
## `gcpckms` Example
|
||||
|
||||
This example shows configuring GCP Cloud KMS through the Boundary
|
||||
configuration file by providing all the required values:
|
||||
|
||||
```hcl
|
||||
kms "gcpckms" {
|
||||
credentials = "/usr/boundary/boundary-project-user-creds.json"
|
||||
project = "boundary-project"
|
||||
region = "global"
|
||||
key_ring = "boundary-keyring"
|
||||
crypto_key = "boundary-key"
|
||||
}
|
||||
```
|
||||
|
||||
## `gcpckms` Parameters
|
||||
|
||||
These parameters apply to the `kms` stanza in the Boundary configuration file:
|
||||
|
||||
- `credentials` `(string: <required>)`: The path to the credentials JSON file
|
||||
to use. May be also specified by the `GOOGLE_CREDENTIALS` or
|
||||
`GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if
|
||||
running under Google App Engine, Google Compute Engine or Google Kubernetes
|
||||
Engine.
|
||||
|
||||
- `project` `(string: <required>)`: The GCP project ID to use. May also be
|
||||
specified by the `GOOGLE_PROJECT` environment variable.
|
||||
|
||||
- `region` `(string: "us-east-1")`: The GCP region/location where the key ring
|
||||
lives. May also be specified by the `GOOGLE_REGION` environment variable.
|
||||
|
||||
- `key_ring` `(string: <required>)`: The GCP CKMS key ring to use.
|
||||
|
||||
- `crypto_key` `(string: <required>)`: The GCP CKMS crypto key to use for
|
||||
encryption and decryption.
|
||||
|
||||
## Authentication & Permissions
|
||||
|
||||
Authentication-related values must be provided, either as environment
|
||||
variables or as configuration parameters.
|
||||
|
||||
GCP authentication values:
|
||||
|
||||
- `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`
|
||||
- `GOOGLE_PROJECT`
|
||||
- `GOOGLE_REGION`
|
||||
@ -0,0 +1,32 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: KMS - Configuration
|
||||
sidebar_title: <code>kms</code>
|
||||
description: |-
|
||||
The KMS stanza configures KMS-specifc parameters.
|
||||
---
|
||||
|
||||
# `kms` Stanza
|
||||
|
||||
The `kms` stanza configures Boundary kms-specific parameters.
|
||||
|
||||
For more examples, please choose a specific KMS technology from the sidebar.
|
||||
|
||||
## Configuration
|
||||
|
||||
KMS configuration can be done through the Vault configuration file using the
|
||||
`kms` stanza:
|
||||
|
||||
```hcl
|
||||
kms [NAME] {
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```hcl
|
||||
kms "pkcs11" {
|
||||
# ...
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,99 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: OCI KMS - KMSs - Configuration
|
||||
sidebar_title: OCI KMS
|
||||
description: |-
|
||||
The OCI KMS configures Boundary to use OCI KMS for key management.
|
||||
---
|
||||
|
||||
# `ocikms` KMS
|
||||
|
||||
The OCI KMS configures Boundary to use OCI KMS for key management.
|
||||
|
||||
The OCI KMS is activated by the presence of a `kms "ocikms"` block in Boundary's configuration file.
|
||||
|
||||
## `ocikms` Example
|
||||
|
||||
This example shows configuring the OCI KMS through the Boundary configuration file
|
||||
by providing all the required values:
|
||||
|
||||
```hcl
|
||||
kms "ocikms" {
|
||||
key_id = "ocid1.key.oc1.iad.afnxza26aag4s.abzwkljsbapzb2nrha5nt3s7s7p42ctcrcj72vn3kq5qx"
|
||||
crypto_endpoint = "https://afnxza26aag4s-crypto.kms.us-ashburn-1.oraclecloud.com"
|
||||
management_endpoint = "https://afnxza26aag4s-management.kms.us-ashburn-1.oraclecloud.com"
|
||||
auth_type_api_key = "true"
|
||||
}
|
||||
```
|
||||
|
||||
## `ocikms` Parameters
|
||||
|
||||
These parameters apply to the `kms` stanza in the Boundary configuration file:
|
||||
|
||||
- `key_id` `(string: <required>)`: The OCI KMS key ID to use.
|
||||
- `crypto_endpoint` `(string: <required>)`: The OCI KMS cryptographic endpoint (or data plane endpoint)
|
||||
to be used to make OCI KMS encryption/decryption requests.
|
||||
- `management_endpoint` `(string: <required>)`: The OCI KMS management endpoint (or control plane endpoint)
|
||||
to be used to make OCI KMS key management requests.
|
||||
- `auth_type_api_key` `(boolean: false)`: Specifies if using API key to authenticate to OCI KMS service.
|
||||
If it is `false`, Boundary authenticates using the instance principal from the compute instance. See Authentication section for details. Default is `false`.
|
||||
|
||||
## Authentication
|
||||
|
||||
Authentication-related values must be provided, either as environment
|
||||
variables or as configuration parameters.
|
||||
|
||||
If you want to use Instance Principal, add section configuration below and add further configuration settings as detailed in the [configuration docs](/docs/configuration/).
|
||||
|
||||
```hcl
|
||||
kms "ocikms" {
|
||||
crypto_endpoint = "<kms-crypto-endpoint>"
|
||||
management_endpoint = "<kms-management-endpoint>"
|
||||
key_id = "<kms-key-id>"
|
||||
}
|
||||
```
|
||||
|
||||
If you want to use User Principal, the plugin will take the API key you defined for OCI SDK, often under `~/.oci/config`.
|
||||
|
||||
```hcl
|
||||
kms "ocikms" {
|
||||
auth_type_api_key = true
|
||||
crypto_endpoint = "<kms-crypto-endpoint>"
|
||||
management_endpoint = "<kms-management-endpoint>"
|
||||
key_id = "<kms-key-id>"
|
||||
}
|
||||
```
|
||||
|
||||
To grant permission for a compute instance to use OCI KMS service, write policies for KMS access.
|
||||
|
||||
- Create a [Dynamic Group][oci-dg] in your OCI tenancy.
|
||||
- Create a policy that allows the Dynamic Group to use or manage keys from OCI KMS. There are multiple ways to write these policies. The [OCI Identity Policy][oci-id] can be used as a reference or starting point.
|
||||
|
||||
The most common policy allows a dynamic group of tenant A to use KMS's keys in tenant B:
|
||||
|
||||
```text
|
||||
define tenancy tenantB as <tenantB-ocid>
|
||||
|
||||
endorse dynamic-group <dynamic-group-name> to use keys in tenancy tenantB
|
||||
|
||||
```
|
||||
|
||||
```text
|
||||
define tenancy tenantA as <tenantA-ocid>
|
||||
|
||||
define dynamic-group <dynamic-group-name> as <dynamic-group-ocid>
|
||||
|
||||
admit dynamic-group <dynamic-group-name> of tenancy tenantA to use keys in compartment <key-compartment>
|
||||
|
||||
```
|
||||
|
||||
## `ocikms` Rotate OCI KMS Master Key
|
||||
|
||||
For the [OCI KMS key rotation feature][oci-kms-rotation], OCI KMS will create a new version of key internally. This process is independent from Boundary, and boundary still uses the same `key_id` without any interruption.
|
||||
|
||||
If you want to change the `key_id`: migrate to Shamir, change `key_id`, and then migrate to OCI KMS with the new `key_id`.
|
||||
|
||||
[oci-sdk]: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm
|
||||
[oci-dg]: https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/managingdynamicgroups.htm
|
||||
[oci-id]: https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policies.htm
|
||||
[oci-kms-rotation]: https://docs.cloud.oracle.com/iaas/Content/KeyManagement/Tasks/managingkeys.htm
|
||||
@ -0,0 +1,107 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Vault Transit - Seals - Configuration
|
||||
sidebar_title: Vault Transit
|
||||
description: |-
|
||||
The Transit configures Boundary to use Vault's Transit Secret Engine for key management.
|
||||
---
|
||||
|
||||
# `transit` Seal
|
||||
|
||||
The Transit configures Boundary to use Vault's Transit Secret Engine for key management.
|
||||
|
||||
The Transit KMS is activated by the presence of a `kms "transit"` block in Boundary's configuration file
|
||||
|
||||
## `transit` Example
|
||||
|
||||
This example shows configuring Transit KMS through the Boundary configuration file
|
||||
by providing all the required values:
|
||||
|
||||
```hcl
|
||||
kms "transit" {
|
||||
address = "https://vault:8200"
|
||||
token = "s.Qf1s5zigZ4OX6akYjQXJC1jY"
|
||||
disable_renewal = "false"
|
||||
|
||||
// Key configuration
|
||||
key_name = "transit_key_name"
|
||||
mount_path = "transit/"
|
||||
namespace = "ns1/"
|
||||
|
||||
// TLS Configuration
|
||||
tls_ca_cert = "/etc/vault/ca_cert.pem"
|
||||
tls_client_cert = "/etc/vault/client_cert.pem"
|
||||
tls_client_key = "/etc/vault/ca_cert.pem"
|
||||
tls_server_name = "vault"
|
||||
tls_skip_verify = "false"
|
||||
}
|
||||
```
|
||||
|
||||
## `transit` Parameters
|
||||
|
||||
These parameters apply to the `kms` stanza in the Vault configuration file:
|
||||
|
||||
- `address` `(string: <required>)`: The full address to the Vault cluster.
|
||||
This may also be specified by the `VAULT_ADDR` environment variable.
|
||||
|
||||
- `token` `(string: <required>)`: The Vault token to use. This may also be
|
||||
specified by the `VAULT_TOKEN` environment variable.
|
||||
|
||||
- `key_name` `(string: <required>)`: The transit key to use for encryption and
|
||||
decryption. This may also be supplied using the `VAULT_TRANSIT_SEAL_KEY_NAME`
|
||||
environment variable.
|
||||
|
||||
- `mount_path` `(string: <required>)`: The mount path to the transit secret engine.
|
||||
This may also be supplied using the `VAULT_TRANSIT_SEAL_MOUNT_PATH` environment
|
||||
variable.
|
||||
|
||||
- `namespace` `(string: "")`: The namespace path to the transit secret engine.
|
||||
This may also be supplied using the `VAULT_NAMESPACE` environment variable.
|
||||
|
||||
- `disable_renewal` `(string: "false")`: Disables the automatic renewal of the token
|
||||
in case the lifecycle of the token is managed with some other mechanism outside of
|
||||
Vault, such as Vault Agent. This may also be specified using the
|
||||
`VAULT_TRANSIT_SEAL_DISABLE_RENEWAL` environment variable.
|
||||
|
||||
- `tls_ca_cert` `(string: "")`: Specifies the path to the CA certificate file used
|
||||
for communication with the Vault server. This may also be specified using the
|
||||
`VAULT_CA_CERT` environment variable.
|
||||
|
||||
- `tls_client_cert` `(string: "")`: Specifies the path to the client certificate
|
||||
for communication with the Vault server. This may also be specified using the
|
||||
`VAULT_CLIENT_CERT` environment variable.
|
||||
|
||||
- `tls_client_key` `(string: "")`: Specifies the path to the private key for
|
||||
communication with the Vault server. This may also be specified using the
|
||||
`VAULT_CLIENT_KEY` environment variable.
|
||||
|
||||
- `tls_server_name` `(string: "")`: Name to use as the SNI host when connecting
|
||||
to the Vault server via TLS. This may also be specified via the
|
||||
`VAULT_TLS_SERVER_NAME` environment variable.
|
||||
|
||||
- `tls_skip_verify` `(bool: "false")`: Disable verification of TLS certificates.
|
||||
Using this option is highly discouraged and decreases the security of data
|
||||
transmissions to and from the Vault server. This may also be specified using the
|
||||
`VAULT_SKIP_VERIFY` environment variable.
|
||||
|
||||
## Authentication
|
||||
|
||||
Authentication-related values must be provided, either as environment
|
||||
variables or as configuration parameters.
|
||||
|
||||
~> **Note:** Although the configuration file allows you to pass in
|
||||
`VAULT_TOKEN` as part of the KMS's parameters, it is _strongly_ recommended
|
||||
to set these values via environment variables.
|
||||
|
||||
The Vault token used to authenticate needs the following permissions on the
|
||||
transit key:
|
||||
|
||||
```hcl
|
||||
path "<mount path>/encrypt/<key name>" {
|
||||
capabilities = ["update"]
|
||||
}
|
||||
|
||||
path "<mount path>/decrypt/<key name>" {
|
||||
capabilities = ["update"]
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,15 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Listeners - Configuration
|
||||
sidebar_title: <code>listener</code>
|
||||
description: |-
|
||||
The listener stanza configures the addresses and ports on which Boundary will
|
||||
respond to requests.
|
||||
---
|
||||
|
||||
# `listener` Stanza
|
||||
|
||||
The `listener` stanza configures the addresses and ports on which Boundary will
|
||||
respond to requests. At this time, there is only one listener - [TCP][tcp].
|
||||
|
||||
[tcp]: /docs/configuration/listener/tcp
|
||||
@ -0,0 +1,12 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Telemetry - Configuration
|
||||
sidebar_title: <code>telemetry</code>
|
||||
description: |-
|
||||
The telemetry stanza specifies various configurations for Boundary to publish
|
||||
metrics to upstream systems.
|
||||
---
|
||||
|
||||
# `telemetry` Stanza
|
||||
|
||||
NOT YET IMPLEMENTED
|
||||
@ -0,0 +1,25 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Worker - Configuration
|
||||
sidebar_title: <code>worker</code>
|
||||
description: |-
|
||||
The worker stanza configures worker-specifc parameters.
|
||||
---
|
||||
|
||||
# `worker` Stanza
|
||||
|
||||
The `worker` stanza configures Boundary worker-specific parameters.
|
||||
|
||||
```hcl
|
||||
worker {
|
||||
name = "example-worker"
|
||||
description = "An example worker"
|
||||
public_addr = "5.1.23.198"
|
||||
}
|
||||
```
|
||||
|
||||
- `name` - Specifies a unique name of this worker within the Boundary worker cluster.
|
||||
|
||||
- `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.
|
||||
@ -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:
|
||||
|
||||
|
||||
|
||||
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 <worker|controller>
|
||||
|
||||
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
|
||||
|
After Width: | Height: | Size: 76 KiB |
Loading…
Reference in new issue