diff --git a/babel.config.js b/babel.config.js deleted file mode 100644 index e00595dae7..0000000000 --- a/babel.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -}; diff --git a/docs/2.0/docs/accountfactory/guides/vend-aws-account.md b/docs/2.0/docs/accountfactory/guides/vend-aws-account.md index 61f2d0bc71..cad08f666f 100644 --- a/docs/2.0/docs/accountfactory/guides/vend-aws-account.md +++ b/docs/2.0/docs/accountfactory/guides/vend-aws-account.md @@ -1,37 +1,66 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Using the Account Factory Workflow -## Introduction +## Generate the account-request file -The Account Factory Workflow in your `infrastructure-live-root` repository can be used to create new AWS accounts. It requires a single input—a JSON payload—generated from the `account-factory-inputs.html` web page. +There are currently two ways to generate the account-request file: -The JSON payload approach provides greater flexibility for account vending, overcoming the GitHub workflow restriction of a 10-input maximum. +1. Using the [Gruntwork Developer Portal](/2.0/docs/accountfactory/guides/vend-aws-account?account-creation-method=ui#using-the-gruntwork-developer-portal) (**GitLab and GitHub non-enterprise customers**) +2. Using the [Account Factory workflow in your repository](/2.0/docs/accountfactory/guides/vend-aws-account?account-creation-method=workflow#using-the-account-factory-workflow-in-your-repository) (**GitHub only**) + + + + + +### Using the Gruntwork Developer Portal + +1. Navigate to the [Account Request](https://app.gruntwork.io/account-factory/request-generator) page in the Gruntwork Developer Portal, as an authenticated user, to access the request generator UI. -:::note + ![Account Request Generator](/img/accountfactory/dev-portal-request-generator.png) -This guide focuses on non-delegated repositories. Enterprise customers can also [use Account Factory to create new Delegated Repositories](/2.0/docs/accountfactory/guides/delegated-repositories). +1. If the form is disabled for filling out, request that an Admin in your Gruntwork Developer Account configures the Account factory settings. +1. Fill out the form with the required information and click on the "Generate Account Request" button. +1. Use the "Download" button to download the account-request file or the "Copy" button to copy the account-request file to your clipboard. +1. Navigate to your repository and create a new branch. +1. Create a new file in the `_new-account-requests` directory by moving the downloaded file to the directory or by creating a new file with the content of your clipboard. If copying content, ensure that the file is created with the correct name displayed in the generator output. +1. Commit your changes and open a Pull Request to the main branch. + + + +### Using the Account Factory workflow in your repository + +:::info +Only available for GitHub customers. This guide focuses on non-delegated repositories. Enterprise GitHub customers can also [use Account Factory to create new Delegated Repositories](/2.0/docs/accountfactory/guides/delegated-repositories). ::: +The Account Factory Workflow in your `infrastructure-live-root` repository can be used to create new AWS accounts. It requires a single input—a JSON payload—generated from the `account-factory-inputs.html` web page. -### Step 1 - Download the file +The JSON payload approach provides greater flexibility for account vending, overcoming the GitHub workflow restriction of a 10-input maximum. + +#### Step 1 - Download the file Locate the inputs web page in your `infrastructure-live-root` repository at `.github/workflows/account-factory-inputs.html` and download it to your local machine. -### Step 2 - Populate the values +#### Step 2 - Populate the values Open the downloaded `account-factory-inputs.html` file in a web browser and populate the input fields as required. Once all values are filled, click "Generate" and copy the resulting JSON output to your clipboard. -### Step 3 - Run the Account Factory workflow +#### Step 3 - Run the Account Factory workflow Access the Actions tab in your `infrastructure-live-root` repository on GitHub and select `Account factory` from the left-hand pane. Click "Run workflow" on the right, paste the generated JSON payload into the dropdown, and click the green "Run workflow" button to initiate the workflow. +After the workflow is complete, a new Pull Request will be created in the `infrastructure-live-root` repository. This PR will add an account request to the `_new-account-requests` directory. -### Step 4 - Merge the account request PR + + -After the workflow is complete, a new Pull Request will be created in the `infrastructure-live-root` repository. This PR will add an account request to the `_new-account-requests` directory. +## Review and merge the account request PR Review and merge the Pull Request to begin the account creation process. @@ -43,7 +72,7 @@ Once the account request PR merges into the main branch, Pipelines will initiate When the account is successfully created, Pipelines will open another Pull Request to baseline the account. -### Step 5 - Merge the Account Baseline PR +## Review and merge the Account Baseline PR Review and merge the Account Baseline Pull Request. This PR contains essential infrastructure for enabling your delegated repository to plan and apply infrastructure changes in AWS. It also includes account baselines and configured account-specific infrastructure, such as a VPC. diff --git a/docs/2.0/docs/overview/getting-started/index.md b/docs/2.0/docs/overview/getting-started/index.md index 73113153d7..4f3d5dca36 100644 --- a/docs/2.0/docs/overview/getting-started/index.md +++ b/docs/2.0/docs/overview/getting-started/index.md @@ -19,9 +19,15 @@ Set up authentication for Pipelines to enable secure automation of infrastructur -### Step 4: [Create new Pipelines repositories](/2.0/docs/pipelines/installation/addingnewrepo) +### Step 4: Create new Pipelines repositories -Alternatively, you can [add Pipelines to an existing repository](/2.0/docs/pipelines/installation/addingexistingrepo). +- [New GitHub repository](/2.0/docs/pipelines/installation/addingnewrepo) +- [New GitLab repository](/2.0/docs/pipelines/installation/addingnewgitlabrepo) + +Alternatively, you can add Pipelines to an existing repository: + +- [Existing GitHub repository](/2.0/docs/pipelines/installation/addingexistingrepo) +- [Existing GitLab repository](/2.0/docs/pipelines/installation/addinggitlabrepo) diff --git a/docs/2.0/docs/pipelines/installation/addinggitlabrepo.md b/docs/2.0/docs/pipelines/installation/addinggitlabrepo.md index 367ba1d8fd..e954860cbe 100644 --- a/docs/2.0/docs/pipelines/installation/addinggitlabrepo.md +++ b/docs/2.0/docs/pipelines/installation/addinggitlabrepo.md @@ -1,6 +1,6 @@ import CustomizableValue from '/src/components/CustomizableValue'; -# Adding Pipelines to a GitLab Project +# Adding Pipelines to an existing GitLab Project This guide walks you through the process of adding Gruntwork Pipelines to a GitLab project. By the end, you'll have a fully configured GitLab CI/CD pipeline that can deploy infrastructure changes automatically. @@ -11,7 +11,7 @@ Before you begin, make sure you have: - Basic familiarity with Git, GitLab, and infrastructure as code concepts - Access to one (or many) AWS account(s) where you have permission to create IAM roles and OIDC providers - Completed the [Pipelines Auth setup for GitLab](/2.0/docs/pipelines/installation/viamachineusers#gitlab) and setup a machine user with appropriate PAT tokens -- Local access to Gruntwork's GitHub repositories, specifically [boilerplate](https://github.com/gruntwork-io/boilerplate) and the [architecture catalog](https://github.com/gruntwork-io/terraform-aws-architecture-catalog/) +- Local access to Gruntwork's GitHub repositories, specifically the [architecture catalog](https://github.com/gruntwork-io/terraform-aws-architecture-catalog/) :::info diff --git a/docs/2.0/docs/pipelines/installation/addingnewgitlabrepo.md b/docs/2.0/docs/pipelines/installation/addingnewgitlabrepo.md new file mode 100644 index 0000000000..024a2c5183 --- /dev/null +++ b/docs/2.0/docs/pipelines/installation/addingnewgitlabrepo.md @@ -0,0 +1,547 @@ +import CustomizableValue from '/src/components/CustomizableValue'; + +# Creating a New GitLab Project with Pipelines + +This guide walks you through the process of setting up a new GitLab Project with the Gruntwork Platform. By the end, you'll have a fully configured GitLab CI/CD pipeline that can create new AWS accounts and deploy infrastructure changes automatically. + +:::info +To use Gruntwork Pipelines in an **existing** GitLab repository, see this [guide](/2.0/docs/pipelines/installation/addinggitlabrepo). +::: + +## Prerequisites + +Before you begin, make sure you have: + +- Basic familiarity with Git, GitLab, and infrastructure as code concepts +- Completed the [AWS Landing Zone setup](/2.0/docs/pipelines/installation/prerequisites/awslandingzone) +- Have programmatic access to the AWS accounts created in the [AWS Landing Zone setup](/2.0/docs/pipelines/installation/prerequisites/awslandingzone) +- Completed the [Pipelines Auth setup for GitLab](/2.0/docs/pipelines/installation/viamachineusers#gitlab) and setup a machine user with appropriate PAT tokens +- Local access to Gruntwork's GitHub repositories, specifically the [architecture catalog](https://github.com/gruntwork-io/terraform-aws-architecture-catalog/) + +
+Additional setup for **custom GitLab instances only** + +### Fork the Pipelines workflow project + +You must [fork](https://docs.gitlab.com/user/project/repository/forking_workflow/#create-a-fork) Gruntwork's public [Pipelines workflow project](https://gitlab.com/gruntwork-io/pipelines-workflows) into your own GitLab instance. +This is necessary because Gruntwork Pipelines uses [GitLab CI/CD components](/2.0/docs/pipelines/architecture/ci-workflows), and GitLab requires components to reside within the [same GitLab instance as the project referencing them](https://docs.gitlab.com/ci/components/#use-a-component). + +When creating the fork, we recommend configuring it as a public mirror of the original Gruntwork project and ensuring that tags are included. + +### Ensure OIDC configuration and JWKS are publicly accessible + +This step only applies if you are using a self-hosted GitLab instance that is not accessible from the public internet. If you are using GitLab.com or a self-hosted instance that is publicly accessible, you can skip this step. + +1. [Follow GitLab's instructions](https://docs.gitlab.com/ci/cloud_services/aws/#configure-a-non-public-gitlab-instance) for hosting your OIDC configuration and JWKS in a public location (e.g. S3 Bucket). This is necessary for both Gruntwork and the AWS OIDC provider to access the GitLab OIDC configuration and JWKS when authenticating JWT's generated by your custom instance. +2. Note the (stored as `ci_id_tokens_issuer_url` in your `gitlab.rb` file per GitLab's instructions) generated above for reuse in the next steps. +
+ +1. Create a new GitLab project for your `infrastructure-live-root` repository. +1. Install dependencies. +1. Configure the variables required to run the infrastructure-live-root boilerplate template. +1. Create your `infrastructure-live-root` repository contents using Gruntwork's architecture-catalog template. +1. Apply the account baselines to your AWS accounts. + + +## Create a new infrastructure-live-root + +### Authorize Your GitLab Group with Gruntwork + +To use Gruntwork Pipelines with GitLab, your group needs authorization from Gruntwork. Email your Gruntwork account manager or support@gruntwork.io with: + + ``` + GitLab group name(s): $$GITLAB_GROUP_NAME$$ (e.g. acme-io) + GitLab Issuer URL: $$ISSUER_URL$$ (For most users this is the URL of your GitLab instance e.g. https://gitlab.acme.io, if your instance is not publicly accessible, this should be a separate URL that is publicly accessible per step 0, e.g. https://s3.amazonaws.com/YOUR_BUCKET_NAME/) + Organization name: $$ORGANIZATION_NAME$$ (e.g. Acme, Inc.) + ``` + +Continue with the rest of the guide while you await confirmation when your group has been authorized. + +### Create a new GitLab project + +1. Navigate to the group. +1. Click the **New Project** button. +1. Enter a name for the project. e.g. infrastructure-live-root +1. Click **Create Project**. +1. Clone the project to your local machine. +1. Navigate to the project directory. +1. Create a new branch `bootstrap-repository`. + +### Install dependencies + +1. Install [mise](https://mise.jdx.dev/getting-started.html) on your machine. +1. Activate mise in your shell: + + ```bash + # For Bash + echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc + + # For Zsh + echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc + + # For Fish + echo 'mise activate fish | source' >> ~/.config/fish/config.fish + ``` + +1. Add the following to a .mise.toml file in the root of your project: + + ```toml title=".mise.toml" + [tools] + boilerplate = "0.8.1" + opentofu = "1.10.0" + terragrunt = "0.81.6" + awscli = "latest" + ``` + +1. Run `mise install`. + + +### Bootstrap the repository + +Gruntwork provides a boilerplate [template](https://github.com/gruntwork-io/terraform-aws-architecture-catalog/tree/main/templates/devops-foundations-infrastructure-live-root) that incorporates best practices while allowing for customization. The template is designed to scaffold a best-practices Terragrunt configurations. It includes patterns for module defaults, global variables, and account baselines. Additionally, it integrates Gruntwork Pipelines. + +#### Configure the variables required to run the boilerplate template + +Copy the content below to a `vars.yaml` file in the root of your project and update the `` values with your own. + +```yaml title="vars.yaml" +SCMProvider: GitLab + +# The GitLab group to use for the infrastructure repositories. This should include any additional sub-groups in the name +# Example: acme/prod +SCMProviderGroup: $$GITLAB_GROUP_NAME$$ + +# The GitLab project to use for the infrastructure-live repository. +SCMProviderRepo: infrastructure-live-root + +# The base URL of your GitLab group repos. E.g., gitlab.com/ +RepoBaseUrl: $$GITLAB_GROUP_REPO_BASE_URL$$ + +# The name of the branch to deploy to. +# Example: main +DeployBranchName: $$DEPLOY_BRANCH_NAME$$ + +# The AWS account ID for the management account +# Example: "123456789012" +AwsManagementAccountId: $$AWS_MANAGEMENT_ACCOUNT_ID$$ + +# The AWS account ID for the security account +# Example: "123456789013" +AwsSecurityAccountId: $$AWS_SECURITY_ACCOUNT_ID$$ + +# The AWS account ID for the logs account +# Example: "123456789014" +AwsLogsAccountId: $$AWS_LOGS_ACCOUNT_ID$$ + +# The AWS account ID for the shared account +# Example: "123456789015" +AwsSharedAccountId: $$AWS_SHARED_ACCOUNT_ID$$ + +# The AWS account Email for the logs account +# Example: logs@acme.com +AwsLogsAccountEmail: $$AWS_LOGS_ACCOUNT_EMAIL$$ + +# The AWS account Email for the management account +# Example: management@acme.com +AwsManagementAccountEmail: $$AWS_MANAGEMENT_ACCOUNT_EMAIL$$ + +# The AWS account Email for the security account +# Example: security@acme.com +AwsSecurityAccountEmail: $$AWS_SECURITY_ACCOUNT_EMAIL$$ + +# The AWS account Email for the shared account +# Example: shared@acme.com +AwsSharedAccountEmail: $$AWS_SHARED_ACCOUNT_EMAIL$$ + +# The name prefix to use for creating resources e.g S3 bucket for OpenTofu state files +# Example: acme +OrgNamePrefix: $$ORG_NAME_PREFIX$$ + +# The default region for AWS Resources +# Example: us-east-1 +DefaultRegion: $$DEFAULT_REGION$$ + +################################################################################ +# OPTIONAL VARIABLES WITH THEIR DEFAULT VALUES. UNCOMMENT AND MODIFY IF NEEDED. +################################################################################ + +# List of the git repositories to populate for the catalog +# CatalogRepositories: +# - github.com/gruntwork-io/terraform-aws-service-catalog + +# The AWS partition to use. Options: aws, aws-us-gov +# AWSPartition: aws + +# The name of the IAM role to use for the plan job. +# PlanIAMRoleName: root-pipelines-plan + +# The name of the IAM role to use for the apply job. +# ApplyIAMRoleName: root-pipelines-apply + +# The default tags to apply to all resources. +# DefaultTags: +# "{{ .OrgNamePrefix }}:Team": "DevOps" + +# The version for terraform-aws-security module to use for OIDC provider and roles provisioning +# SecurityModulesVersion: v0.75.18 + +# The URL of the custom SCM provider instance. Set this if you are using a custom instance of GitLab. +# CustomSCMProviderInstanceURL: https://gitlab.example.io + +# The relative path from the host server to the custom pipelines workflow repository. Set this if you are using a custom/forked instance of the pipelines workflow. +# CustomWorkflowHostRelativePath: pipelines-workflows +``` + +#### Generate the repository contents + +1. Run the following command, from the root of your project, to generate the `infrastructure-live-root` repository contents: + + + ```bash + boilerplate --template-url "git@github.com:gruntwork-io/terraform-aws-architecture-catalog.git//templates/devops-foundations-infrastructure-live-root/?ref=main" --output-folder . --var-file vars.yaml --non-interactive + ``` + + This command adds all code required to set up your `infrastructure-live-root` repository. +1. Remove the boilerplate dependency from the `mise.toml` file. It is no longer needed. + +1. Commit your local changes and push them to the `bootstrap-repository` branch. + + ```bash + git add . + git commit -m "Bootstrap infrastructure-live-root repository initial commit [skip ci]" + git push origin bootstrap-repository + ``` + + Skipping the CI/CD process for now; you will manually apply the infrastructure baselines to your AWS accounts in a later step. + +1. Create a new merge request for the `bootstrap-repository` branch. Review the changes to understand what will be applied to your AWS accounts. The generated files fall under the following categories: + + - GitLab Pipelines workflow file + - Gruntwork Pipelines configuration files + - Module defaults files for infrastructure code + - Account baselines and GitLab OIDC module scaffolding files for your core AWS accounts: management, security, logs and shared. + +### Apply the account baselines to your AWS accounts + +You will manually `terragrunt apply` the generated infrastructure baselines to get your accounts bootstrapped **before** merging this content into your main branch. + +:::tip +You can utilize the AWS SSO Portal to obtain temporary AWS credentials necessary for subsequent steps: + +1. Sign in to the Portal page and select your preferred account to unveil the roles accessible to your SSO user. +1. Navigate to the "Access keys" tab adjacent to the "AWSAdministratorAccess" role. +1. Copy the "AWS environment variables" provided and paste them into your terminal for usage. +::: + + +1. [ ] Apply infrastructure changes in the **management** account + + 1. - [ ] Obtain AWS CLI Administrator credentials for the management account + + 1. - [ ] Navigate to the management account folder + + ```bash + cd management/ + ``` + + 1. - [ ] Using your credentials, run `terragrunt plan`. + + ```bash + terragrunt run --all plan --terragrunt-non-interactive + ``` + + 1. - [ ] After the plan succeeds, apply the changes: + + ```bash + terragrunt run --all apply --terragrunt-non-interactive + ``` + + 1. - [ ] After applying the changes, make sure to lock providers in your `.terraform.lock.hcl` files. The lock files will be committed in the final step of the setup. e.g. + + ```bash + terragrunt run --all providers -- lock -platform=darwin_amd64 -platform=linux_amd64 + ``` + + 1. - [ ] Update Permissions for Account Factory Portfolio + + The account factory pipeline _will fail_ until you grant the pipelines roles (`root-pipelines-plan` and `root-pipelines-apply`) access to the portfolio. This step **must be done after** you provision the pipelines roles in the management account (where control tower is set up). + + Access to the portfolio is separate from IAM access, it **must** be granted in the Service Catalog console. + + #### **Steps to grant access** + + To grant access to the Account Factory Portfolio, you **must** be an individual with Service Catalog administrative permissions. + + 1. Log into the management AWS account + 1. Go into the Service Catalog console + 1. Ensure you are in your default region(control-tower region) + 1. Select the **Portfolios** option in **Administration** from the left side navigation panel + 1. Click on the portfolio named **AWS Control Tower Account Factory Portfolio** + 1. Select the **Access** tab + 1. Click the **Grant access** button + 1. In the **Access type** section, leave the default value of **IAM Principal** + 1. Select the **Roles** tab in the lower section + 1. Enter `root-pipelines` into the search bar, there should be two results (`root-pipelines-plan` and `root-pipelines-apply`). Click the checkbox to the left of each role name. + 1. Click the **Grant access** button in the lower right hand corner + + 1. - [ ] Increase Account Quota Limit (OPTIONAL) + + Note that DevOps Foundations makes it very convenient, and therefore likely, that you will encounter one of the soft limits imposed by AWS on the number of accounts you can create. + + You may need to request a limit increase for the number of accounts you can create in the management account, as the default is currently 10 accounts. + + To request an increase to this limit, search for "Organizations" in the AWS management console [here](https://console.aws.amazon.com/servicequotas/home/dashboard) and request a limit increase to a value that makes sense for your organization. + +1. - [ ] Apply infrastructure changes in the **logs** account + + 1. - [ ] Obtain AWS CLI Administrator credentials for the logs account + 1. - [ ] Navigate to the logs account folder + + ```bash + cd ../logs/ + ``` + + 1. - [ ] Using your credentials, run `terragrunt plan`. + + ```bash + terragrunt run --all plan --terragrunt-non-interactive + ``` + + 1. - [ ] After the plan succeeds, apply the changes: + + ```bash + terragrunt run --all apply --terragrunt-non-interactive + ``` + + 1. - [ ] After applying the changes, make sure to lock providers in your `.terraform.lock.hcl` files. e.g. + + ```bash + terragrunt run --all providers lock -platform=darwin_amd64 -platform=linux_amd64 + ``` + +1. - [ ] Apply infrastructure changes in the **security** account + + 1. - [ ] Obtain AWS CLI Administrator credentials for the security account + 1. - [ ] Navigate to the security account folder + + ```bash + cd ../security/ + ``` + + 1. - [ ] Using your credentials, run `terragrunt plan`. + + ```bash + terragrunt run --all plan --terragrunt-non-interactive + ``` + + 1. - [ ] After the plan succeeds, apply the changes: + + ```bash + terragrunt run --all apply --terragrunt-non-interactive + ``` + + 1. - [ ] After applying the changes, make sure to lock providers in your `.terraform.lock.hcl` files. e.g. + + ```bash + terragrunt run --all providers lock -platform=darwin_amd64 -platform=linux_amd64 + ``` + +1. - [ ] Apply infrastructure changes in the **shared** account + + 1. - [ ] Obtain AWS CLI Administrator credentials for the shared account. You may need to grant your user access to the `AWSAdministratorAccess` permission set in the shared account from the management account's Identity Center Admin console. + 1. - [ ] Using your credentials, create a service role + + ```bash + aws iam create-service-linked-role --aws-service-name autoscaling.amazonaws.com + ``` + + 1. - [ ] Navigate to the shared account folder + + ```bash + cd ../shared/ + ``` + + 1. - [ ] Using your credentials, run `terragrunt plan`. + + ```bash + terragrunt run --all plan --terragrunt-non-interactive + ``` + + 1. - [ ] After the plan succeeds, apply the changes: + + ```bash + terragrunt run --all apply --terragrunt-non-interactive + ``` + + 1. - [ ] After applying the changes, make sure to lock providers in your `.terraform.lock.hcl` files. e.g. + + ```bash + terragrunt run --all providers lock -platform=darwin_amd64 -platform=linux_amd64 + ``` + +1. - [ ] Commit your local changes and push them to the `bootstrap-repository` branch. + + ```bash + cd .. + git add . + git commit -m "Bootstrap infrastructure-live-root repository final commit [skip ci]" + git push origin bootstrap-repository + ``` + +1. - [ ] Merge the open merge request. **Ensure [skip ci] is present in the commit message.** + + +## Create a new infrastructure-live-access-control (optional) + +### Create a new GitLab project + +1. Navigate to the group. +1. Click the **New Project** button. +1. Enter the name for the project as `infrastructure-live-access-control`. +1. Click **Create Project**. +1. Clone the project to your local machine. +1. Navigate to the project directory. +1. Create a new branch `bootstrap-repository`. + +### Install dependencies + +Run `mise install boilerplate@0.8.1` to install the boilerplate tool. + +### Bootstrap the repository + +#### Configure the variables required to run the boilerplate template + +Copy the content below to a `vars.yaml` file in the root of your project and update the customizable values as needed. + +```yaml title="vars.yaml" +SCMProvider: GitLab + +# The GitLab group to use for the infrastructure repositories. This should include any additional sub-groups in the name +# Example: acme/prod +SCMProviderGroup: $$GITLAB_GROUP_NAME$$ + +# The GitLab project to use for the infrastructure-live repository. +SCMProviderRepo: infrastructure-live-access-control + +# The name of the branch to deploy to. +# Example: main +DeployBranchName: $$DEPLOY_BRANCH_NAME$$ + +# The name prefix to use for creating resources e.g S3 bucket for OpenTofu state files +# Example: acme +OrgNamePrefix: $$ORG_NAME_PREFIX$$ + +# The default region for AWS Resources +# Example: us-east-1 +DefaultRegion: $$DEFAULT_REGION$$ + +################################################################################ +# OPTIONAL VARIABLES WITH THEIR DEFAULT VALUES. UNCOMMENT AND MODIFY IF NEEDED. +################################################################################ + +# The AWS partition to use. +# AWSPartition: aws +``` + +#### Generate the repository contents + +1. Run the following command, from the root of your project, to generate the `infrastructure-live-access-control` repository contents: + + + ```bash + boilerplate --template-url "git@github.com:gruntwork-io/terraform-aws-architecture-catalog.git//templates/devops-foundations-infrastructure-live-access-control/?ref=main" --output-folder . --var-file vars.yaml --non-interactive + ``` + + This command adds all code required to set up your `infrastructure-live-access-control` repository. The generated files fall under the following categories: + + - GitLab Pipelines workflow file + - Gruntwork Pipelines configuration files + - Module defaults files for GitLab OIDC roles and policies + + +2. Commit your local changes and push them to the `bootstrap-repository` branch. + + ```bash + git add . + git commit -m "Bootstrap infrastructure-live-access-control repository [skip ci]" + git push origin bootstrap-repository + ``` + + Skipping the CI/CD process now because there is no infrastructure to apply; repository simply contains the GitLab OIDC role module defaults to enable GitLab OIDC authentication from repositories other than `infrastructure-live-root`. + +3. Create a new merge request for the `bootstrap-repository` branch. Review the changes to understand the GitLab OIDC role module defaults. +4. Merge the open merge request. **Ensure [skip ci] is present in the commit message.** + +## Create a new infrastructure-catalog (optional) + +The `infrastructure-catalog` repository is a collection of modules that can be used to build your infrastructure. It is a great way to share modules with your team and across your organization. Learn more about the [Developer Self-Service](/2.0/docs/overview/concepts/developer-self-service) concept. + +### Create a new GitLab project + +1. Navigate to the group. +1. Click the **New Project** button. +1. Enter the name for the project as `infrastructure-catalog`. +1. Click **Create Project**. +1. Clone the project to your local machine. +1. Navigate to the project directory. +1. Create a new branch `bootstrap-repository`. + +### Install dependencies + +Run `mise install boilerplate@0.8.1` to install the boilerplate tool. + +### Bootstrap the repository + +#### Configure the variables required to run the boilerplate template + +Copy the content below to a `vars.yaml` file in the root of your project and update the customizable values as needed. + +```yaml title="vars.yaml" +# The name of the repository to use for the catalog. +InfraModulesRepoName: infrastructure-catalog + +# The version of the Gruntwork Service Catalog to use. https://github.com/gruntwork-io/terraform-aws-service-catalog +ServiceCatalogVersion: v0.111.2 + +# The version of the Gruntwork VPC module to use. https://github.com/gruntwork-io/terraform-aws-vpc +VpcVersion: v0.26.22 + +# The default region for AWS Resources +# Example: us-east-1 +DefaultRegion: $$DEFAULT_REGION$$ + +################################################################################ +# OPTIONAL VARIABLES WITH THEIR DEFAULT VALUES. UNCOMMENT AND MODIFY IF NEEDED. +################################################################################ + +# The base URL of the Organization to use for the catalog. +# If you are using Gruntwork's RepoCopier tool, this should be the base URL of the repository you are copying from. +# RepoBaseUrl: github.com/gruntwork-io + +# The name prefix to use for the Gruntwork RepoCopier copied repositories. +# Example: gruntwork-io- +# GWCopiedReposNamePrefix: +``` + + +#### Generate the repository contents + +1. Run the following command, from the root of your project, to generate the `infrastructure-catalog` repository contents: + + + ```bash + boilerplate --template-url "git@github.com:gruntwork-io/terraform-aws-architecture-catalog.git//templates/devops-foundations-infrastructure-modules/?ref=main" --output-folder . --var-file vars.yaml --non-interactive + ``` + + This command adds some code required to set up your `infrastructure-catalog` repository. The generated files are some usable modules for your infrastructure. + +1. Commit your local changes and push them to the `bootstrap-repository` branch. + + ```bash + git add . + git commit -m "Bootstrap infrastructure-catalog repository" + git push origin bootstrap-repository + ``` + +1. Create a new merge request for the `bootstrap-repository` branch. Review the changes to understand the example Service Catalog modules. +1. Merge the open merge request. diff --git a/docs/2.0/docs/pipelines/installation/scm-comparison.md b/docs/2.0/docs/pipelines/installation/scm-comparison.md index c4f9f44d96..01de723c99 100644 --- a/docs/2.0/docs/pipelines/installation/scm-comparison.md +++ b/docs/2.0/docs/pipelines/installation/scm-comparison.md @@ -7,7 +7,8 @@ Gruntwork Pipelines supports both GitHub Actions and GitLab CI/CD as CI/CD platf | Feature | GitHub | GitLab (Beta) | | -------------------------------- | --------------------------- | ---------------------------- | | Infrastructure as Code Pipelines | ✅ | ✅ | -| Account Factory Integration | ✅ | ❌ | +| Account Factory Integration | ✅ | ✅ | +| Enterprise Account Factory | ✅ | ❌ | | App-based Authentication | ✅ | ❌ | | Machine User Authentication | ✅ | ✅ | | Customizable Workflows | ✅ | ✅ | diff --git a/docs/2.0/docs/pipelines/installation/viamachineusers.md b/docs/2.0/docs/pipelines/installation/viamachineusers.md index d708514c31..7e28d5de9a 100644 --- a/docs/2.0/docs/pipelines/installation/viamachineusers.md +++ b/docs/2.0/docs/pipelines/installation/viamachineusers.md @@ -36,7 +36,7 @@ If screen sharing while generating tokens, **pause or hide your screen** before ::: ### Token types - + GitHub supports two types of tokens: @@ -77,7 +77,7 @@ More information is available [here](https://docs.github.com/en/organizations/ma ![Pending requests](/img/pipelines/security/pending_requests.png) - + GitLab uses access tokens for authentication. There are several types of access tokens in GitLab: @@ -107,8 +107,8 @@ When creating tokens, carefully consider the expiration date and scope of access ## Creating machine users - - + + The recommended setup for Pipelines uses two machine users: one for opening pull requests and running workflows (`ci-user`) and another with read-only access to repositories (`ci-read-only-user`). Each user is assigned restrictive permissions based on their tasks. As a result, both users may need to participate at different stages to successfully run a pipeline job. @@ -389,7 +389,7 @@ For more information on creating and using GitHub Actions Repository secrets, re - + For GitLab, Gruntwork Pipelines two CI variables. The first, the `PIPELINES_GITLAB_TOKEN` requires the `Developer`, `Maintainer` or `Owner` role and the scopes listed below. This token will be used to authenticate API calls and access repositories within your GitLab group. The second, the `PIPELINES_GITLAB_READ_TOKEN` will be used to access your own code within GitLab. If not set, Pipelines will default to the `CI_JOB_TOKEN` when accessing internal GitLab hosted code. diff --git a/docs/2.0/docs/pipelines/tutorials/deploying-to-aws-gov-cloud.md b/docs/2.0/docs/pipelines/tutorials/deploying-to-aws-gov-cloud.md index 05a31d2340..d6bd365a1f 100644 --- a/docs/2.0/docs/pipelines/tutorials/deploying-to-aws-gov-cloud.md +++ b/docs/2.0/docs/pipelines/tutorials/deploying-to-aws-gov-cloud.md @@ -55,7 +55,7 @@ This section covers the Pipelines configuration required to deploy an AWS S3 buc ``` 2. Create a `vars.yaml` file on your local machine with the following content: - + ```yaml title="vars.yaml" AccountName: "$$ACCOUNT_NAME$$" @@ -84,7 +84,7 @@ This section covers the Pipelines configuration required to deploy an AWS S3 buc 3. We'll now use that `vars.yaml` file as input to [boilerplate](https://github.com/gruntwork-io/boilerplate) to generate the Terragrunt code for the OIDC Provider and IAM roles. From the root of your repository, run the following command: - + ```bash boilerplate --template-url "git@github.com:gruntwork-io/terraform-aws-architecture-catalog.git//templates/github-actions-single-account-setup?ref=main" --output-folder . --var-file vars.yaml --non-interactive @@ -130,7 +130,7 @@ aws sts get-caller-identity In the event you already have an OIDC provider for your SCM in the AWS account you can import the existing one: - + ``` cd _global/$$ACCOUNT_NAME$$/github-actions-openid-connect-provider/ diff --git a/sidebars/docs.js b/sidebars/docs.js index 708f3c9a41..e8494ea675 100644 --- a/sidebars/docs.js +++ b/sidebars/docs.js @@ -264,7 +264,12 @@ const sidebar = [ collapsed: false, items: [ { - label: "Adding Pipelines to a GitLab Project", + label: "Creating a New GitLab Project with Pipelines", + type: "doc", + id: "2.0/docs/pipelines/installation/addingnewgitlabrepo", + }, + { + label: "Adding Pipelines to an Existing GitLab Project", type: "doc", id: "2.0/docs/pipelines/installation/addinggitlabrepo", }, diff --git a/src/css/custom.css b/src/css/custom.css index edf266bf75..7df917f44e 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -166,6 +166,8 @@ --ifm-heading-color: #15192d; --ifm-button-border-radius: 12px; + + --ifm-checkbox-border-color: #adb5bd; } html[data-theme="dark"] { @@ -177,6 +179,8 @@ html[data-theme="dark"] { --ifm-background-color: #15192d; --ifm-background-surface-color: #0d0622; + + --ifm-checkbox-border-color: #777; } .docusaurus-highlight-code-line { @@ -695,3 +699,44 @@ html[data-theme="dark"] .customizable-value span::after { border-width: 0 3px 3px 0; transform: rotate(45deg); } + +/* Create a custom checkbox that looks like the default */ +.contains-task-list li input[type="checkbox"] { + -webkit-appearance: none; + appearance: none; + background-color: var(--ifm-background-color); + margin-right: 0.5rem; + font: inherit; + color: currentColor; + width: 1.15em; + height: 1.15em; + border: 0.1em solid var(--ifm-checkbox-border-color); + border-radius: 0.15em; + transform: translateY(-0.075em); + display: inline-grid; + place-content: center; + cursor: pointer; +} + +/* Create the checkmark/indicator using an SVG (hidden when not checked) */ +.contains-task-list li input[type="checkbox"]::before { + content: ""; + width: 0.65em; + height: 0.65em; + transform: scale(0); + transition: 120ms transform ease-in-out; + background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='white' d='M6.564.75l-3.59 3.612-1.538-1.55L0 4.26 2.974 7.25 8 2.193z'/%3e%3c/svg%3e"); + background-position: center; + background-repeat: no-repeat; +} + +/* Show the checkmark when checked */ +.contains-task-list li input[type="checkbox"]:checked::before { + transform: scale(1); +} + +/* Change the background color of the box when checked */ +.contains-task-list li input[type="checkbox"]:checked { + background-color: var(--ifm-color-primary); + border-color: var(--ifm-color-primary); +} diff --git a/src/theme/Root.js b/src/theme/Root.js index 23be6aa2c6..ca9aa7e0f4 100644 --- a/src/theme/Root.js +++ b/src/theme/Root.js @@ -7,6 +7,9 @@ */ import React, { useState, useEffect } from "react" +import { useLocation } from "@docusaurus/router" +import { interactivePersistentCheckboxes } from "/utils/checkbox" +import { scrollToAnchorInClosedSection } from "/utils/anchor" import { getRepos } from "/utils" import { SubscribersOnlyModal, @@ -143,6 +146,15 @@ function Root({ children }) { const [subscriberNoticeLink, setSubscriberNoticeLink] = useState("") const [cisNoticeLink, setCisNoticeLink] = useState("") const [enterpriseNoticeLink, setEnterpriseNoticeLink] = useState("") + const location = useLocation() + + useEffect(() => { + interactivePersistentCheckboxes() + }, [location.pathname]) + + useEffect(() => { + scrollToAnchorInClosedSection(location) + }, [location.hash]) useEffect(function showModalForPrivateGithubLinks() { const listener = (event) => { diff --git a/static/img/accountfactory/dev-portal-request-generator.png b/static/img/accountfactory/dev-portal-request-generator.png new file mode 100644 index 0000000000..f8eefb89d2 Binary files /dev/null and b/static/img/accountfactory/dev-portal-request-generator.png differ diff --git a/utils/anchor.ts b/utils/anchor.ts new file mode 100644 index 0000000000..4173160b22 --- /dev/null +++ b/utils/anchor.ts @@ -0,0 +1,24 @@ +export const scrollToAnchorInClosedSection = (location: Location) => { + const hash = location.hash + + if (hash) { + const id = decodeURIComponent(hash.slice(1)) + const element = document.getElementById(id) + + if (element) { + const details = element.closest("details") + if (details && !details.open) { + const summary = details.querySelector("summary") + if (summary) { + summary.click() + + const timeoutId = setTimeout(() => { + element.scrollIntoView({ behavior: "smooth", block: "start" }) + }, 500) // 500ms to allow for browser to render the element + + return () => clearTimeout(timeoutId) + } + } + } + } +} diff --git a/utils/checkbox.ts b/utils/checkbox.ts new file mode 100644 index 0000000000..93799bbc01 --- /dev/null +++ b/utils/checkbox.ts @@ -0,0 +1,52 @@ +export function interactivePersistentCheckboxes() { + const LOCAL_STORAGE_KEY = "docusaurus.checkboxes" + + const getStorage = () => { + try { + return JSON.parse(window.localStorage.getItem(LOCAL_STORAGE_KEY) || "{}") + } catch (e) { + return {} + } + } + + const updateStorage = (key: string, value: boolean) => { + const data = getStorage() + data[key] = value + window.localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(data)) + } + + const initCheckboxes = () => { + const checkboxes = document.querySelectorAll( + ".contains-task-list > li input[type='checkbox']" + ) + + if (checkboxes.length === 0) { + return + } + + const data = getStorage() + + checkboxes.forEach((checkbox, index) => { + const label = + `${index}:${checkbox?.closest("li")?.textContent?.substring(0, 10)}` || + `checkbox-${index}` + const key = `${window.location.pathname}:${label}` + + checkbox.disabled = false + const checked = data[key] || false + checkbox.checked = checked + + checkbox.addEventListener("click", (e) => { + const target = e.target as HTMLInputElement + updateStorage(key, target.checked) + }) + }) + } + + const timeoutId = setTimeout(initCheckboxes, 100) + + // Cleanup + return () => { + clearTimeout(timeoutId) + } +}