Skip to content

README.md

Latest commit

 

History

History
329 lines (250 loc) · 18.3 KB

README.md

File metadata and controls

329 lines (250 loc) · 18.3 KB
Raw

0-bootstrap

This repo is part of a multi-part guide that shows how to configure and deploy the example.com reference architecture described in Google Cloud security foundations guide. The following table lists the stages of this deployment.

0-bootstrap (this file) Bootstraps a Google Cloud organization, creating all the required resources and permissions to start using the Cloud Foundation Toolkit (CFT). This step also configures a CI/CD pipeline for foundations code in subsequent stages.
1-org Sets up top-level shared folders, monitoring and networking projects, and organization-level logging, and sets baseline security settings through organizational policy.
2-environments Sets up development, nonproduction, and production environments within the Google Cloud organization that you've created.
3-networks-svpc Sets up base and restricted shared VPCs with default DNS, NAT (optional), Private Service networking, VPC service controls, on-premises Dedicated Interconnect, and baseline firewall rules for each environment. It also sets up the global DNS hub.
4-projects Set up a folder structure, projects, and application infrastructure pipeline for applications, which are connected as service projects to the shared VPC created in the previous stage.
5-app-infra Deploys Service Catalog Pipeline and Custom Artifacts Pipeline.

Purpose

The purpose of this step is to bootstrap a Google Cloud organization, creating all the required resources and permissions to start using the Cloud Foundation Toolkit (CFT). This step also configures a CI/CD Pipeline for foundations code in subsequent stages. The CI/CD Pipeline can use either Cloud Build and Cloud Source Repos or Jenkins and your own Git repos (which might live on-premises).

Prerequisites

To run the commands described in this document, install the following:

Notes:

  • Make sure that you use version 1.5.7 of Terraform throughout this series. Otherwise, you might experience Terraform state snapshot lock errors.
  • It is recommended to use Bash terminal de deploy the code from this repository. Using other terminals might cause unexpected behaviours.

Also make sure that you've done the following:

  1. Set up a Google Cloud organization.
  2. Set up a Google Cloud billing account.
  3. Create Cloud Identity or Google Workspace groups for organization and billing admins.
  4. Add the user who will use Terraform to the group_org_admins group. They must be in this group, or they won't have roles/resourcemanager.projectCreator access.
  5. For the user who will run the procedures in this document, grant the following roles:
    • The roles/resourcemanager.organizationAdmin role on the Google Cloud organization.
    • The roles/orgpolicy.policyAdmin role on the Google Cloud organization.
    • The roles/billing.admin role on the billing account.
    • The roles/resourcemanager.folderCreator role.
    • The roles/iam.serviceAccountTokenCreator role

If other users need to be able to run these procedures, add them to the group represented by the org_project_creators variable. For more information about the permissions that are required, and the resources that are created, see the organization bootstrap module documentation.

Optional - Automatic creation of Google Cloud Identity groups

In the foundation, Google Cloud Identity groups are used for authentication and access management .

To enable automatic creation of the required groups, complete the following actions:

  • Have an existing project for Cloud Identity API billing.
  • Enable the Cloud Identity API (cloudidentity.googleapis.com) on the billing project.
  • Grant role roles/serviceusage.serviceUsageConsumer to the user running Terraform on the billing project.
  • Provide values for the groups and billing project in the variable groups.

All groups in the groups.required_groups are required.

All groups in the groups.optional_groups are optional.

Optional - Cloud Build access to on-prem

See onprem for instructions on how to configure Cloud Build access to your on-premises environment.

Troubleshooting

See troubleshooting if you run into issues during this step.

Deploying with Jenkins

If you are using the jenkins_bootstrap sub-module, see README-Jenkins for requirements and instructions on how to run the 0-bootstrap step. Using Jenkins requires a few manual steps, including configuring connectivity with your current Jenkins manager (controller) environment.

Deploying with GitHub Actions

If you are deploying using GitHub Actions, see README-GitHub.md for requirements and instructions on how to run the 0-bootstrap step. Using GitHub Actions requires manual creation of the GitHub repositories used in each stage.

Deploying with Cloud Build

  1. Clone terraform-google-enterprise-genai into your local environment and navigate to the 0-bootstrap folder.

    git clone https://github.com/GoogleCloudPlatform/terraform-google-enterprise-genai.git

cd terraform-google-enterprise-genai/0-bootstrap

  2. Rename terraform.example.tfvars to terraform.tfvars and update the file with values from your environment:

    mv terraform.example.tfvars terraform.tfvars

  3. Use the helper script validate-requirements.sh to validate your environment:

    ../scripts/validate-requirements.sh -o <ORGANIZATION_ID> -b <BILLING_ACCOUNT_ID> -u <END_USER_EMAIL>

    Note: The script is not able to validate if the user is in a Cloud Identity or Google Workspace group with the required roles.

  4. Run terraform init and terraform plan and review the output.

    terraform init
terraform plan -input=false -out bootstrap.tfplan

  5. To validate your policies, run gcloud beta terraform vet. For installation instructions, see Install Google Cloud CLI.

  6. Run the following commands and check for violations:

    export VET_PROJECT_ID=A-VALID-PROJECT-ID
terraform show -json bootstrap.tfplan > bootstrap.json
gcloud beta terraform vet bootstrap.json --policy-library="../policy-library" --project ${VET_PROJECT_ID}

    A-VALID-PROJECT-ID must be an existing project you have access to. This is necessary because gcloud beta terraform vet needs to link resources to a valid Google Cloud Platform project.

  7. Run terraform apply.

    terraform apply bootstrap.tfplan

  8. Run terraform output to get the email address of the terraform service accounts that will be used to run manual steps for shared environments in steps 3-networks-svpc, and 4-projects and the state bucket that will be used by step 4-projects.

    export network_step_sa=$(terraform output -raw networks_step_terraform_service_account_email)
export projects_step_sa=$(terraform output -raw projects_step_terraform_service_account_email)
export projects_gcs_bucket_tfstate=$(terraform output -raw projects_gcs_bucket_tfstate)

echo "network step service account = ${network_step_sa}"
echo "projects step service account = ${projects_step_sa}"
echo "projects gcs bucket tfstate = ${projects_gcs_bucket_tfstate}"

  9. Run terraform output to get the ID of your Cloud Build project:

    export cloudbuild_project_id=$(terraform output -raw cloudbuild_project_id)
echo "cloud build project ID = ${cloudbuild_project_id}"

  10. Copy the backend and update backend.tf with the name of your Google Cloud Storage bucket for Terraform's state. Also update the backend.tf of all steps.

    export backend_bucket=$(terraform output -raw gcs_bucket_tfstate)
echo "backend_bucket = ${backend_bucket}"

export backend_bucket_projects=$(terraform output -raw projects_gcs_bucket_tfstate)
echo "backend_bucket_projects = ${backend_bucket_projects}"

cp backend.tf.example backend.tf
cd ..

for i in `find -name 'backend.tf'`; do sed -i "s/UPDATE_ME/${backend_bucket}/" $i; done
for i in `find -name 'backend.tf'`; do sed -i "s/UPDATE_PROJECTS_BACKEND/${backend_bucket_projects}/" $i; done

cd 0-bootstrap

  11. Re-run terraform init. When you're prompted, agree to copy Terraform state to Cloud Storage.

    terraform init

  12. (Optional) Run terraform plan to verify that state is configured correctly. You should see no changes from the previous state.

  13. Clone the policy repo and copy contents of policy-library to new repo. Clone the repo at the same level of the terraform-google-enterprise-genai folder.

    cd ../..

gcloud source repos clone gcp-policies --project=${cloudbuild_project_id}

cd gcp-policies
git checkout -b main
cp -RT ../terraform-google-enterprise-genai/policy-library/ .

  14. Commit changes and push your main branch to the policy repo.

    git add .
git commit -m 'Initialize policy library repo'
git push --set-upstream origin main

  15. Navigate out of the repo.

    cd ..

  16. Save 0-bootstrap Terraform configuration to gcp-bootstrap source repository:

    gcloud source repos clone gcp-bootstrap --project=${cloudbuild_project_id}

cd gcp-bootstrap
git checkout -b plan
mkdir -p envs/shared

cp -RT ../terraform-google-enterprise-genai/0-bootstrap/ ./envs/shared
cp ../terraform-google-enterprise-genai/build/cloudbuild-tf-* .
cp ../terraform-google-enterprise-genai/build/tf-wrapper.sh .
chmod 755 ./tf-wrapper.sh

git add .
git commit -m 'Initialize bootstrap repo'
git push --set-upstream origin plan
cd ..

  17. Continue with the instructions in the 1-org step.

Note 1: The stages after 0-bootstrap use terraform_remote_state data source to read common configuration like the organization ID from the output of the 0-bootstrap stage. They will fail if the state is not copied to the Cloud Storage bucket.

Note 2: After the deploy, even if you did not receive the project quota error described in the Troubleshooting guide, we recommend that you request 50 additional projects for the projects step service account created in this step.

Running Terraform locally

If you deploy using Cloud Build, the bucket information is replaced in the state backends as part of the build process when the build is executed by Cloud Build. If you want to execute Terraform locally, you need to add your Cloud Storage bucket to the backend.tf files. Each step has instructions for this change.

Inputs

Name Description Type Default Required
billing_account The ID of the billing account to associate projects with. string n/a yes
bucket_force_destroy When deleting a bucket, this boolean option will delete all contained objects. If false, Terraform will fail to delete buckets which contain objects. bool false no
bucket_prefix Name prefix to use for state bucket created. string "bkt" no
bucket_tfstate_kms_force_destroy When deleting a bucket, this boolean option will delete the KMS keys used for the Terraform state bucket. bool false no
default_region Default region to create resources where applicable. string "us-central1" no
folder_deletion_protection Prevent Terraform from destroying or recreating the folder. string true no
folder_prefix Name prefix to use for folders created. Should be the same in all steps. string "fldr" no
group_billing_admins Google Group for GCP Billing Administrators. string n/a yes
group_org_admins Google Group for GCP Organization Administrators. string n/a yes
groups Contain the details of the Groups to be created. 
object({
    create_groups   = bool
    billing_project = optional(string, null)
    required_groups = object({
      group_org_admins           = string
      group_billing_admins       = string
      billing_data_users         = string
      audit_data_users           = string
      monitoring_workspace_users = string
    })
    optional_groups = object({
      gcp_platform_viewer      = optional(string, "")
      gcp_security_reviewer    = optional(string, "")
      gcp_network_viewer       = optional(string, "")
      gcp_scc_admin            = optional(string, "")
      gcp_global_secrets_admin = optional(string, "")
      gcp_audit_viewer         = optional(string, "")
    })
  })
 
{
  "create_groups": false,
  "optional_groups": {
    "gcp_audit_viewer": "",
    "gcp_global_secrets_admin": "",
    "gcp_network_viewer": "",
    "gcp_platform_viewer": "",
    "gcp_scc_admin": "",
    "gcp_security_reviewer": ""
  },
  "required_groups": {
    "audit_data_users": "",
    "billing_data_users": "",
    "group_billing_admins": "",
    "group_org_admins": "",
    "monitoring_workspace_users": ""
  }
}
 no
initial_group_config Define the group configuration when it is initialized. Valid values are: WITH_INITIAL_OWNER, EMPTY and INITIAL_GROUP_CONFIG_UNSPECIFIED. string "WITH_INITIAL_OWNER" no
org_id GCP Organization ID. string n/a yes
org_policy_admin_role Additional Org Policy Admin role for admin group. You can use this for testing purposes. bool false no
org_project_creators Additional list of members to have project creator role across the organization. Prefix of group: user: or serviceAccount: is required. list(string) [] no
parent_folder Optional - for an organization with existing projects or for development/validation. It will place all the example foundation resources under the provided folder instead of the root organization. The value is the numeric folder ID. The folder must already exist. string "" no
project_deletion_policy The deletion policy for the project created. string "PREVENT" no
project_prefix Name prefix to use for projects created. Should be the same in all steps. Max size is 3 characters. string "prj" no
workflow_deletion_protection Whether Terraform will be prevented from destroying a workflow. When the field is set to true or unset in Terraform state, a terraform apply or terraform destroy that would delete the workflow will fail. When the field is set to false, deleting the workflow is allowed. bool true no

Outputs

Name Description
bootstrap_step_terraform_service_account_email Bootstrap Step Terraform Account
cloud_build_peered_network_id The ID of the Cloud Build peered network.
cloud_build_private_worker_pool_id ID of the Cloud Build private worker pool.
cloud_build_worker_peered_ip_range The IP range of the peered service network.
cloud_build_worker_range_id The Cloud Build private worker IP range ID.
cloud_builder_artifact_repo Artifact Registry (AR) Repository created to store TF Cloud Builder images.
cloudbuild_project_id Project where Cloud Build configuration and terraform container image will reside.
common_config Common configuration data to be used in other steps.
csr_repos List of Cloud Source Repos created by the module, linked to Cloud Build triggers.
environment_step_terraform_service_account_email Environment Step Terraform Account
gcs_bucket_cloudbuild_artifacts Bucket used to store Cloud Build artifacts in cicd project.
gcs_bucket_cloudbuild_logs Bucket used to store Cloud Build logs in cicd project.
gcs_bucket_tfstate Bucket used for storing terraform state for Foundations Pipelines in Seed Project.
group_billing_admins Google Group for GCP Billing Administrators.
group_org_admins Google Group for GCP Organization Administrators.
networks_step_terraform_service_account_email Networks Step Terraform Account
optional_groups List of Google Groups created that are optional to the Example Foundation steps.
organization_step_terraform_service_account_email Organization Step Terraform Account
projects_gcs_bucket_tfstate Bucket used for storing terraform state for stage 4-projects foundations pipelines in seed project.
projects_step_terraform_service_account_email Projects Step Terraform Account
required_groups List of Google Groups created that are required by the Example Foundation steps.
seed_project_id Project where service accounts and core APIs will be enabled.