Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs site org to match updated product thinking #1174

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 0 additions & 42 deletions _docs-sources/foundations/landing-zone/index.md

This file was deleted.

2 changes: 1 addition & 1 deletion _docs-sources/foundations/overview/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ When you set up a new DevOps component, you also have access to guidance from Gr

There are 5 DevOps components available today.

1. **[Landing Zone.](../landing-zone)** Set up a best-practice AWS multi-account setup, easily create new AWS accounts, and set secure account baselines.
1. **[Landing Zone.](/landing-zone)** Set up a best-practice AWS multi-account setup, easily create new AWS accounts, and set secure account baselines.
1. **[IaC Foundations.](../iac-foundations)** Set up the foundational Terraform and Terragrunt coding patterns that enable your team to scale.
1. **[Pipelines.](../pipelines)** Roll out an infrastructure change in a way that meets the needs of your organization.
1. **[Network Topology.](../network-topology)** Protect your internal cloud resources from external access.
Expand Down
4 changes: 2 additions & 2 deletions _docs-sources/foundations/pipelines/aws-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Pipelines can intelligently figure out which AWS account to authenticate to base

To perform the actions that Pipelines detects, each AWS account needs to assume an AWS IAM Role using [OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services). To explain OIDC at a high level, AWS considers GitHub an "identity provider," trusts GitHub's request for a temporary IAM Role, and then issues AWS credentials that are valid for the duration of a GitHub Action workflow.

Every time you create a new AWS account, you need to update the AWS OIDC configuration to create an IAM role for this account and allow it to be assumed by GitHub. When you use [Gruntwork Landing Zone](../landing-zone), this role is automatically created when [adding a new AWS account](../landing-zone/add-aws-account.md).
Every time you create a new AWS account, you need to update the AWS OIDC configuration to create an IAM role for this account and allow it to be assumed by GitHub. When you use [Gruntwork Landing Zone](/landing-zone), this role is automatically created when [adding a new AWS account](/landing-zone/add-aws-account.md).

## How Pipelines knows what AWS account to authenticate to

Expand Down Expand Up @@ -66,7 +66,7 @@ The AWS IAM Role for the management account must have permissions to provision n

### Child Accounts

Each child account (e.g., `dev`, `stage`, `prod,` etc.) contains an AWS IAM role that Pipelines can assume from GitHub Actions using OIDC. This role is automatically provisioned as a part of the [account baseline process](../landing-zone/add-aws-account). Once this role is in place in the child account, users may submit Pull Requests to add/modify/delete resources in the child account.
Each child account (e.g., `dev`, `stage`, `prod,` etc.) contains an AWS IAM role that Pipelines can assume from GitHub Actions using OIDC. This role is automatically provisioned as a part of the [account baseline process](/landing-zone/add-aws-account). Once this role is in place in the child account, users may submit Pull Requests to add/modify/delete resources in the child account.

When a Pull Request is created or synchronized, or a push to the `main` branch occurs, Pipelines will detect the changes, map them to the new account, assume the role in the child account, then run a `terragrunt plan` or `terragrunt apply` job (plan for PRs, apply for pushes to main).

2 changes: 1 addition & 1 deletion _docs-sources/foundations/pipelines/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,4 @@ These docs cover how Gruntwork Pipelines works specifically in the context of ot

## Gruntwork Pipelines and Gruntwork Landing Zone

In addition to rolling out infrastructure changes, Gruntwork Pipelines can also manage requests to create new AWS accounts as part of [Gruntwork Landing Zone](../../foundations/landing-zone)
In addition to rolling out infrastructure changes, Gruntwork Pipelines can also manage requests to create new AWS accounts as part of [Gruntwork Landing Zone](/landing-zone)
Original file line number Diff line number Diff line change
Expand Up @@ -124,4 +124,4 @@ Control Tower is now configured! Next you should consider:

- [Configuring IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-choose-identity-source.html) for Access Control.
- [Configuring any controls or SCPs](https://docs.aws.amazon.com/controltower/latest/userguide/controls.html) your organization requires.
- [Setting up your Gruntwork IaC Foundations](../iac-foundations)
- [Setting up your Gruntwork IaC Foundations](/foundations/iac-foundations)
43 changes: 42 additions & 1 deletion _docs-sources/landing-zone/index.md
Original file line number Diff line number Diff line change
@@ -1 +1,42 @@
# Landing Zone
# About Landing Zone

Gruntwork Landing Zone enables your organization to:

- Create an initial best-practice, AWS multi-account setup
- Put in place a system for vending new AWS accounts (commonly known as an "account factory")
- Install secure AWS account baselines compliant with the [CIS AWS Foundations Benchmark](https://www.cisecurity.org/benchmark/amazon_web_services).

Gruntwork Landing Zone is intended to be deployed as your new paradigm for creating and managing AWS accounts. Once set up, you can import existing AWS accounts.

## What's included

- **Strategy.** Gruntwork has designed an approach that extends AWS Control Tower to support the full set of needs around AWS account management with Terraform/OpenTofu and GitHub.
- **IaC Modules.** Gruntwork Landing Zone includes modules to configure Control Tower, configure AWS IAM Identity Center, and install AWS account baselines that meet the CIS AWS Foundations Benchmark.
- **Tooling.** Gruntwork Landing Zone makes use of Gruntwork Pipelines and GitHub Action to support the account request and review process.
- **Setup.** Installing Gruntwork Landing Zone is fully documented.
- **Updates.** Gruntwork publishes regular updates to all Landing Zone modules, including support for the latest versions of the CIS AWS Foundations Benchmark, and ongoing updates to our Landing Zone workflows.

## Extending AWS Control Tower

Gruntwork Landing Zone builds on AWS Control Tower to add important new functionality.

### What is AWS Control Tower?

AWS Control Tower helps you set up and govern AWS accounts, and gives you a centralized way to manage compliance and configuration across your AWS accounts. But Control Tower is fundamentally a Platform-as-a-Service (PaaS) paradigm where you use "ClickOps" to create and configure AWS accounts. That stands in contrast to the vision behind IaC tools like Terraform, which are built on the philosophy that all Cloud resources are described in code. It can also be challenging to customize Control Tower and maintain it over time.

### Additional functionality

Gruntwork Landing Zone directly addresses these limitations by extending Control Tower with the following functionality:

1. Configure and customize new AWS accounts using Terraform/OpenTofu
1. Have all new AWS accounts meet the CIS AWS Foundations Benchmark out of the box
1. Request new AWS accounts using a simple YAML file, GitHub Actions, or any system that can trigger a GitHub Action (e.g. ServiceNow)
1. Review and customize all new AWS account requests using GitHub Pull Request functionality
1. Define a customized account baseline unique to your organization
1. Enable AWS account baselines to stay up to date automatically using [Patcher](/patcher)

## Greenfield vs. brownfield

Gruntwork Landing Zone is optimized for situations where you are creating a "new world" infrastructure. Once your new world is stable, you can then import existing AWS accounts into Gruntwork Landing Zone, and migrate existing resources as needed.

While it possible to migrate an existing Control Tower deployment into Gruntwork Landing Zone, we have not yet defined a formal process for this and we do not currently recommend this. That being said, other Gruntwork DevOps components can still be installed alongside your existing non-Gruntwork Landing Zone solution.
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Access to CloudTrail is controlled by AWS IAM policies that are assigned to indi
Gruntwork recommends that only those with administrative access to an AWS account have access to view CloudTrail logs, as they contain a record of every single API operation that was performed in the account, which may expose the name or configuration of resources an individual user may otherwise not have access to.
:::

Further, the configuration of CloudTrail trails should be defined as code, with all changes reviewed in a pull request before being applied automatically by [Gruntwork Pipelines](../../pipelines/overview/index.md).
Further, the configuration of CloudTrail trails should be defined as code, with all changes reviewed in a pull request before being applied automatically by [Gruntwork Pipelines](/pipelines/overview/).

See [Identity-based policy examples for AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/security_iam_id-based-policy-examples.html) to learn more about granting access to CloudTrail.

Expand Down
2 changes: 1 addition & 1 deletion _docs-sources/pipelines/security/audit-log.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,4 +65,4 @@ When Pipelines is run in response to a pull request being merged, the user that

Gruntwork Pipelines leverages AWS CloudTrail to log all actions taken by Pipelines in your AWS account. Due to our naming scheme, identifying operations performed in your AWS account by Gruntwork Pipelines are clearly identified.

Accessing CloudTrail and querying data is dependent on your organization's policies and settings. If you are a Gruntwork Landing Zone customer, see the documentation on [logging](../../foundations/landing-zone/logging.md) for information on how to access and query your CloudTrail data.
Accessing CloudTrail and querying data is dependent on your organization's policies and settings. If you are a Gruntwork Landing Zone customer, see the documentation on [logging](/landing-zone/logging) for information on how to access and query your CloudTrail data.
50 changes: 0 additions & 50 deletions docs/foundations/landing-zone/index.md

This file was deleted.

4 changes: 2 additions & 2 deletions docs/foundations/overview/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ When you set up a new DevOps component, you also have access to guidance from Gr

There are 5 DevOps components available today.

1. **[Landing Zone.](../landing-zone)** Set up a best-practice AWS multi-account setup, easily create new AWS accounts, and set secure account baselines.
1. **[Landing Zone.](/landing-zone)** Set up a best-practice AWS multi-account setup, easily create new AWS accounts, and set secure account baselines.
1. **[IaC Foundations.](../iac-foundations)** Set up the foundational Terraform and Terragrunt coding patterns that enable your team to scale.
1. **[Pipelines.](../pipelines)** Roll out an infrastructure change in a way that meets the needs of your organization.
1. **[Network Topology.](../network-topology)** Protect your internal cloud resources from external access.
Expand All @@ -32,6 +32,6 @@ The Gruntwork DevOps components implement a meaningful portion of a modern cloud
<!-- ##DOCS-SOURCER-START
{
"sourcePlugin": "local-copier",
"hash": "8443059126ca0f93cea9eea74cdb19ad"
"hash": "88e720adeb9b6ff01cd43ef0402d3ff5"
}
##DOCS-SOURCER-END -->
Loading