cloud-foundation-fabric/fast/stages/3-project-factory/prod/README.md

Project factory

The Project Factory (or PF) builds on top of your foundations to create and set up projects (and related resources) to be used for your workloads. It is organized in folders representing environments (e.g., "dev", "prod"), each implemented by a stand-alone terraform resource factory.

Design overview and choices

A single factory creates projects in a well-defined context, according to your resource management structure. For example, in the diagram above, each Team is structured to have specific folders projects for a given environment, such as Production and Development, per the resource management structure configured in stage 01-resman.

Projects for each environment across different teams are created by dedicated service accounts, as exemplified in the diagram above. While there's no intrinsic limitation regarding where the project factory can create a projects, the IAM bindings for the service account effectively enforce boundaries (e.g., the production service account shouldn't be able to create or have any access to the development projects, and vice versa).

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 and important notifications)

How to run this stage

This stage is meant to be executed after "foundational stages" (i.e., stages 00-bootstrap, 01-resman, 02-networking (either VPN, NVA, NVA with BGP support) and 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., dev.gcp.example.com.)

Provider and Terraform variables

As all other FAST stages, the mechanism used to pass variable values and pre-built provider files from one stage to the next is also leveraged here.

The commands to link or copy the provider and terraform variable files can be easily derived from the stage-links.sh script in the FAST root folder, passing it a single argument with the local output files folder (if configured) or the GCS output bucket in the automation project (derived from stage 0 outputs). The following examples demonstrate both cases, and the resulting commands that then need to be copy/pasted and run.

../../../stage-links.sh ~/fast-config

# copy and paste the following commands for '3-project-factory'

ln -s ~/fast-config/providers/3-project-factory-providers.tf ./
ln -s ~/fast-config/tfvars/globals.auto.tfvars.json ./
ln -s ~/fast-config/tfvars/0-bootstrap.auto.tfvars.json ./
ln -s ~/fast-config/tfvars/1-resman.auto.tfvars.json ./
ln -s ~/fast-config/tfvars/2-networking.auto.tfvars.json ./
ln -s ~/fast-config/tfvars/2-security.auto.tfvars.json ./

../../../stage-links.sh gs://xxx-prod-iac-core-outputs-0

# copy and paste the following commands for '3-project-factory'

gcloud alpha storage cp gs://xxx-prod-iac-core-outputs-0/providers/3-project-factory-providers.tf ./
gcloud alpha storage cp gs://xxx-prod-iac-core-outputs-0/tfvars/globals.auto.tfvars.json ./
gcloud alpha storage cp gs://xxx-prod-iac-core-outputs-0/tfvars/0-bootstrap.auto.tfvars.json ./
gcloud alpha storage cp gs://xxx-prod-iac-core-outputs-0/tfvars/1-resman.auto.tfvars.json ./
gcloud alpha storage cp gs://xxx-prod-iac-core-outputs-0/tfvars/2-networking.auto.tfvars.json ./
gcloud alpha storage cp gs://xxx-prod-iac-core-outputs-0/tfvars/2-security.auto.tfvars.json ./

If you're not using Fast, refer to the 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:

• data/defaults.yaml, manually configured by adapting the data/defaults.yaml, 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 data/projects/project.yaml is provided as reference and documentation for the schema. Projects will be named after the filename, e.g., fast-dev-lab0.yaml will create project fast-dev-lab0.

Once the configuration is complete, run the project factory by running

terraform init
terraform apply

Files

name	description	modules
main.tf	Project factory.	project-factory
outputs.tf	Module outputs.
variables.tf	Module variables.

Variables

name	description	type	required	default	producer
billing_account	Billing account id. If billing account is not part of the same org set is_org_level to false.	object({…})	✓		0-bootstrap
prefix	Prefix used for resources that need unique names. Use 9 characters or less.	string	✓		0-bootstrap
data_dir	Relative path for the folder storing configuration data.	string		"data/projects"
defaults_file	Relative path for the file storing the project factory configuration.	string		"data/defaults.yaml"
environment_dns_zone	DNS zone suffix for environment.	string		null	2-networking
host_project_ids	Host project for the shared VPC.	object({…})		null	2-networking
vpc_self_links	Self link for the shared VPC.	object({…})		null	2-networking

Outputs

name	description	sensitive	consumers
projects	Created projects and service accounts.