diff --git a/docs/guides/aws/event-handlers/index.md b/docs/guides/aws/event-handlers/index.md index 4ebf1165..85d272b8 100644 --- a/docs/guides/aws/event-handlers/index.md +++ b/docs/guides/aws/event-handlers/index.md @@ -8,7 +8,6 @@ nav: # Configuring Real-Time events - In this guide, you will: - You will setup AWS Event Handlers. @@ -21,52 +20,41 @@ Pollers enable Guardrails' **Event-driven model** of operation. Guardrails uses the following infrastructure for event handling: -- **CloudTrail** must be enabled in every region where events are to be sent - from. This can be done with regional, global or Organization trails. An - additional CloudTrail just for Guardrails' use is unnecessary cost. -- **EventBridge** is enabled by default and requires no configuration. Guardrails - uses the 'default' bus. -- **CloudWatch Event Rules** determine which API events to filter for. -- **CloudWatch Event Targets** Direct the events from EventBridge to SNS. -- **SNS Topic** Where the events are published. -- **SNS Subscription** Forwards events to the event ingestion API endpoint where Guardrails will - process them. +| **Infrastructure Service** | **Description** | +|-----------------------------|----------------------------------------------------------------------------------------------------------| +| **CloudTrail** | Must be enabled in every region where events are to be sent from. This can be done with regional, global, or Organization trails. An additional CloudTrail just for Guardrails' use is unnecessary cost. | +| **EventBridge** | Enabled by default and requires no configuration. Guardrails uses the 'default' bus. | +| **CloudWatch Event Rules** | Determine which API events to filter for. | +| **CloudWatch Event Targets**| Direct the events from EventBridge to SNS. | +| **SNS Topic** | Where the events are published. | +| **SNS Subscription** | Forwards events to the event ingestion API endpoint where Guardrails will process them. | + -## Guardrails Mods Required for Event Handling +## Mods Required for Event Handling In order to configure real time eventing, the following set of mods must be installed and up to date in the environment: -### Required for AWS Account Import - -- aws -- aws-iam -- aws-kms - -### Required for Guardrails configuration of CloudTrail +| **Category** | **Required Mods** | +|----------------------------------------|----------------------------------| +| AWS Account Import | `aws`, `aws-iam`, `aws-kms` | +| Configuration of CloudTrail | `aws-cloudtrail`, `aws-s3` | +| Event Handler Configuration | `aws-events`, `aws-sns` | -These mods are required only if using Guardrails to configure CloudTrail. - -- aws-cloudtrail -- aws-s3 - -### Required for Event Handler configuration - -- aws-events -- aws-sns ## Configuring CloudTrail -
You are not required to use the Guardrails Audit Trail to configure CloudTrail, but there must be a CloudTrail configured in each region or a global trail. -
+> [!WARNING] +> You are not required to use the Guardrails Audit Trail to configure CloudTrail, but there must be a CloudTrail configured in each region or a global trail. + The [Guardrails Audit Trail](/guardrails/docs/mods/aws/aws/policy#aws--turbot--audit-trail) policy provides a convenient mechanism for setting up CloudTrail in AWS accounts. -### Creating logging buckets using the default configuration +### Creating Logging Buckets -CloudTrail requires an S3 bucket to store logs. The Guardrails Logging Bucket policy +CloudTrail requires an S3 bucket to store logs. The Guardrails `Logging Bucket policy` can simplify creation of logging buckets. To set up logging buckets in the default configuration, simply set the @@ -99,7 +87,7 @@ policy. The Turbot Audit Trail will only be deployed in a single region. Use [AWS > Turbot > Logging > Bucket > Regions](/guardrails/docs/mods/aws/aws/policy#aws--turbot--logging--bucket--regions) to specify which regions will get logging buckets. -### Set up CloudTrail with the default configuration: +### Setup CloudTrail Once the logging buckets have been created, it is time to set up the **Audit Trail** stack: @@ -204,7 +192,7 @@ region. Deployment often takes a minute or two per region. If not in `ok` then use the information in [How Event Handlers Work](#how-event-handlers-work) to get a sense of what may have gone wrong in the deployment. -## Decomissioning Event Handlers +## Decommissioning Event Handlers Event handlers can be shut-off by setting the [AWS > Turbot > Event Handler](/guardrails/docs/mods/aws/aws/policy#aws--turbot--event-handlers) @@ -214,7 +202,7 @@ an AWS account out of Turbot will not automatically decommission the event handlers. Event Handlers must be set explicitly destroyed before removing the account from Turbot. -## When to decommission Event Handlers +## When to Decommission Event Handlers Event Handlers should be decommissioned before: diff --git a/docs/guides/aws/import-aws-account/gov-cloud.md b/docs/guides/aws/import-aws-account/gov-cloud.md index 0a01bfd6..73e90429 100644 --- a/docs/guides/aws/import-aws-account/gov-cloud.md +++ b/docs/guides/aws/import-aws-account/gov-cloud.md @@ -6,7 +6,12 @@ nav: order: 10 --- -# Importing a AWS Gov Cloud or AWS China account into Guardrails +# Importing a AWS Gov Cloud or AWS China account + +In this guide, you will: + +- Import an AWS Account into a Guardrails Folder. + ## Prerequisites to import AWS GovCloud or AWS China Account @@ -30,7 +35,7 @@ create a user and a role using AWS IAM. } ``` -- If you wish to take advantage of every AWS integration offered by Guardrails +- If you wish to take advantage of every AWS integration offered by Guardrails (recommended), attach the Amazon Managed AdministratorAccess Policy to the Role: - `arn:aws:iam::aws:policy/AdministratorAccess` @@ -92,8 +97,8 @@ Recommended Mods: While you can import an AWS account at the Turbot level, it is recommended that you import accounts into Guardrails Folders, as it provides greater flexibility and -ease of management. -Define a [Folder hierarchy](getting-started/configure_workspace) prior to import. +ease of management. +Define a [Folder hierarchy](/guardrails/docs/concepts/resources/hierarchy) prior to import. #### Importing the account via Terraform diff --git a/docs/guides/aws/import-aws-account/index.md b/docs/guides/aws/import-aws-account/index.md index 938319ce..3b4db4b2 100644 --- a/docs/guides/aws/import-aws-account/index.md +++ b/docs/guides/aws/import-aws-account/index.md @@ -8,18 +8,18 @@ nav: # Importing an AWS account into Guardrails -
-This section details the steps required to import an AWS Account into a Guardrails Folder. -
+In this guide, you will: -## Overview +- Import an AWS Account into a Guardrails Folder. + +## Prerequisites Guardrails can get access to an AWS Account by one of the following ways: - Cross-Account IAM Role (Commercial Cloud) - IAM Role and User Access Key Pair (AWS China and AWS GovCloud) -### Supported AWS Partitions +## Supported AWS Partitions There are three account partitions that AWS offers and Guardrails supports. Valid partition names are: @@ -34,10 +34,10 @@ Consider that Turbot Guardrails is hosted only in AWS commercial accounts. There - To import [AWS China or AWS GovCloud accounts](guides/aws/import-aws-account/gov-cloud) requires hosting of guardrails in the same partition as those account or using access keys for each account outside of the current AWS Partition. -
NOTICE: Free Tier AWS accounts cannot be used with Guardrails. If this is attempted, Guardrails will fail to properly discover resources in the account and will generate errors in the Guardrails console. -
+> [!IMPORTANT] +> Free Tier AWS accounts cannot be used with Guardrails. If this is attempted, Guardrails will fail to properly discover resources in the account and will generate errors in the Guardrails console. -## Prerequisites to import AWS Commercial Account +## Import AWS Commercial Account A few steps must be completed before an account can be imported into a Guardrails workspace: @@ -51,7 +51,7 @@ A few steps must be completed before an account can be imported into a Guardrail Guardrails can't see those resources. Refer to the [Recommended Starting Mods](mods#recommended-starting-mods) for more information. -### What Permissions to Grant +## What Permissions to Grant What permissions you grant to the Guardrails IAM role will depend on your use case(s). Guardrails will use whichever role you specify and the permissions granted @@ -123,7 +123,7 @@ conforms to your requirements. - `ce:getCostForecast` - `ce:GetCostAndUsage` -### Cross Account Trust +## Cross Account Trust The role must grant cross-account access for the Turbot Guardrails master AWS account to assume into your AWS account. @@ -135,7 +135,7 @@ assume into your AWS account. - Turbot Guardrails Enterprise customers, enter the AWS Account ID of the AWS Account where you have installed the Turbot Guardrails Enterprise stacks. -### External IDs +## External IDs It is required that you set an External ID. There are two sources for the External ID: @@ -156,12 +156,12 @@ External ID: - If you are setting your own external ID, be sure it follows [AWS character limits](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html). -### Role Name +## Role Name Give the role a meaningful name such as `turbot-service-readonly` (read only) or `turbot-service-superuser` (for full access), as well as an apt description. -## Creating the Role +### Create IAM Role ### Using CloudFormation @@ -170,7 +170,7 @@ EU customers, use `255798382450`. #### ReadOnly + Global Event Handlers -Reccommended starting point for new installations +Recommended starting point for new installations This represents the minimum privileges required for Guardrails to discover all AWS resources and configure **global** event handlers. @@ -220,7 +220,7 @@ Parameters: Type: String Default: "/" Description: > - The IAM path to use for all IAM roles created in this stack. + The IAM path to use for all IAM roles created in this stack. The path must either be a single forward slash "/" or alphanumeric characters with starting and ending forward slashes "/my-path/". GuardrailsSaaSAccountId: @@ -325,12 +325,12 @@ Outputs: Description: "ARN of the Guardrails IAM role" Value: !GetAtt GuardrailsAccessRole.Arn Export: - Name: "GuardrailsAccessRoleArn" + Name: "GuardrailsAccessRoleArn" AccessRoleExternalIdOutput: Description: "External ID used in the Access Role" Value: !Ref AccessRoleExternalId Export: - Name: "AccessRoleExternalId" + Name: "AccessRoleExternalId" ``` #### Full AdministratorAccess @@ -521,7 +521,7 @@ manually: `turbot-superuser` (for full access), as well as an apt description. Click **Create Role**. -### Install desired mods +### Install Desired Mods The `aws` mod is required to import AWS accounts into a Guardrails workspace. It must be installed before account imports can start. Ensure it is installed and the @@ -555,9 +555,9 @@ Recommended Mods (in order of installation): Importing accounts into Folders offers increased flexibility and easier management over importing directly under the Turbot level. Define a -[Folder hierarchy](getting-started/configure_workspace) prior to import. +[Folder hierarchy](/guardrails/docs/concepts/resources/hierarchy) prior to import. -#### Importing the account via the Guardrails Console +### Importing Account via Guardrails Console 1. At the main Guardrails console after logging in with `Turbot/Admin` permissions, click the purple **IMPORT** card in the top right. @@ -578,7 +578,7 @@ management over importing directly under the Turbot level. Define a discovering the resources in your AWS account. Resources will start appearing right away, and resource discovery will continue to run in the background. -#### Importing the account via Terraform +### Importing Account via Terraform ```hcl diff --git a/docs/guides/using-guardrails/troubleshooting/fix-invalid-controls/index.md b/docs/guides/using-guardrails/troubleshooting/fix-invalid-controls/index.md index 71bd56fc..5a799d65 100644 --- a/docs/guides/using-guardrails/troubleshooting/fix-invalid-controls/index.md +++ b/docs/guides/using-guardrails/troubleshooting/fix-invalid-controls/index.md @@ -15,13 +15,12 @@ Controls enforce policies to ensure cloud resources remain compliant and Guardra - **Turbot/Operator** permissions at the Turbot resource level. - Familiarity with the Guardrails console. -## Step 1: Log In to Guardrails Console +## Step 1: Login to Guardrails Console Log in to the Guardrails console. ![Guardrails Console Login](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-invalid-controls/guardrails-console-login.png) - ## Step 2: Navigate to Reports Choose **Reports** from the top navigation menu. @@ -65,7 +64,6 @@ The control re-evaluates the policies and transitions to an **OK** state if the ![Control OK State](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-invalid-controls/guardrails-control-ok-state.png) - ## Step 6: Optimizing Controls - **Review the controls in Invalid state** and take the necessary actions.