diff --git a/fast/stages/00-bootstrap/README.md b/fast/stages/00-bootstrap/README.md index 3842aa07..f5bf29d0 100644 --- a/fast/stages/00-bootstrap/README.md +++ b/fast/stages/00-bootstrap/README.md @@ -54,6 +54,11 @@ For same-organization billing, we configure a custom organization role that can For details on configuring the different billing account modes, refer to the [How to run this stage](#how-to-run-this-stage) section below. +### Organization-level logging +We create organization-level log sinks early in the bootstrap process to ensure a proper audit trail is in place from the very beginning. By default, we provide log filters to capture [Cloud Audit Logs](https://cloud.google.com/logging/docs/audit) and [VPC Service Controls violations](https://cloud.google.com/vpc-service-controls/docs/troubleshooting#vpc-sc-errors) into a Bigquery dataset in the top-level audit project. + +The [Customizations](#log-sinks-and-log-destinations) section explains how to change the logs captured and their destination. + ### Naming We are intentionally not supporting random prefix/suffixes for names, as that is an antipattern typically only used in development. It does not map to our customer's actual production usage, where they always adopt a fixed naming convention. @@ -278,6 +283,17 @@ In those cases where roles need to be assigned to end-user service accounts (e.g The one exception to this convention is for roles which are part of the delegated grant condition described above, and which can then be assigned from other stages. In this case, use the `iam_additive` variable as they are implemented with non-authoritative resources. Using non-authoritative bindings ensure that re-executing this stage will not override any bindings set in downstream stages. +### Log sinks and log destinations + +You can customize organization-level logs through the `log_sinks` variable in two ways: + +* creating additional log sinks to capture more logs +* changing the destination of captured logs + +By default, all logs are exported to Bigquery, but FAST can create sinks to Cloud Logging Buckets, GCS, or PubSub. + +If you need to capture additional logs, please refer to GCP's documentation on [scenarios for exporting logging data](https://cloud.google.com/architecture/exporting-stackdriver-logging-for-security-and-access-analytics), where you can find ready-made filter expressions for different use cases. + ### Names and naming convention Configuring the individual tokens for the naming convention described above, has varying degrees of complexity: @@ -311,14 +327,14 @@ Names used in internal references (e.g. `module.foo-prod.id`) are only used by T | name | description | type | required | default | producer | |---|---|:---:|:---:|:---:|:---:| | [billing_account](variables.tf#L17) | Billing account id and organization id ('nnnnnnnn' or null). | object({…}) | ✓ | | | -| [organization](variables.tf#L82) | Organization details. | object({…}) | ✓ | | | -| [prefix](variables.tf#L97) | Prefix used for resources that need unique names. | string | ✓ | | | +| [organization](variables.tf#L84) | Organization details. | object({…}) | ✓ | | | +| [prefix](variables.tf#L99) | Prefix used for resources that need unique names. | string | ✓ | | | | [bootstrap_user](variables.tf#L25) | Email of the nominal user running this stage for the first time. | string | | null | | | [groups](variables.tf#L31) | Group names to grant organization-level permissions. | map(string) | | {…} | | | [iam](variables.tf#L45) | Organization-level custom IAM settings in role => [principal] format. | map(list(string)) | | {} | | | [iam_additive](variables.tf#L51) | Organization-level custom IAM settings in role => [principal] format for non-authoritative bindings. | map(list(string)) | | {} | | -| [log_sinks](variables.tf#L57) | Org-level log sinks, in name => {type, filter} format. | map(object({…})) | | {…} | | -| [outputs_location](variables.tf#L91) | Path where providers and tfvars files for the following stages are written. Leave empty to disable. | string | | null | | +| [log_sinks](variables.tf#L59) | Org-level log sinks, in name => {type, filter} format. | map(object({…})) | | {…} | | +| [outputs_location](variables.tf#L93) | Path where providers and tfvars files for the following stages are written. Leave empty to disable. | string | | null | | ## Outputs diff --git a/fast/stages/00-bootstrap/variables.tf b/fast/stages/00-bootstrap/variables.tf index 9f102c77..1bf0e2de 100644 --- a/fast/stages/00-bootstrap/variables.tf +++ b/fast/stages/00-bootstrap/variables.tf @@ -54,6 +54,8 @@ variable "iam_additive" { default = {} } +# See https://cloud.google.com/architecture/exporting-stackdriver-logging-for-security-and-access-analytics +# for additional logging filter examples variable "log_sinks" { description = "Org-level log sinks, in name => {type, filter} format." type = map(object({