Fix broken link & cleanup on the AWS Import Guide Closes #125

turbot · Jan 13, 2025 · bd17b4e · bd17b4e
1 parent 0066d53
commit bd17b4e
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 63 deletions.
diff --git 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
 
-<div className="alert alert-warning"> <strong>You are not required to use the Guardrails Audit Trail</strong> to configure CloudTrail, but <strong>there must be a CloudTrail configured in each region or a global trail.</strong>
-</div>
+> [!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
@@ -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
@@ -8,18 +8,18 @@ nav:
 
 # Importing an AWS account into Guardrails
 
-<div className="alert alert-warning">
-This section details the steps required to import an AWS Account into a Guardrails Folder.
-</div>
+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.
 
-<div className="alert alert-info" role="alert"><b>NOTICE</b>: 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.
-</div>
+> [!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
@@ -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.