85b0871085
* feat(fast/0-org-setup): integrate net-vpc-factory into stage 0 * initial starter dataset * starter pack * fix(fast/0-org-setup): correct factory vpcs paths definition and update test inventory * feat(fast/0-org-setup): add VPC and subnet outputs and update stage tfvars * test(fast/0-org-setup): update gcd starter defaults and regenerate inventory * fix(modules/net-vpc-factory): remove internal defaults logic and pass context correctly * fix typo in dataset fw rule, add missing boilerplate, set sane defaults for net vpc factory * terraform fmt * tfdoc, copyright year * schema docs * yamllint
197 lines
6.7 KiB
Markdown
197 lines
6.7 KiB
Markdown
# Net VPC Factory
|
|
|
|
This module implements the creation of VPCs, subnets, and firewall rules via YAML configurations. It is designed to be embedded in other factories such as the [FAST networking stage](../../fast/stages/2-networking).
|
|
|
|
It supports:
|
|
|
|
- **VPCs** and **Subnets** leveraging the [net-vpc](../net-vpc/) module.
|
|
- **Firewall rules** leveraging the [net-vpc-firewall](../net-vpc-firewall/) module.
|
|
- **Context-based interpolation** for referring to resources dynamically (e.g., project IDs, IAM principals, Locations).
|
|
|
|
The factory is implemented as a thin data translation layer over the underlying modules, ensuring transparency and ease of debugging.
|
|
|
|
The factory is implemented as a thin data translation layer over the underlying modules, so that no "magic" or hidden side effects are implemented in code, and debugging or integration of new features are simple.
|
|
|
|
The code is meant to be executed by a principal with permissions over the network infrastructure across the projects where VPCs are defined:
|
|
|
|
- **Network Admin** (`roles/compute.networkAdmin`): to manage VPCs, subnets, routes, and firewall rules.
|
|
- **DNS Admin** (`roles/dns.admin`): to manage DNS policies.
|
|
- **Security Admin** (`roles/compute.securityAdmin`): to manage firewall policies.
|
|
|
|
## Contents
|
|
|
|
<!-- BEGIN TOC -->
|
|
- [VPC Factory](#vpc-factory)
|
|
- [Defaults](#defaults)
|
|
- [Subnets](#subnets)
|
|
- [Firewall rules](#firewall-rules)
|
|
- [Context-based interpolation](#context-based-interpolation)
|
|
- [Project context ids](#project-context-ids)
|
|
- [Other context ids](#other-context-ids)
|
|
- [Example](#example)
|
|
- [Variables](#variables)
|
|
- [Outputs](#outputs)
|
|
<!-- END TOC -->
|
|
|
|
## VPC Factory
|
|
|
|
The VPC factory is configured via the `factories_config.vpcs` variable, which sets the path containing the YAML definitions for VPCs, where each VPC and their dependent resources are defined in a dedicated directory.
|
|
|
|
Each VPC directory contains a `.config.yaml` file. The structure of the YAML file mirrors the variables of the [`net-vpc`](../net-vpc/) module.
|
|
|
|
```yaml
|
|
project_id: $project_ids:my-project # Or use the project id directly
|
|
description: "My VPC"
|
|
routing_mode: GLOBAL
|
|
```
|
|
|
|
### Defaults
|
|
|
|
In addition to the YAML-based VPC configurations, the factory accepts three additional sets of inputs via Terraform variables to control defaults:
|
|
|
|
- `data_defaults`: defaults for specific VPC attributes, used if not present in YAML.
|
|
- `data_overrides`: overrides that take precedence over YAML values.
|
|
- `factories_config.paths.defaults`: path to a YAML file containing global context and VPC defaults (defaults to `defaults.yaml` in the path set by `factories_config.basepath`)
|
|
|
|
```hcl
|
|
module "net-vpc-factory" {
|
|
source = "./modules/net-vpc-factory"
|
|
data_defaults = {
|
|
routing_mode = "REGIONAL"
|
|
}
|
|
factories_config = {
|
|
basepath = "data"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Subnets
|
|
|
|
Subnets can be defined in separate files within a `subnets` subdirectory in the VPC's folder.
|
|
|
|
```text
|
|
data/vpcs/
|
|
└── my-vpc/
|
|
├── .config.yaml
|
|
└── subnets/
|
|
├── subnet-a.yaml
|
|
└── subnet-b.yaml
|
|
```
|
|
|
|
This allows splitting complex subnet configurations (like those with massive secondary ranges or specialized IAM bindings) into manageable files.
|
|
|
|
### Firewall rules
|
|
|
|
Firewall rules are managed via a `firewall-rules` subdirectory in the VPC's folder. The factory uses the [`net-vpc-firewall`](../net-vpc-firewall/) module to provision these rules - the YAML format for firewall rules follows the structure expected by the module itself.
|
|
|
|
```text
|
|
data/vpcs/
|
|
└── my-vpc/
|
|
├── .config.yaml
|
|
└── firewall-rules/
|
|
├── allow-ssh.yaml
|
|
└── allow-internal.yaml
|
|
```
|
|
|
|
## Context-based interpolation
|
|
|
|
Interpolation allows referring to resources which are external or created at runtime via short aliases. This is particularly useful for Project IDs, which might be generated by the Project Factory.
|
|
|
|
Contexts are passed via the `context` variable or the `factories_config.defaults` file.
|
|
|
|
### Project context ids
|
|
|
|
Project IDs use the `$project_ids:` namespace. This allows decoupling the VPC definition from the actual Project ID string.
|
|
|
|
```yaml
|
|
# data/vpcs/vpc-0/.config.yaml
|
|
project_id: $project_ids:data-project
|
|
name: vpc-0
|
|
```
|
|
|
|
```hcl
|
|
module "net-vpc-factory" {
|
|
# ...
|
|
context = {
|
|
project_ids = {
|
|
data-project = "prefix-prod-data-app-0"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Other context ids
|
|
|
|
Other contexts can be defined freely. Common uses include:
|
|
|
|
- `$locations:` for GCP regions.
|
|
- `$iam_principals:` for IAM principals.
|
|
|
|
## Example
|
|
|
|
```hcl
|
|
module "net-vpc-factory" {
|
|
source = "./fabric/modules/net-vpc-factory"
|
|
context = {
|
|
project_ids = {
|
|
net-project = "my-host-project-id"
|
|
}
|
|
locations = {
|
|
primary = "europe-west1"
|
|
}
|
|
}
|
|
factories_config = {
|
|
basepath = "data"
|
|
}
|
|
}
|
|
# tftest files=vpc,fw,subnet modules=3 inventory=example.yaml
|
|
```
|
|
|
|
```yaml
|
|
# data/vpcs/shared-vpc/.config.yaml
|
|
project_id: $project_ids:net-project
|
|
name: data-vpc-0
|
|
# tftest-file id=vpc path=data/vpcs/data-vpc-0/.config.yaml schema=vpc-factory.schema.json
|
|
```
|
|
|
|
```yaml
|
|
# data/vpcs/data-vpc-0/subnets/primary-subnet.yaml
|
|
name: primary-subnet
|
|
region: $locations:primary
|
|
ip_cidr_range: 10.10.0.0/24
|
|
description: Primary subnet for data-vpc-0
|
|
# tftest-file id=subnet path=data/vpcs/data-vpc-0/subnets/primary-subnet.yaml schema=subnet.schema.json
|
|
```
|
|
|
|
```yaml
|
|
# data/vpcs/data-vpc-0/firewall-rules/allow-iap.yaml
|
|
ingress:
|
|
allow-iap:
|
|
description: Allow IAP for SSH
|
|
source_ranges:
|
|
- 35.235.240.0/20
|
|
rules:
|
|
- protocol: tcp
|
|
ports: [22]
|
|
targets: ["ssh"]
|
|
# tftest-file id=fw path=data/vpcs/data-vpc-0/firewall-rules/allow-iap.yaml schema=firewall-rules.schema.json
|
|
```
|
|
<!-- BEGIN TFDOC -->
|
|
## Variables
|
|
|
|
| name | description | type | required | default |
|
|
|---|---|:---:|:---:|:---:|
|
|
| [factories_config](variables.tf#L99) | Path to folder with YAML resource description data files. | <code>object({…})</code> | ✓ | |
|
|
| [context](variables.tf#L17) | Context-specific interpolations. | <code>object({…})</code> | | <code>{}</code> |
|
|
| [data_defaults](variables.tf#L29) | Optional default values used when corresponding vpc data from files are missing. | <code>object({…})</code> | | <code>{}</code> |
|
|
| [data_overrides](variables.tf#L64) | Optional values that override corresponding data from files. Takes precedence over file data and `data_defaults`. | <code>object({…})</code> | | <code>{}</code> |
|
|
|
|
## Outputs
|
|
|
|
| name | description | sensitive |
|
|
|---|---|:---:|
|
|
| [firewall_rules](outputs.tf#L17) | Firewall rules. | |
|
|
| [vpcs](outputs.tf#L22) | VPCs. | |
|
|
| [vpcs_config](outputs.tf#L27) | Processed VPC configuration data. | |
|
|
<!-- END TFDOC -->
|