diff --git a/docs/_docset.yml b/docs/_docset.yml index 5f0cdbef8..fa7608b52 100644 --- a/docs/_docset.yml +++ b/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 diff --git a/docs/infrastructure/environments/index.md b/docs/infrastructure/environments/index.md new file mode 100644 index 000000000..d27141e93 --- /dev/null +++ b/docs/infrastructure/environments/index.md @@ -0,0 +1 @@ +# Environments diff --git a/docs/infrastructure/environments/preview.md b/docs/infrastructure/environments/preview.md new file mode 100644 index 000000000..1926751dd --- /dev/null +++ b/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. diff --git a/docs/infrastructure/environments/production.md b/docs/infrastructure/environments/production.md new file mode 100644 index 000000000..692a43ca5 --- /dev/null +++ b/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. diff --git a/docs/infrastructure/environments/staging.md b/docs/infrastructure/environments/staging.md new file mode 100644 index 000000000..a6d8956a1 --- /dev/null +++ b/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) | diff --git a/docs/infrastructure/index.md b/docs/infrastructure/index.md new file mode 100644 index 000000000..c83cc7186 --- /dev/null +++ b/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.)