GatewayPolicy

This topic provides reference information for the API gateway policy resource. These resources define policies for listeners on API gateways deployed to Kubernetes-orchestrated networks.

Configuration model

The following list outlines field hierarchy, data types, and requirements in a gateway policy resource. Click on a property name to view additional details, including default values.

• apiVersion: string | required | must be set to consul.hashicorp.com/v1alpha1
• kind: string | required | must be set to GatewayPolicy
• metadata: map | required
  • name: string | required
  • namespace: string | default
• spec: map | required
  • targetRef: map | required
    • namespace: string | default
    • name: string | required
    • kind: string | required | must be set to Gateway
    • group: string | required
    • sectionName: string
  • override: map | required
    • jwt: map | required
      • providers: list | required
        • name: string | required
        • verifyClaims: map | required
          • path: list of strings | required
          • value: string | required
  • default: map | required
    • jwt: map | required
      • providers: list | required
        • name: string | required
        • verifyClaims: map | required
          • path: list of strings | required
          • value: string | required

Complete configuration

When every field is defined, a gateway policy has the following form:

apiVersion: consul.hashicorp.com/v1alpha1
kind: GatewayPolicy
metadata:
   name: <name for the policy>
   namespace: <Consul namespace the policy applies to>
spec:
  targetRef:
    name: gateway
    kind: Gateway
    group: gateway.networking.k8s.io/v1beta1
    sectionName: <name of a specific listener the policy applies>
  override:
    jwt:
      providers:
      - name: "<name of the provider all listeners verify against>"
        verifyClaims:
        - path:
          - "aud"
          value: "api.apps.organization.com"
  default:
    jwt:
      providers:
      - name: "<name of the JWT provider to verify against>"
        verifyClaims:
        - path:
          - "roles"
          - "perm"
          value: "user"

Specification

This section provides details about the fields you can configure in the gateway policy resource.

apiVersion

Specifies the version of the Consul API for integrating with Kubernetes. The value must be consul.hashicorp.com/v1alpha1.

Values

• Default: None
• This field is required.
• String value that must be set to consul.hashicorp.com/v1alpha1.

kind

Specifies the type of configuration entry to implement. Must be set to GatewayPolicy.

Values

• Default: None
• This field is required.
• Data type: String value that must be set to GatewayPolicy.

metadata

Map that contains an arbitrary name for the resource and the namespace it applies to.

Values

• Default: None
• Data type: Map

metadata.name

Specifies a name for the resource. The name is metadata that you can use to reference the resource when performing Consul operations, such as applying the resource to a specific cluster.

Values

• Default: None
• This field is required.
• Data type: String

metadata.namespace

Specifies the namespace that the configuration applies to. Refer to namespaces for more information.

Values

• Default: None
• Data type: String

spec

Map that contains the details about the gateway policy. The apiVersion, kind, and metadata fields are siblings of the spec field. All other configurations are children.

Values

• Default: None
• This field is required.
• Data type: Map

targetRef

Map that contains references to the gateway that the policy applies to.

Values

• Default: None
• This field is required.
• Data type: Map

The following table describes the members of the targetRef map:

spec.override

Map that contains configurations to apply to the listener when the policy is attached to the gateway. The override settings have precedence over the spec.default configurations.

Values

• Default: None
• Data type: Map

spec.override.jwt

Map that contains JWT verification configurations to apply to listeners when the policy is attached to the gateway. The override settings have precedence over the default configurations as well as any route-specific JWT configurations defined in RouteAuthFilter configurations.

Values

• Default: None
• Data type: Map

spec.override.jwt.providers

Specifies a list of JWT provider configurations to apply to listeners when the policy is attached to the gateway listener. A provider configuration contains the name of the provider and claims. The override settings have precedence over defaults as well as any listener specific configuration. Refer to Use JWTs to verify requests to API gateways on Kubernetes for additional information.

Values

• Default: None
• Data type: List of maps

The following table describes the parameters you can specify in a member of the Providers list:

spec.default

Map that contains default configurations to apply to listeners when the policy is attached to the gateway. All routes attached to the gateway listener inherit the default configurations. You can specify override configurations that have precedence over default configurations. Refer to spec.override for details.

Values

• Default: None
• Data type: Map

spec.default.jwt

Specifies default JWT configurations to apply to listeners when the policy is attached to the gateway. Specify configurations that have precedence over the defaults in either the spec.override.JWT block or in an RouteAuthFilter attached to an HTTP route. Refer to Use JWTs to verify requests to API gateways for order of precedence and other details about using JWT verification in API gateways.

Values

• Default: None
• Data type: Map

spec.default.jwt.providers

Specifies default JWT provider configurations to apply to the listener when the policy is attached to the gateway. A provider configuration contains the name of the provider and claims. Specify configurations that have precedence over the defaults in either the spec.override.JWT.providers block or in an RouteAuthFilter attached to an HTTP route configuration. Refer to Use JWTs to verify requests to API gateways for order of precedence and other details about using JWT verification in API gateways.

Values

• Default: None
• Data type: List of maps

The following table describes the parameters you can specify in a member of the Providers list:

Example configuration

In the following example, all requests through the gateway must have the api.apps.organization.com audience claim. Additionally, requests through the gateway must have a user role by default.

apiVersion: consul.hashicorp.com/v1alpha1
kind: GatewayPolicy
metadata:
  name: my-policy
spec:
  targetRef:
    name: gateway
    kind: Gateway
    group: gateway.networking.k8s.io/v1beta1
    sectionName: to-server
  override:
    jwt:
      providers:
      - name: "okta"
        verifyClaims:
        - path:
          - "aud"
          value: "api.apps.organization.com"
  default:
    jwt:
      providers:
      - name: "okta"
        verifyClaims:
        - path:
          - "roles"
          - "perm"
          value: "user"