diff --git a/_docs-sources/guides/build-it-yourself/index.md b/_docs-sources/guides/build-it-yourself/index.md new file mode 100644 index 0000000000..d63bbcb01d --- /dev/null +++ b/_docs-sources/guides/build-it-yourself/index.md @@ -0,0 +1,58 @@ +import Card from "/src/components/Card" +import Grid from "/src/components/Grid" + +# Build Your Own Architecture + +The Gruntwork IaC library empowers you to construct your own bespoke architecture in record time. By mix-and-matching our modules and services you can quickly define a custom architecture to suit your needs, all with the confidence of having world-class, battle-tested code running under the hood. This series of guides aims to teach you how to configure and deploy some of our most popular services. Additional guides will be added over time, but the principles covered extend to the rest of the IaC library. If you have trouble, don’t hesitate to ask questions via our [support channels](/docs/guides/support). + +## Follow Our Deployment Guides + + + + Set up a multi-account structure using Gruntwork Landing Zone. + + + Implement continuous deployment for your infrastructure code with Gruntwork + Pipelines. + + + Set up your network according to industry best practices using our VPC service. + + + Deploy a Kubernetes Cluster to host all of your apps and services. + + + Make your infrastructure compliant with the CIS AWS Foundations Benchmark. + + + +## Dig Into the Code + + + + View the API reference for our entire service catalog to learn what’s + available. + + + If you're the type who likes to jump straight to the source, this is for + you. + + diff --git a/_docs-sources/guides/index.md b/_docs-sources/guides/index.md index 91f179f04e..7a99dbba26 100644 --- a/_docs-sources/guides/index.md +++ b/_docs-sources/guides/index.md @@ -1,124 +1,21 @@ ---- -sidebar_label: "Introduction" -sidebar_position": 1 -hide_table_of_contents: true -hide_title: true ---- - import Card from "/src/components/Card" -import Grid from "/src/components/Grid" -import CenterLayout from "/src/components/CenterLayout" - - +import CardGroup from "/src/components/CardGroup" # Gruntwork Guides -As a Gruntwork subscriber, you have two primary ways to engage with our library. Whichever approach you choose, our guides provide step-by-step instructions to help you deploy your infrastructure with confidence. We also offer detailed upgrade guides to ensure that your infrastructure remains up-to-date with the latest security patches, compliance requirements, and DevOps best practices. - - - - Learn how to use and administer a Reference Architecture which Gruntwork has - deployed for you. - - - Learn how to utilize our service modules to construct a world-class - architecture on your own. - - - -## Build Your Own Architecture - -The Gruntwork IaC library empowers you to construct your own bespoke architecture in record time. By mix-and-matching our modules and services you can quickly define a custom architecture to suit your needs, all with the confidence of having world-class, battle-tested code running under the hood. This series of guides aims to teach you how to configure and deploy some of our most popular services. Additional guides will be added over time, but the principles covered extend to the rest of the IaC library. If you have trouble, don’t hesitate to ask questions via our [support channels](/docs/guides/support). - -### Follow Our Step-By-Step Guides - - - - Set up a multi-account structure using Gruntwork Landing Zone. - - - Implement continuous deployment for your infrastructure code with Gruntwork - Pipelines. - - - Set up your network according to industry best practices using our VPC service. - - - Deploy a Kubernetes Cluster to host all of your apps and services. - - - Make your infrastructure compliant with the CIS AWS Foundations Benchmark. - - - -### Dig Into the Code - - - - View the API reference for our entire service catalog to learn what’s - available. - - - If you're the type who likes to jump straight to the source, this is for - you. - - - -## Stay Up to Date - - - - - -### Terraform - -- [Update to version 1.X](/docs/guides/stay-up-to-date/terraform/terraform-1.x) -- [Update to Terraform 15](/docs/guides/stay-up-to-date/terraform/terraform-15) -- [Update to Terraform 14](/docs/guides/stay-up-to-date/terraform/terraform-14) -- [Update to Terraform 13](/docs/guides/stay-up-to-date/terraform/terraform-13) -- [Update to Terraform 12](/docs/guides/stay-up-to-date/terraform/terraform-12) -- [Update to Version 3 of the Terraform provider](/docs/guides/stay-up-to-date/terraform/how-to-update-to-aws-provider-v3) -- [DRY your Reference Architecture](/docs/guides/stay-up-to-date/terraform/how-to-dry-your-reference-architecture) - - - - -### CIS AWS Foundations Benchmark - -- [Update to version 1.4.0](/docs/guides/stay-up-to-date/cis/cis-1.4.0) -- [Update to version 1.3.0](/docs/guides/stay-up-to-date/cis/cis-1.3.0) - - - - +Before you get too deep into the code, it's important to understand Gruntwork's core principles. These guides will give you the necessary background to succeed with your Gruntwork subscription, and provide an essential framework for constructing a world-class DevOps infrastructure. -## Style Guides + -- [Terraform Style Guide](/docs/guides/style/terraform-style-guide) -- [Go Style Guide](/docs/guides/style/golang-style-guide) + +Before anything else, check out our introductory guide to set up your account, prepare your tools, and understand what to expect. + + +We present a comprehensive model to help you establish a robust infrastructure platform, and explain how Gruntwork can accelarate its adoption in your org. + - + diff --git a/_docs-sources/guides/reference-architecture/02-authenticate/01-intro.md b/_docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/01-intro.md similarity index 100% rename from _docs-sources/guides/reference-architecture/02-authenticate/01-intro.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/01-intro.md diff --git a/_docs-sources/guides/reference-architecture/02-authenticate/02-setting-up-initial-access.md b/_docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/02-setting-up-initial-access.md similarity index 100% rename from _docs-sources/guides/reference-architecture/02-authenticate/02-setting-up-initial-access.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/02-setting-up-initial-access.md diff --git a/_docs-sources/guides/reference-architecture/02-authenticate/03-authenticate-to-the-aws-web-console.md b/_docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/03-authenticate-to-the-aws-web-console.md similarity index 100% rename from _docs-sources/guides/reference-architecture/02-authenticate/03-authenticate-to-the-aws-web-console.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/03-authenticate-to-the-aws-web-console.md diff --git a/_docs-sources/guides/reference-architecture/02-authenticate/04-authenticate-to-aws-via-the-cli.md b/_docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/04-authenticate-to-aws-via-the-cli.md similarity index 100% rename from _docs-sources/guides/reference-architecture/02-authenticate/04-authenticate-to-aws-via-the-cli.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/04-authenticate-to-aws-via-the-cli.md diff --git a/_docs-sources/guides/reference-architecture/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md b/_docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md similarity index 100% rename from _docs-sources/guides/reference-architecture/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md diff --git a/_docs-sources/guides/reference-architecture/02-authenticate/06-authenticate-to-the-vpn-server.md b/_docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/06-authenticate-to-the-vpn-server.md similarity index 100% rename from _docs-sources/guides/reference-architecture/02-authenticate/06-authenticate-to-the-vpn-server.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/02-authenticate/06-authenticate-to-the-vpn-server.md diff --git a/_docs-sources/guides/reference-architecture/03-deploy-apps/01-intro.md b/_docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/01-intro.md similarity index 100% rename from _docs-sources/guides/reference-architecture/03-deploy-apps/01-intro.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/01-intro.md diff --git a/_docs-sources/guides/reference-architecture/03-deploy-apps/02-what-is-already-deployed.md b/_docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/02-what-is-already-deployed.md similarity index 100% rename from _docs-sources/guides/reference-architecture/03-deploy-apps/02-what-is-already-deployed.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/02-what-is-already-deployed.md diff --git a/_docs-sources/guides/reference-architecture/03-deploy-apps/03-the-app.md b/_docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/03-the-app.md similarity index 100% rename from _docs-sources/guides/reference-architecture/03-deploy-apps/03-the-app.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/03-the-app.md diff --git a/_docs-sources/guides/reference-architecture/03-deploy-apps/04-dockerizing.md b/_docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/04-dockerizing.md similarity index 100% rename from _docs-sources/guides/reference-architecture/03-deploy-apps/04-dockerizing.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/04-dockerizing.md diff --git a/_docs-sources/guides/reference-architecture/03-deploy-apps/05-publish-docker-image.md b/_docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/05-publish-docker-image.md similarity index 100% rename from _docs-sources/guides/reference-architecture/03-deploy-apps/05-publish-docker-image.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/03-deploy-apps/05-publish-docker-image.md diff --git a/_docs-sources/guides/reference-architecture/04-configure-gw-pipelines/01-intro.md b/_docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/01-intro.md similarity index 100% rename from _docs-sources/guides/reference-architecture/04-configure-gw-pipelines/01-intro.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/01-intro.md diff --git a/_docs-sources/guides/reference-architecture/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md b/_docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md similarity index 87% rename from _docs-sources/guides/reference-architecture/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md index 9c09e8d85b..66e2ec919f 100644 --- a/_docs-sources/guides/reference-architecture/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md +++ b/_docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md @@ -2,7 +2,7 @@ This diagram shows a rough overview of the Gruntwork Pipelines architecture: -![Architecture Diagram](/img/guides/reference-architecture/gruntwork-pipelines-architecture.png) +![Architecture Diagram](/img/guides/reference-architecture/example-usage-guide/gruntwork-pipelines-architecture.png) The Gruntwork Pipelines workflow, defined in [`.github/workflows/pipelines.yml`](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/.github/workflows/pipelines.yml), works like this: @@ -34,23 +34,23 @@ If you'd like to send Slack notifications when the pipeline is running, follow t 1. In Slack, open the Workflow builder: - ![Slack Workflow Builder](/img/guides/reference-architecture/slack-workflow-1.png) + ![Slack Workflow Builder](/img/guides/reference-architecture/example-usage-guide/slack-workflow-1.png) 1. Create a new Webhook workflow called "Gruntwork Pipelines" - ![Slack Webhook workflow](/img/guides/reference-architecture/slack-workflow-2.png) + ![Slack Webhook workflow](/img/guides/reference-architecture/example-usage-guide/slack-workflow-2.png) 1. Add the following text variables to the workflow: `branch`, `status`, `url`, `repo`, and `actor` - ![Slack workflow variables](/img/guides/reference-architecture/slack-workflow-3.png) + ![Slack workflow variables](/img/guides/reference-architecture/example-usage-guide/slack-workflow-3.png) 1. Once all of the variables are added, click Next. 1. Now add another step to the workflow - ![Slack workflow add step](/img/guides/reference-architecture/slack-workflow-4.png) + ![Slack workflow add step](/img/guides/reference-architecture/example-usage-guide/slack-workflow-4.png) -1. Add the "Send a message" step +1. Add the "Send a message" step 1. Choose a channel from the dropdown menu @@ -72,7 +72,7 @@ If you'd like to send Slack notifications when the pipeline is running, follow t 1. Copy the webhook URL and save it. We will use this value below. - ![Slack workflow add step](/img/guides/reference-architecture/slack-workflow-5.png) + ![Slack workflow add step](/img/guides/reference-architecture/example-usage-guide/slack-workflow-5.png) 1. Note that the webhook URL should be treated as sensitive. Anyone with the URL can send HTTP requests to the webhook! @@ -80,12 +80,12 @@ If you'd like to send Slack notifications when the pipeline is running, follow t 1. Open the GitHub repository and navigate to Settings => Secrets. - ![GitHub Secrets](/img/guides/reference-architecture/secrets.png) + ![GitHub Secrets](/img/guides/reference-architecture/example-usage-guide/secrets.png) 1. Create the following repository secrets: -- `AWS_ACCESS_KEY_ID`: This is the first value from the AWS IAM user step above. -- `AWS_SECRET_ACCESS_KEY`: This is the second value from the AWS IAM user step above. +- `AWS_ACCESS_KEY_ID`: This is the first value from the AWS IAM user step above. +- `AWS_SECRET_ACCESS_KEY`: This is the second value from the AWS IAM user step above. - `GH_TOKEN`: Enter the GitHub machine user's oauth token here. If you don't know this, you can find it in the AWS Secrets Manager secret that you provided in the [`reference-architecture-form.yml`](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/examples/for-production/infrastructure-live/reference-architecture-form.yml). - `SLACK_WEBHOOK_URL`: This is the value from the Slack Workflow step above. diff --git a/_docs-sources/guides/reference-architecture/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md b/_docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md similarity index 100% rename from _docs-sources/guides/reference-architecture/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md diff --git a/_docs-sources/guides/reference-architecture/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md b/_docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md similarity index 100% rename from _docs-sources/guides/reference-architecture/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md diff --git a/_docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/01-intro.md b/_docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/01-intro.md similarity index 100% rename from _docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/01-intro.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/01-intro.md diff --git a/_docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/02-metrics.md b/_docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/02-metrics.md similarity index 100% rename from _docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/02-metrics.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/02-metrics.md diff --git a/_docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/03-alerts.md b/_docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/03-alerts.md similarity index 100% rename from _docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/03-alerts.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/03-alerts.md diff --git a/_docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/04-logs.md b/_docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/04-logs.md similarity index 100% rename from _docs-sources/guides/reference-architecture/05-monitoring-alerting-logging/04-logs.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/04-logs.md diff --git a/_docs-sources/guides/reference-architecture/06-adding-a-new-account/01-intro.md b/_docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/01-intro.md similarity index 100% rename from _docs-sources/guides/reference-architecture/06-adding-a-new-account/01-intro.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/01-intro.md diff --git a/_docs-sources/guides/reference-architecture/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md b/_docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md similarity index 100% rename from _docs-sources/guides/reference-architecture/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md diff --git a/_docs-sources/guides/reference-architecture/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md b/_docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md similarity index 100% rename from _docs-sources/guides/reference-architecture/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md diff --git a/_docs-sources/guides/reference-architecture/06-adding-a-new-account/04-deploy-the-security-baseline.md b/_docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/04-deploy-the-security-baseline.md similarity index 100% rename from _docs-sources/guides/reference-architecture/06-adding-a-new-account/04-deploy-the-security-baseline.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/04-deploy-the-security-baseline.md diff --git a/_docs-sources/guides/reference-architecture/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md b/_docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md similarity index 100% rename from _docs-sources/guides/reference-architecture/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/01-intro.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/01-intro.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/01-intro.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/01-intro.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/02-before-you-get-started.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/02-before-you-get-started.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/02-before-you-get-started.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/02-before-you-get-started.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/04-pre-requisite-understand-module-dependencies.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/04-pre-requisite-understand-module-dependencies.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/04-pre-requisite-understand-module-dependencies.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/04-pre-requisite-understand-module-dependencies.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/06-manually-undeploying-a-single-module.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/06-manually-undeploying-a-single-module.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/06-manually-undeploying-a-single-module.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/06-manually-undeploying-a-single-module.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/08-removing-the-terraform-state.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/08-removing-the-terraform-state.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/08-removing-the-terraform-state.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/08-removing-the-terraform-state.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/09-useful-tips.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/09-useful-tips.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/09-useful-tips.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/09-useful-tips.md diff --git a/_docs-sources/guides/reference-architecture/07-undeploy/10-known-errors.md b/_docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/10-known-errors.md similarity index 100% rename from _docs-sources/guides/reference-architecture/07-undeploy/10-known-errors.md rename to _docs-sources/guides/reference-architecture/example-usage-guide/07-undeploy/10-known-errors.md diff --git a/_docs-sources/guides/reference-architecture/example-usage-guide/index.md b/_docs-sources/guides/reference-architecture/example-usage-guide/index.md new file mode 100644 index 0000000000..4d85875db5 --- /dev/null +++ b/_docs-sources/guides/reference-architecture/example-usage-guide/index.md @@ -0,0 +1,160 @@ +# Example Reference Architecture Usage Guide + +:::caution + +This guide presents example usage for a _specific_ Reference Architecture configuration with ASG, Aurora, and GitHub CI. Once you purchase a Reference Architecture, you'll receive documentation customized to your chosen configuration in your own repo. + +::: + +This documentation contains an overview of a deployed and managed architecture. + +First, the short version: + +- This is an end-to-end tech stack for [Amazon Web Services (AWS)](https://aws.amazon.com/) that includes all the + basic infrastructure a company needs, including the network topology, orchestration tools (e.g., Kubernetes or ECS), databases, caches, load balancers, CI / CD pipeline, monitoring, alerting, log aggregation, etc.- It's built on top of the [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog). +- It's all defined and managed as code using tools such as [Terraform](https://www.terraform.io/), [Packer](https://www.packer.io/), and [Docker](https://www.docker.com/). + +Here's a diagram that shows a rough overview of what the Reference Architecture looks like: + +![Architecture Diagram](/img/guides/reference-architecture/example-usage-guide/landing-zone-ref-arch.png) + +Now, the long version: + +## Infrastructure as code + +All of the infrastructure in this repo is managed as **code** using [Terragrunt](https://terragrunt.gruntwork.io/), a thin wrapper around [Terraform](https://www.terraform.io). That is, instead of clicking around a web UI or SSHing to a server and manually executing commands, the idea behind infrastructure as code (IAC) is that you write code to define your infrastructure and you let an automated tool (e.g., Terraform) apply the code changes to your infrastructure. This has a number of benefits: + +- You can automate your entire provisioning and deployment process, which makes it much faster and more reliable than + any manual process. + +- You can represent the state of your infrastructure in source files that anyone can read, rather than having that knowledge trapped inside a sysadmin's head. + +- You can store those source files in version control, which means the entire history of your infrastructure is + captured in the commit log, which you can use to debug problems, and if necessary, roll back to older versions. + +- You can validate each infrastructure change through code reviews and automated tests. + +- You can package your infrastructure as reusable, documented, battle-tested modules that make it easier to scale and + evolve your infrastructure. In fact, most of the infrastructure code in this architecture is deployed from the service modules in the + [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog/). + +For more info on Infrastructure as Code and Terraform, check out [A Comprehensive Guide to +Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca) and our our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) section. + +## AWS accounts + +The infrastructure is deployed across multiple AWS accounts. For example, the staging environment is in one account, +the production environment in another account, shared tooling is in yet another account, and so on. This gives you +better isolation between environments so that if you break something in one environment (e.g., staging)—or worse yet, a +hacker breaks into that environment—it should have no effect on your other environments (e.g., prod). It also gives you +better control over what resources each employee can access, helps you to keep track of costs, and gives you an easy way to test out new features and services in isolation. + +The list of accounts includes: + +- **dev**: Sandbox environment. +- **stage**: Pre-production environment. +- **prod**: Production environment. +- **security**: All IAM users and permissions are defined in this account. +- **shared-services**: DevOps tooling. +- **logs**: An account for centralizing logs from all of the accounts. + +Check out the [Authentication docs](02-authenticate/01-intro.md) for more info on how to authenticate to these accounts and +switch between them. + +## VPCs and subnets + +Each environment lives in a separate [Virtual Private Cloud (VPC)](https://aws.amazon.com/vpc/), which is a logically +isolated section within an AWS account. Each VPC defines a virtual network, with its own IP address space and rules for +what can go in and out of that network. The IP addresses within each VPC are further divided into multiple +[subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html), where each subnet controls the +routing for its IP address. + +- _Public subnets_ are directly accessible from the public Internet. +- _Private subnets_ are only accessible from within the VPC. + +Just about everything in this infrastructure is deployed in private subnets to reduce the surface area to attackers. +The only exceptions are load balancers and the [OpenVPN server](#openvpn-server), both of which are described below. + +Each VPC is also configured with [VPC flow logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html), which +can be useful for monitoring and auditing network traffic across the VPC. Each VPC publishes its flow logs to CloudWatch +Logs, under the log group `VPC_NAME-vpc-flow-logs`, where the `VPC_NAME` is an input variable to the `vpc` module. + +To learn more about VPCs and subnets, check out the Gruntwork [`vpc service`](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/vpc). + +## Load balancers + +Traffic from the public Internet (e.g., requests from your users) initially goes to a public load balancer, which proxies the traffic to your apps. Traffic between services that are within your network (e.g. east-west traffic) uses a private load balancer, which is not exposed to the Internet. This topology allows you to run multiple copies of your application for scalability and high availability, while limiting exposure of your services. The Application Load Balancer (ALB) is an AWS-managed load balancer service that is designed for routing HTTP and HTTPS traffic. The advantage of using a managed service is that AWS takes care of fault tolerance, security, and scaling the load balancer for you automatically. + +## Docker clusters + +Application code is packaged into Docker containers and deployed across an Amazon Elastic Container Service (ECS) cluster. The advantage of Docker is that it allows you to package your code so that it runs exactly the same way in all environments (dev, stage, prod). The advantage of a Docker Cluster is that it makes it easy to deploy your Docker containers across a cluster of servers, making efficient use of wherever resources are available. Moreover, ECS can automatically scale your app up and down in response to load and redeploy containers that crashed. + +For a quick intro to Docker, see Running microservices on AWS using Docker, Terraform, and ECS. For more info on using ECS, see terraform-aws-ecs. + +## Data stores + +The infrastructure includes the following data stores: + +1. **Amazon RDS Aurora**: [Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraOverview.html) is Amazon's MySQL- and PostgreSQL-compatible managed relational database engine. Aurora offers advanced features like automatic storage resizing, clustering, and high performance. +1. **Amazon Elasticache for Redis**: [Elasticache for Redis](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) is a managed service for hosting [Redis](https://redis.io/), the in-memory database and cache. Elasticache offers a web interface for managing Redis, with high performance, scalability, and automatic failure detection and recovery. + +## OpenVPN server + +To reduce surface area to attackers, just about all of the resources in this infrastructure run in private subnets, +which are not accessible from the public Internet at all. To allow company employees to access these private resources, +we expose a single server publicly: an [OpenVPN server](https://openvpn.net/). Once you connect to the server using a +VPN client, you are "in the network", and will be able to access the private resources (e.g., you will be able to SSH +to your EC2 Instances). + +For more info, see the [`openvpn` service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/mgmt/openvpn-server) and the VPN +section of the [Authentication docs](02-authenticate/06-authenticate-to-the-vpn-server.md). + +## GitHub + +We have set up [GitHub](https://github.com) as a Continuous Integration (CI) server. After every commit, a GitHub +job runs your build, tests, packaging, and automated deployment steps. + +For more info, see the [Gruntwork Pipelines docs](04-configure-gw-pipelines/01-intro.md). + +## Monitoring, log aggregation, alerting + +You can find metrics, log files from all your servers, and subscribe to alert notifications using [Amazon +CloudWatch](https://aws.amazon.com/cloudwatch/). + +For more info, see the [Monitoring, Alerting, and Logging docs](05-monitoring-alerting-logging/01-intro.md). + +## DNS and TLS + +We are using [Amazon Route 53](https://aws.amazon.com/route53/) to configure DNS entries for all services. We +have configured SSL/TLS certificates for your domain names using [Amazon's Certificate Manager +(ACM)](https://aws.amazon.com/certificate-manager/), which issues certificates that are free and renew automatically. + +For more info, see the [route53 service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/route53). + +## Security + +We have configured security best practices in every aspect of this infrastructure: + +- **Network security**: see [VPCs and subnets](#vpcs-and-subnets). + +- **Server access**: see SSH and VPN sections of the [Authentication docs](02-authenticate/01-intro.md). + +- **Application secrets**: see secrets management section of the [Deploy your Apps docs](03-deploy-apps/01-intro.md). + +- **User accounts**: see the [Authentication docs](02-authenticate/02-setting-up-initial-access.md). + +- **Auditing**: see the [CloudTrail](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/cloudtrail) and + [AWS Config](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/aws-config) modules. + +- **Intrusion detection**: see the [`fail2ban`](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/fail2ban) + and [GuardDuty](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/guardduty-multi-region) modules. + +- **Security updates**: see the [`auto-update` module](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/auto-update). + +Check out [Gruntwork Security Best +Practices](https://docs.google.com/document/d/e/2PACX-1vTikva7hXPd2h1SSglJWhlW8W6qhMlZUxl0qQ9rUJ0OX22CQNeM-91w4lStRk9u2zQIn6lPejUbe-dl/pub) +for more info. + +## Next steps + +Next up, let's have a look at [how to authenticate](02-authenticate/01-intro.md). diff --git a/_docs-sources/guides/reference-architecture/index.md b/_docs-sources/guides/reference-architecture/index.md index 876ff2c405..b9313d151e 100644 --- a/_docs-sources/guides/reference-architecture/index.md +++ b/_docs-sources/guides/reference-architecture/index.md @@ -1,158 +1,23 @@ ---- -pagination_label: Reference Architecture ---- +import Card from "/src/components/Card" +import CardGroup from "/src/components/CardGroup" -# Setting Up Your Reference Architecture +# The Gruntwork Reference Architecture -This documentation contains an overview of a deployed and managed architecture. +The Reference Architecture is an opinionated, battle-tested, best-practices way to assemble the code from the Infrastructure as Code Library into an end-to-end tech stack that includes just about everything you need: server cluster, load balancer, database, cache, network topology, monitoring, alerting, CI/CD, secrets management, VPN, and more. We generate the Reference Architecture based on your needs, deploy into your AWS accounts, and give you 100% of the code. -First, the short version: +If you've purchased a Reference Architecture, these guides will help guide you through the process of choosing your configuration as well as deploying your apps and services. If you haven't but would like to, contact [sales@gruntwork.io](mailto:sales@gruntwork.io). -- This is an end-to-end tech stack for [Amazon Web Services (AWS)](https://aws.amazon.com/) that includes all the - basic infrastructure a company needs, including the network topology, orchestration tools (e.g., Kubernetes or ECS), databases, caches, load balancers, CI / CD pipeline, monitoring, alerting, log aggregation, etc.- It's built on top of the [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog). -- It's all defined and managed as code using tools such as [Terraform](https://www.terraform.io/), [Packer](https://www.packer.io/), and [Docker](https://www.docker.com/). + -Here's a diagram that shows a rough overview of what the Reference Architecture looks like: + +Learn how to configure your Reference Architecture so Gruntwork can deliver it directly into your repo. + + +See a preview of how to use your customized Reference Architecture once we've delivered it in your repo. + -![Architecture Diagram](/img/guides/reference-architecture/landing-zone-ref-arch.png) - -Now, the long version: - -## Infrastructure as code - -All of the infrastructure in this repo is managed as **code** using [Terragrunt](https://terragrunt.gruntwork.io/), a thin wrapper around [Terraform](https://www.terraform.io). That is, instead of clicking around a web UI or SSHing to a server and manually executing commands, the idea behind infrastructure as code (IAC) is that you write code to define your infrastructure and you let an automated tool (e.g., Terraform) apply the code changes to your infrastructure. This has a number of benefits: - -- You can automate your entire provisioning and deployment process, which makes it much faster and more reliable than - any manual process. - -- You can represent the state of your infrastructure in source files that anyone can read, rather than having that knowledge trapped inside a sysadmin's head. - -- You can store those source files in version control, which means the entire history of your infrastructure is - captured in the commit log, which you can use to debug problems, and if necessary, roll back to older versions. - -- You can validate each infrastructure change through code reviews and automated tests. - -- You can package your infrastructure as reusable, documented, battle-tested modules that make it easier to scale and - evolve your infrastructure. In fact, most of the infrastructure code in this architecture is deployed from the service modules in the - [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog/). - -For more info on Infrastructure as Code and Terraform, check out [A Comprehensive Guide to -Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca) and our our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) section. - -## AWS accounts - -The infrastructure is deployed across multiple AWS accounts. For example, the staging environment is in one account, -the production environment in another account, shared tooling is in yet another account, and so on. This gives you -better isolation between environments so that if you break something in one environment (e.g., staging)—or worse yet, a -hacker breaks into that environment—it should have no effect on your other environments (e.g., prod). It also gives you -better control over what resources each employee can access, helps you to keep track of costs, and gives you an easy way to test out new features and services in isolation. - -The list of accounts includes: - -- **dev**: Sandbox environment. -- **stage**: Pre-production environment. -- **prod**: Production environment. -- **security**: All IAM users and permissions are defined in this account. -- **shared-services**: DevOps tooling. -- **logs**: An account for centralizing logs from all of the accounts. - -Check out the [Authentication docs](02-authenticate/01-intro.md) for more info on how to authenticate to these accounts and -switch between them. - -## VPCs and subnets - -Each environment lives in a separate [Virtual Private Cloud (VPC)](https://aws.amazon.com/vpc/), which is a logically -isolated section within an AWS account. Each VPC defines a virtual network, with its own IP address space and rules for -what can go in and out of that network. The IP addresses within each VPC are further divided into multiple -[subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html), where each subnet controls the -routing for its IP address. - -- _Public subnets_ are directly accessible from the public Internet. -- _Private subnets_ are only accessible from within the VPC. - -Just about everything in this infrastructure is deployed in private subnets to reduce the surface area to attackers. -The only exceptions are load balancers and the [OpenVPN server](#openvpn-server), both of which are described below. - -Each VPC is also configured with [VPC flow logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html), which -can be useful for monitoring and auditing network traffic across the VPC. Each VPC publishes its flow logs to CloudWatch -Logs, under the log group `VPC_NAME-vpc-flow-logs`, where the `VPC_NAME` is an input variable to the `vpc` module. - -To learn more about VPCs and subnets, check out the Gruntwork [`vpc service`](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/vpc). - -## Load balancers - -Traffic from the public Internet (e.g., requests from your users) initially goes to a public load balancer, which proxies the traffic to your apps. Traffic between services that are within your network (e.g. east-west traffic) uses a private load balancer, which is not exposed to the Internet. This topology allows you to run multiple copies of your application for scalability and high availability, while limiting exposure of your services. The Application Load Balancer (ALB) is an AWS-managed load balancer service that is designed for routing HTTP and HTTPS traffic. The advantage of using a managed service is that AWS takes care of fault tolerance, security, and scaling the load balancer for you automatically. - -## Docker clusters - -Application code is packaged into Docker containers and deployed across an Amazon Elastic Container Service (ECS) cluster. The advantage of Docker is that it allows you to package your code so that it runs exactly the same way in all environments (dev, stage, prod). The advantage of a Docker Cluster is that it makes it easy to deploy your Docker containers across a cluster of servers, making efficient use of wherever resources are available. Moreover, ECS can automatically scale your app up and down in response to load and redeploy containers that crashed. - -For a quick intro to Docker, see Running microservices on AWS using Docker, Terraform, and ECS. For more info on using ECS, see terraform-aws-ecs. - -## Data stores - -The infrastructure includes the following data stores: - -1. **Amazon RDS Aurora**: [Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraOverview.html) is Amazon's MySQL- and PostgreSQL-compatible managed relational database engine. Aurora offers advanced features like automatic storage resizing, clustering, and high performance. -1. **Amazon Elasticache for Redis**: [Elasticache for Redis](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) is a managed service for hosting [Redis](https://redis.io/), the in-memory database and cache. Elasticache offers a web interface for managing Redis, with high performance, scalability, and automatic failure detection and recovery. - -## OpenVPN server - -To reduce surface area to attackers, just about all of the resources in this infrastructure run in private subnets, -which are not accessible from the public Internet at all. To allow company employees to access these private resources, -we expose a single server publicly: an [OpenVPN server](https://openvpn.net/). Once you connect to the server using a -VPN client, you are "in the network", and will be able to access the private resources (e.g., you will be able to SSH -to your EC2 Instances). - -For more info, see the [`openvpn` service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/mgmt/openvpn-server) and the VPN -section of the [Authentication docs](02-authenticate/06-authenticate-to-the-vpn-server.md). - -## GitHub - -We have set up [GitHub](https://github.com) as a Continuous Integration (CI) server. After every commit, a GitHub -job runs your build, tests, packaging, and automated deployment steps. - -For more info, see the [Gruntwork Pipelines docs](04-configure-gw-pipelines/01-intro.md). - -## Monitoring, log aggregation, alerting - -You can find metrics, log files from all your servers, and subscribe to alert notifications using [Amazon -CloudWatch](https://aws.amazon.com/cloudwatch/). - -For more info, see the [Monitoring, Alerting, and Logging docs](05-monitoring-alerting-logging/01-intro.md). - -## DNS and TLS - -We are using [Amazon Route 53](https://aws.amazon.com/route53/) to configure DNS entries for all services. We -have configured SSL/TLS certificates for your domain names using [Amazon's Certificate Manager -(ACM)](https://aws.amazon.com/certificate-manager/), which issues certificates that are free and renew automatically. - -For more info, see the [route53 service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/route53). - -## Security - -We have configured security best practices in every aspect of this infrastructure: - -- **Network security**: see [VPCs and subnets](#vpcs-and-subnets). - -- **Server access**: see SSH and VPN sections of the [Authentication docs](02-authenticate/01-intro.md). - -- **Application secrets**: see secrets management section of the [Deploy your Apps docs](03-deploy-apps/01-intro.md). - -- **User accounts**: see the [Authentication docs](02-authenticate/02-setting-up-initial-access.md). - -- **Auditing**: see the [CloudTrail](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/cloudtrail) and - [AWS Config](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/aws-config) modules. - -- **Intrusion detection**: see the [`fail2ban`](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/fail2ban) - and [GuardDuty](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/guardduty-multi-region) modules. - -- **Security updates**: see the [`auto-update` module](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/auto-update). - -Check out [Gruntwork Security Best -Practices](https://docs.google.com/document/d/e/2PACX-1vTikva7hXPd2h1SSglJWhlW8W6qhMlZUxl0qQ9rUJ0OX22CQNeM-91w4lStRk9u2zQIn6lPejUbe-dl/pub) -for more info. - -## Next steps - -Next up, let's have a look at [how to authenticate](02-authenticate/01-intro.md). + diff --git a/_docs-sources/guides/stay-up-to-date/index.md b/_docs-sources/guides/stay-up-to-date/index.md new file mode 100644 index 0000000000..ca78ecde50 --- /dev/null +++ b/_docs-sources/guides/stay-up-to-date/index.md @@ -0,0 +1,71 @@ +--- +hide_table_of_contents: true +--- + +import Grid from "/src/components/Grid" +import Card from "/src/components/Card" +import CardGroup from "/src/components/CardGroup" + +# Stay Up To Date + + + + + +## Terraform + + + + + + + + + + + + + + + + + +## CIS AWS Foundations Benchmark + + + + + + + + + + + diff --git a/_docs-sources/guides/style/index.md b/_docs-sources/guides/style/index.md new file mode 100644 index 0000000000..4c73ff15d1 --- /dev/null +++ b/_docs-sources/guides/style/index.md @@ -0,0 +1,19 @@ +import Card from "/src/components/Card" +import CardGroup from "/src/components/CardGroup" + +# Style Guides + + + + +Learn Gruntwork's Terraform coding style. + + +Learn Gruntwork's Go coding style. + + + diff --git a/docs/guides/build-it-yourself/index.md b/docs/guides/build-it-yourself/index.md new file mode 100644 index 0000000000..b4c11810c0 --- /dev/null +++ b/docs/guides/build-it-yourself/index.md @@ -0,0 +1,63 @@ +import Card from "/src/components/Card" +import Grid from "/src/components/Grid" + +# Build Your Own Architecture + +The Gruntwork IaC library empowers you to construct your own bespoke architecture in record time. By mix-and-matching our modules and services you can quickly define a custom architecture to suit your needs, all with the confidence of having world-class, battle-tested code running under the hood. This series of guides aims to teach you how to configure and deploy some of our most popular services. Additional guides will be added over time, but the principles covered extend to the rest of the IaC library. If you have trouble, don’t hesitate to ask questions via our [support channels](/docs/guides/support). + +## Follow Our Deployment Guides + + + + Set up a multi-account structure using Gruntwork Landing Zone. + + + Implement continuous deployment for your infrastructure code with Gruntwork + Pipelines. + + + Set up your network according to industry best practices using our VPC service. + + + Deploy a Kubernetes Cluster to host all of your apps and services. + + + Make your infrastructure compliant with the CIS AWS Foundations Benchmark. + + + +## Dig Into the Code + + + + View the API reference for our entire service catalog to learn what’s + available. + + + If you're the type who likes to jump straight to the source, this is for + you. + + + + + diff --git a/docs/guides/index.md b/docs/guides/index.md index bf323829d2..10506dc68b 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,129 +1,26 @@ ---- -sidebar_label: "Introduction" -sidebar_position": 1 -hide_table_of_contents: true -hide_title: true ---- - import Card from "/src/components/Card" -import Grid from "/src/components/Grid" -import CenterLayout from "/src/components/CenterLayout" - - +import CardGroup from "/src/components/CardGroup" # Gruntwork Guides -As a Gruntwork subscriber, you have two primary ways to engage with our library. Whichever approach you choose, our guides provide step-by-step instructions to help you deploy your infrastructure with confidence. We also offer detailed upgrade guides to ensure that your infrastructure remains up-to-date with the latest security patches, compliance requirements, and DevOps best practices. - - - - Learn how to use and administer a Reference Architecture which Gruntwork has - deployed for you. - - - Learn how to utilize our service modules to construct a world-class - architecture on your own. - - - -## Build Your Own Architecture - -The Gruntwork IaC library empowers you to construct your own bespoke architecture in record time. By mix-and-matching our modules and services you can quickly define a custom architecture to suit your needs, all with the confidence of having world-class, battle-tested code running under the hood. This series of guides aims to teach you how to configure and deploy some of our most popular services. Additional guides will be added over time, but the principles covered extend to the rest of the IaC library. If you have trouble, don’t hesitate to ask questions via our [support channels](/docs/guides/support). - -### Follow Our Step-By-Step Guides - - - - Set up a multi-account structure using Gruntwork Landing Zone. - - - Implement continuous deployment for your infrastructure code with Gruntwork - Pipelines. - - - Set up your network according to industry best practices using our VPC service. - - - Deploy a Kubernetes Cluster to host all of your apps and services. - - - Make your infrastructure compliant with the CIS AWS Foundations Benchmark. - - - -### Dig Into the Code - - - - View the API reference for our entire service catalog to learn what’s - available. - - - If you're the type who likes to jump straight to the source, this is for - you. - - - -## Stay Up to Date - - - - - -### Terraform - -- [Update to version 1.X](/docs/guides/stay-up-to-date/terraform/terraform-1.x) -- [Update to Terraform 15](/docs/guides/stay-up-to-date/terraform/terraform-15) -- [Update to Terraform 14](/docs/guides/stay-up-to-date/terraform/terraform-14) -- [Update to Terraform 13](/docs/guides/stay-up-to-date/terraform/terraform-13) -- [Update to Terraform 12](/docs/guides/stay-up-to-date/terraform/terraform-12) -- [Update to Version 3 of the Terraform provider](/docs/guides/stay-up-to-date/terraform/how-to-update-to-aws-provider-v3) -- [DRY your Reference Architecture](/docs/guides/stay-up-to-date/terraform/how-to-dry-your-reference-architecture) - - - - -### CIS AWS Foundations Benchmark - -- [Update to version 1.4.0](/docs/guides/stay-up-to-date/cis/cis-1.4.0) -- [Update to version 1.3.0](/docs/guides/stay-up-to-date/cis/cis-1.3.0) - - - - +Before you get too deep into the code, it's important to understand Gruntwork's core principles. These guides will give you the necessary background to succeed with your Gruntwork subscription, and provide an essential framework for constructing a world-class DevOps infrastructure. -## Style Guides + -- [Terraform Style Guide](/docs/guides/style/terraform-style-guide) -- [Go Style Guide](/docs/guides/style/golang-style-guide) + +Before anything else, check out our introductory guide to set up your account, prepare your tools, and understand what to expect. + + +We present a comprehensive model to help you establish a robust infrastructure platform, and explain how Gruntwork can accelarate its adoption in your org. + - + diff --git a/docs/guides/reference-architecture/02-authenticate/01-intro.md b/docs/guides/reference-architecture/example-usage-guide/02-authenticate/01-intro.md similarity index 100% rename from docs/guides/reference-architecture/02-authenticate/01-intro.md rename to docs/guides/reference-architecture/example-usage-guide/02-authenticate/01-intro.md diff --git a/docs/guides/reference-architecture/02-authenticate/02-setting-up-initial-access.md b/docs/guides/reference-architecture/example-usage-guide/02-authenticate/02-setting-up-initial-access.md similarity index 100% rename from docs/guides/reference-architecture/02-authenticate/02-setting-up-initial-access.md rename to docs/guides/reference-architecture/example-usage-guide/02-authenticate/02-setting-up-initial-access.md diff --git a/docs/guides/reference-architecture/02-authenticate/03-authenticate-to-the-aws-web-console.md b/docs/guides/reference-architecture/example-usage-guide/02-authenticate/03-authenticate-to-the-aws-web-console.md similarity index 100% rename from docs/guides/reference-architecture/02-authenticate/03-authenticate-to-the-aws-web-console.md rename to docs/guides/reference-architecture/example-usage-guide/02-authenticate/03-authenticate-to-the-aws-web-console.md diff --git a/docs/guides/reference-architecture/02-authenticate/04-authenticate-to-aws-via-the-cli.md b/docs/guides/reference-architecture/example-usage-guide/02-authenticate/04-authenticate-to-aws-via-the-cli.md similarity index 100% rename from docs/guides/reference-architecture/02-authenticate/04-authenticate-to-aws-via-the-cli.md rename to docs/guides/reference-architecture/example-usage-guide/02-authenticate/04-authenticate-to-aws-via-the-cli.md diff --git a/docs/guides/reference-architecture/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md b/docs/guides/reference-architecture/example-usage-guide/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md similarity index 100% rename from docs/guides/reference-architecture/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md rename to docs/guides/reference-architecture/example-usage-guide/02-authenticate/05-authenticate-to-ec2-instances-via-ssh.md diff --git a/docs/guides/reference-architecture/02-authenticate/06-authenticate-to-the-vpn-server.md b/docs/guides/reference-architecture/example-usage-guide/02-authenticate/06-authenticate-to-the-vpn-server.md similarity index 100% rename from docs/guides/reference-architecture/02-authenticate/06-authenticate-to-the-vpn-server.md rename to docs/guides/reference-architecture/example-usage-guide/02-authenticate/06-authenticate-to-the-vpn-server.md diff --git a/docs/guides/reference-architecture/03-deploy-apps/01-intro.md b/docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/01-intro.md similarity index 100% rename from docs/guides/reference-architecture/03-deploy-apps/01-intro.md rename to docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/01-intro.md diff --git a/docs/guides/reference-architecture/03-deploy-apps/02-what-is-already-deployed.md b/docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/02-what-is-already-deployed.md similarity index 100% rename from docs/guides/reference-architecture/03-deploy-apps/02-what-is-already-deployed.md rename to docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/02-what-is-already-deployed.md diff --git a/docs/guides/reference-architecture/03-deploy-apps/03-the-app.md b/docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/03-the-app.md similarity index 100% rename from docs/guides/reference-architecture/03-deploy-apps/03-the-app.md rename to docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/03-the-app.md diff --git a/docs/guides/reference-architecture/03-deploy-apps/04-dockerizing.md b/docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/04-dockerizing.md similarity index 100% rename from docs/guides/reference-architecture/03-deploy-apps/04-dockerizing.md rename to docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/04-dockerizing.md diff --git a/docs/guides/reference-architecture/03-deploy-apps/05-publish-docker-image.md b/docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/05-publish-docker-image.md similarity index 100% rename from docs/guides/reference-architecture/03-deploy-apps/05-publish-docker-image.md rename to docs/guides/reference-architecture/example-usage-guide/03-deploy-apps/05-publish-docker-image.md diff --git a/docs/guides/reference-architecture/04-configure-gw-pipelines/01-intro.md b/docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/01-intro.md similarity index 100% rename from docs/guides/reference-architecture/04-configure-gw-pipelines/01-intro.md rename to docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/01-intro.md diff --git a/docs/guides/reference-architecture/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md b/docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md similarity index 86% rename from docs/guides/reference-architecture/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md rename to docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md index 640a626d3f..429f48d33d 100644 --- a/docs/guides/reference-architecture/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md +++ b/docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/02-ci--cd-pipeline-for-infrastructure-code.md @@ -2,7 +2,7 @@ This diagram shows a rough overview of the Gruntwork Pipelines architecture: -![Architecture Diagram](/img/guides/reference-architecture/gruntwork-pipelines-architecture.png) +![Architecture Diagram](/img/guides/reference-architecture/example-usage-guide/gruntwork-pipelines-architecture.png) The Gruntwork Pipelines workflow, defined in [`.github/workflows/pipelines.yml`](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/.github/workflows/pipelines.yml), works like this: @@ -34,23 +34,23 @@ If you'd like to send Slack notifications when the pipeline is running, follow t 1. In Slack, open the Workflow builder: - ![Slack Workflow Builder](/img/guides/reference-architecture/slack-workflow-1.png) + ![Slack Workflow Builder](/img/guides/reference-architecture/example-usage-guide/slack-workflow-1.png) 1. Create a new Webhook workflow called "Gruntwork Pipelines" - ![Slack Webhook workflow](/img/guides/reference-architecture/slack-workflow-2.png) + ![Slack Webhook workflow](/img/guides/reference-architecture/example-usage-guide/slack-workflow-2.png) 1. Add the following text variables to the workflow: `branch`, `status`, `url`, `repo`, and `actor` - ![Slack workflow variables](/img/guides/reference-architecture/slack-workflow-3.png) + ![Slack workflow variables](/img/guides/reference-architecture/example-usage-guide/slack-workflow-3.png) 1. Once all of the variables are added, click Next. 1. Now add another step to the workflow - ![Slack workflow add step](/img/guides/reference-architecture/slack-workflow-4.png) + ![Slack workflow add step](/img/guides/reference-architecture/example-usage-guide/slack-workflow-4.png) -1. Add the "Send a message" step +1. Add the "Send a message" step 1. Choose a channel from the dropdown menu @@ -72,7 +72,7 @@ If you'd like to send Slack notifications when the pipeline is running, follow t 1. Copy the webhook URL and save it. We will use this value below. - ![Slack workflow add step](/img/guides/reference-architecture/slack-workflow-5.png) + ![Slack workflow add step](/img/guides/reference-architecture/example-usage-guide/slack-workflow-5.png) 1. Note that the webhook URL should be treated as sensitive. Anyone with the URL can send HTTP requests to the webhook! @@ -80,12 +80,12 @@ If you'd like to send Slack notifications when the pipeline is running, follow t 1. Open the GitHub repository and navigate to Settings => Secrets. - ![GitHub Secrets](/img/guides/reference-architecture/secrets.png) + ![GitHub Secrets](/img/guides/reference-architecture/example-usage-guide/secrets.png) 1. Create the following repository secrets: -- `AWS_ACCESS_KEY_ID`: This is the first value from the AWS IAM user step above. -- `AWS_SECRET_ACCESS_KEY`: This is the second value from the AWS IAM user step above. +- `AWS_ACCESS_KEY_ID`: This is the first value from the AWS IAM user step above. +- `AWS_SECRET_ACCESS_KEY`: This is the second value from the AWS IAM user step above. - `GH_TOKEN`: Enter the GitHub machine user's oauth token here. If you don't know this, you can find it in the AWS Secrets Manager secret that you provided in the [`reference-architecture-form.yml`](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/examples/for-production/infrastructure-live/reference-architecture-form.yml). - `SLACK_WEBHOOK_URL`: This is the value from the Slack Workflow step above. @@ -99,5 +99,5 @@ For instructions on how to destroy infrastructure, see the [Undeploy guide](../0 diff --git a/docs/guides/reference-architecture/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md b/docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md similarity index 100% rename from docs/guides/reference-architecture/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md rename to docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/03-ci--cd-pipeline-for-app-code.md diff --git a/docs/guides/reference-architecture/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md b/docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md similarity index 100% rename from docs/guides/reference-architecture/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md rename to docs/guides/reference-architecture/example-usage-guide/04-configure-gw-pipelines/04-update-the-ci--cd-pipeline-itself.md diff --git a/docs/guides/reference-architecture/05-monitoring-alerting-logging/01-intro.md b/docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/01-intro.md similarity index 100% rename from docs/guides/reference-architecture/05-monitoring-alerting-logging/01-intro.md rename to docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/01-intro.md diff --git a/docs/guides/reference-architecture/05-monitoring-alerting-logging/02-metrics.md b/docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/02-metrics.md similarity index 100% rename from docs/guides/reference-architecture/05-monitoring-alerting-logging/02-metrics.md rename to docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/02-metrics.md diff --git a/docs/guides/reference-architecture/05-monitoring-alerting-logging/03-alerts.md b/docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/03-alerts.md similarity index 100% rename from docs/guides/reference-architecture/05-monitoring-alerting-logging/03-alerts.md rename to docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/03-alerts.md diff --git a/docs/guides/reference-architecture/05-monitoring-alerting-logging/04-logs.md b/docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/04-logs.md similarity index 100% rename from docs/guides/reference-architecture/05-monitoring-alerting-logging/04-logs.md rename to docs/guides/reference-architecture/example-usage-guide/05-monitoring-alerting-logging/04-logs.md diff --git a/docs/guides/reference-architecture/06-adding-a-new-account/01-intro.md b/docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/01-intro.md similarity index 100% rename from docs/guides/reference-architecture/06-adding-a-new-account/01-intro.md rename to docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/01-intro.md diff --git a/docs/guides/reference-architecture/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md b/docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md similarity index 100% rename from docs/guides/reference-architecture/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md rename to docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/02-create-new-account-in-your-aws-org.md diff --git a/docs/guides/reference-architecture/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md b/docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md similarity index 100% rename from docs/guides/reference-architecture/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md rename to docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/03-update-logs-security-shared-accounts-to-allow-cross-account-access.md diff --git a/docs/guides/reference-architecture/06-adding-a-new-account/04-deploy-the-security-baseline.md b/docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/04-deploy-the-security-baseline.md similarity index 100% rename from docs/guides/reference-architecture/06-adding-a-new-account/04-deploy-the-security-baseline.md rename to docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/04-deploy-the-security-baseline.md diff --git a/docs/guides/reference-architecture/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md b/docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md similarity index 100% rename from docs/guides/reference-architecture/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md rename to docs/guides/reference-architecture/example-usage-guide/06-adding-a-new-account/05-deploy-the-ecs-deploy-runner.md diff --git a/docs/guides/reference-architecture/07-undeploy/01-intro.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/01-intro.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/01-intro.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/01-intro.md diff --git a/docs/guides/reference-architecture/07-undeploy/02-before-you-get-started.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/02-before-you-get-started.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/02-before-you-get-started.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/02-before-you-get-started.md diff --git a/docs/guides/reference-architecture/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/03-pre-requisite-force-destroy-on-s3-buckets.md diff --git a/docs/guides/reference-architecture/07-undeploy/04-pre-requisite-understand-module-dependencies.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/04-pre-requisite-understand-module-dependencies.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/04-pre-requisite-understand-module-dependencies.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/04-pre-requisite-understand-module-dependencies.md diff --git a/docs/guides/reference-architecture/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/05-undeploying-modules-using-gruntwork-pipelines.md diff --git a/docs/guides/reference-architecture/07-undeploy/06-manually-undeploying-a-single-module.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/06-manually-undeploying-a-single-module.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/06-manually-undeploying-a-single-module.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/06-manually-undeploying-a-single-module.md diff --git a/docs/guides/reference-architecture/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/07-manually-undeploying-multiple-modules-or-an-entire-environment.md diff --git a/docs/guides/reference-architecture/07-undeploy/08-removing-the-terraform-state.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/08-removing-the-terraform-state.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/08-removing-the-terraform-state.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/08-removing-the-terraform-state.md diff --git a/docs/guides/reference-architecture/07-undeploy/09-useful-tips.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/09-useful-tips.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/09-useful-tips.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/09-useful-tips.md diff --git a/docs/guides/reference-architecture/07-undeploy/10-known-errors.md b/docs/guides/reference-architecture/example-usage-guide/07-undeploy/10-known-errors.md similarity index 100% rename from docs/guides/reference-architecture/07-undeploy/10-known-errors.md rename to docs/guides/reference-architecture/example-usage-guide/07-undeploy/10-known-errors.md diff --git a/docs/guides/reference-architecture/example-usage-guide/index.md b/docs/guides/reference-architecture/example-usage-guide/index.md new file mode 100644 index 0000000000..bae91af76d --- /dev/null +++ b/docs/guides/reference-architecture/example-usage-guide/index.md @@ -0,0 +1,165 @@ +# Example Reference Architecture Usage Guide + +:::caution + +This guide presents example usage for a _specific_ Reference Architecture configuration with ASG, Aurora, and GitHub CI. Once you purchase a Reference Architecture, you'll receive documentation customized to your chosen configuration in your own repo. + +::: + +This documentation contains an overview of a deployed and managed architecture. + +First, the short version: + +- This is an end-to-end tech stack for [Amazon Web Services (AWS)](https://aws.amazon.com/) that includes all the + basic infrastructure a company needs, including the network topology, orchestration tools (e.g., Kubernetes or ECS), databases, caches, load balancers, CI / CD pipeline, monitoring, alerting, log aggregation, etc.- It's built on top of the [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog). +- It's all defined and managed as code using tools such as [Terraform](https://www.terraform.io/), [Packer](https://www.packer.io/), and [Docker](https://www.docker.com/). + +Here's a diagram that shows a rough overview of what the Reference Architecture looks like: + +![Architecture Diagram](/img/guides/reference-architecture/example-usage-guide/landing-zone-ref-arch.png) + +Now, the long version: + +## Infrastructure as code + +All of the infrastructure in this repo is managed as **code** using [Terragrunt](https://terragrunt.gruntwork.io/), a thin wrapper around [Terraform](https://www.terraform.io). That is, instead of clicking around a web UI or SSHing to a server and manually executing commands, the idea behind infrastructure as code (IAC) is that you write code to define your infrastructure and you let an automated tool (e.g., Terraform) apply the code changes to your infrastructure. This has a number of benefits: + +- You can automate your entire provisioning and deployment process, which makes it much faster and more reliable than + any manual process. + +- You can represent the state of your infrastructure in source files that anyone can read, rather than having that knowledge trapped inside a sysadmin's head. + +- You can store those source files in version control, which means the entire history of your infrastructure is + captured in the commit log, which you can use to debug problems, and if necessary, roll back to older versions. + +- You can validate each infrastructure change through code reviews and automated tests. + +- You can package your infrastructure as reusable, documented, battle-tested modules that make it easier to scale and + evolve your infrastructure. In fact, most of the infrastructure code in this architecture is deployed from the service modules in the + [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog/). + +For more info on Infrastructure as Code and Terraform, check out [A Comprehensive Guide to +Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca) and our our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) section. + +## AWS accounts + +The infrastructure is deployed across multiple AWS accounts. For example, the staging environment is in one account, +the production environment in another account, shared tooling is in yet another account, and so on. This gives you +better isolation between environments so that if you break something in one environment (e.g., staging)—or worse yet, a +hacker breaks into that environment—it should have no effect on your other environments (e.g., prod). It also gives you +better control over what resources each employee can access, helps you to keep track of costs, and gives you an easy way to test out new features and services in isolation. + +The list of accounts includes: + +- **dev**: Sandbox environment. +- **stage**: Pre-production environment. +- **prod**: Production environment. +- **security**: All IAM users and permissions are defined in this account. +- **shared-services**: DevOps tooling. +- **logs**: An account for centralizing logs from all of the accounts. + +Check out the [Authentication docs](02-authenticate/01-intro.md) for more info on how to authenticate to these accounts and +switch between them. + +## VPCs and subnets + +Each environment lives in a separate [Virtual Private Cloud (VPC)](https://aws.amazon.com/vpc/), which is a logically +isolated section within an AWS account. Each VPC defines a virtual network, with its own IP address space and rules for +what can go in and out of that network. The IP addresses within each VPC are further divided into multiple +[subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html), where each subnet controls the +routing for its IP address. + +- _Public subnets_ are directly accessible from the public Internet. +- _Private subnets_ are only accessible from within the VPC. + +Just about everything in this infrastructure is deployed in private subnets to reduce the surface area to attackers. +The only exceptions are load balancers and the [OpenVPN server](#openvpn-server), both of which are described below. + +Each VPC is also configured with [VPC flow logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html), which +can be useful for monitoring and auditing network traffic across the VPC. Each VPC publishes its flow logs to CloudWatch +Logs, under the log group `VPC_NAME-vpc-flow-logs`, where the `VPC_NAME` is an input variable to the `vpc` module. + +To learn more about VPCs and subnets, check out the Gruntwork [`vpc service`](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/vpc). + +## Load balancers + +Traffic from the public Internet (e.g., requests from your users) initially goes to a public load balancer, which proxies the traffic to your apps. Traffic between services that are within your network (e.g. east-west traffic) uses a private load balancer, which is not exposed to the Internet. This topology allows you to run multiple copies of your application for scalability and high availability, while limiting exposure of your services. The Application Load Balancer (ALB) is an AWS-managed load balancer service that is designed for routing HTTP and HTTPS traffic. The advantage of using a managed service is that AWS takes care of fault tolerance, security, and scaling the load balancer for you automatically. + +## Docker clusters + +Application code is packaged into Docker containers and deployed across an Amazon Elastic Container Service (ECS) cluster. The advantage of Docker is that it allows you to package your code so that it runs exactly the same way in all environments (dev, stage, prod). The advantage of a Docker Cluster is that it makes it easy to deploy your Docker containers across a cluster of servers, making efficient use of wherever resources are available. Moreover, ECS can automatically scale your app up and down in response to load and redeploy containers that crashed. + +For a quick intro to Docker, see Running microservices on AWS using Docker, Terraform, and ECS. For more info on using ECS, see terraform-aws-ecs. + +## Data stores + +The infrastructure includes the following data stores: + +1. **Amazon RDS Aurora**: [Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraOverview.html) is Amazon's MySQL- and PostgreSQL-compatible managed relational database engine. Aurora offers advanced features like automatic storage resizing, clustering, and high performance. +1. **Amazon Elasticache for Redis**: [Elasticache for Redis](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) is a managed service for hosting [Redis](https://redis.io/), the in-memory database and cache. Elasticache offers a web interface for managing Redis, with high performance, scalability, and automatic failure detection and recovery. + +## OpenVPN server + +To reduce surface area to attackers, just about all of the resources in this infrastructure run in private subnets, +which are not accessible from the public Internet at all. To allow company employees to access these private resources, +we expose a single server publicly: an [OpenVPN server](https://openvpn.net/). Once you connect to the server using a +VPN client, you are "in the network", and will be able to access the private resources (e.g., you will be able to SSH +to your EC2 Instances). + +For more info, see the [`openvpn` service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/mgmt/openvpn-server) and the VPN +section of the [Authentication docs](02-authenticate/06-authenticate-to-the-vpn-server.md). + +## GitHub + +We have set up [GitHub](https://github.com) as a Continuous Integration (CI) server. After every commit, a GitHub +job runs your build, tests, packaging, and automated deployment steps. + +For more info, see the [Gruntwork Pipelines docs](04-configure-gw-pipelines/01-intro.md). + +## Monitoring, log aggregation, alerting + +You can find metrics, log files from all your servers, and subscribe to alert notifications using [Amazon +CloudWatch](https://aws.amazon.com/cloudwatch/). + +For more info, see the [Monitoring, Alerting, and Logging docs](05-monitoring-alerting-logging/01-intro.md). + +## DNS and TLS + +We are using [Amazon Route 53](https://aws.amazon.com/route53/) to configure DNS entries for all services. We +have configured SSL/TLS certificates for your domain names using [Amazon's Certificate Manager +(ACM)](https://aws.amazon.com/certificate-manager/), which issues certificates that are free and renew automatically. + +For more info, see the [route53 service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/route53). + +## Security + +We have configured security best practices in every aspect of this infrastructure: + +- **Network security**: see [VPCs and subnets](#vpcs-and-subnets). + +- **Server access**: see SSH and VPN sections of the [Authentication docs](02-authenticate/01-intro.md). + +- **Application secrets**: see secrets management section of the [Deploy your Apps docs](03-deploy-apps/01-intro.md). + +- **User accounts**: see the [Authentication docs](02-authenticate/02-setting-up-initial-access.md). + +- **Auditing**: see the [CloudTrail](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/cloudtrail) and + [AWS Config](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/aws-config) modules. + +- **Intrusion detection**: see the [`fail2ban`](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/fail2ban) + and [GuardDuty](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/guardduty-multi-region) modules. + +- **Security updates**: see the [`auto-update` module](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/auto-update). + +Check out [Gruntwork Security Best +Practices](https://docs.google.com/document/d/e/2PACX-1vTikva7hXPd2h1SSglJWhlW8W6qhMlZUxl0qQ9rUJ0OX22CQNeM-91w4lStRk9u2zQIn6lPejUbe-dl/pub) +for more info. + +## Next steps + +Next up, let's have a look at [how to authenticate](02-authenticate/01-intro.md). + + + diff --git a/docs/guides/reference-architecture/index.md b/docs/guides/reference-architecture/index.md index b227eb07a6..fcbc039e9e 100644 --- a/docs/guides/reference-architecture/index.md +++ b/docs/guides/reference-architecture/index.md @@ -1,163 +1,28 @@ ---- -pagination_label: Reference Architecture ---- +import Card from "/src/components/Card" +import CardGroup from "/src/components/CardGroup" -# Setting Up Your Reference Architecture +# The Gruntwork Reference Architecture -This documentation contains an overview of a deployed and managed architecture. +The Reference Architecture is an opinionated, battle-tested, best-practices way to assemble the code from the Infrastructure as Code Library into an end-to-end tech stack that includes just about everything you need: server cluster, load balancer, database, cache, network topology, monitoring, alerting, CI/CD, secrets management, VPN, and more. We generate the Reference Architecture based on your needs, deploy into your AWS accounts, and give you 100% of the code. -First, the short version: +If you've purchased a Reference Architecture, these guides will help guide you through the process of choosing your configuration as well as deploying your apps and services. If you haven't but would like to, contact [sales@gruntwork.io](mailto:sales@gruntwork.io). -- This is an end-to-end tech stack for [Amazon Web Services (AWS)](https://aws.amazon.com/) that includes all the - basic infrastructure a company needs, including the network topology, orchestration tools (e.g., Kubernetes or ECS), databases, caches, load balancers, CI / CD pipeline, monitoring, alerting, log aggregation, etc.- It's built on top of the [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog). -- It's all defined and managed as code using tools such as [Terraform](https://www.terraform.io/), [Packer](https://www.packer.io/), and [Docker](https://www.docker.com/). + -Here's a diagram that shows a rough overview of what the Reference Architecture looks like: + +Learn how to configure your Reference Architecture so Gruntwork can deliver it directly into your repo. + + +See a preview of how to use your customized Reference Architecture once we've delivered it in your repo. + -![Architecture Diagram](/img/guides/reference-architecture/landing-zone-ref-arch.png) - -Now, the long version: - -## Infrastructure as code - -All of the infrastructure in this repo is managed as **code** using [Terragrunt](https://terragrunt.gruntwork.io/), a thin wrapper around [Terraform](https://www.terraform.io). That is, instead of clicking around a web UI or SSHing to a server and manually executing commands, the idea behind infrastructure as code (IAC) is that you write code to define your infrastructure and you let an automated tool (e.g., Terraform) apply the code changes to your infrastructure. This has a number of benefits: - -- You can automate your entire provisioning and deployment process, which makes it much faster and more reliable than - any manual process. - -- You can represent the state of your infrastructure in source files that anyone can read, rather than having that knowledge trapped inside a sysadmin's head. - -- You can store those source files in version control, which means the entire history of your infrastructure is - captured in the commit log, which you can use to debug problems, and if necessary, roll back to older versions. - -- You can validate each infrastructure change through code reviews and automated tests. - -- You can package your infrastructure as reusable, documented, battle-tested modules that make it easier to scale and - evolve your infrastructure. In fact, most of the infrastructure code in this architecture is deployed from the service modules in the - [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog/). - -For more info on Infrastructure as Code and Terraform, check out [A Comprehensive Guide to -Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca) and our our [Introduction to Gruntwork](/docs/intro/overview/intro-to-gruntwork) section. - -## AWS accounts - -The infrastructure is deployed across multiple AWS accounts. For example, the staging environment is in one account, -the production environment in another account, shared tooling is in yet another account, and so on. This gives you -better isolation between environments so that if you break something in one environment (e.g., staging)—or worse yet, a -hacker breaks into that environment—it should have no effect on your other environments (e.g., prod). It also gives you -better control over what resources each employee can access, helps you to keep track of costs, and gives you an easy way to test out new features and services in isolation. - -The list of accounts includes: - -- **dev**: Sandbox environment. -- **stage**: Pre-production environment. -- **prod**: Production environment. -- **security**: All IAM users and permissions are defined in this account. -- **shared-services**: DevOps tooling. -- **logs**: An account for centralizing logs from all of the accounts. - -Check out the [Authentication docs](02-authenticate/01-intro.md) for more info on how to authenticate to these accounts and -switch between them. - -## VPCs and subnets - -Each environment lives in a separate [Virtual Private Cloud (VPC)](https://aws.amazon.com/vpc/), which is a logically -isolated section within an AWS account. Each VPC defines a virtual network, with its own IP address space and rules for -what can go in and out of that network. The IP addresses within each VPC are further divided into multiple -[subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html), where each subnet controls the -routing for its IP address. - -- _Public subnets_ are directly accessible from the public Internet. -- _Private subnets_ are only accessible from within the VPC. - -Just about everything in this infrastructure is deployed in private subnets to reduce the surface area to attackers. -The only exceptions are load balancers and the [OpenVPN server](#openvpn-server), both of which are described below. - -Each VPC is also configured with [VPC flow logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html), which -can be useful for monitoring and auditing network traffic across the VPC. Each VPC publishes its flow logs to CloudWatch -Logs, under the log group `VPC_NAME-vpc-flow-logs`, where the `VPC_NAME` is an input variable to the `vpc` module. - -To learn more about VPCs and subnets, check out the Gruntwork [`vpc service`](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/vpc). - -## Load balancers - -Traffic from the public Internet (e.g., requests from your users) initially goes to a public load balancer, which proxies the traffic to your apps. Traffic between services that are within your network (e.g. east-west traffic) uses a private load balancer, which is not exposed to the Internet. This topology allows you to run multiple copies of your application for scalability and high availability, while limiting exposure of your services. The Application Load Balancer (ALB) is an AWS-managed load balancer service that is designed for routing HTTP and HTTPS traffic. The advantage of using a managed service is that AWS takes care of fault tolerance, security, and scaling the load balancer for you automatically. - -## Docker clusters - -Application code is packaged into Docker containers and deployed across an Amazon Elastic Container Service (ECS) cluster. The advantage of Docker is that it allows you to package your code so that it runs exactly the same way in all environments (dev, stage, prod). The advantage of a Docker Cluster is that it makes it easy to deploy your Docker containers across a cluster of servers, making efficient use of wherever resources are available. Moreover, ECS can automatically scale your app up and down in response to load and redeploy containers that crashed. - -For a quick intro to Docker, see Running microservices on AWS using Docker, Terraform, and ECS. For more info on using ECS, see terraform-aws-ecs. - -## Data stores - -The infrastructure includes the following data stores: - -1. **Amazon RDS Aurora**: [Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraOverview.html) is Amazon's MySQL- and PostgreSQL-compatible managed relational database engine. Aurora offers advanced features like automatic storage resizing, clustering, and high performance. -1. **Amazon Elasticache for Redis**: [Elasticache for Redis](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) is a managed service for hosting [Redis](https://redis.io/), the in-memory database and cache. Elasticache offers a web interface for managing Redis, with high performance, scalability, and automatic failure detection and recovery. - -## OpenVPN server - -To reduce surface area to attackers, just about all of the resources in this infrastructure run in private subnets, -which are not accessible from the public Internet at all. To allow company employees to access these private resources, -we expose a single server publicly: an [OpenVPN server](https://openvpn.net/). Once you connect to the server using a -VPN client, you are "in the network", and will be able to access the private resources (e.g., you will be able to SSH -to your EC2 Instances). - -For more info, see the [`openvpn` service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/mgmt/openvpn-server) and the VPN -section of the [Authentication docs](02-authenticate/06-authenticate-to-the-vpn-server.md). - -## GitHub - -We have set up [GitHub](https://github.com) as a Continuous Integration (CI) server. After every commit, a GitHub -job runs your build, tests, packaging, and automated deployment steps. - -For more info, see the [Gruntwork Pipelines docs](04-configure-gw-pipelines/01-intro.md). - -## Monitoring, log aggregation, alerting - -You can find metrics, log files from all your servers, and subscribe to alert notifications using [Amazon -CloudWatch](https://aws.amazon.com/cloudwatch/). - -For more info, see the [Monitoring, Alerting, and Logging docs](05-monitoring-alerting-logging/01-intro.md). - -## DNS and TLS - -We are using [Amazon Route 53](https://aws.amazon.com/route53/) to configure DNS entries for all services. We -have configured SSL/TLS certificates for your domain names using [Amazon's Certificate Manager -(ACM)](https://aws.amazon.com/certificate-manager/), which issues certificates that are free and renew automatically. - -For more info, see the [route53 service](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/modules/networking/route53). - -## Security - -We have configured security best practices in every aspect of this infrastructure: - -- **Network security**: see [VPCs and subnets](#vpcs-and-subnets). - -- **Server access**: see SSH and VPN sections of the [Authentication docs](02-authenticate/01-intro.md). - -- **Application secrets**: see secrets management section of the [Deploy your Apps docs](03-deploy-apps/01-intro.md). - -- **User accounts**: see the [Authentication docs](02-authenticate/02-setting-up-initial-access.md). - -- **Auditing**: see the [CloudTrail](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/cloudtrail) and - [AWS Config](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/aws-config) modules. - -- **Intrusion detection**: see the [`fail2ban`](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/fail2ban) - and [GuardDuty](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/guardduty-multi-region) modules. - -- **Security updates**: see the [`auto-update` module](https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/auto-update). - -Check out [Gruntwork Security Best -Practices](https://docs.google.com/document/d/e/2PACX-1vTikva7hXPd2h1SSglJWhlW8W6qhMlZUxl0qQ9rUJ0OX22CQNeM-91w4lStRk9u2zQIn6lPejUbe-dl/pub) -for more info. - -## Next steps - -Next up, let's have a look at [how to authenticate](02-authenticate/01-intro.md). + diff --git a/docs/guides/stay-up-to-date/index.md b/docs/guides/stay-up-to-date/index.md new file mode 100644 index 0000000000..048fce3560 --- /dev/null +++ b/docs/guides/stay-up-to-date/index.md @@ -0,0 +1,76 @@ +--- +hide_table_of_contents: true +--- + +import Grid from "/src/components/Grid" +import Card from "/src/components/Card" +import CardGroup from "/src/components/CardGroup" + +# Stay Up To Date + + + + + +## Terraform + + + + + + + + + + + + + + + + + +## CIS AWS Foundations Benchmark + + + + + + + + + + + + + + diff --git a/docs/guides/style/index.md b/docs/guides/style/index.md new file mode 100644 index 0000000000..d77e5786fc --- /dev/null +++ b/docs/guides/style/index.md @@ -0,0 +1,24 @@ +import Card from "/src/components/Card" +import CardGroup from "/src/components/CardGroup" + +# Style Guides + + + + +Learn Gruntwork's Terraform coding style. + + +Learn Gruntwork's Go coding style. + + + + + + diff --git a/sidebars.js b/sidebars.js index f498d862cd..1ad4592dac 100644 --- a/sidebars.js +++ b/sidebars.js @@ -10,8 +10,9 @@ */ const introSidebar = require("./sidebars/intro-guide.js") -const refarchSidebar = require("./sidebars/refarch-guide.js") -const productionFrameworkSidebars = require("./sidebars/production-framework-guide.js") +const guidesSidebar = require("./sidebars/guides-index.js") +const productionFrameworkSidebar = require("./sidebars/production-framework-guide.js") +const refarchUsageSidebar = require("./sidebars/refarch-usage-guide.js") const landingZoneSidebar = require("./sidebars/landing-zone-guide.js") const pipelineSidebar = require("./sidebars/pipelines-guide.js") const vpcSidebar = require("./sidebars/vpc-guide.js") @@ -25,8 +26,9 @@ const apiSidebars = require("./sidebars/api-reference.js") /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { introSidebar, - refarchSidebar, - productionFrameworkSidebars, + guidesSidebar, + productionFrameworkSidebar, + refarchUsageSidebar, landingZoneSidebar, pipelineSidebar, vpcSidebar, diff --git a/sidebars/compliance-guide.js b/sidebars/compliance-guide.js index 237974407c..e570e05d84 100644 --- a/sidebars/compliance-guide.js +++ b/sidebars/compliance-guide.js @@ -1,4 +1,10 @@ const complianceGuide = [ + { + label: "Build Your Own Architecture", + type: "link", + href: "/docs/guides/build-it-yourself", + className: "back-button", + }, { label: "CIS Benchmark Compliance Guide", type: "category", diff --git a/sidebars/guides-index.js b/sidebars/guides-index.js new file mode 100644 index 0000000000..ff6fd02c6d --- /dev/null +++ b/sidebars/guides-index.js @@ -0,0 +1,29 @@ +const guidesIndex = [ + { + label: "Foundations", + type: "doc", + id: "guides/index", + }, + { + label: "Reference Architecture", + type: "doc", + id: "guides/reference-architecture/index", + }, + { + label: "Build Your Own Architecture", + type: "doc", + id: "guides/build-it-yourself/index", + }, + { + label: "Update Guides", + type: "doc", + id: "guides/stay-up-to-date/index", + }, + { + label: "Style Guides", + type: "doc", + id: "guides/style/index", + }, +] + +module.exports = guidesIndex diff --git a/sidebars/kubernetes-guide.js b/sidebars/kubernetes-guide.js index 103f26660c..1acc9eb9e1 100644 --- a/sidebars/kubernetes-guide.js +++ b/sidebars/kubernetes-guide.js @@ -1,4 +1,10 @@ const vpcGuide = [ + { + label: "Build Your Own Architecture", + type: "link", + href: "/docs/guides/build-it-yourself", + className: "back-button", + }, { label: "Kubernetes Guide", type: "category", diff --git a/sidebars/landing-zone-guide.js b/sidebars/landing-zone-guide.js index 99f9724d5c..acaa693a57 100644 --- a/sidebars/landing-zone-guide.js +++ b/sidebars/landing-zone-guide.js @@ -1,4 +1,10 @@ const landingZoneGuide = [ + { + label: "Build Your Own Architecture", + type: "link", + href: "/docs/guides/build-it-yourself", + className: "back-button", + }, { label: "Landing Zone Guide", type: "category", diff --git a/sidebars/pipelines-guide.js b/sidebars/pipelines-guide.js index c9f27da218..5570a28272 100644 --- a/sidebars/pipelines-guide.js +++ b/sidebars/pipelines-guide.js @@ -1,4 +1,10 @@ const pipelineGuide = [ + { + label: "Build Your Own Architecture", + type: "link", + href: "/docs/guides/build-it-yourself", + className: "back-button", + }, { label: "Pipelines Guide", type: "category", diff --git a/sidebars/production-framework-guide.js b/sidebars/production-framework-guide.js index dc97832b76..3baae63b10 100644 --- a/sidebars/production-framework-guide.js +++ b/sidebars/production-framework-guide.js @@ -1,4 +1,4 @@ -const refarchSidebar = [ +const productionFrameworkSidebar = [ { label: "Production Framework Guide", type: "category", @@ -12,96 +12,96 @@ const refarchSidebar = [ type: "category", link: { type: "doc", - id: "guides/production-framework/ingredients/index" + id: "guides/production-framework/ingredients/index", }, items: [ - { - label: "Service Catalog", - type: "category", - link: { - type: "doc", - id: "guides/production-framework/ingredients/service-catalog/index" - }, - items: [ - "guides/production-framework/ingredients/service-catalog/modern-service-catalog", - "guides/production-framework/ingredients/service-catalog/infrastructure-templates", - "guides/production-framework/ingredients/service-catalog/application-templates", - ] - }, - { - label: "Landing Zone", - type: "category", - link: { - type: "doc", - id: "guides/production-framework/ingredients/landing-zone/index" - }, - items: [ - "guides/production-framework/ingredients/landing-zone/what-landing-zone-should-include", - "guides/production-framework/ingredients/landing-zone/account-vending-machine", - ], + { + label: "Service Catalog", + type: "category", + link: { + type: "doc", + id: "guides/production-framework/ingredients/service-catalog/index", }, - { - label: "CI / CD Pipeline", - type: "category", - link: { - type: "doc", - id: "guides/production-framework/ingredients/ci-cd-pipeline/index" - }, - items: [ - "guides/production-framework/ingredients/ci-cd-pipeline/ci-cd-only-path-to-prod", - "guides/production-framework/ingredients/ci-cd-pipeline/ci-cd-features", - ], + items: [ + "guides/production-framework/ingredients/service-catalog/modern-service-catalog", + "guides/production-framework/ingredients/service-catalog/infrastructure-templates", + "guides/production-framework/ingredients/service-catalog/application-templates", + ], + }, + { + label: "Landing Zone", + type: "category", + link: { + type: "doc", + id: "guides/production-framework/ingredients/landing-zone/index", }, - { - label: "Self-Service", - type: "category", - link: { - type: "doc", - id: "guides/production-framework/ingredients/self-service/index" - }, - items: [ - "guides/production-framework/ingredients/self-service/how-self-service-should-work", - "guides/production-framework/ingredients/self-service/common-self-service-use-cases", - ], + items: [ + "guides/production-framework/ingredients/landing-zone/what-landing-zone-should-include", + "guides/production-framework/ingredients/landing-zone/account-vending-machine", + ], + }, + { + label: "CI / CD Pipeline", + type: "category", + link: { + type: "doc", + id: "guides/production-framework/ingredients/ci-cd-pipeline/index", }, - { - label: "Automatic Updates", - type: "category", - link: { - type: "doc", - id: "guides/production-framework/ingredients/automatic-updates/index" - }, - items: [ - "guides/production-framework/ingredients/automatic-updates/how-auto-update-should-work", - "guides/production-framework/ingredients/automatic-updates/auto-update-features", - ], + items: [ + "guides/production-framework/ingredients/ci-cd-pipeline/ci-cd-only-path-to-prod", + "guides/production-framework/ingredients/ci-cd-pipeline/ci-cd-features", + ], + }, + { + label: "Self-Service", + type: "category", + link: { + type: "doc", + id: "guides/production-framework/ingredients/self-service/index", }, - { - label: "Other Ingredients", + items: [ + "guides/production-framework/ingredients/self-service/how-self-service-should-work", + "guides/production-framework/ingredients/self-service/common-self-service-use-cases", + ], + }, + { + label: "Automatic Updates", + type: "category", + link: { type: "doc", - id: "guides/production-framework/ingredients/other-ingredients/index" + id: "guides/production-framework/ingredients/automatic-updates/index", }, - ] + items: [ + "guides/production-framework/ingredients/automatic-updates/how-auto-update-should-work", + "guides/production-framework/ingredients/automatic-updates/auto-update-features", + ], + }, + { + label: "Other Ingredients", + type: "doc", + id: "guides/production-framework/ingredients/other-ingredients/index", + }, + ], }, { label: "Recipes", type: "category", link: { type: "doc", - id: "guides/production-framework/recipes/index" + id: "guides/production-framework/recipes/index", }, items: [ "guides/production-framework/recipes/dev-team-experience", "guides/production-framework/recipes/ops-team-experience", - ] + ], }, { label: "How Gruntwork can help", type: "doc", - id: "guides/production-framework/gruntwork-solutions/index" + id: "guides/production-framework/gruntwork-solutions/index", }, ], }, ] -module.exports = refarchSidebar +module.exports = productionFrameworkSidebar diff --git a/sidebars/refarch-guide.js b/sidebars/refarch-guide.js deleted file mode 100644 index 5b19b3ee82..0000000000 --- a/sidebars/refarch-guide.js +++ /dev/null @@ -1,71 +0,0 @@ -const refarchSidebar = [ - { - label: "Reference Architecture Guide", - type: "category", - link: { - type: "doc", - id: "guides/reference-architecture/index", - }, - items: [ - { - Authentication: [ - "guides/reference-architecture/authenticate/intro", - "guides/reference-architecture/authenticate/setting-up-initial-access", - "guides/reference-architecture/authenticate/authenticate-to-the-aws-web-console", - "guides/reference-architecture/authenticate/authenticate-to-aws-via-the-cli", - "guides/reference-architecture/authenticate/authenticate-to-ec2-instances-via-ssh", - "guides/reference-architecture/authenticate/authenticate-to-the-vpn-server", - ], - }, - { - "Deploying Your Apps": [ - "guides/reference-architecture/deploy-apps/intro", - "guides/reference-architecture/deploy-apps/what-is-already-deployed", - "guides/reference-architecture/deploy-apps/the-app", - "guides/reference-architecture/deploy-apps/dockerizing", - "guides/reference-architecture/deploy-apps/publish-docker-image", - ], - }, - { - "Configure Gruntwork Pipelines": [ - "guides/reference-architecture/configure-gw-pipelines/intro", - "guides/reference-architecture/configure-gw-pipelines/ci--cd-pipeline-for-infrastructure-code", - "guides/reference-architecture/configure-gw-pipelines/ci--cd-pipeline-for-app-code", - "guides/reference-architecture/configure-gw-pipelines/update-the-ci--cd-pipeline-itself", - ], - }, - { - "Monitoring, Alerting & Logging": [ - "guides/reference-architecture/monitoring-alerting-logging/intro", - "guides/reference-architecture/monitoring-alerting-logging/metrics", - "guides/reference-architecture/monitoring-alerting-logging/alerts", - "guides/reference-architecture/monitoring-alerting-logging/logs", - ], - }, - { - "Adding a New Account": [ - "guides/reference-architecture/adding-a-new-account/intro", - "guides/reference-architecture/adding-a-new-account/create-new-account-in-your-aws-org", - "guides/reference-architecture/adding-a-new-account/update-logs-security-shared-accounts-to-allow-cross-account-access", - "guides/reference-architecture/adding-a-new-account/deploy-the-security-baseline", - "guides/reference-architecture/adding-a-new-account/deploy-the-ecs-deploy-runner", - ], - }, - { - "Undeploying Your Architecture": [ - "guides/reference-architecture/undeploy/intro", - "guides/reference-architecture/undeploy/before-you-get-started", - "guides/reference-architecture/undeploy/pre-requisite-force-destroy-on-s3-buckets", - "guides/reference-architecture/undeploy/pre-requisite-understand-module-dependencies", - "guides/reference-architecture/undeploy/manually-undeploying-a-single-module", - "guides/reference-architecture/undeploy/manually-undeploying-multiple-modules-or-an-entire-environment", - "guides/reference-architecture/undeploy/removing-the-terraform-state", - "guides/reference-architecture/undeploy/useful-tips", - "guides/reference-architecture/undeploy/known-errors", - ], - }, - ], - }, -] - -module.exports = refarchSidebar diff --git a/sidebars/refarch-usage-guide.js b/sidebars/refarch-usage-guide.js new file mode 100644 index 0000000000..e6330d478a --- /dev/null +++ b/sidebars/refarch-usage-guide.js @@ -0,0 +1,77 @@ +const refarchUsageSidebar = [ + { + label: "Reference Architecture Guides", + type: "link", + href: "/docs/guides/reference-architecture", + className: "back-button", + }, + { + label: "Reference Architecture Usage", + type: "category", + link: { + type: "doc", + id: "guides/reference-architecture/example-usage-guide/index", + }, + items: [ + { + Authentication: [ + "guides/reference-architecture/example-usage-guide/authenticate/intro", + "guides/reference-architecture/example-usage-guide/authenticate/setting-up-initial-access", + "guides/reference-architecture/example-usage-guide/authenticate/authenticate-to-the-aws-web-console", + "guides/reference-architecture/example-usage-guide/authenticate/authenticate-to-aws-via-the-cli", + "guides/reference-architecture/example-usage-guide/authenticate/authenticate-to-ec2-instances-via-ssh", + "guides/reference-architecture/example-usage-guide/authenticate/authenticate-to-the-vpn-server", + ], + }, + { + "Deploying Your Apps": [ + "guides/reference-architecture/example-usage-guide/deploy-apps/intro", + "guides/reference-architecture/example-usage-guide/deploy-apps/what-is-already-deployed", + "guides/reference-architecture/example-usage-guide/deploy-apps/the-app", + "guides/reference-architecture/example-usage-guide/deploy-apps/dockerizing", + "guides/reference-architecture/example-usage-guide/deploy-apps/publish-docker-image", + ], + }, + { + "Configure Gruntwork Pipelines": [ + "guides/reference-architecture/example-usage-guide/configure-gw-pipelines/intro", + "guides/reference-architecture/example-usage-guide/configure-gw-pipelines/ci--cd-pipeline-for-infrastructure-code", + "guides/reference-architecture/example-usage-guide/configure-gw-pipelines/ci--cd-pipeline-for-app-code", + "guides/reference-architecture/example-usage-guide/configure-gw-pipelines/update-the-ci--cd-pipeline-itself", + ], + }, + { + "Monitoring, Alerting & Logging": [ + "guides/reference-architecture/example-usage-guide/monitoring-alerting-logging/intro", + "guides/reference-architecture/example-usage-guide/monitoring-alerting-logging/metrics", + "guides/reference-architecture/example-usage-guide/monitoring-alerting-logging/alerts", + "guides/reference-architecture/example-usage-guide/monitoring-alerting-logging/logs", + ], + }, + { + "Adding a New Account": [ + "guides/reference-architecture/example-usage-guide/adding-a-new-account/intro", + "guides/reference-architecture/example-usage-guide/adding-a-new-account/create-new-account-in-your-aws-org", + "guides/reference-architecture/example-usage-guide/adding-a-new-account/update-logs-security-shared-accounts-to-allow-cross-account-access", + "guides/reference-architecture/example-usage-guide/adding-a-new-account/deploy-the-security-baseline", + "guides/reference-architecture/example-usage-guide/adding-a-new-account/deploy-the-ecs-deploy-runner", + ], + }, + { + "Undeploying Your Architecture": [ + "guides/reference-architecture/example-usage-guide/undeploy/intro", + "guides/reference-architecture/example-usage-guide/undeploy/before-you-get-started", + "guides/reference-architecture/example-usage-guide/undeploy/pre-requisite-force-destroy-on-s3-buckets", + "guides/reference-architecture/example-usage-guide/undeploy/pre-requisite-understand-module-dependencies", + "guides/reference-architecture/example-usage-guide/undeploy/manually-undeploying-a-single-module", + "guides/reference-architecture/example-usage-guide/undeploy/manually-undeploying-multiple-modules-or-an-entire-environment", + "guides/reference-architecture/example-usage-guide/undeploy/removing-the-terraform-state", + "guides/reference-architecture/example-usage-guide/undeploy/useful-tips", + "guides/reference-architecture/example-usage-guide/undeploy/known-errors", + ], + }, + ], + }, +] + +module.exports = refarchUsageSidebar diff --git a/sidebars/update-guides.js b/sidebars/update-guides.js index 2567838441..d49631e57b 100644 --- a/sidebars/update-guides.js +++ b/sidebars/update-guides.js @@ -1,5 +1,13 @@ +const backLink = { + label: "Update Guides", + type: "link", + href: "/docs/guides/stay-up-to-date", + className: "back-button", +} + const updateGuideSidebars = { cis130: [ + backLink, { label: "CIS 1.3.0 Update Guide", type: "category", @@ -20,6 +28,7 @@ const updateGuideSidebars = { }, ], cis140: [ + backLink, { label: "CIS 1.4.0 Update Guide", type: "category", @@ -41,6 +50,7 @@ const updateGuideSidebars = { }, ], terraform12: [ + backLink, { label: "Update to Terraform 12", type: "category", @@ -55,6 +65,7 @@ const updateGuideSidebars = { }, ], terraform13: [ + backLink, { label: "Update to Terraform 13", type: "category", @@ -76,6 +87,7 @@ const updateGuideSidebars = { }, ], terraform14: [ + backLink, { label: "Update to Terraform 14", type: "category", @@ -97,6 +109,7 @@ const updateGuideSidebars = { }, ], terraform15: [ + backLink, { label: "Update to Terraform 15", type: "category", @@ -117,6 +130,7 @@ const updateGuideSidebars = { }, ], terraform1x: [ + backLink, { label: "Update to Terraform 1.X", type: "category", @@ -136,6 +150,7 @@ const updateGuideSidebars = { }, ], terraformServiceProviderV3: [ + backLink, { label: "Update to AWS Provider v3", type: "category", @@ -150,6 +165,7 @@ const updateGuideSidebars = { }, ], dryRefArch: [ + backLink, { label: "How To DRY Your Reference Architecture", type: "category", diff --git a/sidebars/vpc-guide.js b/sidebars/vpc-guide.js index 55a0d2c31e..7864a10269 100644 --- a/sidebars/vpc-guide.js +++ b/sidebars/vpc-guide.js @@ -1,4 +1,10 @@ const vpcGuide = [ + { + label: "Build Your Own Architecture", + type: "link", + href: "/docs/guides/build-it-yourself", + className: "back-button", + }, { label: "VPC Guide", type: "category", diff --git a/src/components/Card.module.css b/src/components/Card.module.css index 93e2a70ef0..f6a7fc099a 100644 --- a/src/components/Card.module.css +++ b/src/components/Card.module.css @@ -21,10 +21,6 @@ align-items: left; } -.horizontal .title { - margin-bottom: 0.25rem; -} - /* APPEARANCES */ .flush { @@ -81,8 +77,15 @@ html[data-theme="dark"] .icon { } .card .title { - margin-top: 0; - margin-bottom: 0.75rem; + margin: 0; +} + +.card .description { + margin-top: 0.75rem; +} + +.horizontal .description { + margin-top: 0.25rem; } .card strong { @@ -178,3 +181,7 @@ html[data-theme="dark"] .cardlink .invisible:hover { .cardlink .invisible:hover h3 { color: var(--ifm-color-primary); } + +.cardlink .flush:hover { + border-color: transparent; +} diff --git a/src/components/Card.tsx b/src/components/Card.tsx index b880b9f1e9..8d47c93236 100644 --- a/src/components/Card.tsx +++ b/src/components/Card.tsx @@ -11,6 +11,7 @@ export type CardProps = { tags?: string[] orientation?: "horizontal" | "vertical" appearance?: "float" | "flush" | "invisible" + padding?: number | string className?: string } @@ -23,6 +24,7 @@ export const Card: React.FunctionComponent = ({ tags, orientation = "vertical", appearance = "float", + padding, className, children, }) => { @@ -37,6 +39,9 @@ export const Card: React.FunctionComponent = ({ appearance === "invisible" && styles.invisible, className )} + style={{ + padding: padding !== undefined ? padding : "", + }} >
{number && {number}} @@ -46,7 +51,9 @@ export const Card: React.FunctionComponent = ({

{title}

-
{children || description}
+ {(children || description) && ( +
{children || description}
+ )} {tags && (
    {tags.map((tag, idx) => ( diff --git a/src/components/CardGroup.tsx b/src/components/CardGroup.tsx index 608b7fafc9..54f34dc9f3 100644 --- a/src/components/CardGroup.tsx +++ b/src/components/CardGroup.tsx @@ -16,6 +16,7 @@ export const CardGroup: React.FunctionComponent = ({ colGap, rowGap, equalHeightRows, + stacked, children, }) => { return ( @@ -24,6 +25,7 @@ export const CardGroup: React.FunctionComponent = ({ gap={gap} colGap={colGap} rowGap={rowGap} + stacked={stacked} equalHeightRows={equalHeightRows} > {React.Children.map(children || null, (child: JSX.Element, idx) => ( diff --git a/src/components/Grid.module.css b/src/components/Grid.module.css index ce3f8eb56e..abe4d3710c 100644 --- a/src/components/Grid.module.css +++ b/src/components/Grid.module.css @@ -31,13 +31,13 @@ } @media only screen and (max-width: 1280px) { - .grid { + .grid:not(.col1) { grid-template-columns: repeat(2, 1fr); } } @media only screen and (max-width: 640px) { - .grid { + .grid:not(.col1) { grid-template-columns: repeat(1, 1fr); } } diff --git a/src/css/custom.css b/src/css/custom.css index 428181e8aa..b4e28457fb 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -69,6 +69,13 @@ main { margin-top: 2em; } +/* Constrain pages without a TOC to same width */ +@media only screen and (min-width: 997px) { + aside + main [class="col"]:only-child { + max-width: 75% !important; + } +} + /* IMAGES & CAPTIONS */ p > img:not(.no-zoom) { @@ -211,15 +218,41 @@ html[data-theme="dark"] aside { font-weight: 600; } -/* Special styles for top level guide titles */ -.menu__list-item-collapsible a:not(.menu__link--sublist) { +/* Special styles for top level guide titles. This selects a top-level + category which uses the category-index pattern (is selectable) and + is either the only or last of exactly two items in the sidebar + (the other of which could be a back button.) + */ +li.theme-doc-sidebar-item-category-level-1:last-child:nth-child(1) + > *:first-child, +li.theme-doc-sidebar-item-category-level-1:last-child:nth-child(2) + > *:first-child { text-transform: uppercase; font-size: 0.85rem; letter-spacing: 0.05rem; } +.back-button { + margin-bottom: 1rem; + font-size: 15px; + font-weight: bold; + justify-content: left; +} + +.back-button a { + justify-content: left; +} + +.back-button > a:before { + content: "←"; + margin-right: 0.5rem; +} + /* Hide disclosure carats on top level of guides */ -.menu__list-item-collapsible a:not(.menu__link--sublist) + button { +li.theme-doc-sidebar-item-category-level-1 + > div + > a:not(.menu__link--sublist) + + button { display: none; } @@ -233,15 +266,13 @@ html[data-theme="dark"] aside { background: var(--ifm-menu-link-sublist-icon) 50% / 1.25rem 1.25rem; } -html[data-theme="light"] .menu__link--sublist { - color: black; +html[data-theme="light"] .menu__link--sublist:not(.menu__link--active), +html[data-theme="light"] + .menu__list-item-collapsible + a:not(.menu__link--active) { color: #33376d; } -html[data-theme="dark"] .menu__link--sublist { - color: white; -} - /* TOC */ .table-of-contents { @@ -320,16 +351,18 @@ html[data-theme="dark"] .menu__link--sublist { } } -#more_dropdown { +#more_dropdown, +#more_dropdown + ul { display: none; } -@media only screen and (max-width: 1280px) and (min-width: 996px) { +@media only screen and (max-width: 1280px) and (min-width: 997px) { .navbar__items--right > a { display: none; } - #more_dropdown { + #more_dropdown, + #more_dropdown + ul { display: block; } } @@ -338,4 +371,8 @@ html[data-theme="dark"] .menu__link--sublist { .navbar__brand { border-right: none; } + + .navbar-sidebar__brand .navbar__brand { + display: none; + } } diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 60201861f2..7d18d4855c 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -46,7 +46,7 @@ export default function Home(): JSX.Element { Bought a Reference Architecture? Get your new infrastructure up @@ -54,7 +54,7 @@ export default function Home(): JSX.Element { Follow our tutorials and learn how to deploy Gruntwork services diff --git a/static/img/guides/reference-architecture/gruntwork-pipelines-architecture.png b/static/img/guides/reference-architecture/example-usage-guide/gruntwork-pipelines-architecture.png similarity index 100% rename from static/img/guides/reference-architecture/gruntwork-pipelines-architecture.png rename to static/img/guides/reference-architecture/example-usage-guide/gruntwork-pipelines-architecture.png diff --git a/static/img/guides/reference-architecture/landing-zone-ref-arch.png b/static/img/guides/reference-architecture/example-usage-guide/landing-zone-ref-arch.png similarity index 100% rename from static/img/guides/reference-architecture/landing-zone-ref-arch.png rename to static/img/guides/reference-architecture/example-usage-guide/landing-zone-ref-arch.png diff --git a/static/img/guides/reference-architecture/secrets.png b/static/img/guides/reference-architecture/example-usage-guide/secrets.png similarity index 100% rename from static/img/guides/reference-architecture/secrets.png rename to static/img/guides/reference-architecture/example-usage-guide/secrets.png diff --git a/static/img/guides/reference-architecture/slack-workflow-1.png b/static/img/guides/reference-architecture/example-usage-guide/slack-workflow-1.png similarity index 100% rename from static/img/guides/reference-architecture/slack-workflow-1.png rename to static/img/guides/reference-architecture/example-usage-guide/slack-workflow-1.png diff --git a/static/img/guides/reference-architecture/slack-workflow-2.png b/static/img/guides/reference-architecture/example-usage-guide/slack-workflow-2.png similarity index 100% rename from static/img/guides/reference-architecture/slack-workflow-2.png rename to static/img/guides/reference-architecture/example-usage-guide/slack-workflow-2.png diff --git a/static/img/guides/reference-architecture/slack-workflow-3.png b/static/img/guides/reference-architecture/example-usage-guide/slack-workflow-3.png similarity index 100% rename from static/img/guides/reference-architecture/slack-workflow-3.png rename to static/img/guides/reference-architecture/example-usage-guide/slack-workflow-3.png diff --git a/static/img/guides/reference-architecture/slack-workflow-4.png b/static/img/guides/reference-architecture/example-usage-guide/slack-workflow-4.png similarity index 100% rename from static/img/guides/reference-architecture/slack-workflow-4.png rename to static/img/guides/reference-architecture/example-usage-guide/slack-workflow-4.png diff --git a/static/img/guides/reference-architecture/slack-workflow-5.png b/static/img/guides/reference-architecture/example-usage-guide/slack-workflow-5.png similarity index 100% rename from static/img/guides/reference-architecture/slack-workflow-5.png rename to static/img/guides/reference-architecture/example-usage-guide/slack-workflow-5.png