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

# Firewall

> External and internal firewall rules for inbound and outbound traffic. Covers CIDR allowlists, hostname filtering, and HTTP header-based access control.

> [!NOTE]
>
> Inbound network access is only available for workloads of types `serverless`, `standard`, and `stateful`. For other workload types, only outbound firewall settings are relevant.

## External

The external firewall is used to control Internet traffic to/from a workload.

```yaml YAML theme={null}
spec:
  firewallConfig:
    external:
      inboundAllowCIDR:
        - 1.2.3.0/24
      outboundAllowCIDR:
        - 1.2.3.0/24
      outboundAllowHostname:
        - example.com
      outboundAllowPort:
        - protocol: http
          number: 80
      inboundBlockedCIDR:
        - 1.2.3.4/32
      outboundBlockedCIDR:
        - 1.2.3.4/32
      http:
        inboundHeaderFilter:
          - key: foo
            allowedValues:
              - bar.*
```

### Inbound Requests

* By default, all inbound requests are disabled.
* Access is granted by explicitly adding one or more IPv4 / IPv6 / [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) addresses or allowing all addresses.
* Using the UI:
  * Multiple addresses can be entered within the textbox by delimiting each address with either a comma or space.
  * An import file can be uploaded containing each address on its own line or delimited with either a comma or space.

> [!TIP]
>
> The CIDR address `0.0.0.0/0` allows full inbound access from the public Internet.

### Outbound Requests

* By default, all outbound requests are disabled.
* By default, or by specifying NO outbound ports, all are ALLOWED.
* When outbound ports are specified, only traffic to those ports will be allowed.
* Access is granted by explicitly adding one or more IPv4 / IPv6 / [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) addresses or public hostnames or allowing all addresses / hostnames.
  * **When using a hostname, only ports 80, 443, and 445 will be reachable. To allow all ports, enable all outbound requests.**
  * When using an IP or CIDR, all ports will be reachable.
* The IP/CIDR addresses takes precedence over hostnames.
* Using the UI:
  * Multiple addresses can be entered within the textbox by delimiting each address with either a comma or space.
  * An import file can be uploaded containing each address on its own line or delimited with either a comma or space.

> [!TIP]
>
> The CIDR address `0.0.0.0/0` allows full outbound access to the public Internet.

### Blocked Addresses

All addresses specified will be blocked from outbound/inbound requests to/from this workload

```yaml YAML theme={null}
spec:
  firewallConfig:
    external:
      inboundBlockedCIDR:
        - 1.2.3.4/32
      outboundBlockedCIDR:
        - 1.2.3.4/32
```

* Blocking an address has the same effect as not including it in the allow CIDR list

### Inbound HTTP Header Filter

Use `inboundHeaderFilter` to allow or block inbound requests based on their HTTP headers. It is set under `spec.firewallConfig.external.http`.

The filter only accepts or rejects requests. To remove or rewrite headers instead, use [header mutation](https://docs.controlplane.com/reference/workload/header-mutation.md).

```yaml YAML theme={null}
spec:
  firewallConfig:
    external:
      http:
        inboundHeaderFilter:
          - key: foo
            allowedValues:
              - bar
```

Each entry names one header (`key`) and sets either `allowedValues` or `blockedValues`, not both. A request is checked as follows:

* **Blocked values:** a request is rejected if any `blockedValues` pattern matches its header. Blocked values take precedence over allowed values.
* **Allowed values:** once any entry has `allowedValues`, a request must match at least one allowed value to be accepted. A request that lacks the header is rejected. When several headers have allowed values, matching any **one** of them is enough.
* Rejected requests receive `403` with the body `RBAC: access denied`. A rejected gRPC request (content type `application/grpc`) receives `grpc-status: 7` (`PERMISSION_DENIED`) with the message `RBAC: access denied`.

How values are matched:

* Values are [RE2](https://github.com/google/re2/wiki/Syntax) regular expressions, and each must match the **whole** header value. `bar` matches `bar`, but not `barbell` or `xbar`. No `^` or `$` is needed.
* Header names are case-insensitive. Header values are case-sensitive.

Where the filter applies:

* Only to requests that arrive through the workload's public endpoint, including requests from other workloads that call that endpoint. Requests to the workload's internal address (`<workload>.<gvc>.cpln.local`), from any GVC, are not filtered.
* Only to containers with an `http`, `http2` or `grpc` port. It has no effect on a `tcp` port.

Rules for entries:

* Use one entry per header, and list several values under it. If two entries share the same `key`, only the first is kept.
* `key` must be a valid HTTP header name (no spaces or colons). An invalid name is accepted, but in an allow rule it rejects every request.

Changes usually take effect within a minute. While a change is propagating, some requests may still be handled by the previous rules.

> [!WARNING]
>
> If a request contains the same header more than once, the values are joined with a comma (`bar,bar`) before matching, because HTTP treats repeated headers as one comma-separated list. A pattern such as `bar` matches only when the header holds that single value, so a client can avoid a `blockedValues` rule by repeating the header. To block a value wherever it appears in the list, use a pattern that allows other list items around it, as shown in the last example below.

#### Examples

Only allow requests that have the `foo` header, with any value:

```yaml YAML theme={null}
spec:
  firewallConfig:
    external:
      http:
        inboundHeaderFilter:
          - key: foo
            allowedValues:
              - .*
```

Allow all requests except those with the header `foo: bar`:

```yaml YAML theme={null}
spec:
  firewallConfig:
    external:
      http:
        inboundHeaderFilter:
          - key: foo
            blockedValues:
              - bar
```

Only allow requests whose `x-client` header is `web` or `mobile`, and block one user agent:

```yaml YAML theme={null}
spec:
  firewallConfig:
    external:
      http:
        inboundHeaderFilter:
          - key: x-client
            allowedValues:
              - web
              - mobile
          - key: user-agent
            blockedValues:
              - badbot.*
```

Block the value `bar` even when the header is sent more than once or as a list (`foo: zzz, bar`):

```yaml YAML theme={null}
spec:
  firewallConfig:
    external:
      http:
        inboundHeaderFilter:
          - key: foo
            blockedValues:
              - '(.*,)?\s*bar\s*(,.*)?'
```

#### Geo Filtering

The header filter can use the [geo location headers](https://docs.controlplane.com/reference/workload/load-balancing.md#geo-location-headers) that the load balancer adds to each request. The country header contains the two-letter ISO country code (for example `US`), not the country name.

This example only allows requests from the United States:

```yaml YAML theme={null}
spec:
  loadBalancer:
    geoLocation:
      enabled: true
      headers:
        country: x-country
  firewallConfig:
    external:
      http:
        inboundHeaderFilter:
          - key: x-country
            allowedValues:
              - US
```

> [!WARNING]
>
> Geo location must be enabled for geo filtering to be reliable. When it is enabled, the load balancer overwrites any geo header that the client
> sends. When it is disabled, a client can send the header itself and pass the filter.

## Internal

The internal firewall is used to control access between other workloads within an [org](https://docs.controlplane.com/reference/org.md). Only the ports listed in the workload containers array will be made accessible to other workloads.

This example allows workloads running in the same [GVC](https://docs.controlplane.com/reference/gvc.md) to access this workload.

```yaml YAML theme={null}
spec:
  firewallConfig:
    internal:
      inboundAllowType: same-gvc
```

This example allows a few specific workloads across the org to access this workload.

```yaml YAML theme={null}
spec:
  firewallConfig:
    internal:
      inboundAllowType: workload-list
      inboundAllowWorkload:
        - //gvc/amazingapp/workload/users
        - //gvc/bestapp/workload/orders
```

This example allows a few specific workloads across the org and all workloads in the same GVC to access this workload.

```yaml YAML theme={null}
spec:
  firewallConfig:
    internal:
      inboundAllowType: same-gvc
      inboundAllowWorkload:
        - //gvc/amazingapp/workload/users
        - //gvc/bestapp/workload/orders
```

**Available Options:**

* `none`: No access is allowed between workloads.
* `same-gvc`: Workloads running in the same [GVC](https://docs.controlplane.com/reference/gvc.md) are accessible. Adding `inboundAllowWorkload` alongside it also allows the workloads named there, which may live in other GVCs. The Console shows that combination as `Same GVC & Workload List`, but it is stored as `same-gvc` with a populated list, not as a separate value.
* `same-org`: Workloads running in the same [org](https://docs.controlplane.com/reference/org.md) are accessible.
* `workload-list`: Specific workloads are allowed to access this workload.
  * These workloads can be from the same or different GVCs.
  * The user configuring this setting must have the `view` permission, set within a [policy](https://docs.controlplane.com/reference/policy.md#permissions), on the workload being specified.
  * Use `inboundAllowWorkload` to list out the allowed workloads using their links.
