CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs 0.16.0 assembly minio (#4708)

Browse Source 
* adds configure-worker-storage.mdx

* adds session-recording/storage-providers pages

* migrates worker and provider reqs to new pages

* adds TOC

* update storage requirements to be provider agnostic

* updates requirements with bucket considerations

* creates tabs, adds minio support

* adds minio requirements

* fixes Amazon S3 branding

* style guide fixes for UI tabs

* makes UI tab primary

* removes KMS and adds service account policy

* cleans up service account and region notes

* restricts ListBucket policy

* adds minio API port example

* reformats CLI attributes, fixed typos

* adds Resources section

* adds Resources section with KMS docs link

* docs: Add ENT banners

* docs: Fix links

* docs: Move BSR storage requirements

* docs: Add Requirements sections to old topics

* docs: Add next steps sections

* docs: Minor style edits

* docs: Add NetBSD caveat

* docs: Make NetBSD caveat a note

---------

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
This commit is contained in:
Robin BeckandDan Heath authored and GitHub committed 2024-04-30 14:29:24 -04:00
1 parent a373f97ee9
commit 471f9476e2
8 files changed
+586 -301
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

website/content/docs/configuration/session-recording/configure-storage-policy.mdx
+8 -10
View File
@@ -22,9 +22,7 @@ For more information about using session recording to audit user sessions, refer
## Requirements
Before you can create a storage bucket in Boundary, you must ensure that your environment meets certain requirements.
Session recording requires specific configuration for both the external store and the Boundary worker.
At this time, the only supported storage is AWS S3.
Before you can create a storage bucket in Boundary, you must ensure that your environment meets certain requirements. Session recording requires specific configuration for both the external storage provider and the Boundary worker.
A Boundary worker configured for local storage is also required to set up session recording and configure recording bucket policies.
@@ -47,7 +45,7 @@ Complete the following steps to create a storage policy in Boundary for session
<Tab heading="UI" group="ui">
1. Log in to Boundary.
1. Select **Storage Policies** in the navigation panel in the `global` scope.
1. Click **Storage Policies** in the navigation panel in the `global` scope.
1. Click **Create a new storage policy**.
1. Complete the following fields to create the Boundary storage policy:
- **Name**: (Optional) The name field is optional, but if you enter a name it must be unique.
@@ -183,8 +181,8 @@ The following example applies the policy created above to an org named `prod-dat
<Tab heading="UI" group="ui">
1. Log in to Boundary.
1. Select **Orgs** in the navigation panel and select the `prod-databases` org.
1. Select **Org Settings** in the navigation panel for the `prod-databases` org.
1. Click **Orgs** in the navigation panel and select the `prod-databases` org.
1. Click **Org Settings** in the navigation panel for the `prod-databases` org.
1. Under **Storage Policy**, click **Add Storage Policy**.
1. Select the `soc2-policy`.
1. Click **Save**. This applies the policy to this scope and its children.
@@ -332,8 +330,8 @@ Check that the storage policy was successfully attached to the `prod-databases`
<Tab heading="UI">
1. Log in to Boundary.
1. Select **Orgs** in the navigation panel and select the `prod-databases` org.
1. Select **Org Settings** in the navigation panel for the `prod-databases` org.
1. Click **Orgs** in the navigation panel and select the `prod-databases` org.
1. Click **Org Settings** in the navigation panel for the `prod-databases` org.
1. Verify that the `soc2-policy` is listed under **Storage Policy**.
</Tab>
@@ -474,8 +472,8 @@ New session recordings under the `prod-databases` scope should now show a `retai
1. Create a new session recording on a target within the `prod-databases` org.
1. Log in to Boundary.
1. Select **Session Recordings** in the navigation panel.
1. Select **View** for a new recording that was made after the storage policy was attached to the `prod-databases` scope.
1. Click **Session Recordings** in the navigation panel.
1. Click **View** for a new recording that was made after the storage policy was attached to the `prod-databases` scope.
1. Under **Session details**, verify that the *Retain until* and *Delete after* dates match the durations defined in the `soc2-policy`.
</Tab>
website/content/docs/configuration/session-recording/configure-worker-storage.mdx
+69
View File
@@ -0,0 +1,69 @@
---
layout: docs
page_title: Configure workers for local storage
description: |-
How to configure Boundary workers for session recording.
---
# Configure workers for session recording
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
Session recording requires that you configure at least one worker for local storage.
<Note>
You cannot use an HCP managed worker for the local storage. HCP Boundary users must configure a self-managed worker to enable session recording.
</Note>
## Requirements
Workers that you configure for storage must:
- Have access to the external storage provider
- Have an accessible directory defined by `recording_storage_path` for storing session recordings while they are in progress. On session closure, Boundary moves the local session recording to remote storage and deletes the local copy.
- For HCP Boundary, refer to the [Self-managed worker configuration](/hcp/docs/boundary/self-managed-workers/session-recording) documentation.
- For Boundary Enterprise, refer to the refer to the [worker configuration](/boundary/docs/configuration/worker/worker-configuration#session-recording) documentation.
- Have available disk space defined by `recording_storage_minimum_available_capacity`. If you do not configure the minimum available storage capacity, Boundary uses the default value of 500MiB.
For more information about how much space is required to store BSR files, refer to [storage considerations](/boundary/docs/configuration/session-recording#storage-considerations).
- Run Darwin, Windows, or Linux. The following binaries are not supported for session recording: NetBSD, OpenBSD, Solaris.
## Local storage
Workers require sufficient local disk space in the `recording_storage_path` to store session recordings while they are in progress. Local disk space is also required for session recording playback.
The `recording_storage_minimum_available_capacity` vaule defines the minimum available disk space that must be available on the worker for session recording and session recording playback. This threshold determines the local storage state of the worker.
The possible storage states determined by the `recording_storage_minimum_available_capacity` are:
- `Available`: The worker is above the storage threshold and is available to proxy sessions that are enabled with session recording.
- `Low storage`: The worker is below the storage threshold. Existing sessions can continue without interruption, but new sessions that are enabled with session recording cannot be proxied. The worker is not available to record new sessions or play back existing recordings.
- `Critically low storage`: The worker is below half the storage threshold. Existing sessions that are enabled with session recording will be forcefully closed. The worker is not available to record new sessions or play back existing recordings.
- `Out of storage`: The worker is out of local disk space. It is not available to record new sessions or play back existing recordings. The worker is in a unrecoverable state. An administrator must intervene to remedy the issue.
- `Not configured`: The worker does not have a `recording_storage_path` configured.
- `Unknown`: The default local storage state of a worker. This state indicates that the local storage state of a worker is not yet known. Older workers (< 0.16.0) will be in this state.
If a worker is in an unhealthy local storage state, Boundary does not allow new session recordings or session recording playback until the worker is in an `available` local storage state.
## Example configuration
Refer to the following example configuration to configure workers for session recording storage:
```hcl
worker {
auth_storage_path = "/boundary/demo-worker-1"
initial_upstreams = ["10.0.0.1"]
recording_storage_path = "/local/storage/directory"
recording_storage_minimum_available_capacity = "500MB"
}
```
## Next steps
After you configure worker storage, you can configure the external storage provider for [Amazon S3](/boundary/docs/configuration/session-recording/storage-providers/configure-s3) or [MinIO](/boundary/docs/configuration/session-recording/storage-providers/configure-minio).
website/content/docs/configuration/session-recording/create-storage-bucket.mdx
+178 -255
View File
@@ -9,285 +9,49 @@ description: |-
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
As of Boundary 0.13.0, you can record and audit user sessions.
A Boundary resource known as a [storage bucket](/boundary/docs/concepts/domain-model/storage-buckets) is used to store the recorded sessions.
The storage bucket represents a bucket in an external store.
User sessions can be recorded and audited using Boundary 0.13 or greater. A Boundary resource known as a [storage bucket](/boundary/docs/concepts/domain-model/storage-buckets) is used to store the recorded sessions.
The storage bucket represents a bucket in an external storage provider.
Before you can enable session recording, you must create one or more storage buckets in Boundary and associate them with the external store.
A storage bucket can only belong to the global scope or an org scope.
A storage bucket that is associated with the global scope can be associated with any target.
However, a storage bucket in an Org scope can only be associated with targets in a project from the same org scope.
Any storage buckets associated with an Org scope are deleted when the org itself is deleted.
A storage bucket can only belong to the global scope or an org scope. A storage bucket that is associated with the global scope can be associated with any target. However, a storage bucket in an Org scope can only be associated with targets in a project from the same org scope. Any storage buckets associated with an Org scope are deleted when the org itself is deleted.
For more information about using session recording to audit user sessions, refer to [Auditing](/boundary/docs/concepts/auditing).
## Requirements
Before you can create a storage bucket in Boundary, you must ensure that your environment meets certain requirements.
Session recording requires specific configuration for both the external store and the Boundary worker.
At this time, the only supported storage is AWS S3.
Before you create a storage bucket in Boundary, you must:
### Storage requirements
- [Configure workers for storage](/boundary/docs/configuration/session-recording/configure-worker-storage)
- Configure one of the following storage providers:
- [Amazon S3](/boundary/docs/configuration/session-recording/storage-providers/configure-s3)
- [MinIO](/boundary/docs/configuration/session-recording/storage-providers/configure-minio)
A [BSR](/boundary/docs/concepts/auditing/#bsr-directory-structure) (Boundary Session Recording) captures all the data
transmitted between a user and a target during a single session. As a result, the size of a BSR is dependent on user
activity. At a minimum, a BSR for a session with one connection requires 8KB of space for its files- this is the
overhead for BSR keys, checksums, metadata, etc.
## Create a storage bucket
Determining how much storage you need to allocate on workers and AWS for recordings depends on user activity, but the following two
examples are provided to help with storage estimates:
- For a minute of simple shell activity, a BSR can be around 20KB in size. The storage requirements for 1,000 such sessions would be 20MB.
- Sending 50MB of data results in a BSR around 50.1MB in size. The storage requirements for 1,000 such sessions would be 50.1 GB.
When you estimate worker storage requirements, consider the number of concurrent sessions that will be recorded on that worker.
Boundary writes the BSR to the worker's local storage while the session is active, and then moves it to the remote storage bucket when the session is closed.
When you estimate AWS storage requirements, consider your [storage policy](/boundary/docs/concepts/domain-model/storage-policy)
and how long a BSR will be retained in the storage bucket.
### AWS requirements
- An AWS S3 storage bucket
You must associate the Boundary storage bucket with an AWS S3 storage bucket.
An AWS S3 storage bucket contains the bucket name, region, and optional prefix, as well as any credentials needed to access the bucket.
The AWS S3 storage bucket can use static or dynamic credentials.
You can configure static credentials using an access key and secret key or dynamic credentials using the AWS [`AssumeRole` API](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole).
- An AWS IAM role policy with the following statement:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectAttributes",
"s3:DeleteObject",
"s3:ListBucket"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::session_recording_storage*",
"Resource": "arn:aws:s3:::session_recording_storage/foo/bar/zoo/*"
},
{
"Action": [
"iam:DeleteAccessKey",
"iam:GetUser",
"iam:CreateAccessKey"
],
"Effect": "Allow",
"Resource": "arn:aws:iam::123456789012:user/JohnDoe"
}
]
}
```
- If you apply KMS encryption to the storage bucket, you must add these additional permissions to the role policy for the storage bucket's IAM user:
```json
{
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Effect": "Allow",
"Resource": "arn:aws:kms:us-east-1:1234567890:key/uuid"
}
```
The following is an example working policy with KMS encryption configured on the S3 bucket:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "S3Permissions",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectAttributes",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::test-session-recording-bucket/*"
]
},
{
"Sid": "UserPermissions",
"Effect": "Allow",
"Action": [
"iam:DeleteAccessKey",
"iam:GetUser",
"iam:CreateAccessKey"
],
"Resource": [
"arn:aws:iam::1234567890:user/test-boundary"
]
},
{
"Sid": "KMSPermissions",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Resource": [
"arn:aws:kms:us-east-2:1234567890:key/4b887395-c376-4936-8f37-80c592ea582c"
]
}
]
}
```
### Boundary workers requirements
[Session recording](/boundary/docs/configuration/session-recording) requires that you [configure at least one worker for local storage](/boundary/docs/configuration/session-recording/create-storage-bucket#boundary-workers-requirements).
The worker that you configure for storage must:
<Note>
You cannot use an HCP managed worker for the local storage. HCP Boundary users must configure a self-managed worker to enable session recording.
</Note>
- Have access to the AWS S3 storage bucket
- Have an accessible directory defined by `recording_storage_path` for storing session recordings while they are in progress. On session closure, Boundary moves the local session recording to remote storage and deletes the local copy.
- For HCP Boundary, refer to the [Self-managed worker configuration](/hcp/docs/boundary/self-managed-workers/session-recording) documentation.
- For Boundary Enterprise, refer to the refer to the [worker configuration](/boundary/docs/configuration/worker/worker-configuration#session-recording) documentation.
- Have available disk space defined by `recording_storage_minimum_available_capacity`. If you do not configure the minimum available storage capacity, Boundary uses the default value of 500MiB.
- Run Darwin, Windows, or Linux. The following binaries are not supported for session recording: NetBSD, OpenBSD, Solaris.
#### Local storage
Workers require sufficient local disk space in the `recording_storage_path` to store session recordings while they are in progress. Local disk space is also required for session recording playback.
The `recording_storage_minimum_available_capacity` vaule defines the minimum available disk space that must be available on the worker for session recording and session recording playback.
This threshold determines the local storage state of the worker.
The possible storage states based on the `recording_storage_minimum_available_capacity` are:
- `Available`: The worker is above the storage threshold and is available to proxy sessions that are enabled with session recording.
- `Low storage`: The worker is below the storage threshold. Existing sessions can continue without interruption, but new sessions that are enabled with session recording cannot be proxied. The worker is not available to record new sessions or play back existing recordings.
- `Critically low storage`: The worker is below half the storage threshold. Existing sessions that are enabled with session recording will be forcefully closed. The worker is not available to record new sessions or play back existing recordings.
- `Out of storage`: The worker is out of local disk space. It is not available to record new sessions or play back existing recordings. The worker is in a unrecoverable state. An administrator must intervene to remedy the issue.
- `Not configured`: The worker does not have a `recording_storage_path` configured.
- `Unknown`: The default local storage state of a worker. This state indicates that the local storage state of a worker is not yet known. Older workers (< 0.16.0) will be in this state.
If a worker is in an unhealthy local storage state, Boundary does not allow new session recordings or session recording playback until the worker is in an `available` local storage state.
Refer to the following example configuration:
```hcl
worker {
auth_storage_path="/boundary/demo-worker-1"
initial_upstreams = ["10.0.0.1"]
recording_storage_path="/local/storage/directory"
recording_storage_minimum_available_capacity="500MB"
}
```
### Create a storage bucket
Complete the following steps to create a storage bucket in Boundary for session recording:
Select a storage provider.
<Tabs>
<Tab heading="CLI">
<Tab heading="Amazon S3">
The required fields for creating a storage bucket vary depending on whether you configured the AWS S3 bucket with static or dynamic credentials:
Complete the following steps to create a storage bucket in Boundary.
<Tabs>
<Tab heading="Static credentials">
1. Log in to Boundary.
1. Use the following command to create a storage bucket in Boundary:
```shell-session
boundary storage-buckets create \
-bucket-name mybucket1 \
-plugin-name aws \
-secrets ‘{“access_key_id”: “123456789” , “secret_access_key” : “123/456789/12345678”}’ \
-worker-filter ‘“dev” in “/tags/type”’ \
-attributes ‘{“region”:”us-east-1”,”disable_credential_rotation”:true}’ \
-scope-id o_1234567890
```
Replace the values above with the following required AWS secrets and any optional [attributes](/boundary/docs/concepts/domain-model/storage-buckets) you want to associate with the Boundary storage bucket:
- `region`: (Required) The AWS region to use.
- `bucket-name`: (Required) Name of the AWS bucket you want to associate with the Boundary storage bucket.
- `access_key_id`: (Required) The AWS access key to use.
- `secret_access_key_id`: (Required) The AWS secret access key to use.
This attribute contains the secret access key for static credentials.
- `worker-filter`: (Required) A filter that indicates which Boundary workers have access to the storage. The filter must match an existing worker in order to create a Boundary storage bucket.
- `shared_credentials_file`: (Optional) The shared credentials file to use.
- `shared_credentials_profile`: (Optional) The profile name to use in the shared credentials file.
- `disable_credential_rotation`: (Optional) Prevents the AWS plugin from automatically rotating credentials.
Although credentials are stored encrypted in Boundary, by default the [AWS plugin](https://github.com/hashicorp/boundary-plugin-aws) attempts to rotate the credentials you provide. The given credentials are used to create a new credential, and then the original credential is revoked. After rotation, only Boundary knows the client secret the plugin uses.
</Tab>
<Tab heading="Dynamic credentials">
1. Log in to Boundary.
1. Use the following command to create a storage bucket in Boundary:
```shell-session
boundary storage-buckets create \
-bucket-name mybucket1 \
-plugin-name aws \
-worker-filter ‘“dev” in “/tags/type”’ \
-attributes ‘{“region”:”us-east-1”,”disable_credential_rotation”:true,"role_arn":"arn:aws:iam::123456789012:role/S3Access"}’ \
-scope-id o_1234567890
```
Replace the values above with the following required AWS secrets and any optional [attributes](/boundary/docs/concepts/domain-model/storage-buckets) you want to associate with the Boundary storage bucket:
- `region`: (Required) The AWS region to use.
- `bucket-name`: (Required) Name of the AWS bucket you want to associate with the Boundary storage bucket.
- `role_arn`: (Required) The ARN (Amazon Resource Name) role that is attached to the EC2 instance that the self-managed worker runs on.
- `role_external_id`: (Optional) A required value if you delegate third party access to your AWS resources.
For more information, refer to the AWS documentation for [How to use an external ID when granting access to your AWS resources to a third party](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html).
- `role_session_name`: (Optional) A unique identifier for the AWS session.
You can use this value to control how IAM principals and applications name their role sesions when they assume an IAM role.
By providing a session name, you enable tracking session actions in AWS CloudTrail logs.
For more information, refer to the AWS documentation for [Logging IAM and AWS STS API calls with AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/cloudtrail-integration.html).
- `role_tags`: (Optional) An object with key-value pair attributes that is passed when you assume an IAM role.
For more information, refer to the AWS documentation for [Passing session tags in AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html).
- `worker-filter`: (Required) A filter that indicates which Boundary workers have access to the storage. The filter must match an existing worker in order to create a Boundary storage bucket.
- `shared_credentials_file`: (Optional) The shared credentials file to use.
- `shared_credentials_profile`: (Optional) The profile name to use in the shared credentials file.
- `disable_credential_rotation`: (Required) Prevents the AWS plugin from automatically rotating credentials.
This option must be set to `true` if you use dynamic credentials.
</Tab>
</Tabs>
</Tab>
<Tab heading="UI">
1. Log in to Boundary.
1. Select **Storage Buckets** in the navigation bar.
1. Select **New Storage Bucket**.
1. Click **Storage Buckets** in the navigation bar.
1. Click **New Storage Bucket**.
1. Complete the following fields to create the Boundary storage bucket:
- **Name**: (Optional) The name field is optional, but if you enter a name it must be unique.
- **Description**: (Optional) An optional description of the Boundary storage bucket for identification purposes.
- **Scope**: (Required) A storage bucket can belong to the Global scope or an Org scope.
It can only associated with targets from the scope it belongs to.
- **Provider**: (Required) The external storage bucket provider.
- **Bucket name**: (Required) Name of the AWS bucket you want to associate with the Boundary storage bucket.
- **Bucket prefix**: (Optional) A base path where session recordings are stored.
- **Region**: (Required) The AWS region to use.
- **Credential type**: (Required) The type of credential you want to use to authenticate to the external storage.
The required fields for creating a storage bucket vary depending on whether you configured the AWS S3 bucket with static or dynamic credentials:
The required fields for creating a storage bucket vary depending on whether you configured the Amazon S3 bucket with static or dynamic credentials:
- **Static**: Authenticates to the storage bucket using an access key that AWS generates.
- **Dynamic**: Authenticates to the storage bucket using credentials that were generated by AWS `AssumeRole`.
@@ -299,8 +63,7 @@ The required fields for creating a storage bucket vary depending on whether you
- **Worker filter**: (Required) A filter that indicates which Boundary workers have access to the storage. The filter must match an existing worker in order to create a Boundary storage bucket.
- **Disable credential rotation**: (Optional) Prevents the AWS plugin from automatically rotating credentials.
Although credentials are stored encrypted in Boundary, by default the [AWS plugin](https://github.com/hashicorp/boundary-plugin-aws) attempts to rotate the credentials you provide.
The given credentials are used to create a new credential, and then the original credential is revoked.
Although credentials are stored encrypted in Boundary, by default the [AWS plugin](https://github.com/hashicorp/boundary-plugin-aws) attempts to rotate the credentials you provide. The given credentials are used to create a new credential, and then the original credential is revoked.
After rotation, only Boundary knows the client secret the plugin uses.
</Tab>
@@ -323,7 +86,158 @@ The required fields for creating a storage bucket vary depending on whether you
</Tab>
</Tabs>
1. Select **Save**.
1. Click **Save**.
</Tab>
<Tab heading="CLI">
The required fields for creating a storage bucket depend on whether you configured the Amazon S3 bucket with static or dynamic credentials:
<Tabs>
<Tab heading="Static credentials">
1. Log in to Boundary.
1. Use the following command to create a storage bucket in Boundary:
```shell-session
$ boundary storage-buckets create \
-bucket-name mybucket1 \
-plugin-name aws \
-scope-id o_1234567890 \
-worker-filter ‘“dev” in “/tags/type”’ \
-secret ‘{“access_key_id”: “123456789” , “secret_access_key” : “123/456789/12345678”}’ \
-attributes ‘{“region”:”us-east-1”,”disable_credential_rotation”:true}’
```
Replace the values above with the following required AWS secrets and any [attributes](/boundary/docs/concepts/domain-model/storage-buckets) you want to associate with the Boundary storage bucket:
- `region`: (Required) The AWS region to use.
- `bucket-name`: (Required) The name of the AWS bucket you want to associate with the Boundary storage bucket.
- `plugin-name`: (Required) The name of the Boundary storage plugin.
- `scope_id`: (Required) A storage bucket can belong to the Global scope or an Org scope.
- `worker-filter`: (Required) A filter that indicates which Boundary workers have access to the storage. The filter must match an existing worker in order to create a Boundary storage bucket.
- `secret`: (Required) The AWS credentials to use.
- `access_key_id`: (Required) The AWS access key to use.
- `secret_access_key_id`: (Required) The AWS secret access key to use.
This attribute contains the secret access key for static credentials.
- `attributes` or `-attr`: Attributes of the Amazon S3 storage bucket.
- `shared_credentials_file`: (Optional) The shared credentials file to use.
- `shared_credentials_profile`: (Optional) The profile name to use in the shared credentials file.
- `disable_credential_rotation`: (Optional) Prevents the AWS plugin from automatically rotating credentials.
Although credentials are stored encrypted in Boundary, by default the [AWS plugin](https://github.com/hashicorp/boundary-plugin-aws) attempts to rotate the credentials you provide. The given credentials are used to create a new credential, and then the original credential is revoked. After rotation, only Boundary knows the client secret the plugin uses.
</Tab>
<Tab heading="Dynamic credentials">
1. Log in to Boundary.
1. Use the following command to create a storage bucket in Boundary:
```shell-session
$ boundary storage-buckets create \
-bucket-name mys3bucket \
-plugin-name aws \
-scope-id o_1234567890 \
-worker-filter ‘“s3” in “/tags/type”’ \
-attributes ‘{“region”:”us-east-1”,”disable_credential_rotation”:true,"role_arn":"arn:aws:iam::123456789012:role/S3Access"}’
```
Replace the values above with the following required AWS secrets and any [attributes](/boundary/docs/concepts/domain-model/storage-buckets) you want to associate with the Boundary storage bucket:
- `region`: (Required) The AWS region to use.
- `bucket-name`: (Required) The name of the AWS bucket you want to associate with the Boundary storage bucket.
- `plugin-name`: (Required) The name of the Boundary storage plugin.
- `scope_id`: (Required) A storage bucket can belong to the Global scope or an Org scope.
- `worker-filter`: (Required) A filter that indicates which Boundary workers have access to the storage. The filter must match an existing worker in order to create a Boundary storage bucket.
- `attributes` or `-attr`: Attributes of the Amazon S3 storage bucket.
- `role_arn`: (Required) The ARN (Amazon Resource Name) role that is attached to the EC2 instance that the self-managed worker runs on.
- `role_external_id`: (Optional) A required value if you delegate third party access to your AWS resources.
For more information, refer to the AWS documentation for [How to use an external ID when granting access to your AWS resources to a third party](https://docs.aws.amazon.com/IAM/latest/UserGuide/ id_roles_create_for-user_externalid.html).
- `role_session_name`: (Optional) A unique identifier for the AWS session.
You can use this value to control how IAM principals and applications name their role sesions when they assume an IAM role.
By providing a session name, you enable tracking session actions in AWS CloudTrail logs.
For more information, refer to the AWS documentation for [Logging IAM and AWS STS API calls with AWS CloudTrail](https://docs.aws.amazon.com/IAM/ latest/UserGuide/cloudtrail-integration.html).
- `role_tags`: (Optional) An object with key-value pair attributes that is passed when you assume an IAM role.
For more information, refer to the AWS documentation for [Passing session tags in AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/ id_session-tags.html).
</Tab>
</Tabs>
</Tab>
</Tabs>
</Tab>
<Tab heading="MinIO">
Complete the following steps to create a storage bucket in Boundary.
<Note>
MinIO requires a service account and its associated access keys to set up a Boundary storage bucket. Refer to the [Configure MinIO](/boundary/docs/configuration/session-recording/storage-providers/configure-minio#minio-requirements) page to learn more.
</Note>
<Tabs>
<Tab heading="UI">
1. Log in to Boundary.
1. Click **Storage Buckets** in the navigation bar.
1. Click **New Storage Bucket**.
1. Complete the following fields to create the Boundary storage bucket:
- **Name**: (Optional) The name field is optional, but if you enter a name it must be unique.
- **Description**: (Optional) An optional description of the Boundary storage bucket for identification purposes.
- **Scope**: (Required) A storage bucket can belong to the Global scope or an Org scope.
It can only be associated with targets from the scope it belongs to.
- **Provider**: (Required) The external storage bucket provider.
- **Endpoint URL**: (Required) The fully-qualified endpoint pointing to a MinIO S3 API, such as `https://my-minio-instance.dev:9000`.
- **Bucket name**: (Required) Name of the AWS bucket you want to associate with the Boundary storage bucket.
- **Region**: (Optional) The region to configure the storage bucket for.
- **Access key ID** (Required): The MinIO service account's access key to use with this storage bucket.
- **Secret access key** (Required): The MinIO service account's secret key to use with this storage bucket.
- **Worker filter**: (Required) A filter that indicates which Boundary workers have access to the storage. The filter must match an existing worker in order to create a Boundary storage bucket.
- **Disable credential rotation**: (Optional) Controls whether the plugin will rotate the incoming credentials and manage a new MinIO service account. If this attribute is set to false, or not provided, the plugin will rotate the incoming credentials, using them to create a new MinIO service account, then delete the incoming credentials.
1. Click **Save**.
</Tab>
<Tab heading="CLI">
1. Log in to Boundary.
1. Use the following command to create a storage bucket in Boundary:
```shell-session
$ boundary storage-buckets create \
-bucket-name myminiobucket \
-plugin-name minio \
-scope-id o_1234567890 \
-bucket-prefix="foo/bar/zoo" \
-worker-filter '"minio" in "/tags/type"' \
-attr endpoint_url="https://my-minio-instance.dev:9000" \
-attr region="REGION" \
-attr disable_credential_rotation=true \
-secret access_key_id="KEY" \
-secret secret_access_key="SECRET"
```
Replace the values above with the following required secrets and any optional [attributes](/boundary/docs/concepts/domain-model/storage-buckets) you want to associate with the Boundary storage bucket:
- `bucket-name`: (Required) Name of the MinIO bucket you want to associate with the Boundary storage bucket.
- `plugin-name`: (Required) The name of the Boundary storage plugin.
- `scope_id`: (Required) A storage bucket can belong to the Global scope or an Org scope.
- `worker-filter`: (Required) A filter that indicates which Boundary workers have access to the storage. The filter must match an existing worker in order to create a Boundary storage bucket.
- `secret`: (Required) The MinIO credentials to use.
- `access_key_id` (Required): The MinIO service account's access key to use with this storage bucket.
- `secret_access_key` (Required): The MinIO service account's secret key to use with this storage bucket.
- `attributes` or `-attr`: Attributes of the MinIO storage bucket.
- `endpoint_url` (Required): Fully-qualified endpoint pointing to a MinIO S3 API.
- `region`: (Optional) The region to configure the storage bucket for.
- `disable_credential_rotation`: (Optional) Controls whether the plugin will rotate the incoming credentials and manage a new MinIO service account. If this attribute is set to `false`, or not provided, the plugin will rotate the incoming credentials to create a new MinIO service account, then delete the incoming credentials.
This option must be set to `true` if you use dynamic credentials.
</Tab>
</Tabs>
</Tab>
</Tabs>
@@ -333,3 +247,12 @@ Boundary creates the storage bucket resource and provides you with the bucket's
## Next steps
After the storage bucket is created in Boundary, you can use the bucket's ID to [enable session recording on targets](/boundary/docs/configuration/session-recording/enable-session-recording).
## Resources
The following docs are relevant to configuring storage buckets:
- [Storage bucket attributes](/boundary/docs/concepts/domain-model/storage-buckets)
- [Worker filter examples](/boundary/docs/concepts/filtering/worker-tags#example-worker-filter-for-storage-buckets)
- [Boundary AWS plugin](https://github.com/hashicorp/boundary-plugin-aws)
- [Boundary MinIO plugin](https://github.com/hashicorp/boundary-plugin-minio)
website/content/docs/configuration/session-recording/enable-session-recording.mdx
+34 -31
View File
@@ -13,7 +13,7 @@ You must enable session recording for any targets that you want to record sessio
When you [create a storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket), Boundary provides you with an ID.
You use the storage bucket's ID to associate a target with the storage bucket.
**Requirements**:
## Requirements
- One or more storage buckets to store the recordings.
- Session recording is only supported for SSH targets at this time.
@@ -27,6 +27,35 @@ Refer to [SSH target attributes](/boundary/docs/concepts/domain-model/targets#ss
Complete the following steps to enable session recording on a target.
<Tabs>
<Tab heading="UI">
1. Log in to Boundary.
1. Click **Orgs** in the navigation pane.
1. Select the org that contains the target you want to enable for session recording.
1. Select the project that contains the target you want to enable for session recording.
1. Select **Targets** in the navigation pane.
1. Do one of the following:
- To create a new target, select **New Target**.
- To edit an existing target, select the target, and then select **Edit Form**.
1. Configure the target with any relevant [attributes](/boundary/docs/concepts/domain-model/targets).
The following setting is required for session recording:
- Select **SSH** for the **Type**.
1. Click **Save**.
1. Click **Enable recording**.
![Enable session recording](/img/enable-session-recording.png)
1. Enable the **Record sessions for this target** option.
1. Select the storage bucket where you want to store recordings from this target.
You can also [create a new storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket).
1. Click **Save**.
</Tab>
<Tab heading="CLI">
1. Log in to Boundary.
@@ -53,38 +82,12 @@ Complete the following steps to enable session recording on a target.
You can now view the target from the **Targets** page in the Boundary console.
</Tab>
<Tab heading="UI">
1. Log in to Boundary.
1. Select **Orgs** in the navigation pane.
1. Select the org that contains the target you want to enable for session recording.
1. Select the project that contains the target you want to enable for session recording.
1. Select **Targets** in the navigation pane.
1. Do one of the following:
- To create a new target, select **New Target**.
- To edit an existing target, select the target, and then select **Edit Form**.
1. Configure the target with any relevant [attributes](/boundary/docs/concepts/domain-model/targets).
The following setting is required for session recording:
- Select **SSH** for the **Type**.
1. Select **Save**.
1. Select **Enable recording**.
![Enable session recording](/img/enable-session-recording.png)
1. Enable the **Record sessions for this target** option.
1. Select the storage bucket where you want to store recordings from this target.
You can also [create a new storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket).
1. Select **Save**.
</Tab>
</Tabs>
The target is now enabled for session recording.
Any user session that connects to the target is automatically recorded.
## Next steps
After you have enabled session recording, you may want to [configure storage policies](//boundary/docs/configuration/session-recording/configure-storage-policy) to codify the lifecycle management of your session recordings.
website/content/docs/configuration/session-recording/index.mdx
+37 -5
View File
@@ -9,11 +9,43 @@ description: |-
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
Boundary provides auditing capabilities via session recording.
In Boundary, a session represents a set of connections between a user and a host from a target.
The session begins when an authorized user requests access to a target, and it ends when that access is terminated.
Boundary provides auditing capabilities using a feature called session recording.
When you enable session recording on a target, a worker records any sessions that access that target.
In Boundary, a session represents a set of connections between a user and a host from a target. The session begins when an authorized user requests access to a target, and it ends when that access is terminated.
When you enable session recording on a target, a worker records any sessions that access that target. The worker stores the session recording on local disk during the recording phase, and then moves the recording to the external object store when the session is terminated.
Session recordings are stored in the [BSR (Boundary Session Recording)](/boundary/docs/concepts/auditing/#bsr-directory-structure) format. Any credentials needed to access the external object store are passed from the controller to the recording worker when the session is established.
You can view the recordings later with a session player that runs in a web browser.
To enable session recording you must first [create a storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket) and then [enable session recording on the target](/boundary/docs/configuration/session-recording/enable-session-recording).
## Storage considerations
The BSR captures all the data transmitted between a user and a target during a single session. As a result, the size of a BSR is dependent on user activity. At a minimum, a BSR for a session with one connection requires 8KB of space for its file for BSR keys, checksums, and metadata.
Determining how much storage you need to allocate on workers and the external storage provider for recordings depends on user activity, but the following two examples are provided to help with storage estimates:
- For one minute of simple shell activity, a BSR can be around 20KB in size. The storage requirements for 1,000 such sessions would be 20MB.
- Sending 50MB of data results in a BSR around 50.1MB in size. The storage requirements for 1,000 such sessions would be 50.1 GB.
When you estimate worker storage requirements, consider the number of concurrent sessions that will be recorded on that worker. Boundary writes the BSR to the worker's local storage while the session is active, and then moves it to the remote storage bucket when the session is closed.
When you estimate storage requirements for the external storage provider, consider your [storage policy](/boundary/docs/concepts/domain-model/storage-policy) and how long a BSR will be retained in the external storage bucket.
## Enable session recording
To enable session recording, you must:
1. [Configure workers for local storage](/boundary/docs/configuration/session-recording/configure-worker-storage)
1. Configure an external storage provider:
- [Amazon S3](/boundary/docs/configuration/session-recording/storage-providers/configure-s3)
- [MinIO](/boundary/docs/configuration/session-recording/storage-providers/configure-minio)
1. [Create a storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket)
1. [Enable session recording on a target](/boundary/docs/configuration/session-recording/enable-session-recording)
## Configure recording retention policies
After enabling session recording, you can configure retention policies for recorded sessions:
1. [Configure storage policies](/boundary/docs/configuration/session-recording/configure-storage-policy)
1. [Update storage policies](/boundary/docs/configuration/session-recording/update-storage-policy)
website/content/docs/configuration/session-recording/storage-providers/configure-minio.mdx
+112
View File
@@ -0,0 +1,112 @@
---
layout: docs
page_title: Configure MinIO
description: |-
How to configure MinIO as a storage provider for Boundary session recording.
---
# Configure MinIO as a storage provider
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
This page describes how to configure MinIO as a storage provider for session recording with Boundary.
## Requirements
Before you can create a storage bucket in Boundary, you must ensure that your environment meets certain requirements.
Session recording requires specific configuration for both the external storage provider and the Boundary worker.
Refer to [Configure workers for session recording](/boundary/docs/configuration/session-recording/configure-worker-storage) to learn about configuring self-managed workers for session recording.
When you determine storage requirements for the external bucket, you should consider:
- [BSR storage considerations](/boundary/docs/configuration/session-recording#storage-considerations)
- [Storage bucket retention policies](/boundary/docs/configuration/session-recording/configure-storage-policy)
### MinIO requirements
- A MinIO storage bucket
You must associate the Boundary storage bucket with a MinIO storage bucket. A Boundary MinIO storage bucket contains the bucket name, endpoint URL, optional region, optional prefix, and the service account credentials needed to access the bucket. To enable credential rotation, you cannot add a Boundary storage bucket without a MinIO service account. You can disable credential rotation when you create the Boundary storage bucket.
<Note>
At this time, the NetBSD operating system is not supported for the MinIO storage bucket.
</Note>
- A MinIO service account and access keys
You must provide service account access keys when you configure a Boundary storage bucket later on.
Refer to the [MinIO Access Keys](https://min.io/docs/minio/kubernetes/upstream/administration/console/security-and-access.html#access-keys) documentation page to learn how to set up a MinIO service account.
- A MinIO storage bucket must be configured with R/W access. If you use a
restricted IAM user policy, the following policy actions must be allowed at a minimum.
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectAttributes",
"s3:DeleteObject"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::test-session-recording-bucket/*"
},
{
"Action": "s3:ListBucket",
"Effect": "Allow",
"Resource": "arn:aws:s3:::test-session-recording-bucket"
}
]
}
```
- HashiCorp recommends that you enable credential rotation. To enable credential rotation, use the following service account policy:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectAttributes",
"s3:DeleteObject"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::test-session-recording-bucket/*"
},
{
"Action": "s3:ListBucket",
"Effect": "Allow",
"Resource": "arn:aws:s3:::test-session-recording-bucket"
},
{
"Action": [
"admin:CreateServiceAccount",
"admin:RemoveServiceAccount"
],
"Effect": "Allow"
}
]
}
```
## Resources
The following docs MinIO docs are relevant for configuring storage buckets and service accounts:
- Refer to the [MinIO Policy Action Keys](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#mc-admin-policy-action-keys) documentation to learn more about restricting IAM user policies.
- Refer to the [MinIO Object Encryption with KES](https://min.io/docs/minio/linux/operations/server-side-encryption/configure-minio-kes.html#minio-sse-vault) documentation to learn more about KMS and data encryption with vault key management.
## Next steps
After you configure the external storage provider, you can [create the storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket) in Boundary.
website/content/docs/configuration/session-recording/storage-providers/configure-s3.mdx
+131
View File
@@ -0,0 +1,131 @@
---
layout: docs
page_title: Configure Amazon S3
description: |-
How to Amazon S3 as a storage provider for Boundary session recording.
---
# Configure Amazon S3 as a storage provider
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
This page describes how to configure Amazon S3 as a storage provider for session recording with Boundary.
## Requirements
Before you can create a storage bucket in Boundary, you must ensure that your environment meets certain requirements.
Session recording requires specific configuration for both the external storage provider and the Boundary worker.
Refer to [Configure workers for session recording](/boundary/docs/configuration/session-recording/configure-worker-storage) to learn about configuring self-managed workers for session recording.
When you determine storage requirements for the external bucket, you should consider:
- [BSR storage considerations](/boundary/docs/configuration/session-recording#storage-considerations)
- [Storage bucket retention policies](/boundary/docs/configuration/session-recording/configure-storage-policy)
### AWS requirements
- An Amazon S3 storage bucket
You must associate the Boundary storage bucket with an Amazon S3 storage bucket. A Boundary Amazon S3 storage bucket contains the bucket name, region, and optional prefix, as well as any credentials needed to access the bucket.
The Amazon S3 storage bucket can use static or dynamic credentials.
You can configure static credentials using an access key and secret key or dynamic credentials using the AWS [`AssumeRole` API](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole).
- An AWS IAM role policy with the following statement:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectAttributes",
"s3:DeleteObject",
"s3:ListBucket"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::session_recording_storage*",
"Resource": "arn:aws:s3:::session_recording_storage/foo/bar/zoo/*"
},
{
"Action": [
"iam:DeleteAccessKey",
"iam:GetUser",
"iam:CreateAccessKey"
],
"Effect": "Allow",
"Resource": "arn:aws:iam::123456789012:user/JohnDoe"
}
]
}
```
- If you apply KMS encryption to the storage bucket, you must add these additional permissions to the role policy for the storage bucket's IAM user:
```json
{
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Effect": "Allow",
"Resource": "arn:aws:kms:us-east-1:1234567890:key/uuid"
}
```
The following is an example working policy with KMS encryption configured on the S3 bucket:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "S3Permissions",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectAttributes",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::test-session-recording-bucket/*"
]
},
{
"Sid": "UserPermissions",
"Effect": "Allow",
"Action": [
"iam:DeleteAccessKey",
"iam:GetUser",
"iam:CreateAccessKey"
],
"Resource": [
"arn:aws:iam::1234567890:user/test-boundary"
]
},
{
"Sid": "KMSPermissions",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Resource": [
"arn:aws:kms:us-east-2:1234567890:key 4b887395-c376-4936-8f37-80c592ea582c"
]
}
]
}
```
## Next steps
After you configure the external storage provider, you can [create the storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket) in Boundary.
website/data/docs-nav-data.json
+17
View File
@@ -523,6 +523,23 @@
"title": "Overview",
"path": "configuration/session-recording"
},
{
"title": "Configure workers for storage",
"path": "configuration/session-recording/configure-worker-storage"
},
{
"title": "Configure storage provider",
"routes": [
{
"title": "Amazon S3",
"path": "configuration/session-recording/storage-providers/configure-s3"
},
{
"title": "MinIO",
"path": "configuration/session-recording/storage-providers/configure-minio"
}
]
},
{
"title": "Create storage buckets",
"path": "configuration/session-recording/create-storage-bucket"