cloud-foundation-fabric/blueprints/factories/project-factory/README.md

Minimal Project Factory

This module implements a minimal, opinionated project factory (see Factories for rationale) that allows for the creation of projects.

While the module can be invoked by manually populating the required variables, its interface is meant for the massive creation of resources leveraging a set of well-defined YaML documents, as shown in the examples below.

The Project Factory is meant to be executed by a Service Account (or a regular user) having this minimal set of permissions over your resources:

• Org 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 will be created
  • "roles/logging.admin"
  • "roles/owner"
  • "roles/resourcemanager.folderAdmin"
  • "roles/resourcemanager.projectCreator"
• on the host project for the Shared VPC/s
  • "roles/browser"
  • "roles/compute.viewer"
  • "roles/dns.admin"

Example

Directory structure

.
├── data
│   ├── defaults.yaml
│   └── projects
│       ├── project-example-one.yaml
│       ├── project-example-two.yaml
│       └── project-example-three.yaml
├── main.tf
└── terraform.tfvars

Terraform code

locals {
  defaults = yamldecode(file(local._defaults_file))
  projects = {
    for f in fileset("${local._data_dir}", "**/*.yaml") :
    trimsuffix(f, ".yaml") => yamldecode(file("${local._data_dir}/${f}"))
  }
  # these are usually set via variables
  _base_dir      = "./fabric/blueprints/factories/project-factory"
  _data_dir      = "${local._base_dir}/sample-data/projects/"
  _defaults_file = "${local._base_dir}/sample-data/defaults.yaml"
}

module "projects" {
  source                 = "./fabric/blueprints/factories/project-factory"
  for_each               = local.projects
  defaults               = local.defaults
  project_id             = each.key
  descriptive_name       = try(each.value.descriptive_name, null)
  billing_account_id     = try(each.value.billing_account_id, null)
  billing_alert          = try(each.value.billing_alert, null)
  dns_zones              = try(each.value.dns_zones, [])
  essential_contacts     = try(each.value.essential_contacts, [])
  folder_id              = each.value.folder_id
  group_iam              = try(each.value.group_iam, {})
  iam                    = try(each.value.iam, {})
  kms_service_agents     = try(each.value.kms_service_agents, {})
  labels                 = try(each.value.labels, {})
  org_policies           = try(each.value.org_policies, {})
  prefix                 = each.value.prefix
  service_accounts       = try(each.value.service_accounts, {})
  services               = try(each.value.services, [])
  service_identities_iam = try(each.value.service_identities_iam, {})
  vpc                    = try(each.value.vpc, null)
}
# tftest modules=7 resources=38 inventory=example.yaml

Projects configuration

# ./data/defaults.yaml
# The following applies as overridable defaults for all projects
# All attributes are required

billing_account_id: 012345-67890A-BCDEF0
billing_alert:
  amount: 1000
  thresholds:
    current: [0.5, 0.8]
    forecasted: [0.5, 0.8]
  credit_treatment: INCLUDE_ALL_CREDITS
environment_dns_zone: prod.gcp.example.com
essential_contacts: []
labels:
  environment: production
  department: legal
  application: my-legal-bot
notification_channels: []
shared_vpc_self_link: https://www.googleapis.com/compute/v1/projects/project-example-host-project/global/networks/vpc-one
vpc_host_project: project-example-host-project

# ./data/projects/project-example-one.yaml
# One file per project - projects will be named after the filename

# [opt] Billing account id - overrides default if set
billing_account_id: 012345-67890A-BCDEF0

# [opt] Billing alerts config - overrides default if set
billing_alert:
  amount: 10
  thresholds:
    current:
      - 0.5
      - 0.8
    forecasted: []

# [opt] DNS zones to be created as children of the environment_dns_zone defined in defaults
dns_zones:
    - lorem
    - ipsum

# [opt] Contacts for billing alerts and important notifications
essential_contacts:
  - team-a-contacts@example.com

# Folder the project will be created as children of
folder_id: folders/012345678901

# [opt] Authoritative IAM bindings in group => [roles] format
group_iam:
  test-team-foobar@fast-lab-0.gcp-pso-italy.net:
    - roles/compute.admin

# [opt] Authoritative IAM bindings in role => [principals] format
# Generally used to grant roles to service accounts external to the project
iam:
  roles/compute.admin:
    - serviceAccount:service-account

# [opt] Service robots and keys they will be assigned as cryptoKeyEncrypterDecrypter
# in service => [keys] format
kms_service_agents:
  compute: [key1, key2]
  storage: [key1, key2]

# [opt] Labels for the project - merged with the ones defined in defaults
labels:
  environment: prod

# [opt] Org policy overrides defined at project level
org_policies:
  compute.disableGuestAttributesAccess:
    rules:
    - enforce: true
  compute.trustedImageProjects:
    rules:
    - allow:
        values:
        - projects/fast-dev-iac-core-0
  compute.vmExternalIpAccess:
    rules:
    - deny:
        all: true

# [opt] Service account to create for the project and their roles on the project
# in name => [roles] format
service_accounts:
  another-service-account:
    - roles/compute.admin
  my-service-account:
    - roles/compute.admin

# [opt] IAM bindings on the service account resources.
# in name => {role => [members]} format
service_accounts_iam:
  another-service-account:
    - roles/iam.serviceAccountTokenCreator:
      - group: app-team-1@example.com

# [opt] APIs to enable on the project.
services:
  - storage.googleapis.com
  - stackdriver.googleapis.com
  - compute.googleapis.com

# [opt] Roles to assign to the robots service accounts in robot => [roles] format
services_iam:
  compute:
    - roles/storage.objectViewer

 # [opt] VPC setup.
 # If set enables the `compute.googleapis.com` service and configures
 # service project attachment
vpc:

  # [opt] If set, enables the container API
  gke_setup:

    # Grants "roles/container.hostServiceAgentUser" to the container robot if set
    enable_host_service_agent: false

    # Grants  "roles/compute.securityAdmin" to the container robot if set
    enable_security_admin: true

  # Host project the project will be service project of
  host_project: fast-prod-net-spoke-0

  # [opt] Services for which set up the IAM in the host project
  service_iam_grants:
    - dataproc.googleapis.com

  # [opt] Roles to rant service project service identities in host project
  service_identity_iam:
    "roles/compute.networkUser":
      - cloudservices
      - container-engine

  # [opt] Subnets in the host project where principals will be granted networkUser
  # in region/subnet-name => [principals]
  subnets_iam:
    europe-west1/prod-default-ew1:
      - user:foobar@example.com
      - serviceAccount:service-account1@my-project.iam.gserviceaccount.com

Variables

name	description	type	required	default
billing_account_id	Billing account id.	string	✓
prefix	Prefix used for resource names.	string	✓
project_id	Project id.	string	✓
billing_alert	Billing alert configuration.	object({…})		null
defaults	Project factory default values.	object({…})		null
descriptive_name	Name of the project name. Used for project name instead of name variable.	string		null
dns_zones	DNS private zones to create as child of var.defaults.environment_dns_zone.	list(string)		[]
essential_contacts	Email contacts to be used for billing and GCP notifications.	list(string)		[]
folder_id	Folder ID for the folder where the project will be created.	string		null
group_iam	Custom IAM settings in group => [role] format.	map(list(string))		{}
group_iam_additive	Custom additive IAM settings in group => [role] format.	map(list(string))		{}
iam	Custom IAM settings in role => [principal] format.	map(list(string))		{}
iam_additive	Custom additive IAM settings in role => [principal] format.	map(list(string))		{}
kms_service_agents	KMS IAM configuration in as service => [key].	map(list(string))		{}
labels	Labels to be assigned at project level.	map(string)		{}
org_policies	Org-policy overrides at project level.	map(object({…}))		{}
service_accounts	Service accounts to be created, and roles assigned them on the project.	map(list(string))		{}
service_accounts_additive	Service accounts to be created, and roles assigned them on the project additively.	map(list(string))		{}
service_accounts_iam	IAM bindings on service account resources. Format is KEY => {ROLE => [MEMBERS]}.	map(map(list(string)))		{}
service_accounts_iam_additive	IAM additive bindings on service account resources. Format is KEY => {ROLE => [MEMBERS]}.	map(map(list(string)))		{}
service_identities_iam	Custom IAM settings for service identities in service => [role] format.	map(list(string))		{}
service_identities_iam_additive	Custom additive IAM settings for service identities in service => [role] format.	map(list(string))		{}
services	Services to be enabled for the project.	list(string)		[]
vpc	VPC configuration for the project.	object({…})		{…}

Outputs

name	description	sensitive
project	The project resource as return by the project module.
project_id	Project ID.