Relates to

#1492
#1821
#1846

What is this?

SecurityPolicy is a proposal for a new policy attachment resource that can be applied to Gateways and xRoute resources. It is meant to supplement a lot of config that Gateway API currently lacks while also providing a way to specify global defaults. It is similar to the proposal for an UpstreamTrafficPolicy with the notable difference that this tackles authentication based features and will thus support overrides and defaults.

How would I use this resource?

You can attach an SecurityPolicy to a Gateway to set global defaults that will apply to all children xRoute objects of that Gateway. You can also create an SecurityPolicy to attach to an xRoute object to configure things on a route-to-route basis and override global defaults if needed.

How will the overrides and defaults work?

If there is an SecurityPolicy X attached to a Gateway, and an SecurityPolicy Y attached to an HTTPRoute:

• overrides from policy X will win in a conflict with overrides from policy Y.
  • This is to support the use-case of a cluster admin/operator setting some global overrides that are not allowed to be changed on a route level
• defaults from policy Y will win in a conflict with defaults from policy X.
  • While cluster admins/operators might want to provide sane defaults, developers creating xRoute objects should still be able to override those defaults on a route-to-route basis (unless otherwise enforced by Gateway level overrides in the above scenario)

What if Gateway API implements a GEP that delivers the same functionality as some of the fields of this resource?

If Gateway improves any of their existing resources to deliver functionality that meets all of the needs of any of the below config,
then we will deprecate the field in this resource and use the Gateway API config instead. Ideally, a lot of this config can be
upstreamed into Gateway API in some form eventually since this resource only exists to solve areas where Gateway API is lacking for the needs of Envoy Gateway.

Can you use multiple SecurityPolicy resources at the same time?

You may use multiple AuthPolicies that target different resources, but you may not attach multiple AuthPolicies
to the same resource. For example, it is invalid to attach two AuthPolicies to the same Gateway. Merging config in this scenario would quickly become convoluted and confusing, and there are many edge-case scenarios that make supporting this undesirable.

How will this be developed/implemented?

This issue serves as a proposal for the high-level design and fields of the API, but that does not mean that every field included below will be immediately available. My plan for the implementation is to add and implement one high-level field at a time until the whole resource is implemented.

API outline

---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: example-policy
spec:
  # defaults and overrides will have the same configuration options.
  # If there is an SecurityPolicy A attached to a Gateway, and an SecurityPolicy B
  # attached to an xRoute, `overrides` from policy A win and `defaults` win for policy B
  # This allows for global defaults, changing those defaults on a route to route basis and enforcing
  # certain settings at a Gateway level.
  defaults:
  overrides:
    connections: # optional
      ipBlocking: # optional
        mode: Enum(allow-list/deny-list) # required
        ips: # required, minItems=1
        - type: Enum(peer/remote) # required
          value: string # required (example: 127.0.0.1 or 99.99.0.0/16)
    cors: # optional
      allowedOrigins: []string # required
      allowedMethods: []string # optional
      allowedHeaders: []string # optional
      allowCredentials: bool # optional
      exposedHeaders: []string # optional
      maxAge: string # optional
    authentication: # optional
      bypassAuth: bool # optional
      filters: # optional (allows setting default auth filter(s) or forcing them)
        # action controls how the filter is added. add will add the filter to the list of existing filters, 
        # replace will remove any existing AuthenticationFilters first.
        action: Enum (add/replace) # optional, default=add
        # priority determines the ordering of the filter if there are other filters on the resource.
        # The derfault priority of all filters is interpreted as 0 which will cause the filter to be 
        # appended to the list if other filters exist. negative values can prepend the filter(s) to any existing ones.
        priority: int # optional, default=0.
        targetRef: # required
          group: string
          kind: string # only Envoy Gateway's AuthenticationFilter will be supported for now
          name: string
  targetRef: # required
    group: string
    kind: string # must be a Gateway or xRoute object reference
    name: string

Open questions

• This resource can be attached to a Gateway, but you can configure multiple listeners on a single Gateway. Realistically, this resource makes the most sense targeting listeners instead of forcing this to apply to the entire gateway. There should be a way to specify which listeners it applies to so that you can have different config for each listener.
  • After discussion with @arkodg in the Gateway meeting today, we agree that the best approach is likely to start with making this apply to the entire Gateway and then adding in support for @zhaohuabing's SectionName to PolicyTargetReference enhancement when it lands and becomes available.

Edits

• Changed name from AuthPolicy to SecurityPolicy