hunfabric/fast/addons/2-networking-swp/README.md

Secure Web Proxy Add-on

This add-on allows creating an arbitrary number of Secure Web Proxy (SWP), including resources required to enable TLS inspection.

This diagram shows the resources used by this add-on, and their relationships with its networking parent stage.

• Design overview and choices
• How to run this stage
  • Provider and Terraform variables
  • Impersonating the automation service account
  • Variable configuration
  • Running the stage
• Files
• Variables
• Outputs

Design overview and choices

This add-on is intentionally self-contained to allow directly using it to implement different designs, via a single instance or multiple instances.

All project-level resources in this stage are created in the same project, so that dependencies and IAM configurations are kept as simple as possible, and everything is within the same span of control.

The controlling project is usually one of those already created and managed by the networking stage: the landing host project, or a shared environment project if that exists. Alternatively, a dedicated project can be created and used here provided the necessary IAM and organization policies configurations are also defined.

How to run this stage

Once the main networking stage has been configured and applied, the following configuration is added the the resource management fast_addon variable to create the add-on provider files, and its optional CI/CD resources if those are also required. The add-on name (networking-swp) is customizable, in case the add-on needs to be run multiple times to create gateways in different projects.

fast_addon = {
  networking-swp = {
    parent_stage = "2-networking"
    # cicd_config = {
    #   identity_provider = "github-test"
    #   repository = {
    #     name   = "test/swp"
    #     type   = "github"
    #     branch = "main"
    #   }
    # }
  }
}

Provider and Terraform variables

As all other FAST stages, the mechanism used to pass variable values and pre-built provider files from one stage to the next is also leveraged here.

The commands to link or copy the provider and terraform variable files can be easily derived from the fast-links.sh script in the FAST stages folder, passing it a single argument with the local output files folder (if configured) or the GCS output bucket in the automation project (derived from stage 0 outputs). The following example uses local files but GCS behaves identically.

../../stages/fast-links.sh ~/fast-config
# File linking commands for Secure Web Proxy networking add-on

# provider file
ln -s ~/fast-config/providers/2-networking-swp-providers.tf ./

# input files from other stages
ln -s ~/fast-config/tfvars/0-globals.auto.tfvars.json ./
ln -s ~/fast-config/tfvars/0-org-setup.auto.tfvars.json ./
ln -s ~/fast-config/tfvars/2-networking.auto.tfvars.json ./

# conventional place for stage tfvars (manually created)
ln -s ~/fast-config/2-networking-swp.auto.tfvars ./

# optional files
ln -s ~/fast-config/tfvars/2-security.auto.tfvars.json ./

Impersonating the automation service account

The preconfigured provider file uses impersonation to run with this stage's automation service account's credentials. The gcp-devops and organization-admins groups have the necessary IAM bindings in place to do that, so make sure the current user is a member of one of those groups.

Variable configuration

Variables in this stage -- like most other FAST stages -- are broadly divided into three separate sets:

• variables which refer to global values for the whole organization (org id, billing account id, prefix, etc.), which are pre-populated via the 0-globals.auto.tfvars.json file linked or copied above
• variables which refer to resources managed by previous stages, which are prepopulated here via the 0-org-setup.auto.tfvars.json, 2-networking.auto.tfvars.json files linked or copied above
• and finally variables that optionally control this stage's behaviour and customizations, and can to be set in a custom terraform.tfvars file

The first two sets are defined in the variables-fast.tf file, the latter set in the variables.tf file. The full list of variables can be found in the Variables table at the bottom of this document.

Note that the outputs_location variable is disabled by default, you need to explicitly set it in your terraform.tfvars file if you want output files to be generated by this stage. This is a sample terraform.tfvars that configures it, refer to the bootstrap stage documentation for more details:

outputs_location = "~/fast-config"

Once output files are in place, define your addon configuration in a tfvars file. This is an example of configuring this addon, with optional variable attributes filled in for illustration purposes.

Note that project id and networking variables use interpolation from FAST, and refer to the aliased resource names for portability. This is of course optional, and full resource ids can be used instead if needed.

certificate_authority = {
  ca_configs = {
    swp = {
      deletion_protection = false
      subject = {
        common_name  = "fast-test-00.joonix.net"
        organization = "FAST Test 00"
      }
    }
  }
}
locations = {
  pri = "primary"
}
outputs_location = "~/fast-config"
project_id       = "prod-landing"
swp_configs = {
  shared = {
    network_id    = "prod-landing"
    subnetwork_id = "net"
  }
  # any other option supported by the net-swp module can be used here
}
tls_inspection_policy = {
  exclude_public_ca_set = true
}

Running the stage

Once provider and variable values are in place and the correct user is configured, the stage can be run:

terraform init
terraform apply

Files

name	description	modules	resources
main.tf	Module-level locals and resources.	net-swp · project
outputs.tf	Module outputs.		google_storage_bucket_object · local_file
tls-inspection.tf	TLS inspection policies and supporting resources.	certificate-authority-service	google_network_security_tls_inspection_policy
variables-fast.tf	FAST stage interface.
variables.tf	Module variables.

Variables

name	description	type	required	default	producer
automation	Automation resources created by the bootstrap stage.	object({…})	✓		0-bootstrap
certificate_authority	Optional Certificate Authority Service pool and CA used by SWP.	object({…})	✓
project_id	Project where the resources will be created.	string	✓
_fast_debug	Internal FAST variable used for testing and debugging. Do not use.	object({…})		{}
enable_services	Configure project by enabling services required for this add-on.	bool		false
factories_config	SWP factories configuration paths. Keys in the swp_configs variable will be appended to derive individual SWP factory paths.	object({…})		{}
host_project_ids	Networking stage host project id aliases.	map(string)		{}	2-networking
locations	Regions where the resources will be created. Keys are used as short names appended to resource names. Interpolation with FAST region names is supported.	map(string)		{}
name	Name used for resource names.	string		"swp"
outputs_location	Path where providers and tfvars files for the following stages are written. Leave empty to disable.	string		null
policy_rules_contexts	Replacement contexts for policy rules matcher arguments.	object({…})		{}
regions	Networking stage region aliases.	map(string)		{}	2-networking
subnet_self_links	VPC subnetwork self links.	map(map(string))		{}	2-networking
swp_configs	Secure Web Proxy configuration, one per region.	map(object({…}))		{}
tls_inspection_policy	TLS inspection policy configuration. If a CA pool is not specified a local one must be created via the certificate_authority variable.	object({…})		null
vpc_self_links	VPC network self links.	map(string)		{}	2-networking

Outputs

name	description	sensitive	consumers
cas_pool_ids	Certificate Authority Service pool ids.
gateway_security_policies	The gateway security policy resources.
gateways	The gateway resources.
ids	Gateway IDs.
service_attachments	Service attachment IDs.