From c1f064ef8845916c4cb933e5ec8da5179e715407 Mon Sep 17 00:00:00 2001 From: Joris van de Donk Date: Wed, 20 Nov 2024 11:39:57 +0000 Subject: [PATCH] docs: clarify that modules are intended to be depended on, and samples are reference implementations meant to be copied and modified --- docs/getting-started.md | 4 ++-- docs/index.md | 2 +- docs/samples/simple-build-pipeline.md | 2 -- modules/README.md | 8 +++++--- samples/README.md | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 55ff4ff6..189daf86 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -10,11 +10,11 @@ An _asset_ is a singular template, script, or automation document that may prove ### Modules -A _module_ is a reusable [Terraform](https://www.terraform.io/) configuration encapsulating all of the resources needed to deploy a particular workload on AWS. These modules are highly configurable through variables, and provide necessary outputs for building interconnected architectures. We recommend reviewing the [Terraform module documentation](https://developer.hashicorp.com/terraform/language/modules) if you are unfamiliar with this concept. +A _module_ is a reusable [Terraform](https://www.terraform.io/) configuration encapsulating all of the resources needed to deploy a particular workload on AWS. These modules are highly configurable through variables, and provide necessary outputs for building interconnected architectures. We recommend reviewing the [Terraform module documentation](https://developer.hashicorp.com/terraform/language/modules) if you are unfamiliar with this concept. Modules are designed for you to depend on in your own Terraform modules, and we don't expect you to have to make any modifications to them; that said, if a module doesn't meet your needs, please raise an issue! ### Samples -A _sample_ is a complete reference architecture that stitches together [modules](./modules/index.md) and first-party AWS services. A _sample_ is deployed with Terraform, and is the best way to get started with the **Cloud Game Development Toolkit**. +A _sample_ is a complete reference architecture that stitches together [modules](./modules/index.md) and first-party AWS services. A _sample_ is deployed with Terraform, and is the best way to get started with the **Cloud Game Development Toolkit**. Samples are designed for you to copy from and modify as needed to suit your architecture and needs. ???+ Note Because samples may deploy resources that have unique name constraints, we cannot guarantee that two different samples can be deployed into the same AWS account without modifying either of the samples to integrate shared infrastructure or resolve conflicts. If you're interested in using functionality from multiple samples, we recommend that you use them as reference material to base your own infrastructure off of. diff --git a/docs/index.md b/docs/index.md index 0547ee7b..049fac81 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,7 +19,7 @@ features: - title: Samples #image: media/images/samples.svg link: samples/index.html - description: Opinionated ready-to-use implementations to address common use cases for expedited game studio setup and battle-tested scenarios from the community. + description: Opinionated reference implementations to address common use cases for expedited game studio setup and battle-tested scenarios from the community. companies: title: list: diff --git a/docs/samples/simple-build-pipeline.md b/docs/samples/simple-build-pipeline.md index 11559895..3978fa02 100644 --- a/docs/samples/simple-build-pipeline.md +++ b/docs/samples/simple-build-pipeline.md @@ -2,8 +2,6 @@ The Simple Build Pipeline is the best place to get started when first exploring the Cloud Game Development Toolkit. It encapsulates many of the available modules alongside best practice deployments of core AWS services. The Simple Build Pipeline provisions a well-architected Virtual Private Cloud ([VPC](https://aws.amazon.com/vpc/)), a skeleton for managing DNS and SSL certificates with [Route 53](https://aws.amazon.com/route53/) and AWS Certificate Manager([ACM](https://aws.amazon.com/certificate-manager/)), [Jenkins](https://www.jenkins.io/) for continuous integration and deployment, [Perforce Helix Core](https://www.perforce.com/products/helix-core/aws) for version control, [Perforce Helix Swarm](https://www.perforce.com/products/helix-swarm) for code review, and [Perforce Helix Authentication Service](https://github.com/perforce/helix-authentication-service) for external identity provider integrations. -We recommend that you [**fork**](https://github.com/aws-games/cloud-game-development-toolkit/fork) the Cloud Game Development Toolkit and then use this Simple Build Pipeline as the starting point for managing your studio's infrastructure. - ## Predeployment There are a few prerequisites that need to be completed **prior** to deploying this sample architecture. We'll walk through those here. diff --git a/modules/README.md b/modules/README.md index 5a28798a..255d115e 100644 --- a/modules/README.md +++ b/modules/README.md @@ -2,11 +2,13 @@ ## Introduction -These modules simplify the deployment of common game development workloads on AWS. Some have pre-requisites that will be outlined in their respective documentation. They are designed to easily integrate with each other, and provide relevant outputs to simplify permissions, networking, and access. +These modules simplify the deployment of common game development workloads on AWS. Some have pre-requisites that will be outlined in their respective documentation. They are designed to be depended on from other modules (including your own root module), easily integrate with each other, and provide relevant outputs to simplify permissions, networking, and access. -## Contribution +## How to include these modules + +We've found that including the **CGD Toolkit** repository as a git submodule in your own infrastructure repository is a good way of depending on the modules within an (existing) Terraform root module. Forking the **CGD Toolkit** and submoduling your fork may be a good approach if you intend to make changes to any modules. We recommend starting with the [Terraform module documentation](https://developer.hashicorp.com/terraform/language/modules) for a crash course in the way the **CGD Toolkit** is designed. Note how you can use the [module source argument](https://developer.hashicorp.com/terraform/language/modules/sources) to declare modules that use the **CGD Toolkit**'s module source code. -We recommend starting with the [Terraform module documentation](https://developer.hashicorp.com/terraform/language/modules) for a crash course in the way the **CGD Toolkit** is designed. +## Contribution Please follow these guidelines when developing a new module. These are also outlined in the pull-request template for Module additions. diff --git a/samples/README.md b/samples/README.md index f2bb076c..5b48f136 100644 --- a/samples/README.md +++ b/samples/README.md @@ -1,6 +1,6 @@ # Overview -Samples represent a reference implementation that can be deployed to solve for a specific use-case or workload. These are Terraform configurations and integrations with other common AWS workloads and services. Each sample will provide its own documentation and instructions that follows the template below: +Samples represent a reference implementation that can be copied, modified and deployed to solve for a specific use-case or workload. These are Terraform configurations and integrations with other common AWS workloads and services. Each sample will provide its own documentation and instructions that follows the template below: #### 1) Predeployment