> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Network Firewall

export const Alert = ({type, title, children}) => {
  const variant = ["info", "success", "warning", "danger", "note"].includes(type) ? type : "note";
  return <div className={`alert alert--${variant}`}>
      <div className="alert-icon" />
      <div className="alert-content">
        {title && <div className="alert-title">{title}</div>}
        <div className="alert-body">{children}</div>
      </div>
    </div>;
};

Route outbound traffic from your Cloud-Prem account through [AWS Network Firewall](https://docs.aws.amazon.com/network-firewall/latest/developerguide/what-is-aws-network-firewall.html) so you can inspect and filter it. The firewall is yours: you choose how it's deployed and you control its rules.

This applies to outbound traffic only. To filter inbound traffic, use [custom WAF rule groups](/enterprise/cloud-prem/configure/waf-rule-groups).

## Choose a setup

You configure Network Firewall with variables in the bootstrap Terraform you run during [deployment](/enterprise/cloud-prem/deployment-guide). The bootstrap README walks you through setting them. Use this page to choose a setup and confirm the right variables are set for it. See the [variable reference](#bootstrap-variable-reference) for every variable.

Pick one of three setups:

| Setup | Who deploys the firewall | Who manages the rules | Traffic it filters |
| - | - | - | - |
| [Bring your own firewall](#bring-your-own-firewall) | You | You | Control plane and Superblocks-managed data planes |
| [Bootstrap-managed firewall](#bootstrap-managed-firewall) | The bootstrap Terraform | You. The firewall starts by passing all traffic | Control plane only |
| [Bootstrap-managed firewall with the default allowlist](#use-the-default-allowlist) | The bootstrap Terraform | The bootstrap Terraform, using the Superblocks default allowlist plus your additions and exclusions | Control plane only |

<Alert type="warning" title="Bootstrap-managed firewalls don't filter data plane traffic">
  A firewall created with `enable_network_firewall` only filters traffic from the Cloud-Prem control plane. If your instance includes Superblocks-managed data planes, their outbound traffic doesn't go through it. That means builders can create REST APIs and integrations that connect to domains outside your allowlist. To filter data plane traffic as well, [bring your own firewall](#bring-your-own-firewall) instead.

  Self-hosted data planes run outside the Cloud-Prem account, so neither setup covers them.
</Alert>

You can add Network Firewall during your initial deployment or later. To add it or change setups later, update the variables and re-apply the bootstrap Terraform. Superblocks wires the firewall into your instance at the next deployment.

## Bring your own firewall

Use a Network Firewall you already deploy and manage. Cloud-Prem routes outbound traffic from each availability zone's public subnet through your firewall endpoint instead of directly to the internet gateway. This applies to both the control plane and Superblocks-managed data planes.

The bootstrap Terraform creates the Cloud-Prem VPC, so set up the firewall in this order:

1. Apply the bootstrap Terraform without any firewall variables. This creates the Cloud-Prem VPC.

2. Deploy your Network Firewall with an endpoint in the Cloud-Prem VPC for each availability zone Cloud-Prem uses.

3. Set `firewall_endpoint_ids` to a map of availability zone ID to firewall endpoint ID. Use AZ IDs such as `usw2-az1`, not AZ names such as `us-west-2a`.

   ```hcl theme={null}
   firewall_endpoint_ids = {
     "usw2-az1" = "vpce-0123456789abcdef0"
     "usw2-az2" = "vpce-0fedcba9876543210"
   }
   ```

4. Re-apply the bootstrap Terraform. Superblocks wires the firewall into your instance at the next deployment.

Your firewall rules must allow the [required outbound domains](#required-outbound-domains), or Cloud-Prem can't reach the services it depends on.

Don't set `enable_network_firewall` when you bring your own firewall. The two options can't be combined.

## Bootstrap-managed firewall

Have the bootstrap Terraform create the firewall for you. It creates firewall subnets and endpoints in the Cloud-Prem VPC and routes outbound traffic, and the return traffic from the internet gateway, through them. It filters control plane traffic only, not traffic from [Superblocks-managed data planes](#choose-a-setup).

1. Set `enable_network_firewall` to `true`.

2. Add a `cidr_firewall` entry with exactly one IPv4 CIDR to each availability zone in `network.subnets`:

   ```hcl theme={null}
   enable_network_firewall = true

   network = {
     # ...your existing network settings
     subnets = {
       "usw2-az1" = {
         # ...your existing subnet settings
         cidr_firewall = ["10.0.250.0/28"]
       }
       "usw2-az2" = {
         # ...your existing subnet settings
         cidr_firewall = ["10.0.250.16/28"]
       }
     }
   }
   ```

3. Apply the bootstrap Terraform. Superblocks wires the firewall into your instance at the next deployment.

The firewall policy starts by passing all traffic. You manage the rules yourself in AWS, outside Terraform, and re-applying the bootstrap doesn't overwrite them. Your rules must allow the [required outbound domains](#required-outbound-domains). To have the bootstrap enforce an allowlist for you instead, [use the default allowlist](#use-the-default-allowlist).

## Use the default allowlist

With a bootstrap-managed firewall, you can have the bootstrap enforce the Superblocks default allowlist. Outbound control plane traffic is then blocked unless it's going to an allowed domain. Traffic from Superblocks-managed data planes isn't filtered.

```hcl theme={null}
enable_network_firewall                     = true
enable_network_firewall_default_rule_groups = true

# Domains your deployment reaches beyond the Superblocks platform
network_firewall_extra_allowed_domains = [
  ".okta.com",
  "api.example.com",
]

# Default domains for parts of the platform you don't use
network_firewall_excluded_default_domains = [
  "registry.npmjs.org",
]
```

| <div style={{ width: 340 }}>Variable</div> | Description |
| - | - |
| `enable_network_firewall_default_rule_groups` | Enforces the default allowlist. Requires `enable_network_firewall` |
| `network_firewall_extra_allowed_domains` | Domains to allow in addition to the default list, such as your identity provider, an internal package registry, or your own APIs. A leading dot, such as `.example.com`, matches the domain and all its subdomains |
| `network_firewall_excluded_default_domains` | Default domains to remove for parts of the platform you don't use. Each entry must match a [default domain](#required-outbound-domains) exactly, or the Terraform plan fails |
| `network_firewall_default_rule_group_capacity` | Capacity reserved for the allowlist rule group. Defaults to `100` |

To see the allowlist the firewall is enforcing, run:

```bash theme={null}
terraform output network_firewall
```

<Alert type="warning">
  While the default allowlist is on, Terraform owns the firewall policy. Rules you change outside Terraform are reverted the next time you re-apply the bootstrap. Make changes with the variables above instead.
</Alert>

### Increase the rule group capacity

AWS fixes a rule group's capacity when it's created. Raise `network_firewall_default_rule_group_capacity` before adding enough extra domains to exceed it. Changing the capacity replaces the rule group, so apply it in two steps:

1. Set `enable_network_firewall_default_rule_groups` to `false` and apply.
2. Set the new capacity, set `enable_network_firewall_default_rule_groups` back to `true`, and apply again.

## Required outbound domains

The Cloud-Prem control plane needs to reach these domains. The default allowlist includes all of them. If you manage your own rules, allow them yourself. Replace `<region>` with your Cloud-Prem AWS region.

| Purpose | Domains |
| - | - |
| AWS services | `.amazonaws.com`, `.<region>.api.aws`, `eks-auth.<region>.api.aws`, `ssm.<region>.api.aws`, `ec2.<region>.api.aws`, `eks.<region>.api.aws` |
| Superblocks | `.superblocks.com`, `.superblockshq.com` |
| Datadog | `.datadoghq.com` |
| Container and package registries | `github.com`, `.githubusercontent.com`, `registry.npmjs.org`, `npm.pkg.github.com`, `registry.terraform.io`, `releases.hashicorp.com`, `checkpoint-api.hashicorp.com` |
| TLS certificate issuance | `acme-v02.api.letsencrypt.org` |

Also allow the domains your deployment reaches beyond the Superblocks platform, such as your identity provider, the APIs and databases your apps connect to, and any [observability destinations](/enterprise/cloud-prem/configure/observability-destinations) you send telemetry to.

<Alert type="info" title="Allowlists limit Clark web search">
  If your firewall blocks all outbound traffic except allowed domains, Clark can't search the web. Clark then can't explore documentation or gather information from the internet while it builds, so its results may be less informed.

  To let Clark reach specific sites, such as documentation for the libraries and APIs your team builds with, allow their domains. With the [default allowlist](#use-the-default-allowlist), add them to `network_firewall_extra_allowed_domains`.
</Alert>

## Bootstrap variable reference

| <div style={{ width: 340 }}>Variable</div> | Type | Default | Set it for |
| - | - | - | - |
| `firewall_endpoint_ids` | Map of AZ ID to firewall endpoint ID | `{}` | Bring your own firewall. Filters control plane and Superblocks-managed data plane traffic. Must be empty when `enable_network_firewall` is `true` |
| `enable_network_firewall` | Boolean | `false` | Bootstrap-managed firewall, with or without the default allowlist. Filters control plane traffic only |
| `network.subnets[*].cidr_firewall` | List with one IPv4 CIDR | Empty | Bootstrap-managed firewall. Required for every availability zone when `enable_network_firewall` is `true`, and must be empty otherwise |
| `enable_network_firewall_default_rule_groups` | Boolean | `false` | Default allowlist. Requires `enable_network_firewall` |
| `network_firewall_extra_allowed_domains` | List of strings | `[]` | Default allowlist. Ignored otherwise |
| `network_firewall_excluded_default_domains` | List of strings | `[]` | Default allowlist. Ignored otherwise |
| `network_firewall_default_rule_group_capacity` | Number | `100` | Default allowlist, when you need more capacity |

## Related

* [Optional configurations](/enterprise/cloud-prem/configure/index)
* [Custom WAF rule groups](/enterprise/cloud-prem/configure/waf-rule-groups)
* [Cloud-Prem deployment guide](/enterprise/cloud-prem/deployment-guide)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.