From 18e029fce3df706c8ef096db2f0ccd390aabb553 Mon Sep 17 00:00:00 2001 From: arsci Date: Tue, 14 Mar 2023 21:04:29 -0700 Subject: [PATCH 1/6] update refarch config guide --- .../configuration-guide/index.md | 339 ++++++++++------- .../configuration-guide/index.md | 340 +++++++++++------- 2 files changed, 406 insertions(+), 273 deletions(-) diff --git a/_docs-sources/guides/reference-architecture/configuration-guide/index.md b/_docs-sources/guides/reference-architecture/configuration-guide/index.md index 907bc79af0..fd848ce397 100644 --- a/_docs-sources/guides/reference-architecture/configuration-guide/index.md +++ b/_docs-sources/guides/reference-architecture/configuration-guide/index.md @@ -1,6 +1,6 @@ # Gruntwork Reference Architecture Setup Instructions -This repository is used to generate the code to deploy and manage the [the Gruntwork Reference Architecture](https://gruntwork.io/reference-architecture/). When we have finished the initial deployment, all of the code will be committed to this repository. We will then hand off the architecture for you to use, and we will include instructions for copying the code to your own repository outside of the `gruntwork-clients` GitHub organization. +This repository is used to generate the code to deploy and manage the [the Gruntwork Reference Architecture](https://gruntwork.io/reference-architecture/). You will receive an automated email at the end of the deployment indicating that the initial deployment has finished, which includes instructions for copying the code to your own repository outside of the `gruntwork-clients` GitHub organization. ![Landing Zone Reference Architecture](/img/guides/reference-architecture/configuration-guide/landing-zone-ref-arch.png) @@ -18,220 +18,285 @@ Caveat: at this time, the Reference Architecture does not configure or manage th ::: -## Clone this repository +## 1. Create an infrastructure-live repository -The very first step is to clone this repository to your local machine. You must have Git installed on your machine. Refer to [these instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install Git on your platform. +1. Create a new repository in your VCS platform. We recommend naming it _infrastructure-live_. +1. Keep this repo handy, as you'll be prompted for the following information in a subsequent step: + - HTTPS URL (e.g. `https://github.com/gruntwork-io/infrastructure-live`) + - SSH URL (e.g. `git@github.com:gruntwork-io/infrastructure-live.git`) + - Default branch (e.g. `main` or `master`) -1. Clone the repository. +## 2. Set up the machine user - ```bash - git clone git@github.com:gruntwork-clients/.git - ``` +The next step is to configure the Machine User Personal Access Token(s) -1. Check out a new branch with your changes: +If you are using GitHub to host your `infrastructure-live` repository, you will only need the one +personal access token as the permissions will allow access to both your `infrastructure-live` repo and +Gruntwork's private repositories. - ```bash - git checkout -b ref-arch-form - ``` +If you are using GitLab or Bitbucket to host your `infrastructure-live` repository, you will need a +Personal Access Token for your respective VCS in addition to a GitHub PAT for access to the +private Gruntwork GitHub repositories. Note that at this time GitHub is the only supported VCS for +Reference Architecture deployments. -## Create and configure AWS Accounts +First we will create a GitHub Personal Access Token: -1. Create the following AWS accounts: +1. In GitHub, create a new user account, then create a [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). +1. In the ref arch form, `MachineUserGitUsername` and `MachineUserGitEmail` is where you enter this account’s details. +1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. +1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. You should include `GitHub-MachineUser-PAT` as part of the name/description of the token to be able to identify it later. +1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret, but it's recommended you include `GitHub-MachineUser-PAT` as part of the name to be able to identify it later. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. +1. Once the secret is created, **make a note of the ARN**. - - Security: for centralized authentication to other accounts, including management of IAM users, groups, and roles. - - Logs: A log archive account that contains a central Amazon S3 bucket for storing copies of all AWS CloudTrail and AWS Config log files. - - Shared: Shared services account for sharing resources such as Amazon Machine Images (AMIs) and Docker images with other accounts. This account can also be used to provide common infrastructure such as self-hosted CI/CD systems (e.g. Jenkins) and monitoring systems (e.g. Grafana) with other accounts. - - Dev: A dedicated app account for development purposes, intended to isolate early development releases from the rest of your infrastructure. - - Stage: A dedicated app account for hosting staging, testing, and/or QA environments. - - Prod: A dedicated app account for production deployments, intended for live environments used by customers. +If your `infrastructure-live` repository is hosted in GitHub, enter the secrets manager ARN from the above steps into the Ref Arch `VCSPATSecretsManagerARN` field. This token will provide access to both your `infrastructure-live` repo and to the Gruntwork private repositories and you are done setting up the machine user! You can skip to the next section. -1. Once they are created, record the account IDs. +If your `infrastructure-live` repository is hosted in BitBucket or GitLab, expand the `BitBucket / GitLab` tab below for more details. -1. These account IDs will go under `AWSAccounts` in the reference architecture form. +
BitBucket / GitLab -For the best results, use [Gruntwork CLI](https://github.com/gruntwork-io/gruntwork) to create the accounts. The Gruntwork CLI automatically grants Gruntwork engineers access to your accounts through an IAM role. However, **if you choose to create the accounts manually and do not use the Gruntwork CLI, you still MUST run the `gruntwork aws grant` command to grant the Gruntwork team access to these accounts**. MFA is enforced for all Gruntwork access. You can use the same tool to revoke access when the deployment is complete. See [CLI documentation](https://github.com/gruntwork-io/gruntwork) for details. +> Note that at this time, GitHub is the only supported VCS for Reference Architecture deployments. -:::info +If you are using GitLab or BitBucket to host your `infrastructure-live` repository, enter the secrets manager ARN from the above steps into the `GitHubPATSecretsManagerARN` field. Since this token will provide access to only the Gruntwork private repositories, we will next need to create the token to access your `infrastructure-live` repo. -- The accounts must be new, empty accounts, with no resources present. That means no EC2 instances, RDS databases, CloudTrail trails, AWS Config recorders, etc. -- Do not apply any Service Control Policies to the accounts as they may interfere with the Terraform resources in the Reference Architecture. -- You can name the _dev, stage,_ and _prod_ accounts anything you like, but the others must be named _shared_, _logs_, and _security_. +- For GitLab, use [these instructions](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), and + grant the following scopes (NOTE: `api`, `read_user`, and `read_api` scopes are only used for uploading the public SSH + key for the user. You can replace the token with a new one that only has `write_repository` permission after the + Reference Architecture is deployed.): -::: + - `write_repository` + - `api` + - `read_user` + - `read_api` -## Purchase and register domain names + You should name the token `GitLab-MachineUser-PAT` to be able to identify it later -The Reference Architecture uses Route 53 to setup public DNS records for several aspects of the infrastructure, such as the network bastion and the [AWS Sample App](https://github.com/gruntwork-io/aws-sample-app/). For this to work, we ask that you set up domains for each application account (_dev_, _stage_, and _prod_) and, if you’re using Jenkins, in the _shared_ account. These domains should be configured as public hosted zones in Route 53. There are two options for domain registration: +- For Bitbucket, use [these instructions](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/), and + grant the following scopes (NOTE: `Account:Write` is only used for uploading the public SSH key for the user. You can + replace the token with a new one that only has `Repositories:Write` permission after the Reference Architecture is + deployed.): -### Option A: Register one domain per account (recommended!) + - `Repositories:Write` + - `Account:Write` -Follow the instructions in the [Gruntwork CLI documentation](https://github.com/gruntwork-io/gruntwork#create-the-aws-accounts) to complete this step. + You should name the token `BitBucket-MachineUser-PAT` to be able to identify it later. -If you choose not to use the Gruntwork CLI, you may either [register a new domain using Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) yourself, or you may register a domain using an external provider, and [set up Route 53 as the DNS service for that domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/MigratingDNS.html). +Now you will need to create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. You should name the secret following the above naming convention (`GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT`). Once the secret is created, **make a note of the ARN**. -#### Explanation +Finally, enter the newly created `GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT` secrets manager ARN from the above step into the Ref Arch `VCSPATSecretsManagerARN` field. -You’ll be using Route 53 to register a separate domain name in the _dev_, _stage_, _prod_ accounts, as well as _shared_ if you are using Jenkins. +
-This is the more secure option because: +### Explanation -- Reduces the chance of making changes to the wrong domain: e.g., accidentally update prod while working on dev. -- Less likely to make a mistake such as issuing cookies for the wrong domain: e.g., accidentally create a cookie in dev that is also accepted in prod. -- Lowers the possibility of issuing TLS certificates for the wrong domain: e.g., accidentally create a TLS cert in dev that is also accepted in prod. +The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. -Most domains in Route 53 are just $12, so this should not add much expense. +There are two primary uses for the Machine User: +- Accessing Gruntwork private repositories hosted in GitHub +- Accessing your `infrastructure-live` repository that is hosted in GitHub, BitBucket, or GitLab -### Option B: Register one domain with subdomains in each account +You need at least one [machine user in GitHub](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) to access the repos in the Gruntwork IaC Library private repositories. If you are using GitHub to host your `infrastructure-live` repo then this machine user PAT will also grant all the access you will need. -Follow the instructions in the [Route 53 documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html) to delegate a subdomain. We recommend that you manage the top-level domain as a hosted zone in either the _security_ or the root account of your AWS Organization, and delegate subdomains to each of the other accounts (e.g. _dev_, _stage_, _prod_, and _shared_ if using Jenkins). +If you have chosen Bitbucket or GitLab to host your `infrastructure-live` repo, then you will need a second PAT that grants access to that repo. -#### Explanation +In the `reference-architecture-form.yml` there are two fields that relate to the machine user PAT(s) +- `VCSPATSecretsManagerARN` +- `GitHubPATSecretsManagerARN` -You’ll be purchasing one domain (e.g. _example.com_), and delegate subdomains to each account (e.g. _dev.example.com_, _stage.example.com_, etc.). The upside of this approach is that there is a single [top-level domain namespace](https://en.wikipedia.org/wiki/Top-level_domain) (e.g. _example.com_) for all of your accounts. However, there are several important downsides: +`VCSPATSecretsManagerARN` is for the secrets manager ARN that contains the PAT for your VCS system hosting your `infrastructure-live` repo. If your VCS happens to be GitHub then it automatically grants all the access you need and you can set `GitHubPATSecretsManagerARN` to an empty string as it is not needed. -- You may accidentally make a mistake when managing the top-level domain that may impact all of your subdomains. -- A subdomain such as `prod.example.com` is less intuitive for users. This can be mitigated by choosing a top-level domain for prod, and subdomains for non-production environments. -- You must be careful about issuing cookies with the [`Set-Cookie` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) so that cookies are valid only for the intended subdomain. +Since BitBucket and GitLab PATs wouldn't grant access to GitHub, the additional `GitHubPATSecretsManagerARN` is needed in order to access Gruntwork Private IaC Library repositories. -## Confirm the domain configuration +## 3. Clone this repository -Once everything is configured up correctly, check that you can resolve the domains and confirm the nameserver settings using the `dig` command on MacOS or Linux, or `nslookup` on Windows. For example, the hosted zone configuration for the _gruntwork.in_ domain used by Gruntwork for testing looks like this in Route 53: +Use Git to clone this repository. If you do not have `git` available on your system, refer to [these instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install Git on your platform. -![](/img/guides/reference-architecture/configuration-guide/gruntwork.in.ns.png) +1. Clone the repository. -1. On MacOS or Linux, use `dig` to confirm that the domain can be resolved correctly over the Internet: + ```bash + git clone git@github.com:gruntwork-clients/.git + ``` - ```bash - $ dig gruntwork.in +short ns - ns-1202.awsdns-22.org. - ns-1749.awsdns-26.co.uk. - ns-559.awsdns-05.net. - ns-67.awsdns-08.com. - ``` +## 4. Authenticate to AWS on your command line -1. On Windows, use `nslookup`: +The bootstrap script will prepare your AWS accounts for deployment. To use the bootstrap script and form filling wizard, +the CLI will need access to your AWS Root account you would like to use for the Reference Architecture. The Root account +is where the AWS Organization is defined. - ```bash - $ nslookup -type=mx gruntwork.in - Server: 8.8.8.8 - Address: 8.8.8.8#53 +1. If you do not have a Root account (an AWS account with AWS Organizations setup) already, create one. We recommend + creating a brand new account to use as the Root account if you are not already using AWS Organizations, and import + your existing AWS Account(s) to it as members. +1. Setup AWS Organizations in your Root account if you haven't already. Refer to [this + documentation](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_tutorials_basic.html) for instructions + on how to setup AWS Organizations. +1. If you do not have one already, [create an IAM + User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) with administrator permissions (attach + the `AdministratorAccess` IAM policy). Make sure to create AWS Access Keys for the IAM User as well. +1. Once you have an IAM User and AWS Access Keys for accessing the Root account, configure your terminal to be able to + authenticate to the IAM User. If you do not know how to do this, refer to our [Comprehensive Guide to Authenticating + to AWS on the Command + Line](https://blog.gruntwork.io/a-comprehensive-guide-to-authenticating-to-aws-on-the-command-line-63656a686799). - Non-authoritative answer: - gruntwork.in nameserver = ns-1202.awsdns-22.org. - gruntwork.in nameserver = ns-1749.awsdns-26.co.uk. - gruntwork.in nameserver = ns-559.awsdns-05.net. - gruntwork.in nameserver = ns-67.awsdns-08.com. - ``` +## 5. Run the bootstrap script -Notice that the NS records in the image match the values returned by the commands. The same process applies if you’re using subdomains. Make sure to validate each domain or subdomain in this manner. +We're ready to run the wizard to fill in your `reference-architecture-form.yml` with valid values. -## Create an infrastructure-live repository +Before running the wizard, ensure you have completed steps 1, 2 and 3 and that you have the following values ready at hand: -1. Create a new repository in your VCS platform. We recommend naming it _infrastructure-live_. -2. In the ref arch form, `InfraLiveRepoURL` is where you enter this repo’s HTTPS URL (e.g. ). -3. `InfraLiveRepoSSHURL` is where you enter this repo’s SSH URL (e.g. :gruntwork-io/infrastructure-live.git). -4. `InfraLiveDefaultBranchName` is where you enter your repo’s default branch name (e.g. main). +- Personal Access Token for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. + - If you do not have one, generate a new Personal Access Token with `repo` level permissions. +- GitHub Machine User Personal Access Token (required in all cases) +- VCS Machine User Personal Access Token (only required if your ultimate infrastructure-live destination is NOT GitHub) +- The HTTPS URL to your VCS `infrastructure-live` repo (e.g., `https://github.com/gruntwork-io/infrastructure-live.git`) +- The SSH URL to your same VCS `infrastructure-live` repo (e.g., `git@github.com:gruntwork-io/infrastructure-live.git`) -This current repository will contain all of the infrastructure code you need to extend and operate the environment. For you to have access to all the code, you should copy this code into your newly created _infrastructure-live_ repo once the deployment is done. +In your repo, you will find two scripts: -## Set up the machine user +- `bootstrap_unix.sh` +- `bootstrap_windows.py` -Whatever VCS platform you are using, do this: +Both scripts will: -1. In GitHub, create a new user account, then create a [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). -1. In the ref arch form, `MachineUserGitUsername` and `MachineUserGitEmail` is where you enter this account’s details. -1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. -1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. -1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. -1. Once the secret is created, **make a note of the ARN**. -1. In the ref arch form, `VCSPATSecretsManagerARN` is where you enter this ARN. +1. Sanity check that you have access to the required organizations. +2. Install the Gruntwork command line tool, which does all the heavy lifting for you +3. Run the Gruntwork wizard for you, which helps you: + - Provision your AWS accounts + - Register domains + - Set up your VCS token secrets + - Fill in your reference-architecture-form.yml file with valid values + - Commit and push your form to GitHub and open a pull request -If you are using GitHub as your VCS, you’re done with this section! If you’re using GitLab or BitBucket, do the following: +Run the corresponding script based on your platform: -- For GitLab, use [these instructions](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), and - grant the following scopes (NOTE: `api`, `read_user`, and `read_api` scopes are only used for uploading the public SSH - key for the user. You can replace the token with a new one that only has `write_repository` permission after the - Reference Architecture is deployed.): +### Linux or Mac OS - - `write_repository` - - `api` - - `read_user` - - `read_api` +```bash +export GITHUB_OAUTH_TOKEN= +./bootstrap_unix.sh +``` -- For Bitbucket, use [these instructions](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/), and - grant the following scopes (NOTE: `Account:Write` is only used for uploading the public SSH key for the user. You can - replace the token with a new one that only has `Repositories:Write` permission after the Reference Architecture is - deployed.): +### Windows - - `Repositories:Write` - - `Account:Write` +Install python, and then run: -- Then create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. **Note the ARN, as in the GitHub step above**. +``` +$env:GITHUB_OAUTH_TOKEN = 'YOUR GITHUB PERSONAL ACCESS TOKEN' +python3 bootstrap_windows.py +``` -- In the ref arch form, `GitHubPATSecretsManagerARN` is where you enter this ARN. +## 6. Iterate on your form and push your changes up to run your Preflight Checks -### Explanation +![Gruntwork Preflight Checks on GitHub](/img/guides/reference-architecture/configuration-guide/preflight-checks.png) -The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. +Once your form is filled in and pushed to GitHub, our GitHub automations will take over. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: -You need one [machine user in GitHub](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) to access the repos in the Gruntwork IaC Library. If you’re not using GitHub, (e.g., in BitBucket or GitLab), you’ll need to create a machine user for that VCS. +![Gruntwork Preflight Checks](/img/guides/reference-architecture/configuration-guide/preflight-checks-preview.png) -## Fill out the reference architecture form +You can then locally iterate on your form by editing `reference-architecture-form.yml` on the `ref-arch-form` branch and pushing your changes up to GitHub. Each time you make a new commit and push it, the Gruntwork _Preflight Checks_ will be run against your form. -The [reference architecture form](https://github.com/gruntwork-clients/infrastructure-live/blob/main/reference-architecture-form.yml) is a [YAML file](https://en.wikipedia.org/wiki/YAML) that contains all the fields that Gruntwork needs to deploy your reference architecture. +## Next Steps -You’ll need all the information you’ve noted in the previous steps. This is where you’ll also be able to customize your infrastructure by choosing a compute option (e.g. ASG, ECS, or EKS), a cache cluster (Redis or Memcached), and a database (e.g. MySQL, PostgreSQL, Aurora, etc). The form contains detailed descriptions of each field. +Once all your _Preflight Checks_ pass, you can merge your pull request, which will commence your Ref Arch deployment. -YAML files are space-sensitive. As you edit the file, be sure to retain the correct whitespace! This should be apparent as you review the file. +Gruntwork engineers are automatically notified of each new Ref Arch deployment, so there's no need to reach out to support just to inform us that your deployment has commenced. -1. Open `reference-architecture-form.yml` in a text editor. -1. Update the _replace-me_ placeholder text in each field. Use double quotes (`""`) to wrap the values, as shown in the examples. +Gruntwork engineers will monitor your deployment and receive notifications about failures and issues that may require intervention to resolve. -If you’re unsure about how to answer any of the questions, email and let us know! +Gruntwork engineers rotate through all active deployments to fix up issues preventing them from making forward progress. In general, deployments take "A few days", although there are plenty of variables outside of our control that can occasionally interfere with a deployment, and which may take longer to remediate. -## Complete the set up process and open a pull request to engage our GitHub Automations +Gruntwork engineers will reach out to you to communicate a status update or next steps if your deployment requires additional intervention to complete. -1. Review your changes. If you notice any errors, correct them, and rerun: +## Manual setup instructions - ```bash - git diff - ``` +
+ +Click here if you would like to perform the setup actions manually + -1. Commit the changes and push to the remote repository: +Visit [the Gruntwork releases page](https://github.com/gruntwork-io/gruntwork/releases) - ```bash - git add reference-architecture-form.yml - git commit -m 'Completed reference architecture form.' - git push origin ref-arch-form - ``` +Find and download the correct binary for your platform. -1. [Open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). +### Mac and Linux instructions -## Use Preflight Checks to iterate on your form and fix any configuration issues +Mac and Linux users, move it into `/usr/local/bin/`. For example, assuming you downloaded `gruntwork_linux_amd64`: -![Gruntwork Preflight Checks on GitHub](/img/guides/reference-architecture/configuration-guide/preflight-checks.png) +`sudo mv ~/Downloads/gruntwork_linux_amd64 /usr/local/bin/gruntwork` -Once your form is filled in and pushed to GitHub, our GitHub automations will take over. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: +Make the binary executable -![Gruntwork Preflight Checks](/img/guides/reference-architecture/configuration-guide/preflight-checks-preview.png) +`chmod +x /usr/local/bin/gruntwork` -You can then locally iterate on your form by editing `reference-architecture-form.yml` on the `ref-arch-form` branch and pushing your changes up to GitHub. Each time you make a new commit and push it, the Gruntwork _Preflight Checks_ will be run against your form. +Run the setup wizard -Keep iterating on your form and pushing new commits up until the Preflight Checks check passes and you see no more error annotations on your pull request. +`gruntwork wizard` -## Next Steps +### Windows users -Once all your _Preflight Checks_ pass, you can merge your pull request, which will commence your Ref Arch deployment. +Download and move your binary to your `C:\Program Files` directory. -Gruntwork engineers are automatically notified of each new Ref Arch deployment, so there's no need to reach out to support just to inform us that your deployment has commenced. +Append the full path to your `gruntwork` binary to your system's PATH. -Gruntwork engineers will monitor your deployment and receive notifications about failures and issues that may require intervention to resolve. +Run the setup wizard -Gruntwork engineers rotate through all active deployments to fix up issues preventing them from making forward progress. In general, deployments take "A few days", although there are plenty of variables outside of our control that can occasionally interfere with a deployment, and which may take longer to remediate. +`gruntwork wizard` -Gruntwork engineers will reach out to you to communicate a status update or next steps if your deployment requires additional intervention to complete. +
+ +## Frequently Asked Questions (F.A.Q) + +
+Click to expand the FAQ section + +_Why do I need to create another repository? Can't I use this repository for my infrastructure code?_ + +Our Reference Architecture deployment process depends on having access to the code. In lieu of requesting for access to +a repository that you own, we use this current repository in the `gruntwork-clients` GitHub organization to stage the +code for the Reference Architecture deployment. -## Appendix: How to create a secret for the VCS token in AWS Secrets Manager +This code should be moved to a repository that you have full control over once everything is deployed. + + +_Why do I need a machine user?_ + +The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. + +You need one [machine user in GitHub](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) to access the repos in the Gruntwork IaC Library. + + +_What are the various Ref Arch accounts used for?_ + +This is the breakdown of AWS accounts in the Reference Architecture: + +- **Security**: for centralized authentication to other accounts, including management of IAM users, groups, and roles. +- **Logs**: A log archive account that contains a central Amazon S3 bucket for storing copies of all AWS CloudTrail and AWS Config log files. +- **Shared**: Shared services account for sharing resources such as Amazon Machine Images (AMIs) and Docker images with other accounts. This account can also be used to provide common infrastructure such as monitoring systems (e.g. Grafana) with other accounts. +- **Dev**: A dedicated app account for development purposes, intended to isolate early development releases from the rest of your infrastructure. +- **Stage**: A dedicated app account for hosting staging, testing, and/or QA environments. +- **Prod**: A dedicated app account for production deployments, intended for live environments used by customers. + + +_Where can I read the Ref Arch Setup FAQ?_ + +Please find our [Reference Architecture Pre-Deployment FAQ page here](https://docs.gruntwork.io/faq/ref-arch-predeployment/). + + +_How do I commit and push my form changes?_ + +Committing changes and pushing to the remote repository: + +```bash +git add reference-architecture-form.yml +git commit -m 'Completed reference architecture form.' +git push origin ref-arch-form +``` + + +_How do I open a pull request with my changes?_ + +[See the GitHub docs on how to open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). + + +_How do I create a secret for the VCS token in AWS Secrets Manager?_ To create a secret in AWS Secrets Manager, first open the AWS console for the _shared_ AWS account, and navigate to the Secrets Manager console. @@ -254,3 +319,5 @@ Choose a name for the secret (we’ve chosen _GitHubPAT_ here), then click _Next ![](/img/guides/reference-architecture/configuration-guide/SM5.png) In the ref arch form, `VCSPATSecretsManagerARN` is where you enter this ARN. + +
\ No newline at end of file diff --git a/docs/guides/reference-architecture/configuration-guide/index.md b/docs/guides/reference-architecture/configuration-guide/index.md index 289c3933d2..04bdf7a5c8 100644 --- a/docs/guides/reference-architecture/configuration-guide/index.md +++ b/docs/guides/reference-architecture/configuration-guide/index.md @@ -1,6 +1,6 @@ # Gruntwork Reference Architecture Setup Instructions -This repository is used to generate the code to deploy and manage the [the Gruntwork Reference Architecture](https://gruntwork.io/reference-architecture/). When we have finished the initial deployment, all of the code will be committed to this repository. We will then hand off the architecture for you to use, and we will include instructions for copying the code to your own repository outside of the `gruntwork-clients` GitHub organization. +This repository is used to generate the code to deploy and manage the [the Gruntwork Reference Architecture](https://gruntwork.io/reference-architecture/). You will receive an automated email at the end of the deployment indicating that the initial deployment has finished, which includes instructions for copying the code to your own repository outside of the `gruntwork-clients` GitHub organization. ![Landing Zone Reference Architecture](/img/guides/reference-architecture/configuration-guide/landing-zone-ref-arch.png) @@ -18,220 +18,285 @@ Caveat: at this time, the Reference Architecture does not configure or manage th ::: -## Clone this repository +## 1. Create an infrastructure-live repository -The very first step is to clone this repository to your local machine. You must have Git installed on your machine. Refer to [these instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install Git on your platform. +1. Create a new repository in your VCS platform. We recommend naming it _infrastructure-live_. +1. Keep this repo handy, as you'll be prompted for the following information in a subsequent step: + - HTTPS URL (e.g. `https://github.com/gruntwork-io/infrastructure-live`) + - SSH URL (e.g. `git@github.com:gruntwork-io/infrastructure-live.git`) + - Default branch (e.g. `main` or `master`) -1. Clone the repository. +## 2. Set up the machine user - ```bash - git clone git@github.com:gruntwork-clients/.git - ``` +The next step is to configure the Machine User Personal Access Token(s) -1. Check out a new branch with your changes: +If you are using GitHub to host your `infrastructure-live` repository, you will only need the one +personal access token as the permissions will allow access to both your `infrastructure-live` repo and +Gruntwork's private repositories. - ```bash - git checkout -b ref-arch-form - ``` +If you are using GitLab or Bitbucket to host your `infrastructure-live` repository, you will need a +Personal Access Token for your respective VCS in addition to a GitHub PAT for access to the +private Gruntwork GitHub repositories. Note that at this time GitHub is the only supported VCS for +Reference Architecture deployments. -## Create and configure AWS Accounts +First we will create a GitHub Personal Access Token: -1. Create the following AWS accounts: +1. In GitHub, create a new user account, then create a [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). +1. In the ref arch form, `MachineUserGitUsername` and `MachineUserGitEmail` is where you enter this account’s details. +1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. +1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. You should include `GitHub-MachineUser-PAT` as part of the name/description of the token to be able to identify it later. +1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret, but it's recommended you include `GitHub-MachineUser-PAT` as part of the name to be able to identify it later. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. +1. Once the secret is created, **make a note of the ARN**. - - Security: for centralized authentication to other accounts, including management of IAM users, groups, and roles. - - Logs: A log archive account that contains a central Amazon S3 bucket for storing copies of all AWS CloudTrail and AWS Config log files. - - Shared: Shared services account for sharing resources such as Amazon Machine Images (AMIs) and Docker images with other accounts. This account can also be used to provide common infrastructure such as self-hosted CI/CD systems (e.g. Jenkins) and monitoring systems (e.g. Grafana) with other accounts. - - Dev: A dedicated app account for development purposes, intended to isolate early development releases from the rest of your infrastructure. - - Stage: A dedicated app account for hosting staging, testing, and/or QA environments. - - Prod: A dedicated app account for production deployments, intended for live environments used by customers. +If your `infrastructure-live` repository is hosted in GitHub, enter the secrets manager ARN from the above steps into the Ref Arch `VCSPATSecretsManagerARN` field. This token will provide access to both your `infrastructure-live` repo and to the Gruntwork private repositories and you are done setting up the machine user! You can skip to the next section. -1. Once they are created, record the account IDs. +If your `infrastructure-live` repository is hosted in BitBucket or GitLab, expand the `BitBucket / GitLab` tab below for more details. -1. These account IDs will go under `AWSAccounts` in the reference architecture form. +
BitBucket / GitLab -For the best results, use [Gruntwork CLI](https://github.com/gruntwork-io/gruntwork) to create the accounts. The Gruntwork CLI automatically grants Gruntwork engineers access to your accounts through an IAM role. However, **if you choose to create the accounts manually and do not use the Gruntwork CLI, you still MUST run the `gruntwork aws grant` command to grant the Gruntwork team access to these accounts**. MFA is enforced for all Gruntwork access. You can use the same tool to revoke access when the deployment is complete. See [CLI documentation](https://github.com/gruntwork-io/gruntwork) for details. +> Note that at this time, GitHub is the only supported VCS for Reference Architecture deployments. -:::info +If you are using GitLab or BitBucket to host your `infrastructure-live` repository, enter the secrets manager ARN from the above steps into the `GitHubPATSecretsManagerARN` field. Since this token will provide access to only the Gruntwork private repositories, we will next need to create the token to access your `infrastructure-live` repo. -- The accounts must be new, empty accounts, with no resources present. That means no EC2 instances, RDS databases, CloudTrail trails, AWS Config recorders, etc. -- Do not apply any Service Control Policies to the accounts as they may interfere with the Terraform resources in the Reference Architecture. -- You can name the _dev, stage,_ and _prod_ accounts anything you like, but the others must be named _shared_, _logs_, and _security_. +- For GitLab, use [these instructions](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), and + grant the following scopes (NOTE: `api`, `read_user`, and `read_api` scopes are only used for uploading the public SSH + key for the user. You can replace the token with a new one that only has `write_repository` permission after the + Reference Architecture is deployed.): -::: + - `write_repository` + - `api` + - `read_user` + - `read_api` -## Purchase and register domain names + You should name the token `GitLab-MachineUser-PAT` to be able to identify it later -The Reference Architecture uses Route 53 to setup public DNS records for several aspects of the infrastructure, such as the network bastion and the [AWS Sample App](https://github.com/gruntwork-io/aws-sample-app/). For this to work, we ask that you set up domains for each application account (_dev_, _stage_, and _prod_) and, if you’re using Jenkins, in the _shared_ account. These domains should be configured as public hosted zones in Route 53. There are two options for domain registration: +- For Bitbucket, use [these instructions](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/), and + grant the following scopes (NOTE: `Account:Write` is only used for uploading the public SSH key for the user. You can + replace the token with a new one that only has `Repositories:Write` permission after the Reference Architecture is + deployed.): -### Option A: Register one domain per account (recommended!) + - `Repositories:Write` + - `Account:Write` -Follow the instructions in the [Gruntwork CLI documentation](https://github.com/gruntwork-io/gruntwork#create-the-aws-accounts) to complete this step. + You should name the token `BitBucket-MachineUser-PAT` to be able to identify it later. -If you choose not to use the Gruntwork CLI, you may either [register a new domain using Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) yourself, or you may register a domain using an external provider, and [set up Route 53 as the DNS service for that domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/MigratingDNS.html). +Now you will need to create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. You should name the secret following the above naming convention (`GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT`). Once the secret is created, **make a note of the ARN**. -#### Explanation +Finally, enter the newly created `GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT` secrets manager ARN from the above step into the Ref Arch `VCSPATSecretsManagerARN` field. -You’ll be using Route 53 to register a separate domain name in the _dev_, _stage_, _prod_ accounts, as well as _shared_ if you are using Jenkins. +
-This is the more secure option because: +### Explanation -- Reduces the chance of making changes to the wrong domain: e.g., accidentally update prod while working on dev. -- Less likely to make a mistake such as issuing cookies for the wrong domain: e.g., accidentally create a cookie in dev that is also accepted in prod. -- Lowers the possibility of issuing TLS certificates for the wrong domain: e.g., accidentally create a TLS cert in dev that is also accepted in prod. +The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. -Most domains in Route 53 are just $12, so this should not add much expense. +There are two primary uses for the Machine User: +- Accessing Gruntwork private repositories hosted in GitHub +- Accessing your `infrastructure-live` repository that is hosted in GitHub, BitBucket, or GitLab -### Option B: Register one domain with subdomains in each account +You need at least one [machine user in GitHub](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) to access the repos in the Gruntwork IaC Library private repositories. If you are using GitHub to host your `infrastructure-live` repo then this machine user PAT will also grant all the access you will need. -Follow the instructions in the [Route 53 documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html) to delegate a subdomain. We recommend that you manage the top-level domain as a hosted zone in either the _security_ or the root account of your AWS Organization, and delegate subdomains to each of the other accounts (e.g. _dev_, _stage_, _prod_, and _shared_ if using Jenkins). +If you have chosen Bitbucket or GitLab to host your `infrastructure-live` repo, then you will need a second PAT that grants access to that repo. -#### Explanation +In the `reference-architecture-form.yml` there are two fields that relate to the machine user PAT(s) +- `VCSPATSecretsManagerARN` +- `GitHubPATSecretsManagerARN` -You’ll be purchasing one domain (e.g. _example.com_), and delegate subdomains to each account (e.g. _dev.example.com_, _stage.example.com_, etc.). The upside of this approach is that there is a single [top-level domain namespace](https://en.wikipedia.org/wiki/Top-level_domain) (e.g. _example.com_) for all of your accounts. However, there are several important downsides: +`VCSPATSecretsManagerARN` is for the secrets manager ARN that contains the PAT for your VCS system hosting your `infrastructure-live` repo. If your VCS happens to be GitHub then it automatically grants all the access you need and you can set `GitHubPATSecretsManagerARN` to an empty string as it is not needed. -- You may accidentally make a mistake when managing the top-level domain that may impact all of your subdomains. -- A subdomain such as `prod.example.com` is less intuitive for users. This can be mitigated by choosing a top-level domain for prod, and subdomains for non-production environments. -- You must be careful about issuing cookies with the [`Set-Cookie` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) so that cookies are valid only for the intended subdomain. +Since BitBucket and GitLab PATs wouldn't grant access to GitHub, the additional `GitHubPATSecretsManagerARN` is needed in order to access Gruntwork Private IaC Library repositories. -## Confirm the domain configuration +## 3. Clone this repository -Once everything is configured up correctly, check that you can resolve the domains and confirm the nameserver settings using the `dig` command on MacOS or Linux, or `nslookup` on Windows. For example, the hosted zone configuration for the _gruntwork.in_ domain used by Gruntwork for testing looks like this in Route 53: +Use Git to clone this repository. If you do not have `git` available on your system, refer to [these instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install Git on your platform. -![](/img/guides/reference-architecture/configuration-guide/gruntwork.in.ns.png) +1. Clone the repository. -1. On MacOS or Linux, use `dig` to confirm that the domain can be resolved correctly over the Internet: + ```bash + git clone git@github.com:gruntwork-clients/.git + ``` - ```bash - $ dig gruntwork.in +short ns - ns-1202.awsdns-22.org. - ns-1749.awsdns-26.co.uk. - ns-559.awsdns-05.net. - ns-67.awsdns-08.com. - ``` +## 4. Authenticate to AWS on your command line -1. On Windows, use `nslookup`: +The bootstrap script will prepare your AWS accounts for deployment. To use the bootstrap script and form filling wizard, +the CLI will need access to your AWS Root account you would like to use for the Reference Architecture. The Root account +is where the AWS Organization is defined. - ```bash - $ nslookup -type=mx gruntwork.in - Server: 8.8.8.8 - Address: 8.8.8.8#53 +1. If you do not have a Root account (an AWS account with AWS Organizations setup) already, create one. We recommend + creating a brand new account to use as the Root account if you are not already using AWS Organizations, and import + your existing AWS Account(s) to it as members. +1. Setup AWS Organizations in your Root account if you haven't already. Refer to [this + documentation](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_tutorials_basic.html) for instructions + on how to setup AWS Organizations. +1. If you do not have one already, [create an IAM + User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) with administrator permissions (attach + the `AdministratorAccess` IAM policy). Make sure to create AWS Access Keys for the IAM User as well. +1. Once you have an IAM User and AWS Access Keys for accessing the Root account, configure your terminal to be able to + authenticate to the IAM User. If you do not know how to do this, refer to our [Comprehensive Guide to Authenticating + to AWS on the Command + Line](https://blog.gruntwork.io/a-comprehensive-guide-to-authenticating-to-aws-on-the-command-line-63656a686799). - Non-authoritative answer: - gruntwork.in nameserver = ns-1202.awsdns-22.org. - gruntwork.in nameserver = ns-1749.awsdns-26.co.uk. - gruntwork.in nameserver = ns-559.awsdns-05.net. - gruntwork.in nameserver = ns-67.awsdns-08.com. - ``` +## 5. Run the bootstrap script -Notice that the NS records in the image match the values returned by the commands. The same process applies if you’re using subdomains. Make sure to validate each domain or subdomain in this manner. +We're ready to run the wizard to fill in your `reference-architecture-form.yml` with valid values. -## Create an infrastructure-live repository +Before running the wizard, ensure you have completed steps 1, 2 and 3 and that you have the following values ready at hand: -1. Create a new repository in your VCS platform. We recommend naming it _infrastructure-live_. -2. In the ref arch form, `InfraLiveRepoURL` is where you enter this repo’s HTTPS URL (e.g. ). -3. `InfraLiveRepoSSHURL` is where you enter this repo’s SSH URL (e.g. :gruntwork-io/infrastructure-live.git). -4. `InfraLiveDefaultBranchName` is where you enter your repo’s default branch name (e.g. main). +- Personal Access Token for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. + - If you do not have one, generate a new Personal Access Token with `repo` level permissions. +- GitHub Machine User Personal Access Token (required in all cases) +- VCS Machine User Personal Access Token (only required if your ultimate infrastructure-live destination is NOT GitHub) +- The HTTPS URL to your VCS `infrastructure-live` repo (e.g., `https://github.com/gruntwork-io/infrastructure-live.git`) +- The SSH URL to your same VCS `infrastructure-live` repo (e.g., `git@github.com:gruntwork-io/infrastructure-live.git`) -This current repository will contain all of the infrastructure code you need to extend and operate the environment. For you to have access to all the code, you should copy this code into your newly created _infrastructure-live_ repo once the deployment is done. +In your repo, you will find two scripts: -## Set up the machine user +- `bootstrap_unix.sh` +- `bootstrap_windows.py` -Whatever VCS platform you are using, do this: +Both scripts will: -1. In GitHub, create a new user account, then create a [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). -1. In the ref arch form, `MachineUserGitUsername` and `MachineUserGitEmail` is where you enter this account’s details. -1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. -1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. -1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. -1. Once the secret is created, **make a note of the ARN**. -1. In the ref arch form, `VCSPATSecretsManagerARN` is where you enter this ARN. +1. Sanity check that you have access to the required organizations. +2. Install the Gruntwork command line tool, which does all the heavy lifting for you +3. Run the Gruntwork wizard for you, which helps you: + - Provision your AWS accounts + - Register domains + - Set up your VCS token secrets + - Fill in your reference-architecture-form.yml file with valid values + - Commit and push your form to GitHub and open a pull request -If you are using GitHub as your VCS, you’re done with this section! If you’re using GitLab or BitBucket, do the following: +Run the corresponding script based on your platform: -- For GitLab, use [these instructions](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), and - grant the following scopes (NOTE: `api`, `read_user`, and `read_api` scopes are only used for uploading the public SSH - key for the user. You can replace the token with a new one that only has `write_repository` permission after the - Reference Architecture is deployed.): +### Linux or Mac OS - - `write_repository` - - `api` - - `read_user` - - `read_api` +```bash +export GITHUB_OAUTH_TOKEN= +./bootstrap_unix.sh +``` -- For Bitbucket, use [these instructions](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/), and - grant the following scopes (NOTE: `Account:Write` is only used for uploading the public SSH key for the user. You can - replace the token with a new one that only has `Repositories:Write` permission after the Reference Architecture is - deployed.): +### Windows - - `Repositories:Write` - - `Account:Write` +Install python, and then run: -- Then create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. **Note the ARN, as in the GitHub step above**. +``` +$env:GITHUB_OAUTH_TOKEN = 'YOUR GITHUB PERSONAL ACCESS TOKEN' +python3 bootstrap_windows.py +``` -- In the ref arch form, `GitHubPATSecretsManagerARN` is where you enter this ARN. +## 6. Iterate on your form and push your changes up to run your Preflight Checks -### Explanation +![Gruntwork Preflight Checks on GitHub](/img/guides/reference-architecture/configuration-guide/preflight-checks.png) -The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. +Once your form is filled in and pushed to GitHub, our GitHub automations will take over. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: -You need one [machine user in GitHub](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) to access the repos in the Gruntwork IaC Library. If you’re not using GitHub, (e.g., in BitBucket or GitLab), you’ll need to create a machine user for that VCS. +![Gruntwork Preflight Checks](/img/guides/reference-architecture/configuration-guide/preflight-checks-preview.png) -## Fill out the reference architecture form +You can then locally iterate on your form by editing `reference-architecture-form.yml` on the `ref-arch-form` branch and pushing your changes up to GitHub. Each time you make a new commit and push it, the Gruntwork _Preflight Checks_ will be run against your form. -The [reference architecture form](https://github.com/gruntwork-clients/infrastructure-live/blob/main/reference-architecture-form.yml) is a [YAML file](https://en.wikipedia.org/wiki/YAML) that contains all the fields that Gruntwork needs to deploy your reference architecture. +## Next Steps -You’ll need all the information you’ve noted in the previous steps. This is where you’ll also be able to customize your infrastructure by choosing a compute option (e.g. ASG, ECS, or EKS), a cache cluster (Redis or Memcached), and a database (e.g. MySQL, PostgreSQL, Aurora, etc). The form contains detailed descriptions of each field. +Once all your _Preflight Checks_ pass, you can merge your pull request, which will commence your Ref Arch deployment. -YAML files are space-sensitive. As you edit the file, be sure to retain the correct whitespace! This should be apparent as you review the file. +Gruntwork engineers are automatically notified of each new Ref Arch deployment, so there's no need to reach out to support just to inform us that your deployment has commenced. -1. Open `reference-architecture-form.yml` in a text editor. -1. Update the _replace-me_ placeholder text in each field. Use double quotes (`""`) to wrap the values, as shown in the examples. +Gruntwork engineers will monitor your deployment and receive notifications about failures and issues that may require intervention to resolve. -If you’re unsure about how to answer any of the questions, email and let us know! +Gruntwork engineers rotate through all active deployments to fix up issues preventing them from making forward progress. In general, deployments take "A few days", although there are plenty of variables outside of our control that can occasionally interfere with a deployment, and which may take longer to remediate. -## Complete the set up process and open a pull request to engage our GitHub Automations +Gruntwork engineers will reach out to you to communicate a status update or next steps if your deployment requires additional intervention to complete. -1. Review your changes. If you notice any errors, correct them, and rerun: +## Manual setup instructions - ```bash - git diff - ``` +
+ +Click here if you would like to perform the setup actions manually + -1. Commit the changes and push to the remote repository: +Visit [the Gruntwork releases page](https://github.com/gruntwork-io/gruntwork/releases) - ```bash - git add reference-architecture-form.yml - git commit -m 'Completed reference architecture form.' - git push origin ref-arch-form - ``` +Find and download the correct binary for your platform. -1. [Open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). +### Mac and Linux instructions -## Use Preflight Checks to iterate on your form and fix any configuration issues +Mac and Linux users, move it into `/usr/local/bin/`. For example, assuming you downloaded `gruntwork_linux_amd64`: -![Gruntwork Preflight Checks on GitHub](/img/guides/reference-architecture/configuration-guide/preflight-checks.png) +`sudo mv ~/Downloads/gruntwork_linux_amd64 /usr/local/bin/gruntwork` -Once your form is filled in and pushed to GitHub, our GitHub automations will take over. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: +Make the binary executable -![Gruntwork Preflight Checks](/img/guides/reference-architecture/configuration-guide/preflight-checks-preview.png) +`chmod +x /usr/local/bin/gruntwork` -You can then locally iterate on your form by editing `reference-architecture-form.yml` on the `ref-arch-form` branch and pushing your changes up to GitHub. Each time you make a new commit and push it, the Gruntwork _Preflight Checks_ will be run against your form. +Run the setup wizard -Keep iterating on your form and pushing new commits up until the Preflight Checks check passes and you see no more error annotations on your pull request. +`gruntwork wizard` -## Next Steps +### Windows users -Once all your _Preflight Checks_ pass, you can merge your pull request, which will commence your Ref Arch deployment. +Download and move your binary to your `C:\Program Files` directory. -Gruntwork engineers are automatically notified of each new Ref Arch deployment, so there's no need to reach out to support just to inform us that your deployment has commenced. +Append the full path to your `gruntwork` binary to your system's PATH. -Gruntwork engineers will monitor your deployment and receive notifications about failures and issues that may require intervention to resolve. +Run the setup wizard -Gruntwork engineers rotate through all active deployments to fix up issues preventing them from making forward progress. In general, deployments take "A few days", although there are plenty of variables outside of our control that can occasionally interfere with a deployment, and which may take longer to remediate. +`gruntwork wizard` + +
+ +## Frequently Asked Questions (F.A.Q) + +
+Click to expand the FAQ section + +_Why do I need to create another repository? Can't I use this repository for my infrastructure code?_ + +Our Reference Architecture deployment process depends on having access to the code. In lieu of requesting for access to +a repository that you own, we use this current repository in the `gruntwork-clients` GitHub organization to stage the +code for the Reference Architecture deployment. + +This code should be moved to a repository that you have full control over once everything is deployed. + + +_Why do I need a machine user?_ + +The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. + +You need one [machine user in GitHub](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) to access the repos in the Gruntwork IaC Library. + + +_What are the various Ref Arch accounts used for?_ + +This is the breakdown of AWS accounts in the Reference Architecture: + +- **Security**: for centralized authentication to other accounts, including management of IAM users, groups, and roles. +- **Logs**: A log archive account that contains a central Amazon S3 bucket for storing copies of all AWS CloudTrail and AWS Config log files. +- **Shared**: Shared services account for sharing resources such as Amazon Machine Images (AMIs) and Docker images with other accounts. This account can also be used to provide common infrastructure such as monitoring systems (e.g. Grafana) with other accounts. +- **Dev**: A dedicated app account for development purposes, intended to isolate early development releases from the rest of your infrastructure. +- **Stage**: A dedicated app account for hosting staging, testing, and/or QA environments. +- **Prod**: A dedicated app account for production deployments, intended for live environments used by customers. + + +_Where can I read the Ref Arch Setup FAQ?_ + +Please find our [Reference Architecture Pre-Deployment FAQ page here](https://docs.gruntwork.io/faq/ref-arch-predeployment/). + + +_How do I commit and push my form changes?_ + +Committing changes and pushing to the remote repository: + +```bash +git add reference-architecture-form.yml +git commit -m 'Completed reference architecture form.' +git push origin ref-arch-form +``` + + +_How do I open a pull request with my changes?_ + +[See the GitHub docs on how to open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). -Gruntwork engineers will reach out to you to communicate a status update or next steps if your deployment requires additional intervention to complete. -## Appendix: How to create a secret for the VCS token in AWS Secrets Manager +_How do I create a secret for the VCS token in AWS Secrets Manager?_ To create a secret in AWS Secrets Manager, first open the AWS console for the _shared_ AWS account, and navigate to the Secrets Manager console. @@ -255,10 +320,11 @@ Choose a name for the secret (we’ve chosen _GitHubPAT_ here), then click _Next In the ref arch form, `VCSPATSecretsManagerARN` is where you enter this ARN. +
From 490c1fdc4ffcf9dfb0635fdec324c04927e6ae8b Mon Sep 17 00:00:00 2001 From: arsci Date: Wed, 15 Mar 2023 08:27:17 -0700 Subject: [PATCH 2/6] add docs --- docs/guides/stay-up-to-date/index.md | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/docs/guides/stay-up-to-date/index.md b/docs/guides/stay-up-to-date/index.md index 98ca5d7898..d6d6f16e0b 100644 --- a/docs/guides/stay-up-to-date/index.md +++ b/docs/guides/stay-up-to-date/index.md @@ -16,22 +16,7 @@ import CardGroup from "/src/components/CardGroup" - - - - - - - - - - - - - - - - + @@ -113,7 +98,7 @@ href="/guides/stay-up-to-date/cis/cis-1.5.0" From e45977331bfeed5f85553be6749d6a24bf8f0ef3 Mon Sep 17 00:00:00 2001 From: arsci Date: Wed, 15 Mar 2023 14:39:01 -0700 Subject: [PATCH 3/6] kick build From d05fa7df44d6117e080ed9109a81a8533cde24c7 Mon Sep 17 00:00:00 2001 From: arsci Date: Wed, 15 Mar 2023 18:29:45 -0700 Subject: [PATCH 4/6] add images --- .../configuration-guide/index.md | 10 ++++++++-- .../configuration-guide/index.md | 12 +++++++++--- .../configuration-guide/vcs-github-pat.png | Bin 0 -> 23664 bytes .../configuration-guide/vcs-pat.png | Bin 0 -> 15420 bytes 4 files changed, 17 insertions(+), 5 deletions(-) create mode 100644 static/img/guides/reference-architecture/configuration-guide/vcs-github-pat.png create mode 100644 static/img/guides/reference-architecture/configuration-guide/vcs-pat.png diff --git a/_docs-sources/guides/reference-architecture/configuration-guide/index.md b/_docs-sources/guides/reference-architecture/configuration-guide/index.md index fd848ce397..57c059e5ef 100644 --- a/_docs-sources/guides/reference-architecture/configuration-guide/index.md +++ b/_docs-sources/guides/reference-architecture/configuration-guide/index.md @@ -52,7 +52,7 @@ If your `infrastructure-live` repository is hosted in GitHub, enter the secrets If your `infrastructure-live` repository is hosted in BitBucket or GitLab, expand the `BitBucket / GitLab` tab below for more details. -
BitBucket / GitLab +
BitBucket / GitLab Guide > Note that at this time, GitHub is the only supported VCS for Reference Architecture deployments. @@ -86,7 +86,7 @@ Finally, enter the newly created `GitLab-MachineUser-PAT`/`BitBucket-MachineUser
-### Explanation +
Explanation The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. @@ -106,6 +106,12 @@ In the `reference-architecture-form.yml` there are two fields that relate to the Since BitBucket and GitLab PATs wouldn't grant access to GitHub, the additional `GitHubPATSecretsManagerARN` is needed in order to access Gruntwork Private IaC Library repositories. +![VCSPATSecretsManagerARN](/img/guides/reference-architecture/configuration-guide/vcs-pat.png) + +![GitHubPATSecretsManagerARN](/img/guides/reference-architecture/configuration-guide/vcs-github-pat.png) + +
+ ## 3. Clone this repository Use Git to clone this repository. If you do not have `git` available on your system, refer to [these instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install Git on your platform. diff --git a/docs/guides/reference-architecture/configuration-guide/index.md b/docs/guides/reference-architecture/configuration-guide/index.md index 04bdf7a5c8..984eb7d03d 100644 --- a/docs/guides/reference-architecture/configuration-guide/index.md +++ b/docs/guides/reference-architecture/configuration-guide/index.md @@ -52,7 +52,7 @@ If your `infrastructure-live` repository is hosted in GitHub, enter the secrets If your `infrastructure-live` repository is hosted in BitBucket or GitLab, expand the `BitBucket / GitLab` tab below for more details. -
BitBucket / GitLab +
BitBucket / GitLab Guide > Note that at this time, GitHub is the only supported VCS for Reference Architecture deployments. @@ -86,7 +86,7 @@ Finally, enter the newly created `GitLab-MachineUser-PAT`/`BitBucket-MachineUser
-### Explanation +
Explanation The reference architecture includes an end-to-end [CI/CD pipeline for infrastructure](https://gruntwork.io/pipelines/). You’ll need to set up a _machine user_ (also known as a _service account_) that will automatically checkout your code, push artifacts (such as Docker images and AMIs), and access the Gruntwork IaC Library. @@ -106,6 +106,12 @@ In the `reference-architecture-form.yml` there are two fields that relate to the Since BitBucket and GitLab PATs wouldn't grant access to GitHub, the additional `GitHubPATSecretsManagerARN` is needed in order to access Gruntwork Private IaC Library repositories. +![VCSPATSecretsManagerARN](/img/guides/reference-architecture/configuration-guide/vcs-pat.png) + +![GitHubPATSecretsManagerARN](/img/guides/reference-architecture/configuration-guide/vcs-github-pat.png) + +
+ ## 3. Clone this repository Use Git to clone this repository. If you do not have `git` available on your system, refer to [these instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install Git on your platform. @@ -325,6 +331,6 @@ In the ref arch form, `VCSPATSecretsManagerARN` is where you enter this ARN. diff --git a/static/img/guides/reference-architecture/configuration-guide/vcs-github-pat.png b/static/img/guides/reference-architecture/configuration-guide/vcs-github-pat.png new file mode 100644 index 0000000000000000000000000000000000000000..9373614a04bff973f7a33ac738b8eeeeace9c0b4 GIT binary patch literal 23664 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 Is=f&MFUINSPyhe` literal 0 HcmV?d00001 diff --git a/static/img/guides/reference-architecture/configuration-guide/vcs-pat.png b/static/img/guides/reference-architecture/configuration-guide/vcs-pat.png new file mode 100644 index 0000000000000000000000000000000000000000..ad008f08e030cfc8580419ceae873c4c7657b82a GIT binary patch literal 15420 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 TW Date: Thu, 16 Mar 2023 10:32:46 -0700 Subject: [PATCH 5/6] refactor: add clarification around PAT --- .../configuration-guide/index.md | 14 +++++++------- .../configuration-guide/index.md | 16 ++++++++-------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/_docs-sources/guides/reference-architecture/configuration-guide/index.md b/_docs-sources/guides/reference-architecture/configuration-guide/index.md index 57c059e5ef..ea928d83f0 100644 --- a/_docs-sources/guides/reference-architecture/configuration-guide/index.md +++ b/_docs-sources/guides/reference-architecture/configuration-guide/index.md @@ -28,7 +28,7 @@ Caveat: at this time, the Reference Architecture does not configure or manage th ## 2. Set up the machine user -The next step is to configure the Machine User Personal Access Token(s) +The next step is to configure the Machine User Personal Access Token(s) (PAT) If you are using GitHub to host your `infrastructure-live` repository, you will only need the one personal access token as the permissions will allow access to both your `infrastructure-live` repo and @@ -41,12 +41,12 @@ Reference Architecture deployments. First we will create a GitHub Personal Access Token: -1. In GitHub, create a new user account, then create a [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). +1. In GitHub, create a new user account, then create a [Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). 1. In the ref arch form, `MachineUserGitUsername` and `MachineUserGitEmail` is where you enter this account’s details. 1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. 1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. You should include `GitHub-MachineUser-PAT` as part of the name/description of the token to be able to identify it later. 1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret, but it's recommended you include `GitHub-MachineUser-PAT` as part of the name to be able to identify it later. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. -1. Once the secret is created, **make a note of the ARN**. +1. Once the secret is created, **copy the ARN** to your favorite text editor for later use. If your `infrastructure-live` repository is hosted in GitHub, enter the secrets manager ARN from the above steps into the Ref Arch `VCSPATSecretsManagerARN` field. This token will provide access to both your `infrastructure-live` repo and to the Gruntwork private repositories and you are done setting up the machine user! You can skip to the next section. @@ -149,9 +149,9 @@ We're ready to run the wizard to fill in your `reference-architecture-form.yml` Before running the wizard, ensure you have completed steps 1, 2 and 3 and that you have the following values ready at hand: - Personal Access Token for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. - - If you do not have one, generate a new Personal Access Token with `repo` level permissions. -- GitHub Machine User Personal Access Token (required in all cases) -- VCS Machine User Personal Access Token (only required if your ultimate infrastructure-live destination is NOT GitHub) + - If you do not have one, generate a new PAT with `repo` level permissions. +- GitHub Machine User PAT (required in all cases) +- VCS Machine User PAT (only required if your ultimate infrastructure-live destination is NOT GitHub) - The HTTPS URL to your VCS `infrastructure-live` repo (e.g., `https://github.com/gruntwork-io/infrastructure-live.git`) - The SSH URL to your same VCS `infrastructure-live` repo (e.g., `git@github.com:gruntwork-io/infrastructure-live.git`) @@ -193,7 +193,7 @@ python3 bootstrap_windows.py ![Gruntwork Preflight Checks on GitHub](/img/guides/reference-architecture/configuration-guide/preflight-checks.png) -Once your form is filled in and pushed to GitHub, our GitHub automations will take over. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: +Once your form is filled in and pushed to GitHub, our automations will take over via GitHub Actions. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: ![Gruntwork Preflight Checks](/img/guides/reference-architecture/configuration-guide/preflight-checks-preview.png) diff --git a/docs/guides/reference-architecture/configuration-guide/index.md b/docs/guides/reference-architecture/configuration-guide/index.md index 984eb7d03d..178c84f1ab 100644 --- a/docs/guides/reference-architecture/configuration-guide/index.md +++ b/docs/guides/reference-architecture/configuration-guide/index.md @@ -28,7 +28,7 @@ Caveat: at this time, the Reference Architecture does not configure or manage th ## 2. Set up the machine user -The next step is to configure the Machine User Personal Access Token(s) +The next step is to configure the Machine User Personal Access Token(s) (PAT) If you are using GitHub to host your `infrastructure-live` repository, you will only need the one personal access token as the permissions will allow access to both your `infrastructure-live` repo and @@ -41,12 +41,12 @@ Reference Architecture deployments. First we will create a GitHub Personal Access Token: -1. In GitHub, create a new user account, then create a [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). +1. In GitHub, create a new user account, then create a [Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). 1. In the ref arch form, `MachineUserGitUsername` and `MachineUserGitEmail` is where you enter this account’s details. 1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. 1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. You should include `GitHub-MachineUser-PAT` as part of the name/description of the token to be able to identify it later. 1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret, but it's recommended you include `GitHub-MachineUser-PAT` as part of the name to be able to identify it later. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. -1. Once the secret is created, **make a note of the ARN**. +1. Once the secret is created, **copy the ARN** to your favorite text editor for later use. If your `infrastructure-live` repository is hosted in GitHub, enter the secrets manager ARN from the above steps into the Ref Arch `VCSPATSecretsManagerARN` field. This token will provide access to both your `infrastructure-live` repo and to the Gruntwork private repositories and you are done setting up the machine user! You can skip to the next section. @@ -149,9 +149,9 @@ We're ready to run the wizard to fill in your `reference-architecture-form.yml` Before running the wizard, ensure you have completed steps 1, 2 and 3 and that you have the following values ready at hand: - Personal Access Token for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. - - If you do not have one, generate a new Personal Access Token with `repo` level permissions. -- GitHub Machine User Personal Access Token (required in all cases) -- VCS Machine User Personal Access Token (only required if your ultimate infrastructure-live destination is NOT GitHub) + - If you do not have one, generate a new PAT with `repo` level permissions. +- GitHub Machine User PAT (required in all cases) +- VCS Machine User PAT (only required if your ultimate infrastructure-live destination is NOT GitHub) - The HTTPS URL to your VCS `infrastructure-live` repo (e.g., `https://github.com/gruntwork-io/infrastructure-live.git`) - The SSH URL to your same VCS `infrastructure-live` repo (e.g., `git@github.com:gruntwork-io/infrastructure-live.git`) @@ -193,7 +193,7 @@ python3 bootstrap_windows.py ![Gruntwork Preflight Checks on GitHub](/img/guides/reference-architecture/configuration-guide/preflight-checks.png) -Once your form is filled in and pushed to GitHub, our GitHub automations will take over. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: +Once your form is filled in and pushed to GitHub, our automations will take over via GitHub Actions. You'll notice a special GitHub check called _Preflight Checks_ that will run against your `reference-architecture-form.yml` file and flag any errors for you directly in your pull request, like so: ![Gruntwork Preflight Checks](/img/guides/reference-architecture/configuration-guide/preflight-checks-preview.png) @@ -331,6 +331,6 @@ In the ref arch form, `VCSPATSecretsManagerARN` is where you enter this ARN. From 4914458b7a640d8b1b7ff52517b1a2c1e24e5e53 Mon Sep 17 00:00:00 2001 From: arsci Date: Fri, 17 Mar 2023 10:27:16 -0700 Subject: [PATCH 6/6] fix: additional PAT references --- .../configuration-guide/index.md | 12 ++++++------ .../configuration-guide/index.md | 14 +++++++------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/_docs-sources/guides/reference-architecture/configuration-guide/index.md b/_docs-sources/guides/reference-architecture/configuration-guide/index.md index ea928d83f0..acb36be795 100644 --- a/_docs-sources/guides/reference-architecture/configuration-guide/index.md +++ b/_docs-sources/guides/reference-architecture/configuration-guide/index.md @@ -31,11 +31,11 @@ Caveat: at this time, the Reference Architecture does not configure or manage th The next step is to configure the Machine User Personal Access Token(s) (PAT) If you are using GitHub to host your `infrastructure-live` repository, you will only need the one -personal access token as the permissions will allow access to both your `infrastructure-live` repo and +PAT as the permissions will allow access to both your `infrastructure-live` repo and Gruntwork's private repositories. If you are using GitLab or Bitbucket to host your `infrastructure-live` repository, you will need a -Personal Access Token for your respective VCS in addition to a GitHub PAT for access to the +PAT for your respective VCS in addition to a GitHub PAT for access to the private Gruntwork GitHub repositories. Note that at this time GitHub is the only supported VCS for Reference Architecture deployments. @@ -46,8 +46,8 @@ First we will create a GitHub Personal Access Token: 1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. 1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. You should include `GitHub-MachineUser-PAT` as part of the name/description of the token to be able to identify it later. 1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret, but it's recommended you include `GitHub-MachineUser-PAT` as part of the name to be able to identify it later. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. -1. Once the secret is created, **copy the ARN** to your favorite text editor for later use. - +1. Once the secret is created, **copy the ARN** to your favorite text editor for the next step. +ß If your `infrastructure-live` repository is hosted in GitHub, enter the secrets manager ARN from the above steps into the Ref Arch `VCSPATSecretsManagerARN` field. This token will provide access to both your `infrastructure-live` repo and to the Gruntwork private repositories and you are done setting up the machine user! You can skip to the next section. If your `infrastructure-live` repository is hosted in BitBucket or GitLab, expand the `BitBucket / GitLab` tab below for more details. @@ -80,7 +80,7 @@ If you are using GitLab or BitBucket to host your `infrastructure-live` reposito You should name the token `BitBucket-MachineUser-PAT` to be able to identify it later. -Now you will need to create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. You should name the secret following the above naming convention (`GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT`). Once the secret is created, **make a note of the ARN**. +Now you will need to create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. You should name the secret following the above naming convention (`GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT`). Once the secret is created, **copy the ARN** to your favorite text editor for the next step. Finally, enter the newly created `GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT` secrets manager ARN from the above step into the Ref Arch `VCSPATSecretsManagerARN` field. @@ -148,7 +148,7 @@ We're ready to run the wizard to fill in your `reference-architecture-form.yml` Before running the wizard, ensure you have completed steps 1, 2 and 3 and that you have the following values ready at hand: -- Personal Access Token for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. +- PAT for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. - If you do not have one, generate a new PAT with `repo` level permissions. - GitHub Machine User PAT (required in all cases) - VCS Machine User PAT (only required if your ultimate infrastructure-live destination is NOT GitHub) diff --git a/docs/guides/reference-architecture/configuration-guide/index.md b/docs/guides/reference-architecture/configuration-guide/index.md index 178c84f1ab..e7a600987c 100644 --- a/docs/guides/reference-architecture/configuration-guide/index.md +++ b/docs/guides/reference-architecture/configuration-guide/index.md @@ -31,11 +31,11 @@ Caveat: at this time, the Reference Architecture does not configure or manage th The next step is to configure the Machine User Personal Access Token(s) (PAT) If you are using GitHub to host your `infrastructure-live` repository, you will only need the one -personal access token as the permissions will allow access to both your `infrastructure-live` repo and +PAT as the permissions will allow access to both your `infrastructure-live` repo and Gruntwork's private repositories. If you are using GitLab or Bitbucket to host your `infrastructure-live` repository, you will need a -Personal Access Token for your respective VCS in addition to a GitHub PAT for access to the +PAT for your respective VCS in addition to a GitHub PAT for access to the private Gruntwork GitHub repositories. Note that at this time GitHub is the only supported VCS for Reference Architecture deployments. @@ -46,8 +46,8 @@ First we will create a GitHub Personal Access Token: 1. In the [Gruntwork developer portal](https://app.gruntwork.io/), add the user to your team, then log in to the portal _as the machine user_ and link the GitHub account. You’ll know it’s set up correctly when you see the Gruntwork icon in the machine user’s GitHub profile, indicating that they are a member of the Gruntwork Organization. 1. The PAT should be granted `repo`, `user:email`, and `admin:public_key` permissions. You should include `GitHub-MachineUser-PAT` as part of the name/description of the token to be able to identify it later. 1. Once you have the PAT, create a new [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) secret in the _shared_ account. You can use any name you wish for this secret, but it's recommended you include `GitHub-MachineUser-PAT` as part of the name to be able to identify it later. See the section [Appendix: How to create a secret for the VCS token in AWS Secrets Manager](#secrets_manager_howto) for details. -1. Once the secret is created, **copy the ARN** to your favorite text editor for later use. - +1. Once the secret is created, **copy the ARN** to your favorite text editor for the next step. +ß If your `infrastructure-live` repository is hosted in GitHub, enter the secrets manager ARN from the above steps into the Ref Arch `VCSPATSecretsManagerARN` field. This token will provide access to both your `infrastructure-live` repo and to the Gruntwork private repositories and you are done setting up the machine user! You can skip to the next section. If your `infrastructure-live` repository is hosted in BitBucket or GitLab, expand the `BitBucket / GitLab` tab below for more details. @@ -80,7 +80,7 @@ If you are using GitLab or BitBucket to host your `infrastructure-live` reposito You should name the token `BitBucket-MachineUser-PAT` to be able to identify it later. -Now you will need to create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. You should name the secret following the above naming convention (`GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT`). Once the secret is created, **make a note of the ARN**. +Now you will need to create _another_ secret in AWS Secrets Manager in the _shared_ account containing this PAT. You should name the secret following the above naming convention (`GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT`). Once the secret is created, **copy the ARN** to your favorite text editor for the next step. Finally, enter the newly created `GitLab-MachineUser-PAT`/`BitBucket-MachineUser-PAT` secrets manager ARN from the above step into the Ref Arch `VCSPATSecretsManagerARN` field. @@ -148,7 +148,7 @@ We're ready to run the wizard to fill in your `reference-architecture-form.yml` Before running the wizard, ensure you have completed steps 1, 2 and 3 and that you have the following values ready at hand: -- Personal Access Token for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. +- PAT for YOUR GitHub user. This token is used to create the Pull Request for the Reference Architecture form. - If you do not have one, generate a new PAT with `repo` level permissions. - GitHub Machine User PAT (required in all cases) - VCS Machine User PAT (only required if your ultimate infrastructure-live destination is NOT GitHub) @@ -331,6 +331,6 @@ In the ref arch form, `VCSPATSecretsManagerARN` is where you enter this ARN.