Skip to content

Commit

Permalink
chore: Ported readme file to new readme format (terraform-google-modu…
Browse files Browse the repository at this point in the history 
…les#421)

* Ported readme file to new readme format.

* Update 0-bootstrap/README.md

Co-authored-by: Bharath KKB <[email protected]>

* Update 0-bootstrap/README.md

Co-authored-by: Bharath KKB <[email protected]>

* Update 0-bootstrap/README.md

Co-authored-by: Bharath KKB <[email protected]>

* Cleaned up blank spaces at end of line. Re-added rest of troubleshooting info.

* Fixed table syntax. Table should not have a header row.

* Fixing code indentation in procedure

* Last comments from current review

* Ported readme file to new readme format.

* Cleaned up blank spaces at end of line. Re-added rest of troubleshooting info.

* Update 0-bootstrap/README.md

Co-authored-by: Bharath KKB <[email protected]>

* Update 0-bootstrap/README.md

Co-authored-by: Bharath KKB <[email protected]>

* Fixed table syntax. Table should not have a header row.

* Fixing code indentation in procedure

* Last comments from current review

* whitespace

* Update 0-bootstrap/README.md

* Update README.md

* Update 0-bootstrap/README.md

Co-authored-by: Daniel Andrade <[email protected]>

* Fixed sed line. Merged inappropriate line break.

* Update README.md

Co-authored-by: Bharath KKB <[email protected]>
Co-authored-by: Daniel Andrade <[email protected]>
  • Loading branch information
@mark1000 @bharathkkb @daniel-cit
3 people authored Apr 16, 2021
1 parent 76efbe8 commit 1d040cd
Showing 1 changed file with 162 additions and 52 deletions.
214 changes: 162 additions & 52 deletions 0-bootstrap/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,59 +1,146 @@
# 0-bootstrap

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

## Prerequisites

1. A GCP [Organization](https://cloud.google.com/resource-manager/docs/creating-managing-organization)
1. A GCP [Billing Account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
1. Cloud Identity / Google Workspace (former G Suite) groups for organization and billing admins
1. User account should be used for running this step, service accounts are not supported.
1. Membership in the `group_org_admins` group for the user running terraform.
1. Grant the roles mentioned in bootstrap module [README.md](https://github.com/terraform-google-modules/terraform-google-bootstrap#permissions), as well as `roles/resourcemanager.folderCreator` for the user running the step.

Further details of groups, permissions required and resources created, can be found in the bootstrap module [documentation.](https://github.com/terraform-google-modules/terraform-google-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](https://services.google.com/fh/files/misc/google-cloud-security-foundations-guide.pdf)
(PDF). The following table lists the parts of the guide.

<table>
<tbody>
<tr>
<td>0-bootstrap (this file)</td>
<td>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.</td>
</tr>
<tr>
<td><a
href="https://github.com/terraform-google-modules/terraform-example-foundation/tree/master/1-org">1-org</a></td>
<td>Sets up top level shared folders, monitoring and networking projects, and
organization-level logging, and sets baseline security settings through
organizational policy.</td>
</tr>
<tr>
<td><a
href="https://github.com/terraform-google-modules/terraform-example-foundation/tree/master/2-environments">2-environments</a></td>
<td>Sets up development, non-production, and production environments within the
Google Cloud organization that you've created.</td>
</tr>
<tr>
<td><a
href="https://github.com/terraform-google-modules/terraform-example-foundation/tree/master/3-networks">3-networks</a></td>
<td>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. Also sets
up the global DNS hub.</td>
</tr>
<tr>
<td><a
href="https://github.com/terraform-google-modules/terraform-example-foundation/tree/master/4-projects">4-projects</a></td>
<td>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.</td>
</tr>
</tbody>
</table>

For an overview of the architecture and the parts, see the
[terraform-example-foundation README](https://github.com/terraform-google-modules/terraform-example-foundation)
file.

## Purpose

The purpose of this step is to bootstrap a Google Cloud organization, creating all the required resources & 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 andCloud Source Repos or Jenkins and your own Git repos (which might live on-premises).

**Note:** when running the examples in this repository, you may receive various errors when applying terraform:

- `Error code 8, message: The project cannot be created because you have exceeded your allotted project quota.`. That means you have reached your [Project creation quota](https://support.google.com/cloud/answer/6330231). In this case you can use this [Request Project Quota Increase](https://support.google.com/code/contact/project_quota_increase) form to request a quota increase. The `terraform_service_account` created in `0-bootstrap` should also be listed in "Email addresses that will be used to create projects" in that support form. If you face others quota errors, check the [Quota documentation](https://cloud.google.com/docs/quota) for guidance.
- `Error: Error when reading or editing Organization Not Found : <organization-id>: googleapi: Error 403: The caller does not have permission, forbidden`.
- Check that your user have [Organization Admin](https://cloud.google.com/iam/docs/understanding-roles#resource-manager-roles) predefined role at the Organization level.
- If this is the case, try the following:
```
gcloud auth application-default login
gcloud auth list # <- confirm that correct account has a star next to it
```
- Re-run `terraform` after.
- `Error: Error setting billing account "XXXXXX-XXXXXX-XXXXXX" for project "projects/some-project": googleapi: Error 400: Precondition check failed., failedPrecondition`. Most likely this is related to billing quota issue.
- To confirm this, try `gcloud alpha billing projects link projects/some-project --billing-account XXXXXX-XXXXXX-XXXXXX`.
- If output states `Cloud billing quota exceeded`, please request increase via [https://support.google.com/code/contact/billing_quota_increase](https://support.google.com/code/contact/billing_quota_increase).
## 0-bootstrap usage to deploy Jenkins
If you are using the `jenkins_bootstrap` sub-module, please see [README-Jenkins](./README-Jenkins.md) 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 Master environment.
## 0-bootstrap usage to deploy Cloud Build
## Prerequisites

1. Change into 0-bootstrap folder
1. Copy tfvars by running `cp terraform.example.tfvars terraform.tfvars` and update `terraform.tfvars` with values from your environment.
1. Run `terraform init`
1. Run `terraform plan` and review output
To run the commands described in this document, you need to have the following
installed:

- The [Google Cloud SDK](https://cloud.google.com/sdk/install) version
206.0.0 or later
- [Terraform](https://www.terraform.io/downloads.html) version 0.13.6 or later.

Note: Make sure that you use the same version of Terraform throughout this
series. Otherwise, you might experience Terraform state snapshot lock errors.

Also make sure that you've done the following:

1. Set up a Google Cloud
[organization](https://cloud.google.com/resource-manager/docs/creating-managing-organization).
1. Set up a Google Cloud
[billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account).
1. Created Cloud Identity or Google Workspace (formerly G Suite) groups for
organization and billing admins.
1. Added 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.
1. For the user who will run the procedures in this document, granted the
following roles:
- The `roles/resourcemanager.organizationAdmin` role on the Google
Cloud organization.
- The `roles/billing.admin` role on the billing account.
- The `roles/resourcemanager.folderCreator` 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.](https://github.com/terraform-google-modules/terraform-google-bootstrap)

## Deploying with Jenkins

If you are using the `jenkins_bootstrap` sub-module, see
[README-Jenkins](https://github.com/terraform-google-modules/terraform-example-foundation/blob/master/0-bootstrap/README-Jenkins.md)
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 (master) environment.

## Deploying with Cloud Build

1. Go to the `0-bootstrap` folder.
1. Copy the `tfvars` file:
```
cp terraform.example.tfvars terraform.tfvars
```
1. Update the `terraform.tfvars` file with values from your environment.
1. Run `terraform init`.
1. Run `terraform plan` and review the output.
1. To run terraform-validator steps please follow the [instructions](https://github.com/forseti-security/policy-library/blob/master/docs/user_guide.md#install-terraform-validator) in the **Install Terraform Validator** section and install version `2021-03-22`. You will also need to rename the binary from `terraform-validator-<your-platform>` to `terraform-validator`.
1. Run `terraform plan -input=false -out bootstrap.tfplan`
1. Run `terraform show -json bootstrap.tfplan > bootstrap.json`
1. Run `terraform-validator validate bootstrap.json --policy-path="../policy-library" --project <A-VALID-PROJECT-ID>` and check for violations (`<A-VALID-PROJECT-ID>` must be an existing project you have access to, this is necessary because Terraform-validator needs to link resources to a valid Google Cloud Platform project).
1. Run `terraform apply`
1. Run `terraform output gcs_bucket_tfstate` to get your GCS bucket from the apply step
1. Copy the backend by running `cp backend.tf.example backend.tf` and update `backend.tf` with your GCS bucket.
1. Re-run `terraform init` agree to copy state to GCS when prompted
1. (Optional) Run `terraform apply` to verify state is configured correctly
### (Optional) State backends for running terraform locally
Currently, the bucket information is replaced in the state backends as a part of the build process when executed by Cloud Build. If you would like to execute terraform locally, you will need to add your GCS bucket to the `backend.tf` files. You can update all of these files with the following steps:
1. Change into the main directory for the terraform-example-foundation.
1. Run this command ```for i in `find -name 'backend.tf'`; do sed -i 's/UPDATE_ME/GCS_BUCKET_NAME/' $i; done``` where `GCS_BUCKET_NAME` is the name of your bucket from the steps executed above.
1. Run `terraform apply`.
1. Run `terraform output gcs_bucket_tfstate` to get your Google Cloud bucket
from the previous step.
1. Copy the backend:
```
cp backend.tf.example backend.tf
```
1. Update `backend.tf` with the name of your Cloud Storage bucket.
1. Run `terraform output terraform_sa_email` to get the email address of the
admin. You need this address in a later procedure.
1. Re-run `terraform init`. When you're prompted, agree to copy state to
Cloud Storage.
1. (Optional) Run `terraform apply` to verify that state is configured
correctly. You should see no changes from the previous state.

## Running Terraform locally

If you deploy using Cloud Build, the bucket information is replaced in the state
backends as a 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. You can update all of these files with
the following steps:

1. Go to the `terraform-example-foundation` directory.
1. Run the following command:
```
for i in `find -name 'backend.tf'`; do sed -i 's/UPDATE_ME/GCS_BUCKET_NAME/' $i; done
```
where `GCS_BUCKET_NAME` is the name of your bucket from the steps you ran
earlier.

<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
## Inputs
Expand Down Expand Up @@ -90,10 +177,33 @@ Currently, the bucket information is replaced in the state backends as a part of

<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

## Requirements
## Troubleshooting

When you run the examples in this repository, you might see the following errors
during a Terraform `apply` command:


### Software
- `Error code 8, message: The project cannot be created because you have exceeded
your allotted project quota`.

- This message means you have reached your [project creation
quota](https://support.google.com/cloud/answer/6330231). In this case, you can
use the
[Request Project Quota Increase](https://support.google.com/code/contact/project_quota_increase)
form to request a quota increase. In the support form, for **Email addresses
that will be used to create projects**, use the `terraform_sa_email` address
that's created in the organization bootstrap module. If you see other quota
errors, see the [Quota documentation](https://cloud.google.com/docs/quota).

- `Error: Error when reading or editing Organization Not Found : <organization-id>: googleapi: Error 403: The caller does not have permission, forbidden`.
- Check that your user have [Organization Admin](https://cloud.google.com/iam/docs/understanding-roles#resource-manager-roles) predefined role at the Organization level.
- If this is the case, try the following:
```
gcloud auth application-default login
gcloud auth list # <- confirm that correct account has a star next to it
```
- Re-run `terraform` after.
- [gcloud sdk](https://cloud.google.com/sdk/install) >= 206.0.0
- [Terraform](https://www.terraform.io/downloads.html) >= 0.13.6
- You should use the same version in the manual steps during 0-bootstrap to avoid possible [Terraform State Snapshot Lock](https://github.com/hashicorp/terraform/issues/23290) errors caused by differences in terraform versions. This can usually be resolved with a version upgrade.
- `Error: Error setting billing account "XXXXXX-XXXXXX-XXXXXX" for project "projects/some-project": googleapi: Error 400: Precondition check failed., failedPrecondition`. Most likely this is related to billing quota issue.
- To confirm this, try `gcloud alpha billing projects link projects/some-project --billing-account XXXXXX-XXXXXX-XXXXXX`.
- If output states `Cloud billing quota exceeded`, please request increase via [https://support.google.com/code/contact/billing_quota_increase](https://support.google.com/code/contact/billing_quota_increase).

0 comments on commit 1d040cd

Please sign in to comment.