Skip to content

Latest commit

 

History

History
578 lines (471 loc) · 29.7 KB

README.md

File metadata and controls

578 lines (471 loc) · 29.7 KB

Organization Module

Original Module from Cloud-Foundation-Fabric

This module allows managing several organization properties:

  • IAM bindings, both authoritative and additive
  • custom IAM roles
  • audit logging configuration for services
  • organization policies
  • organization policy custom constraints

To manage organization policies, the orgpolicy.googleapis.com service should be enabled in the quota project. Furthermore you need to use a service account. End user credentials are not supported!

IAM

There are several mutually exclusive ways of managing IAM in this module

  • non-authoritative via the iam_additive and iam_additive_members variables, where bindings created outside this module will coexist with those managed here
  • authoritative via the group_iam and iam variables, where bindings created outside this module (eg in the console) will be removed at each terraform apply cycle if the same role is also managed here
  • authoritative policy via the iam_bindings_authoritative variable, where any binding created outside this module (eg in the console) will be removed at each terraform apply cycle regardless of the role

If you set audit policies via the iam_audit_config_authoritative variable, be sure to also configure IAM bindings via iam_bindings_authoritative, as audit policies use the underlying google_organization_iam_policy resource, which is also authoritative for any role.

Some care must also be taken with the groups_iam variable (and in some situations with the additive variables) to ensure that variable keys are static values, so that Terraform is able to compute the dependency graph.

Usage

The minimal configuration doesn't do anything.

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
  validation {
    condition     = can(regex("^organizations/[0-9]+", var.organization_id))
    error_message = "The organization_id must in the form organizations/nnn."
  }
}


module "google_organitation" {
  source          = "../.."
  organization_id = var.organization_id
}

So you should configure more than that!

Custom Constraints

Refer to the Creating and managing custom constraints documentation for details on usage. To manage organization policy custom constraints, the orgpolicy.googleapis.com service should be enabled in the quota project.

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}

variable "impersonate_service_account" {
  description = "Mail of service account to impersonate, because ADC not supported."
  type        = string
}


# Make sure to impersonate an service account
# gcloud application-default not supported
provider "google-beta" {
  impersonate_service_account = var.impersonate_service_account
}

provider "google" {
  impersonate_service_account = var.impersonate_service_account
}

module "google_organization" {
  source          = "../.."
  organization_id = var.organization_id

  org_policy_custom_constraints = {
    "custom.gkeEnableAutoUpgrade" = {
      resource_types = ["container.googleapis.com/NodePool"]
      method_types   = ["CREATE"]
      condition      = "resource.management.autoUpgrade == true"
      action_type    = "ALLOW"
      display_name   = "Enable node auto-upgrade"
      description    = "All node pools must have node auto-upgrade enabled."
    }
  }

  # not necessarily to enforce on the org level, policy may be applied on folder/project levels
  org_policies = {
    "custom.gkeEnableAutoUpgrade" = {
      enforce = true
    }
  }
}

Custom Constraints Factory

Org policy custom constraints can be loaded from a directory containing YAML files where each file defines one or more custom constraints. The structure of the YAML files is exactly the same as the org_policy_custom_constraints variable.

The example below deploys a few org policy custom constraints split between two YAML files.

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}

variable "impersonate_service_account" {
  description = "Mail of service account to impersonate, because ADC not supported."
}


# Make sure to impersonate an service account
# gcloud application-default not supported
provider "google-beta" {
  impersonate_service_account = var.impersonate_service_account
}

provider "google" {
  impersonate_service_account = var.impersonate_service_account
}

module "org" {
  source          = "../../"
  organization_id = var.organization_id

  org_policy_custom_constraints_data_path = "custom_constraints"
}

The following two files are in the folder custom_constrains.

custom.dataprocNoMoreThan10Workers:
  resource_types:
  - dataproc.googleapis.com/Cluster
  method_types:
  - CREATE
  - UPDATE
  condition: resource.config.workerConfig.numInstances + resource.config.secondaryWorkerConfig.numInstances > 10
  action_type: DENY
  display_name: Total number of worker instances cannot be larger than 10
  description: Cluster cannot have more than 10 workers, including primary and secondary workers.
custom.gkeEnableLogging:
  resource_types:
  - container.googleapis.com/Cluster
  method_types:
  - CREATE
  - UPDATE
  condition: resource.loggingService == "none"
  action_type: DENY
  display_name: Do not disable Cloud Logging
custom.gkeEnableAutoUpgrade:
  resource_types:
  - container.googleapis.com/NodePool
  method_types:
  - CREATE
  condition: resource.management.autoUpgrade == true
  action_type: ALLOW
  display_name: Enable node auto-upgrade
  description: All node pools must have node auto-upgrade enabled.

Hierarchical firewall policies

Hierarchical firewall policies can be managed in two ways:

  • via the firewall_policies variable, to directly define policies and rules in Terraform
  • via the firewall_policy_factory variable, to leverage external YaML files via a simple "factory" embedded in the module (see here for more context on factories)

Once you have policies (either created via the module or externally), you can associate them using the firewall_policy_association variable.

Directly defined firewall policies

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}


module "google_organization_configuration" {
  source          = "../.."
  organization_id = var.organization_id
  firewall_policies = {
    iap-policy = {
      allow-iap-ssh = {
        description = "Always allow ssh from IAP."
        direction   = "INGRESS"
        action      = "allow"
        priority    = 100
        ranges      = ["35.235.240.0/20"]
        ports = {
          tcp = ["22"]
        }
        target_service_accounts = null
        target_resources        = null
        logging                 = false
      }
    }
  }
  firewall_policy_association = {
    iap_policy = "iap-policy"
  }
}

Firewall policy factory

The in-built factory allows you to define a single policy, using one file for rules, and an optional file for CIDR range substitution variables. Remember that non-absolute paths are relative to the root module (the folder where you run terraform).

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}


module "google_organization_configuration" {
  source          = "../.."
  organization_id = var.organization_id
  firewall_policy_factory = {
    cidr_file   = "./cidrs.yaml"
    policy_name = null
    rules_file  = "./rules.yaml"
  }
  firewall_policy_association = {
    factory-policy = module.google_organization_configuration.firewall_policy_id["factory"]
  }
}

The following two files must exist in the root of the configuration.

cidrs.yaml

rfc1918:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16

rules.yml

allow-admins:
  description: Access from the admin subnet to all subnets
  direction: INGRESS
  action: allow
  priority: 1000
  ranges:
    - $rfc1918
  ports:
    all: []
  target_resources: null
  enable_logging: false

allow-ssh-from-iap:
  description: Enable SSH from IAP
  direction: INGRESS
  action: allow
  priority: 1002
  ranges:
    - 35.235.240.0/20
  ports:
    tcp: ["22"]
  target_resources: null
  enable_logging: false

Logging Sinks

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}

variable "project_id" {
  description = "The id of the project to deploy the logging sinks to."
  type        = string
}


resource "random_id" "gcs" {
  byte_length = 16
}

resource "google_storage_bucket" "this" {
  name          = random_id.gcs.hex
  location      = "EU"
  force_destroy = true
  project       = var.project_id
}

# Also big query-datasets, pubsub, loggingbucket is supported
module "google_organization_configuration" {
  source          = "../.."
  organization_id = var.organization_id

  logging_sinks = {
    warnings = {
      destination = google_storage_bucket.this.id
      filter      = "severity=WARNING"
      type        = "storage"
    }
  }
  logging_exclusions = {
    no-gce-instances = "resource.type=gce_instance"
  }
}

Custom Roles

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}


data "google_client_openid_userinfo" "provider_identity" {
}

module "google_organization_configuration" {
  source          = "../.."
  organization_id = var.organization_id
  custom_roles = {
    "myRole" = [
      "compute.instances.list",
    ]
  }
  iam = {
    (module.google_organization_configuration.custom_role_id.myRole) = ["user:${data.google_client_openid_userinfo.provider_identity.email}"]
  }
}

Tags

Refer to the Creating and managing tags documentation for details on usage.

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}


data "google_client_openid_userinfo" "provider_identity" {
}

module "google_organization_configuration" {
  source          = "../.."
  organization_id = var.organization_id
  tags = {
    environment = {
      description = "Environment specification."
      iam = {
        "roles/resourcemanager.tagAdmin" = ["user:${data.google_client_openid_userinfo.provider_identity.email}"]
      }
      values = {
        dev = {}
        prod = {
          description = "Environment: production."
          iam = {
            "roles/resourcemanager.tagViewer" = ["user:${data.google_client_openid_userinfo.provider_identity.email}"]
          }
        }
      }
    }
  }
  tag_bindings = {
    env-prod = module.google_organization_configuration.tag_values["environment/prod"].id
  }
}

You can also define network tags, through a dedicated variable network_tags.

variable "organization_id" {
  description = "Organization id in organizations/nnnnnn format."
  type        = string
}

variable "project_id" {
  description = "The id of the project to deploy the network to."
  type        = string
}


data "google_client_openid_userinfo" "provider_identity" {
}

resource "google_compute_network" "this" {
  name    = "vpc-network"
  project = var.project_id
}

module "google_organization_configuration" {
  source          = "../.."
  organization_id = var.organization_id
  network_tags = {
    net-environment = {
      description = "This is a network tag."
      network     = "${var.project_id}/${google_compute_network.this.name}"
      iam = {
        "roles/resourcemanager.tagAdmin" = ["user:${data.google_client_openid_userinfo.provider_identity.email}"]
      }
      values = {
        dev = null
        prod = {
          description = "Environment: production."
          iam = {
            "roles/resourcemanager.tagUser" = ["user:${data.google_client_openid_userinfo.provider_identity.email}"]
          }
        }
      }
    }
  }
}

Requirements

Name Version
terraform >= 1.3.1
google >= 4.40.0
google-beta >= 4.40.0

Inputs

Name Description Type Default Required
organization_id Organization id in organizations/nnnnnn format. string n/a yes
contacts List of essential contacts for this resource. Must be in the form EMAIL -> [NOTIFICATION_TYPES]. Valid notification types are ALL, SUSPENSION, SECURITY, TECHNICAL, BILLING, LEGAL, PRODUCT_UPDATES. map(list(string)) {} no
custom_roles Map of role name => list of permissions to create in this project. map(list(string)) {} no
firewall_policies Hierarchical firewall policy rules created in the organization. 
map(map(object({
    action                  = string
    description             = string
    direction               = string
    logging                 = bool
    ports                   = map(list(string))
    priority                = number
    ranges                  = list(string)
    target_resources        = list(string)
    target_service_accounts = list(string)
    # preview                 = bool
  })))
 {} no
firewall_policy_association The hierarchical firewall policy to associate to this folder. Must be either a key in the firewall_policies map or the id of a policy defined somewhere else. map(string) {} no
firewall_policy_factory Configuration for the firewall policy factory. 
object({
    cidr_file   = string
    policy_name = string
    rules_file  = string
  })
 null no
group_iam Authoritative IAM binding for organization groups, in {GROUP_EMAIL => [ROLES]} format. Group emails need to be static. Can be used in combination with the iam variable. map(list(string)) {} no
iam IAM bindings, in {ROLE => [MEMBERS]} format. map(list(string)) {} no
iam_additive Non authoritative IAM bindings, in {ROLE => [MEMBERS]} format. map(list(string)) {} no
iam_additive_members IAM additive bindings in {MEMBERS => [ROLE]} format. This might break if members are dynamic values. map(list(string)) {} no
iam_audit_config Service audit logging configuration. Service as key, map of log permission (eg DATA_READ) and excluded members as value for each service. map(map(list(string))) {} no
iam_audit_config_authoritative IAM Authoritative service audit logging configuration. Service as key, map of log permission (eg DATA_READ) and excluded members as value for each service. Audit config should also be authoritative when using authoritative bindings. Use with caution. map(map(list(string))) null no
iam_bindings_authoritative IAM authoritative bindings, in {ROLE => [MEMBERS]} format. Roles and members not explicitly listed will be cleared. Bindings should also be authoritative when using authoritative audit config. Use with caution. map(list(string)) null no
logging_exclusions Logging exclusions for this organization in the form {NAME -> FILTER}. map(string) {} no
logging_sinks Logging sinks to create for the organization. 
map(object({
    bq_partitioned_table = optional(bool)
    description          = optional(string)
    destination          = string
    disabled             = optional(bool, false)
    exclusions           = optional(map(string), {})
    filter               = string
    include_children     = optional(bool, true)
    type                 = string
  }))
 {} no
network_tags Network tags by key name. The iam attribute behaves like the similarly named one at module level. 
map(object({
    description = optional(string, "Managed by the Terraform organization module.")
    iam         = optional(map(list(string)), {})
    network     = string # project_id/vpc_name
    values = optional(map(object({
      description = optional(string, "Managed by the Terraform organization module.")
      iam         = optional(map(list(string)), {})
    })), {})
  }))
 {} no
org_policies Organization policies applied to this organization keyed by policy name. 
map(object({
    inherit_from_parent = optional(bool) # for list policies only.
    reset               = optional(bool)

    # default (unconditional) values
    allow = optional(object({
      all    = optional(bool)
      values = optional(list(string))
    }))
    deny = optional(object({
      all    = optional(bool)
      values = optional(list(string))
    }))
    enforce = optional(bool, true) # for boolean policies only.

    # conditional values
    rules = optional(list(object({
      allow = optional(object({
        all    = optional(bool)
        values = optional(list(string))
      }))
      deny = optional(object({
        all    = optional(bool)
        values = optional(list(string))
      }))
      enforce = optional(bool, true) # for boolean policies only.
      condition = object({
        description = optional(string)
        expression  = optional(string)
        location    = optional(string)
        title       = optional(string)
      })
    })), [])
  }))
 {} no
org_policies_data_path Path containing org policies in YAML format. string null no
org_policy_custom_constraints Organization policiy custom constraints keyed by constraint name. 
map(object({
    display_name   = optional(string)
    description    = optional(string)
    action_type    = string
    condition      = string
    method_types   = list(string)
    resource_types = list(string)
  }))
 {} no
org_policy_custom_constraints_data_path Path containing org policy custom constraints in YAML format. string null no
tag_bindings Tag bindings for this organization, in key => tag value id format. map(string) null no
tags Tags by key name. The iam attribute behaves like the similarly named one at module level. 
map(object({
    description = optional(string, "Managed by the Terraform organization module.")
    iam         = optional(map(list(string)), {})
    values = optional(map(object({
      description = optional(string, "Managed by the Terraform organization module.")
      iam         = optional(map(list(string)), {})
    })), {})
  }))
 {} no

Outputs

Name Description
custom_role_id Map of custom role IDs created in the organization.
custom_roles Map of custom roles resources created in the organization.
firewall_policies Map of firewall policy resources created in the organization.
firewall_policy_id Map of firewall policy ids created in the organization.
network_tag_keys Tag key resources.
network_tag_values Tag value resources.
organization_id Organization id dependent on module resources.
sink_writer_identities Writer identities created for each sink.
tag_keys Tag key resources.
tag_values Tag value resources.

Resource types

Type Used
google-beta_google_essential_contacts_contact 1
google-beta_google_org_policy_custom_constraint 1
google_bigquery_dataset_iam_member 1
google_compute_firewall_policy 1
google_compute_firewall_policy_association 1
google_compute_firewall_policy_rule 1
google_logging_organization_exclusion 1
google_logging_organization_sink 1
google_org_policy_policy 1
google_organization_iam_audit_config 1
google_organization_iam_binding 1
google_organization_iam_custom_role 1
google_organization_iam_member 1
google_organization_iam_policy 1
google_project_iam_member 1
google_pubsub_topic_iam_member 1
google_storage_bucket_iam_member 1
google_tags_tag_binding 1
google_tags_tag_key 1
google_tags_tag_key_iam_binding 1
google_tags_tag_value 1
google_tags_tag_value_iam_binding 1

Used only includes resource blocks. for_each and count meta arguments, as well as resource blocks of modules are not considered.

Modules

No modules.

Resources by Files

firewall-policies.tf

Name Type
google_compute_firewall_policy.policy resource
google_compute_firewall_policy_association.association resource
google_compute_firewall_policy_rule.rule resource

iam.tf

Name Type
google_organization_iam_audit_config.config resource
google_organization_iam_binding.authoritative resource
google_organization_iam_custom_role.roles resource
google_organization_iam_member.additive resource
google_organization_iam_policy.authoritative resource
google_iam_policy.authoritative data source

logging.tf

Name Type
google_bigquery_dataset_iam_member.bq-sinks-binding resource
google_logging_organization_exclusion.logging-exclusion resource
google_logging_organization_sink.sink resource
google_project_iam_member.bucket-sinks-binding resource
google_pubsub_topic_iam_member.pubsub-sinks-binding resource
google_storage_bucket_iam_member.storage-sinks-binding resource

main.tf

Name Type
google-beta_google_essential_contacts_contact.contact resource

org-policy-custom-constraints.tf

Name Type
google-beta_google_org_policy_custom_constraint.constraint resource

organization-policies.tf

Name Type
google_org_policy_policy.default resource

tags.tf

Name Type
google_tags_tag_binding.binding resource
google_tags_tag_key.default resource
google_tags_tag_key_iam_binding.default resource
google_tags_tag_value.default resource
google_tags_tag_value_iam_binding.default resource

Contribute

This module is derived from google cloud foundation fabric module organization v19. It is designed to be able to integrate new changes from the base repository. Refer to guide in terraform-google-landing-zone repository for information on integrating changes.