Fix READMEs. (#484)
* Fix READMEs. * fix outputs location paths in READMEs * fix output location paths in READMEs * Update README.md * Update README.md Co-authored-by: Ludovico Magnocavallo <ludomagno@google.com>
This commit is contained in:
lcaggio
GitHub
parent
c727abfa3b
commit
6e896382d6
|
|
@ -162,7 +162,7 @@ At any time during the life of this stage, you can configure it to automatically
|
|||
Automatic generation of files is disabled by default. To enable the mechanism, set the `outputs_location` variable to a valid path on a local filesystem, e.g.
|
||||
|
||||
```hcl
|
||||
outputs_location = "../../configs"
|
||||
outputs_location = "../../config"
|
||||
```
|
||||
|
||||
Once the variable is set, `apply` will generate and manage providers and variables files, including the initial one used for this stage after the first run. You can then link these files in the relevant stages, instead of manually transfering outputs from one stage, to Terraform variables in another.
|
||||
|
|
@ -203,13 +203,15 @@ terraform apply \
|
|||
Once the initial `apply` completes successfully, configure a remote backend using the new GCS bucket, and impersonation on the automation service account for this stage. To do this, you can use the generated `providers.tf` file if you have configured output files as described above, or extract its contents from Terraform's output, then migrate state with `terraform init`:
|
||||
|
||||
```bash
|
||||
# if using output files via the outputs_location variable
|
||||
ln -s [path set in outputs_location]/00-bootstrap/* ./
|
||||
# if using output files via the outputs_location and set to `../../config`
|
||||
ln -s ../../config/00-bootstrap/* ./
|
||||
# or from outputs if not using output files
|
||||
terraform output -json providers | jq -r '.["00-bootstrap"]' \
|
||||
> providers.tf
|
||||
# migrate state to GCS bucket configured in providers file
|
||||
terraform init -migrate-state
|
||||
# run terraform apply to remo user iam binding
|
||||
terraform apply
|
||||
```
|
||||
|
||||
## Customizations
|
||||
|
|
|
|||
|
|
@ -53,8 +53,8 @@ To simplify setup, the previous stage pre-configures a valid providers file in i
|
|||
If you have set a valid value for `outputs_location` in the bootstrap stage, simply link the relevant `providers.tf` file from this stage's folder in the path you specified:
|
||||
|
||||
```bash
|
||||
# `outputs_location` is set to `../../configs/example`
|
||||
ln -s ../../configs/example/01-resman/providers.tf
|
||||
# `outputs_location` is set to `../../config`
|
||||
ln -s ../../config/01-resman/providers.tf
|
||||
```
|
||||
|
||||
If you have not configured `outputs_location` in bootstrap, you can derive the providers file from that stage's outputs:
|
||||
|
|
@ -65,6 +65,8 @@ terraform output -json providers | jq -r '.["01-resman"]' \
|
|||
> ../01-resman/providers.tf
|
||||
```
|
||||
|
||||
If you want to continue to rely on `outputs_location` logic, create a `terraform.tfvars` file and configure it as deacribed [here](../00-bootstrap/#output-files-and-cross-stage-variables).
|
||||
|
||||
### Variable configuration
|
||||
|
||||
There are two broad sets of variables you will need to fill in:
|
||||
|
|
@ -77,8 +79,8 @@ To avoid the tedious job of filling in the first group of variable with values d
|
|||
If you configured a valid path for `outputs_location` in the bootstrap stage, simply link the relevant `terraform-*.auto.tfvars.json` files from this stage's outputs folder (under the path you specified), where the `*` above is set to the name of the stage that produced it. For this stage, a single `.tfvars` file is avalaible:
|
||||
|
||||
```bash
|
||||
# `outputs_location` is set to `../../configs/example`
|
||||
ln -s ../../configs/example/01-resman/terraform-bootstrap.auto.tfvars.json
|
||||
# `outputs_location` is set to `../../config`
|
||||
ln -s ../../config/01-resman/terraform-bootstrap.auto.tfvars.json
|
||||
```
|
||||
|
||||
A second set of variables is specific to this stage, they are all optional so if you need to customize them, create an extra `terraform.tfvars` file.
|
||||
|
|
|
|||
|
|
@ -136,8 +136,8 @@ To simplify setup, the previous stage pre-configures a valid providers file in i
|
|||
If you have set a valid value for `outputs_location` in the bootstrap stage, simply link the relevant `providers.tf` file from this stage's folder in the path you specified:
|
||||
|
||||
```bash
|
||||
# `outputs_location` is set to `../../configs/example`
|
||||
ln -s ../../configs/example/02-networking/providers.tf
|
||||
# `outputs_location` is set to `../../config`
|
||||
ln -s ../../config/02-networking/providers.tf
|
||||
```
|
||||
|
||||
If you have not configured `outputs_location` in bootstrap, you can derive the providers file from that stage's outputs:
|
||||
|
|
@ -160,11 +160,13 @@ To avoid the tedious job of filling in the first group of variables with values
|
|||
If you have set a valid value for `outputs_location` in the bootstrap and in the resman stage, simply link the relevant `terraform-*.auto.tfvars.json` files from this stage's folder in the path you specified, where the `*` above is set to the name of the stage that produced it. For this stage, a single `.tfvars` file is available:
|
||||
|
||||
```bash
|
||||
# `outputs_location` is set to `../../configs/example`
|
||||
ln -s ../../configs/example/02-networking/terraform-bootstrap.auto.tfvars.json
|
||||
ln -s ../../configs/example/02-networking/terraform-resman.auto.tfvars.json
|
||||
# `outputs_location` is set to `../../config`
|
||||
ln -s ../../config/02-networking/terraform-bootstrap.auto.tfvars.json
|
||||
ln -s ../../config/02-networking/terraform-resman.auto.tfvars.json
|
||||
```
|
||||
|
||||
If you want to continue to rely on `outputs_location` logic, create a `terraform.tfvars` file and configure it as deacribed [here](../00-bootstrap/#output-files-and-cross-stage-variables).
|
||||
|
||||
Please refer to the [Variables](#variables) table below for a map of the variable origins, and to the sections below on how to adapt this stage to your networking configuration.
|
||||
|
||||
### VPCs
|
||||
|
|
|
|||
|
|
@ -57,8 +57,8 @@ To simplify setup, the previous stage pre-configures a valid providers file in i
|
|||
If you have set a valid value for `outputs_location` in the resource management stage, simply link the relevant `providers.tf` file from this stage's folder in the path you specified:
|
||||
|
||||
```bash
|
||||
# `outputs_location` is set to `../../configs/example`
|
||||
ln -s ../../configs/example/02-security/providers.tf
|
||||
# `outputs_location` is set to `../../config`
|
||||
ln -s ../../config/02-security/providers.tf
|
||||
```
|
||||
|
||||
If you have not configured `outputs_location` in resource management, you can derive the providers file from that stage's outputs:
|
||||
|
|
@ -69,6 +69,8 @@ terraform output -json providers | jq -r '.["02-security"]' \
|
|||
> ../02-security/providers.tf
|
||||
```
|
||||
|
||||
If you want to continue to rely on `outputs_location` logic, create a `terraform.tfvars` file and configure it as deacribed [here](../00-bootstrap/#output-files-and-cross-stage-variables).
|
||||
|
||||
### Variable configuration
|
||||
|
||||
There are two broad sets of variables you will need to fill in:
|
||||
|
|
@ -81,9 +83,9 @@ To avoid the tedious job of filling in the first group of variables with values
|
|||
If you configured a valid path for `outputs_location` in the previous stages, simply link the relevant `terraform-*.auto.tfvars.json` files from this stage's output folder (under the path you specified), where the `*` above is set to the name of the stage that produced it. For this stage, two `.tfvars` files are available:
|
||||
|
||||
```bash
|
||||
# `outputs_location` is set to `../../configs/example`
|
||||
ln -s ../../configs/example/02-security/terraform-bootstrap.auto.tfvars.json
|
||||
ln -s ../../configs/example/02-security/terraform-resman.auto.tfvars.json
|
||||
# `outputs_location` is set to `../../config`
|
||||
ln -s ../../config/02-security/terraform-bootstrap.auto.tfvars.json
|
||||
ln -s ../../config/02-security/terraform-resman.auto.tfvars.json
|
||||
```
|
||||
|
||||
A second set of optional variables is specific to this stage. If you need to customize them, create an extra `terraform.tfvars` file.
|
||||
|
|
|
|||
|
|
@ -15,51 +15,50 @@ Projects for each environment across different teams are created by dedicated se
|
|||
|
||||
The project factory takes care of the following activities:
|
||||
|
||||
* Project creation
|
||||
* API/Services enablement
|
||||
* Service accounts creation
|
||||
* IAM roles assignment for groups and service accounts
|
||||
* KMS keys roles assignment
|
||||
* Shared VPC attachment and subnets IAM binding
|
||||
* DNS zones creation and visibility configuration
|
||||
* Project-level org policies definition
|
||||
* Billing setup (billing account attachment and budget configuration)
|
||||
* Essential contacts definition (for [budget alerts](https://cloud.google.com/billing/docs/how-to/budgets) and [important notifications](https://cloud.google.com/resource-manager/docs/managing-notification-contacts?hl=en))
|
||||
- Project creation
|
||||
- API/Services enablement
|
||||
- Service accounts creation
|
||||
- IAM roles assignment for groups and service accounts
|
||||
- KMS keys roles assignment
|
||||
- Shared VPC attachment and subnets IAM binding
|
||||
- DNS zones creation and visibility configuration
|
||||
- Project-level org policies definition
|
||||
- Billing setup (billing account attachment and budget configuration)
|
||||
- Essential contacts definition (for [budget alerts](https://cloud.google.com/billing/docs/how-to/budgets) and [important notifications](https://cloud.google.com/resource-manager/docs/managing-notification-contacts?hl=en))
|
||||
|
||||
|
||||
## How to run this stage
|
||||
|
||||
This stage is meant to be executed after "foundational stages" (i.e., stages [`00-bootstrap`](../../00-bootstrap), [`01-resman`](../../01-resman), [`02-networking`](../../02-networking) and [`02-security`](../../02-security)) have been run.
|
||||
|
||||
It's of course possible to run this stage in isolation, by making sure the architectural prerequisites are satisfied (e.g., networking), and that the Service Account running the stage is granted the roles/permissions below:
|
||||
|
||||
* One service account per environment, each with appropriate permissions
|
||||
* at the organization level a custom role for networking operations including the following permissions
|
||||
* `"compute.organizations.enableXpnResource"`,
|
||||
* `"compute.organizations.disableXpnResource"`,
|
||||
* `"compute.subnetworks.setIamPolicy"`,
|
||||
* `"dns.networks.bindPrivateDNSZone"`
|
||||
* and role `"roles/orgpolicy.policyAdmin"`
|
||||
* on each folder where projects are created
|
||||
* `"roles/logging.admin"`
|
||||
* `"roles/owner"`
|
||||
* `"roles/resourcemanager.folderAdmin"`
|
||||
* `"roles/resourcemanager.projectCreator"`
|
||||
* on the host project for the Shared VPC
|
||||
* `"roles/browser"`
|
||||
* `"roles/compute.viewer"`
|
||||
* `"roles/dns.admin"`
|
||||
* If networking is used (e.g., for VMs, GKE Clusters or AppEngine flex), VPC Host projects and their subnets should exist when creating projects
|
||||
* If per-environment DNS sub-zones are required, one "root" zone per environment should exist when creating projects (e.g., prod.gcp.example.com.)
|
||||
- One service account per environment, each with appropriate permissions
|
||||
- at the organization level a custom role for networking operations including the following permissions
|
||||
- `"compute.organizations.enableXpnResource"`,
|
||||
- `"compute.organizations.disableXpnResource"`,
|
||||
- `"compute.subnetworks.setIamPolicy"`,
|
||||
- `"dns.networks.bindPrivateDNSZone"`
|
||||
- and role `"roles/orgpolicy.policyAdmin"`
|
||||
- on each folder where projects are created
|
||||
- `"roles/logging.admin"`
|
||||
- `"roles/owner"`
|
||||
- `"roles/resourcemanager.folderAdmin"`
|
||||
- `"roles/resourcemanager.projectCreator"`
|
||||
- on the host project for the Shared VPC
|
||||
- `"roles/browser"`
|
||||
- `"roles/compute.viewer"`
|
||||
- `"roles/dns.admin"`
|
||||
- If networking is used (e.g., for VMs, GKE Clusters or AppEngine flex), VPC Host projects and their subnets should exist when creating projects
|
||||
- If per-environment DNS sub-zones are required, one "root" zone per environment should exist when creating projects (e.g., prod.gcp.example.com.)
|
||||
|
||||
### Providers configuration
|
||||
|
||||
If you're running this on top of Fast, you should run the following commands to create the providers file, and populate the required variables from the previous stage.
|
||||
|
||||
```bash
|
||||
# Variable `outputs_location` is set to `../../configs/example` in stage 01-resman
|
||||
# Variable `outputs_location` is set to `../../config` in stage 01-resman
|
||||
$ cd fabric-fast/stages/03-project-factory/prod
|
||||
ln -s ../../../configs/example/03-project-factory-prod/providers.tf
|
||||
ln -s ../../../config/03-project-factory-prod/providers.tf
|
||||
```
|
||||
|
||||
### Variable configuration
|
||||
|
|
@ -74,18 +73,17 @@ To avoid the tedious job of filling in the first group of variables with values
|
|||
If you configured a valid path for `outputs_location` in the bootstrap and networking stage, simply link the relevant `terraform-*.auto.tfvars.json` files from this stage's outputs folder (under the path you specified), where the `*` above is set to the name of the stage that produced it. For this stage, a single `.tfvars` file is available:
|
||||
|
||||
```bash
|
||||
# Variable `outputs_location` is set to `../../configs/example` in stages 01-bootstrap and 02-networking
|
||||
ln -s ../../../configs/example/03-project-factory-prod/terraform-bootstrap.auto.tfvars.json
|
||||
ln -s ../../../configs/example/03-project-factory-prod/terraform-networking.auto.tfvars.json
|
||||
# Variable `outputs_location` is set to `../../config` in stages 01-bootstrap and 02-networking
|
||||
ln -s ../../../config/03-project-factory-prod/terraform-bootstrap.auto.tfvars.json
|
||||
ln -s ../../../config/03-project-factory-prod/terraform-networking.auto.tfvars.json
|
||||
```
|
||||
|
||||
If you're not using Fast, refer to the [Variables](#variables) table at the bottom of this document for a full list of variables, their origin (e.g., a stage or specific to this one), and descriptions explaining their meaning.
|
||||
|
||||
Besides the values above, a project factory takes 2 additional inputs:
|
||||
Besides the values above, a project factory takes 2 additional inputs:
|
||||
|
||||
* `data/defaults.yaml`, manually configured by adapting the [`prod/data/defaults.yaml.sample`](./prod/data/defaults.yaml.sample), which defines per-environment default values e.g., for billing alerts and labels.
|
||||
|
||||
* `data/projects/*.yaml`, one file per project (optionally grouped in folders), which configures each project. A [`prod/data/projects/project.yaml.sample`](./prod/data/projects/project.yaml.sample) is provided as reference and documentation for the schema. Projects will be named after the filename, e.g., `fast-prod-lab0.yaml` will create project `fast-prod-lab0`.
|
||||
- `data/defaults.yaml`, manually configured by adapting the [`prod/data/defaults.yaml.sample`](./prod/data/defaults.yaml.sample), which defines per-environment default values e.g., for billing alerts and labels.
|
||||
- `data/projects/*.yaml`, one file per project (optionally grouped in folders), which configures each project. A [`prod/data/projects/project.yaml.sample`](./prod/data/projects/project.yaml.sample) is provided as reference and documentation for the schema. Projects will be named after the filename, e.g., `fast-prod-lab0.yaml` will create project `fast-prod-lab0`.
|
||||
|
||||
Once the configuration is complete, run the project factory by running
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue