Terraform Log Export Module

This module allows you to create log exports at the project, folder, organization, or billing account level. Submodules are also available to configure the destination resource that will store all exported logs. The resources/services/activations/deletions that this module will create/trigger are:

• An Aggregated log export on the project-level, folder-level, organization-level, or billing-account-level
• A Service account (logsink writer)
• A Destination (Cloud Storage bucket, Cloud Pub/Sub topic, BigQuery dataset)

Compatibility

Tested with Terraform 0.14.4. This module is meant for use with Terraform >=0.13. If you haven't upgraded and need a Terraform 0.12.x-compatible version of this module, the last released version intended for Terraform 0.12.x is v5.1.0.

Usage

Consider the following example that will configure a Cloud Storage destination and a log export at the project level:

module "log_export" {
  source                 = "<path-to-module>"
  destination_uri        = "${module.destination.destination_uri}"
  filter                 = "severity >= ERROR"
  log_sink_name          = "storage_example_logsink"
  parent_resource_id     = "sample-project"
  parent_resource_type   = "project"
  unique_writer_identity = true
}

module "destination" {
  source                   = "<path-to-module>/modules/storage"
  project_id               = "sample-project"
  storage_bucket_name      = "storage_example_bucket"
  log_sink_writer_identity = "${module.log_export.writer_identity}"
}

At first glance that example seems like a circular dependency as each module declaration is using an output from the other, however Terraform is able to collect and order all the resources so that all dependencies are met.

Inputs

Name	Description	Type	Default	Required
destination_uri	The self_link URI of the destination resource (This is available as an output coming from one of the destination submodules)	string	n/a	yes
filter	The filter to apply when exporting logs. Only log entries that match the filter are exported. Default is '' which exports all logs.	string	""	no
include_children	Only valid if 'organization' or 'folder' is chosen as var.parent_resource.type. Determines whether or not to include children organizations/folders in the sink export. If true, logs associated with child projects are also exported; otherwise only logs relating to the provided organization/folder are included.	bool	false	no
log_sink_name	The name of the log sink to be created.	string	n/a	yes
parent_resource_id	The ID of the GCP resource in which you create the log sink. If var.parent_resource_type is set to 'project', then this is the Project ID (and etc).	string	n/a	yes
parent_resource_type	The GCP resource in which you create the log sink. The value must not be computed, and must be one of the following: 'project', 'folder', 'billing_account', or 'organization'.	string	"project"	no
unique_writer_identity	Whether or not to create a unique identity associated with this sink. If false (the default), then the writer_identity used is serviceAccount:cloud-logs@system.gserviceaccount.com. If true, then a unique service account is created and used for the logging sink.	bool	false	no

Outputs

Name	Description
filter	The filter to be applied when exporting logs.
log_sink_resource_id	The resource ID of the log sink that was created.
log_sink_resource_name	The resource name of the log sink that was created.
parent_resource_id	The ID of the GCP resource in which you create the log sink.
writer_identity	The service account that logging uses to write log entries to the destination.

Requirements

Terraform plugins

• Terraform >= 0.13.0
• terraform-provider-google plugin ~> v3.5.x

Configure a Service Account

In order to execute this module you must have a Service Account with the following:

Roles

The service account should have the following roles:

• roles/logging.configWriter on the logsink's project, folder, or organization (to create the logsink)
• roles/resourcemanager.projectIamAdmin on the destination project (to grant write permissions for logsink service account)
• roles/serviceusage.serviceUsageAdmin on the destination project (to enable destination APIs)

Storage role

To use a Google Cloud Storage bucket as the destination:

• roles/storage.admin on the destination project (to create a storage bucket)

Enable API's

In order to operate with the Service Account you must activate the following API's on the base project where the Service Account was created:

• Cloud Resource Manager API - cloudresourcemanager.googleapis.com
• Cloud Billing API - cloudbilling.googleapis.com
• Identity and Access Management API - iam.googleapis.com
• Service Usage API - serviceusage.googleapis.com
• Stackdriver Logging API - logging.googleapis.com
• Cloud Storage JSON API - storage-api.googleapis.com

Install

Terraform

Be sure you have the correct Terraform version (0.12.x), you can choose the binary here:

• https://releases.hashicorp.com/terraform/