WIP: Infrastructure docs

docs/_docset.yml

@@ -100,6 +100,15 @@ toc:
   # to prevent them from being nested deeply arbitrarily
   # use max_toc_depth to allow deeper nesting (Expert mode, consult with docs team)
   - toc: development
+  - folder: infrastructure
+    children:
+      - file: index.md
+      - folder: environments
+        children:
+          - file: index.md
+          - file: production.md
+          - file: staging.md
+          - file: preview.md
   - folder: testing
     children:
       - file: index.md

docs/infrastructure/environments/index.md

@@ -0,0 +1 @@
+# Environments

docs/infrastructure/environments/preview.md

@@ -0,0 +1,35 @@
+---
+navigation_title: Preview
+---
+
+# Preview Environment
+
+The preview environment is a shared environment that is used to test changes on
+Pull Requests. Each Pull Request is deployed to a unique path in the preview
+environment.
+
+|   |   |
+|---|---|
+| URL | [https://docs-v3-preview.elastic.dev](https://docs-v3-preview.elastic.dev) |
+| Terraform resources | [https://github.com/elastic/docs-infra/tree/main/aws/elastic-web/us-east-1/elastic-docs-v3-preview](https://github.com/elastic/docs-infra/tree/main/aws/elastic-web/us-east-1/elastic-docs-v3-preview) |
+
+
+## Architecture
+
+The preview environment is an S3 bucket served by CloudFront defined by the [elastic-docs-v3 terraform module](https://github.com/elastic/docs-infra/tree/main/modules/elastic-docs-v3).
+
+## Deployment
+
+Each repository has a GitHub Actions workflow that is triggered when a Pull Request is created.
+For example the [docs-build.yml](https://github.com/elastic/elasticsearch/blob/main/.github/workflows/docs-build.yml) workflow on the [elastic/elasticsearch](https://github.com/elastic/elasticsearch) repository. At it's core it uses the [preview-build.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-build.yml) reusable workflow to build and deploy the preview environment.
+
+## Security
+
+We are using OIDC to authenticate the GitHub Actions workflow to AWS.
+You can find a list of GitHub repositories that are allowed to deploy to AWS in the
+[repositories.yml](https://github.com/elastic/docs-infra/blob/main/modules/aws-github-actions-oidc-roles/repositories.yml).
+
+For each repository, we create a new IAM role that allows the GitHub Actions workflow
+of that repository to deploy to a specific path in the S3 bucket.
+
+E.g. The GitHub Actions workflow for the [elastic/kibana](https://github.com/elastic/kibana) repository is allowed to deploy to the `/elastic/kibana` path in the S3 bucket.

docs/infrastructure/environments/production.md

@@ -0,0 +1,27 @@
+---
+navigation_title: Production
+---
+
+# Production Environment
+
+The production environment is the main environment that is used to serve the
+Elastic documentation. The documentation is a static site built with [docs-builder](https://github.com/elastic/docs-builder).
+
+|   |   |
+|---|---|
+| URL | [https://www.elastic.co/docs](https://www.elastic.co/docs) |
+| Terraform resources | [https://github.com/elastic/docs-infra/tree/main/aws/elastic-web/us-east-1/elastic-docs-v3-prod](https://github.com/elastic/docs-infra/tree/main/aws/elastic-web/us-east-1/elastic-docs-v3-prod) |
+
+
+## Architecture
+
+The production environment is an S3 bucket served by CloudFront defined by the [elastic-docs-v3 terraform module](https://github.com/elastic/docs-infra/tree/main/modules/elastic-docs-v3).
+
+However, infront of the CloudFront distribution, Fastly is used to serve the site. 
+The reason is that Web team is using Fastly to serve the website and they are redirecting
+the `/docs` path to our CloudFront distribution.
+
+## Deployment
+
+The production environment is deployed by the [Assembler Build and Deploy](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.prod.yml)
+workflow.

docs/infrastructure/environments/staging.md

@@ -0,0 +1,13 @@
+---
+navigation_title: Staging
+---
+
+# Staging Environment
+
+The staging environment 
+
+
+|   |   |
+|---|---|
+| URL | [https://staging-website.elastic.co/docs](https://staging-website.elastic.co/docs) |
+| Terraform resources | [https://github.com/elastic/docs-infra/tree/main/aws/elastic-web/us-east-1/elastic-docs-v3-staging](https://github.com/elastic/docs-infra/tree/main/aws/elastic-web/us-east-1/elastic-docs-v3-staging) |

docs/infrastructure/index.md

@@ -0,0 +1,29 @@
+# Infrastructure
+
+In this section, we'll cover the infrastructure that powers the Elastic documentation website.
+
+[//]: # (## GitHub)
+
+[//]: # ()
+[//]: # (All of our Git repositories are hosted on GitHub.)
+
+[//]: # ()
+[//]: # (- [elastic/docs-builder](https://github.com/elastic/docs-builder))
+
+[//]: # (- [elastic/docs-infra](https://github.com/elastic/docs-infra))
+
+[//]: # (- [elastic/docs-internal-workflows](https://github.com/elastic/docs-internal-workflows))
+
+[//]: # ()
+[//]: # (## GitHub Actions)
+
+[//]: # ()
+[//]: # (You can find all of our GitHub Actions workflows in our [repositories](#github).)
+
+[//]: # ()
+[//]: # (## AWS)
+
+[//]: # ()
+[//]: # (All of our AWS resources are managed through Terraform.)
+
+[//]: # (You can find the resource definitions in the [elastic/docs-infra](https://github.com/elastic/docs-infra) repository.)