Skip to content

Commit

Permalink
tests and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Luca Prete committed Aug 28, 2024
1 parent a8b9f83 commit 33b53f2
Show file tree
Hide file tree
Showing 16 changed files with 1,765 additions and 300 deletions.
86 changes: 75 additions & 11 deletions fast/stages/2-security/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,15 +50,19 @@ IAM roles on keys can be configured at the logical level for all locations where

### Certificate Authority Service (CAS)

You can use this stage to optionally leverage Certificate Authority Services (CAS) and create as many CAs you need for each environment. To create custom CAS, you can use the `cas_configs` variable. The variables come with some defaults for demo purposes: for each environment, specifying the CA `location` should be enough for most of your test scenarios.
With this stage you can leverage Certificate Authority Services (CAS) and create as many CAs you need for each environments. To create custom CAS, you can use the `cas_configs` variable. The variable comes with some defaults, useful for demos: in each environment, specifying the CA `location` should be enough for most of your test scenarios.

### Trust Configs

The stage lets you also create Certificate Manager trust configs. With trust configs you can trust whole CAs or specific server certificates, when you use them with third-party services in GCP. You can create additional trust configs for each environment with the `trust_configs` variable. At a very minimum, for each trust config you'll need to specify the `location` (the region) and either a `trust_stores` block or an `allowed_certificates` block.
The stage lets you also create Certificate Manager trust configs. With trust configs you can trust whole CAs or specific server certificates, when you use them with other services, such as NGFW Enterprise. You can create additional trust configs for each environment with the `trust_configs` variable. At a very minimum, each trust config needs a `location` (the region) and either a `trust_stores` block or an `allowed_certificates` block.

### NGFW Enterprise and TLS inspection support

We deploy NGFW Enterprise in the [network-security stage](../3-network-security/README.md). If you want to enable TLS inspection, NGFW Enterprise requires CAS and -optionally- a Certificate Manager trust config. You can create both leveraging the `cas_configs` and the `trust_configs` variables. Given the [network-security stage](../3-network-security/README.md) needs to reference these resources, you will need to use specific map keys. These are defined in the `ngfw_tls_config_keys` variable, which comes with default and can be further customized. You can read more about NGFW configurations in the [Customizations section](#customizations) of this document.
We deploy NGFW Enterprise in the [network-security stage](../3-network-security/README.md). If you require TLS inspection, NGFW needs to interact with CAS and -optionally- Certificate Manager trust-configs. These components bind to firewall endpoint associations (created in the [network-security stage](../3-network-security/README.md)) with zonal TLS inspection policies.
Using this module, you can define CAS configurations and trust-configs for NGFW Enterprise. You can create them using the `cas_configs` and `trust_configs` variables. Anyway, these will need to use specific keys (defined in `ngfw_tls_configs.keys`), so that FAST knows which configurations to use for NGFW Enterprise.
You can then enable TLS inspection and customize its behavior for NGFW Enterprise, using the `ngfw_tls_configs.tls_inspection` variable. FAST will create the TLS inspection policies for you in the regions where you defined your CAs for NGFW Enterprise.
When you create your CAs and trust-configs for NGFW Enterprise, make sure their region matches the zones where you will define your firewall endpoints.
You can read more about NGFW configurations in the [Customizations section](#customizations) of this document.

## How to run this stage

Expand Down Expand Up @@ -178,7 +182,7 @@ The script will create one keyring for each specified location and keys on each

### NGFW Enterprise - sample TLS configurations

This is a sample configuration that creates a CA and a trust config, both for dev and prod, for NGFW Enterprise.
This is a minimal configuration that creates a CAs for each environment and enables TLS inspection policies for NGFW Enterprise.

```tfvars
cas_configs = {
Expand All @@ -193,9 +197,70 @@ cas_configs = {
}
}
}
tls_inspection = {
enabled = true
}
```

You can optionally create also trust-configs for NGFW Enterprise.

```tfvars
cas_configs = {
dev = {
ngfw-dev-cas-0 = {
location = "europe-west1"
}
}
prod = {
ngfw-prod-cas-0 = {
location = "europe-west1"
}
}
}
trust_configs = {
dev = {
ngfw-dev-tc-0 = {
allowlisted_certificates = {
my_ca = "~/my_keys/srv-dev.crt"
}
location = "europe-west1"
}
}
prod = {
ngfw-prod-tc-0 = {
allowlisted_certificates = {
my_ca = "~/my_keys/srv-prod.crt"
}
location = "europe-west1"
}
}
}
tls_inspection = {
enabled = true
}
```

You can choose what components to activate in each environment. For example, you may create them just in dev and not in prod. As we do in this example, you can also avoid to create a trust config, if you feel you don't need it. Please, refer to the variable `ngfw_tls_configs` spec for more configuration options.
You can customize the keys of your configurations, as long as they match the ones you specify in the `ngfw_tls_configs.keys` variable.

```tfvars
cas_configs = {
dev = {
my-ca-0 = {
location = "europe-west1"
}
}
}
ngfw_tls_configs = {
keys = {
dev = {
cas = "my-ca-0"
}
}
}
tls_inspection = {
enabled = true
}
```

<!-- TFDOC OPTS files:1 show_extra:1 -->
<!-- BEGIN TFDOC -->
Expand Down Expand Up @@ -232,10 +297,9 @@ You can choose what components to activate in each environment. For example, you

| name | description | sensitive | consumers |
|---|---|:---:|---|
| [cas_configs](outputs.tf#L97) | Certificate Authority Service configurations. | | |
| [kms_keys](outputs.tf#L102) | KMS key ids. | | |
| [ngfw_tls_configs](outputs.tf#L107) | The NGFW Enterprise configurations. | | |
| [tfvars](outputs.tf#L112) | Terraform variable files for the following stages. | ✓ | |
| [tls_inspection_policy_ids](outputs.tf#L118) | TLS inspection policy ids for NGFW by environment and region. | | |
| [trust_config_ids](outputs.tf#L123) | Certificate Manager trust-config ids. | | |
| [cas_configs](outputs.tf#L99) | Certificate Authority Service configurations. | | |
| [kms_keys](outputs.tf#L104) | KMS key ids. | | |
| [ngfw_tls_configs](outputs.tf#L109) | The NGFW Enterprise configurations. | | |
| [tfvars](outputs.tf#L114) | Terraform variable files for the following stages. | ✓ | |
| [trust_config_ids](outputs.tf#L120) | Certificate Manager trust-config ids. | | |
<!-- END TFDOC -->
39 changes: 18 additions & 21 deletions fast/stages/2-security/outputs.tf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,23 +51,25 @@ locals {
}
}
}
ngfw_tls_configs = {
tls_enabled = var.ngfw_tls_configs.tls_inspection.enabled
tls_ip_ids_by_region = {
dev = {
for k, v in google_network_security_tls_inspection_policy.ngfw_dev_tls_ips
: v.location => v.id
}
prod = {
for k, v in google_network_security_tls_inspection_policy.ngfw_prod_tls_ips
: v.location => v.id
}
}
}
output_kms_keys = { for k in local._output_kms_keys : k.key => k.id }
tfvars = {
cas_configs = local.cas_configs
kms_keys = local.output_kms_keys
ngfw_tls_configs = var.ngfw_tls_configs
tls_inspection_policy_ids = local.tls_inspection_policy_ids
trust_config_ids = local.trust_config_ids
}
tls_inspection_policy_ids = {
dev = {
for k, v in google_network_security_tls_inspection_policy.ngfw_dev_tls_ips
: v.location => v.id
}
prod = {
for k, v in google_network_security_tls_inspection_policy.ngfw_prod_tls_ips
: v.location => v.id
}
cas_configs = local.cas_configs
kms_keys = local.output_kms_keys
ngfw_tls_configs = local.ngfw_tls_configs
trust_config_ids = local.trust_config_ids
}
trust_config_ids = {
dev = {
Expand Down Expand Up @@ -106,7 +108,7 @@ output "kms_keys" {

output "ngfw_tls_configs" {
description = "The NGFW Enterprise configurations."
value = var.ngfw_tls_configs
value = local.ngfw_tls_configs
}

output "tfvars" {
Expand All @@ -115,11 +117,6 @@ output "tfvars" {
value = local.tfvars
}

output "tls_inspection_policy_ids" {
description = "TLS inspection policy ids for NGFW by environment and region."
value = local.tls_inspection_policy_ids
}

output "trust_config_ids" {
description = "Certificate Manager trust-config ids."
value = local.trust_config_ids
Expand Down
37 changes: 11 additions & 26 deletions fast/stages/3-network-security/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,31 +137,17 @@ ngfw_enterprise_config = {
}
```

You can optionally enable TLS inspection. As a preliminary step, you should activate the TLS components in stage [2-security](../2-security/README.md). Then, activate the inspection in this stage with this minimal configuration.

```tfvars
ngfw_enterprise_config = {
endpoint_zones = [
"europe-west1-b",
"europe-west1-c",
"europe-west1-d"
]
tls_inspection = {
enabled = true
}
}
```

You can refer to the variable definition for further customizations.
The stage will automatically create as many TLS inspection policies needed, in the regions matching your endpoint zones. The NGFW Enterprise CAS pool and the trusted config created in the security stage should be in the same region as the TLS inspection policy.
Multiple regions support would require further customization in the security stage.
You can optionally enable TLS inspection in stage [2-security](../2-security/README.md).
Ingesting outputs from [stage 2-security](../2-security/README.md), this stage will configure TLS inspection in NGFW Enterprise and will reference the CAs and the trust-configs you created in [stage 2-security](../2-security/README.md).
Make sure the CAs and the trusted configs created for NGFW Enterprise in the [2-security stage](../2-security/README.md) match the region where you defined your zonal firewall endpoints.

<!-- TFDOC OPTS files:1 show_extra:1 -->
<!-- BEGIN TFDOC -->
## Files

| name | description | modules | resources |
|---|---|---|---|
| [3-network-security-providers.tf](./3-network-security-providers.tf) | None | | |
| [main.tf](./main.tf) | Next-Generation Firewall Enterprise configuration. | <code>project</code> | <code>google_network_security_firewall_endpoint</code> |
| [net-dev.tf](./net-dev.tf) | Security components for dev spoke VPC. | <code>net-firewall-policy</code> | <code>google_network_security_firewall_endpoint_association</code> · <code>google_network_security_security_profile</code> · <code>google_network_security_security_profile_group</code> |
| [net-prod.tf](./net-prod.tf) | Security components for prod spoke VPC. | <code>net-firewall-policy</code> | <code>google_network_security_firewall_endpoint_association</code> · <code>google_network_security_security_profile</code> · <code>google_network_security_security_profile_group</code> |
Expand All @@ -174,16 +160,15 @@ Multiple regions support would require further customization in the security sta
| name | description | type | required | default | producer |
|---|---|:---:|:---:|:---:|:---:|
| [billing_account](variables-fast.tf#L17) | Billing account id. If billing account is not part of the same org set `is_org_level` to false. | <code title="object&#40;&#123;&#10; id &#61; string&#10; is_org_level &#61; optional&#40;bool, true&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ | | <code>0-bootstrap</code> |
| [folder_ids](variables-fast.tf#L52) | Folders to be used for the networking resources in folders/nnnnnnnnnnn format. If null, folder will be created. | <code title="object&#40;&#123;&#10; networking &#61; string&#10; networking-dev &#61; string&#10; networking-prod &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ | | <code>1-resman</code> |
| [organization](variables-fast.tf#L101) | Organization details. | <code title="object&#40;&#123;&#10; domain &#61; string&#10; id &#61; number&#10; customer_id &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ | | <code>00-globals</code> |
| [prefix](variables-fast.tf#L111) | Prefix used for resources that need unique names. Use a maximum of 9 chars for organizations, and 11 chars for tenants. | <code>string</code> | ✓ | | <code>0-bootstrap</code> |
| [vpc_self_links](variables-fast.tf#L135) | Self link for the shared VPC. | <code title="object&#40;&#123;&#10; dev-spoke-0 &#61; string&#10; prod-spoke-0 &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ | | <code>2-networking</code> |
| [cas_configs](variables-fast.tf#L30) | The CAS pools and CA ids, by environment. | <code title="object&#40;&#123;&#10; dev &#61; map&#40;object&#40;&#123;&#10; ca_pool_id &#61; string&#10; ca_ids &#61; map&#40;string&#41;&#10; location &#61; string&#10; &#125;&#41;&#41;&#10; prod &#61; map&#40;object&#40;&#123;&#10; ca_pool_id &#61; string&#10; ca_ids &#61; map&#40;string&#41;&#10; location &#61; string&#10; &#125;&#41;&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code title="&#123;&#10; dev &#61; &#123;&#125;&#10; prod &#61; &#123;&#125;&#10;&#125;">&#123;&#8230;&#125;</code> | <code>2-security</code> |
| [folder_ids](variables-fast.tf#L30) | Folders to be used for the networking resources in folders/nnnnnnnnnnn format. If null, folder will be created. | <code title="object&#40;&#123;&#10; networking &#61; string&#10; networking-dev &#61; string&#10; networking-prod &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ | | <code>1-resman</code> |
| [organization](variables-fast.tf#L72) | Organization details. | <code title="object&#40;&#123;&#10; domain &#61; string&#10; id &#61; number&#10; customer_id &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ | | <code>00-globals</code> |
| [prefix](variables-fast.tf#L82) | Prefix used for resources that need unique names. Use a maximum of 9 chars for organizations, and 11 chars for tenants. | <code>string</code> | ✓ | | <code>0-bootstrap</code> |
| [vpc_self_links](variables-fast.tf#L106) | Self link for the shared VPC. | <code title="object&#40;&#123;&#10; dev-spoke-0 &#61; string&#10; prod-spoke-0 &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ | | <code>2-networking</code> |
| [factories_config](variables.tf#L17) | Configuration for network resource factories. | <code title="object&#40;&#123;&#10; cidrs &#61; optional&#40;string, &#34;data&#47;cidrs.yaml&#34;&#41;&#10; firewall_policy_rules &#61; optional&#40;object&#40;&#123;&#10; dev &#61; string&#10; prod &#61; string&#10; &#125;&#41;&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code title="&#123;&#10; firewall_policy_rules &#61; &#123;&#10; dev &#61; &#34;data&#47;firewall-policy-rules&#47;dev&#34;&#10; prod &#61; &#34;data&#47;firewall-policy-rules&#47;prod&#34;&#10; &#125;&#10;&#125;">&#123;&#8230;&#125;</code> | |
| [host_project_ids](variables-fast.tf#L63) | Host project for the shared VPC. | <code title="object&#40;&#123;&#10; dev-spoke-0 &#61; optional&#40;string&#41;&#10; prod-spoke-0 &#61; optional&#40;string&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code>&#123;&#125;</code> | <code>2-networking</code> |
| [host_project_ids](variables-fast.tf#L41) | Host project for the shared VPC. | <code title="object&#40;&#123;&#10; dev-spoke-0 &#61; optional&#40;string&#41;&#10; prod-spoke-0 &#61; optional&#40;string&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code>&#123;&#125;</code> | <code>2-networking</code> |
| [ngfw_enterprise_config](variables.tf#L35) | NGFW Enterprise configuration. | <code title="object&#40;&#123;&#10; endpoint_zones &#61; list&#40;string&#41;&#10; quota_project_id &#61; optional&#40;string, null&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code title="&#123;&#10; endpoint_zones &#61; &#91;&#10; &#34;europe-west1-b&#34;,&#10; &#34;europe-west1-c&#34;,&#10; &#34;europe-west1-d&#34;&#10; &#93;&#10;&#125;">&#123;&#8230;&#125;</code> | |
| [ngfw_tls_configs](variables-fast.tf#L74) | The CAS and trust configurations key names to be used for NGFW Enterprise. | <code title="object&#40;&#123;&#10; keys &#61; optional&#40;object&#40;&#123;&#10; dev &#61; optional&#40;object&#40;&#123;&#10; cas &#61; optional&#40;list&#40;string&#41;, &#91;&#93;&#41;&#10; trust_configs &#61; optional&#40;list&#40;string&#41;, &#91;&#93;&#41;&#10; &#125;&#41;, &#123;&#125;&#41;&#10; prod &#61; optional&#40;object&#40;&#123;&#10; cas &#61; optional&#40;list&#40;string&#41;, &#91;&#93;&#41;&#10; trust_configs &#61; optional&#40;list&#40;string&#41;, &#91;&#93;&#41;&#10; &#125;&#41;, &#123;&#125;&#41;&#10; &#125;&#41;, &#123;&#125;&#41;&#10; tls_inspection &#61; optional&#40;object&#40;&#123;&#10; enabled &#61; optional&#40;bool, false&#41;&#10; exclude_public_ca_set &#61; optional&#40;bool, false&#41;&#10; min_tls_version &#61; optional&#40;string, &#34;TLS_1_0&#34;&#41;&#10; &#125;&#41;, &#123;&#125;&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code title="&#123;&#10; dev &#61; &#123;&#125;&#10; prod &#61; &#123;&#125;&#10;&#125;">&#123;&#8230;&#125;</code> | <code>2-security</code> |
| [tls_inspection_policy_ids](variables-fast.tf#L121) | TLS inspection policy ids for NGFW by environment and region. | <code title="object&#40;&#123;&#10; dev &#61; optional&#40;map&#40;string&#41;&#41;&#10; prod &#61; optional&#40;map&#40;string&#41;&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code title="&#123;&#10; dev &#61; &#123;&#125;&#10; prod &#61; &#123;&#125;&#10;&#125;">&#123;&#8230;&#125;</code> | <code>2-security</code> |
| [ngfw_tls_configs](variables-fast.tf#L52) | The NGFW Enterprise TLS configurations. | <code title="object&#40;&#123;&#10; tls_enabled &#61; optional&#40;bool, false&#41;&#10; tls_ip_ids_by_region &#61; optional&#40;object&#40;&#123;&#10; dev &#61; optional&#40;map&#40;string&#41;, &#123;&#125;&#41;&#10; prod &#61; optional&#40;map&#40;string&#41;, &#123;&#125;&#41;&#10; &#125;&#41;&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code title="&#123;&#10; tls_enabled &#61; false&#10; tls_ip_ids_by_region &#61; &#123;&#10; dev &#61; &#123;&#125;&#10; prod &#61; &#123;&#125;&#10; &#125;&#10;&#125;">&#123;&#8230;&#125;</code> | <code>2-security</code> |
| [tls_inspection_policy_ids](variables-fast.tf#L92) | TLS inspection policy ids for NGFW by environment and region. | <code title="object&#40;&#123;&#10; dev &#61; optional&#40;map&#40;string&#41;&#41;&#10; prod &#61; optional&#40;map&#40;string&#41;&#41;&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> | | <code title="&#123;&#10; dev &#61; &#123;&#125;&#10; prod &#61; &#123;&#125;&#10;&#125;">&#123;&#8230;&#125;</code> | <code>2-security</code> |

## Outputs

Expand Down
4 changes: 2 additions & 2 deletions fast/stages/3-network-security/net-dev.tf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ resource "google_network_security_firewall_endpoint_association" "dev_fw_ep_asso
network = try(local.vpc_ids.dev-spoke-0, null)
# If TLS inspection is enabled, link the regional TLS inspection policy
tls_inspection_policy = (
var.ngfw_tls_configs.tls_inspection.enabled
? var.tls_inspection_policy_ids.dev[substr(each.value, 0, length(each.value) - 2)]
var.ngfw_tls_configs.tls_enabled
? try(var.ngfw_tls_configs.tls_ip_ids_by_region.dev[substr(each.value, 0, length(each.value) - 2)], null)
: null
)
}
Expand Down
Loading

0 comments on commit 33b53f2

Please sign in to comment.