Release notes

Review the release notes for agentgateway.

🔥 Breaking changes

New release version pattern

The previous release version pattern was changed to align with the version number pattern that is used for the agentgateway standalone binary. Going forward, both the agentgateway on Kubernetes and agentgateway standalone binary projects use the same release version number. If you have existing CI/CD workflows that depend on the old pattern, update them.

Note that version 2.2 of the documentation is removed. Use the latest 1.0.0 version instead.

New Helm charts

The agentgateway control plane is now independent from the kgateway open source project. Because of that, the Helm paths changed as follows:

• CRDs: oci://cr.agentgateway.dev/charts/agentgateway-crds
• Control plane: oci://cr.agentgateway.dev/charts/agentgateway

Make sure to update any CI/CD workflows and processes to use the new Helm chart locations.

XListenerSet API promoted to ListenerSet

The experimental XListenerSet API is promoted to the standard ListenerSet API in version 1.5.0. You must install the standard channel of the Kubernetes Gateway API to get the ListenerSet API definition. If you use XListenerSet resources in your setup today, update the CRD kind from XListenerSet to ListenerSet and api version from gateway.networking.x-k8s.io/v1alpha1 to gateway.networking.k8s.io/v1 as shown in the following examples.

Old XListenerSet example:

apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: http-listenerset
  namespace: httpbin
spec:
  parentRef:
    name: agentgateway-proxy-http
    namespace: agentgateway-system
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - protocol: HTTP
    port: 80
    name: http
    allowedRoutes:
      namespaces:
        from: All

Updated ListenerSet example:

apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: http-listenerset
  namespace: httpbin
spec:
  parentRef:
    name: agentgateway-proxy-http
    namespace: agentgateway-system
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - protocol: HTTP
    port: 80
    name: http
    allowedRoutes:
      namespaces:
        from: All

CEL 2.0

This release includes a major refactor to the CEL implementation in agentgateway to improve scalability and performance. The following user facing changes were introduced:

• Function name changes: Due to dependency updates, function names were changed. Previously, function names followed a camel case pattern, such as base64Encode. Now, function names use dot notations, such as base64.encode. The old camel case names remain in place for backwards compatibility.
• New string functions: The following string manipulation functions were added to the CEL library: startsWith, endsWith, stripPrefix, and stripSuffix. These functions align with the Google CEL-Go strings extension.
• Null values fail: If a top-level variable returns a null value, the CEL expression now fails. Previously, null values always returned true. For example, the has(jwt) expression was previously successful if the JWT was missing or could not be found. Now, this expression fails.

Make sure to update and verify any existing CEL expressions that you use in your environment.

For more information, see the CEL expression reference.

🌟 New features

The following features were introduced in 1.0.0.

Kubernetes Gatway API version 1.5.0

The Kubernetes Gateway API dependency is updated to support version 1.5.0. This version introduces several changes, including:

• XListenerSets promoted to ListenerSets: The experimental XListenerSet API is promoted to the standard ListenerSet API in version 1.5.0. You must install the standard channel of the Kubernetes Gateway API to get the ListenerSet API definition. If you use XListenerSet resources in your setup today, update these resources to use the ListenerSet API instead.
• AllowInsecureFallback mode for mTLS listeners: If you set up mTLS listeners on your agentgateway proxy, you can now configure the proxy to establish a TLS connection, even if the client TLS certificate could not be validated successfully. For more information, see the mTLS listener docs.
• CORS wildcard support: The allowOrigins field now supports wildcard * origins to allow any origin.
• BackendTLS:

Autoscaling policies for agentgateway controller

You can now configure Horizontal Pod Autoscaler or Vertical Pod Autoscaler policies for the agentgateway control plane. To set up these policies, you use the horizontalPodAutoscaler or verticalPodAutoscaler fields in the Helm chart.

Review the following Helm configuration examples. For more information, see Advanced install settings.

Vertical Pod Autoscaler:

The following configuration ensures that the control plan pod is always assigned a minimum of 0.1 CPU cores (100millicores) and 128Mi of memory.

verticalPodAutoscaler:
  updatePolicy:
    updateMode: Auto
  resourcePolicy:
    containerPolicies:
    - containerName: "*"
      minAllowed:
        cpu: 100m
        memory: 128Mi

Horizontal Pod Autoscaler:

Make sure to deploy the Kubernetes metrics-server in your cluster. The metrics-server retrieves metrics, such as CPU and memory consumption for your workloads. These metrics can be used by the HPA plug-in to determine if the pod must be scaled up or down.

In the following example, you want to have 1 control plane replica running at any given time. If the CPU utilization averages 80%, you want to gradually scale up your replicas. You can have a maximum of 5 replicas at any given time.

horizontalPodAutoscaler:
  minReplicas: 1
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 80

Priority class support for agentgateway controller

You can now assign a PriorityClassName to the control plane pods by using the Helm chart. Priority indicates the importance of a pod relative to other pods. If a pod cannot be scheduled, the scheduler tries to preempt (evict) lower priority pods to make scheduling of the pending pod possible.

To assign a PriorityClassName to the control plane, you must first create a PriorityClass resource. The following example creates a PriorityClass with the name system-cluster-critical that assigns a priority of 1 Million.

kubectl apply -f- <<EOF
apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: system-cluster-critical
value: 1000000
globalDefault: false
description: "Use this priority class on system-critical pods only."
EOF

In your Helm values file, add the name of the PriorityClass in the controller.priorityClassName field.

controller: 
  priorityClassName: 

Common labels

Add custom labels to all resources that are created by the agentgateway Helm charts, including the Deployment, Service, and ServiceAccount of gateway proxies. This allows you to better organize your resources or integrate with external tools.

The following snippet adds the label-key and agw-managed labels to all resources.

commonLabels: 
  label-key: label-value
  agw-managed: "true"

Static IP addresses for Gateways

You can now assign a static IP address to the Kubernetes service that exposes your Gateway as shown in the following example.

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
  name: agentgateway-proxy
  namespace: agentgateway-system
spec:
  gatewayClassName: agentgateway
  addresses:
    - type: IPAddress
      value: 203.0.113.11
  listeners:
    - protocol: HTTP
      port: 80
      name: http
      allowedRoutes:
        namespaces:
          from: Same

GRPCRoute support

You can now attach GRPCRoutes to your agentgateway proxy to route traffic to gRPC endpoints. For more information, see gRPC routing.

🗑️ Deprecated or removed features