Kubernetes Gateway API Configuration for Artifactory

The JFrog Artifactory and Artifactory HA Helm charts support the Kubernetes Gateway API as an alternative to Ingress. Set gatewayApi.enabled: true and the chart creates a Gateway and an HTTPRoute, plus a controller-specific extension filter if you configure one. The result is comparable to the Ingress support.

Use the Gateway API in any of these cases:

• Your cluster already runs a Gateway controller.
• You want route configuration kept separate from load balancer ownership.
• You need routing that Ingress annotations cannot express portably.

Chart Version Requirements

How Traffic Flows

External requests reach the Gateway, which terminates TLS and hands off to the HTTPRoute. The HTTPRoute matches on path and forwards to the Artifactory service.

flowchart LR
    C["Client"] --> LB["Load Balancer<br/>(provisioned by controller)"]
    LB --> GW["Gateway<br/>TLS termination"]
    GW --> HR["HTTPRoute<br/>path matching"]
    HR -->|routerPath| R["Artifactory Service<br/>port 8082 (Router)"]
    HR -->|artifactoryPath| A["Artifactory Service<br/>port 8081 direct"]

The Gateway controller, not the chart, provisions the external load balancer and reconciles these resources into proxy configuration.

Prerequisites

1. Install the Gateway API CRDs. They are not built into Kubernetes.

   Bash

   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml

   JFrog validated v1.4.1. The chart checks whether your cluster serves gateway.networking.k8s.io/v1 or v1beta1, then emits resources with the matching version. Later standard-channel releases work too. The experimental channel is not required.

2. Run a Gateway controller. Without one the Gateway is created but never programmed, and no traffic reaches Artifactory.

   Controller	Support status
   NGINX Gateway Fabric	Validated by JFrog. Extension filter examples target it.
   Envoy Gateway	Not validated. Expected to handle core routing, since the chart emits standard fields.
   Istio Gateway controller	Not validated. Expected to handle core routing.

3. Create a matching GatewayClass. Its name must equal your gatewayApi.gatewayClassName, otherwise the install fails with gatewayApi.gatewayClassName is required when gatewayApi.enabled is true.

   Bash

   kubectl get gatewayclass

4. Set nginx.enabled: false. The bundled Nginx pod defaults to enabled and is exposed as a LoadBalancer service. Leaving it on alongside a Gateway gives you two entry points and two external load balancers. Nothing routes to the second one, and your cloud provider still bills you for it.

Configure and Deploy

This exposes Artifactory over HTTP and HTTPS with default path routing. Save it as values.yaml.

nginx:
  enabled: false

gatewayApi:
  enabled: true
  gatewayClassName: "nginx"
  hosts:
    - artifactory.example.com
  routerPath: /
  artifactoryPath: /artifactory/
  pathType: PathPrefix
  disableRouterBypass: false
  httpRoute:
    enabled: true
  tls:
    - secretName: artifactory-tls
      hosts:
        - artifactory.example.com

helm upgrade --install artifactory jfrog/artifactory \
  --namespace artifactory --create-namespace \
  --set global.masterKey=${MASTER_KEY} \
  --set global.joinKey=${JOIN_KEY} \
  --values values.yaml

For the jfrog-platform chart, nest the same keys under artifactory.

artifactory:
  nginx:
    enabled: false
  gatewayApi:
    enabled: true
    gatewayClassName: "nginx"
    hosts:
      - artifactory.example.com
    tls:
      - secretName: artifactory-tls
        hosts:
          - artifactory.example.com

Default Routing

With hosts set and no other path configuration, the chart creates two rules.

Ports come from your Artifactory service values rather than being hardcoded, so overriding artifactory.externalPort changes the backend port to match.

The / rule targets the JFrog Router, which fronts every platform microservice including the UI, Xray, and Distribution. The /artifactory/ rule bypasses the Router for direct artifact traffic. Set disableRouterBypass: true to remove the second rule so everything flows through the Router.

TLS Configuration

An HTTP listener on httpExternalPort is always created. HTTPS listeners appear only when you populate tls.

The chart creates one HTTPS listener per hostname, so the controller can match certificates by SNI. Listeners are named https, https-1, https-2, and so on.

To resolve the hostnames for a tls entry, the chart uses the first of these that is not empty:

1. The hosts list on that tls entry.
2. The top-level gatewayApi.hosts list.
3. A wildcard listener with no hostname, matching any host.

Every entry requires secretName, and the secret must already exist in the release namespace. TLS mode is always Terminate, so traffic from the Gateway to Artifactory is plain HTTP inside the cluster.

This creates an http listener plus https and https-1, both referencing artifactory-tls.

gatewayApi:
  hosts:
    - artifactory.example.com
    - docker.example.com
  tls:
    - secretName: artifactory-tls

Docker Registry Support

Docker clients need URL rewrites the Gateway API cannot express natively. Supply them through an extension filter. Add this block to your gatewayApi configuration, targeting NGINX Gateway Fabric's SnippetsFilter.

gatewayApi:
  extensionFilter:
    enabled: true
    apiVersion: gateway.nginx.org/v1alpha1
    kind: SnippetsFilter
    spec:
      snippets:
        - context: http.server
          value: |
            client_max_body_size 0;
            proxy_read_timeout 600;
            proxy_send_timeout 600;
        - context: http.server.location
          value: |
            rewrite ^/(v2)/token /artifactory/api/docker/null/v2/token;
            rewrite ^/(v2)/([^\/]*)(/.*) /artifactory/api/docker/$2/$1$3;

The chart creates the SnippetsFilter and adds an ExtensionRef filter to the HTTPRoute referencing it. It also derives the group from the portion of apiVersion before the slash, so you never set it yourself.

http.server applies server-wide settings such as body size and timeouts. http.server.location applies rewrites per matched route. Setting client_max_body_size to 0 removes the upload limit, which artifact uploads need because they have no predictable upper bound.

Clients address repositories by path, as in artifactory.example.com/docker-local/myimage:tag. The rewrite reads the repository from the first path segment after /v2/.

Artifactory uses that same form in the Location headers it returns during a blob upload. Re-applying the rewrite to those redirected requests therefore produces the same path. Pushes work with Artifactory's default Docker access method, and no reverse proxy setting needs changing.

To reference a filter you create separately, leave extensionFilter.enabled as false and point httpRoute.filters at it. Supply group explicitly here, because the chart derives it only for filters it creates.

gatewayApi:
  httpRoute:
    filters:
      - type: ExtensionRef
        extensionRef:
          group: gateway.nginx.org
          kind: SnippetsFilter
          name: artifactory-docker-rewrites

Additional Routes

Use additionalDirectRoutes to append complete HTTPRoute rules. Both it and additionalRules render through Helm's tpl, so template expressions resolve against the release. Each entry needs both matches and backendRefs.

gatewayApi:
  additionalDirectRoutes: |
    - matches:
      - path:
          type: PathPrefix
          value: /xray/
      backendRefs:
      - name: {{ include "artifactory.fullname" . }}
        port: 8082

Use artifactory.fullname with the artifactory chart and artifactory-ha.fullname with the artifactory-ha chart.

Parameter Reference

All parameters nest under gatewayApi in values.yaml, or under artifactory.gatewayApi in the jfrog-platform chart. The same values apply to both the artifactory and artifactory-ha charts.

For current defaults on the version you deploy, run helm show values jfrog/artifactory | grep -A 60 "^gatewayApi:".

Generated Resource Names

Names derive from the chart fullname, which is not always <release>-artifactory. Helm omits the chart name when your release name already contains it.

The artifactory-ha chart follows the same rule with artifactory-ha in place of artifactory. Run kubectl get gateway,httproute to see actual names rather than assuming them.

The -gateway suffix matters: NGINX Gateway Fabric provisions its own data-plane Service named <gateway-name>-nginx. Without the suffix that would collide with the Service the chart creates for its bundled Nginx pod. If you override gatewayApi.name, avoid values whose -nginx form clashes with an existing Service.

Migrate from Ingress

Most values map directly.

Four differences need attention.

1. pathType is not interchangeable. Ingress defaults to ImplementationSpecific, which the Gateway API rejects. Use PathPrefix, Exact, or RegularExpression. If you relied on ImplementationSpecific regular expression behavior, RegularExpression is closest, and support varies by controller.
2. Ingress annotations do not carry over. Annotations such as nginx.org/client-max-body-size have no Gateway API equivalent. Reimplement them as extension filters or your controller's own policy resources. gatewayApi.annotations applies to the Gateway object itself and is not a substitute.
3. There is no backendService equivalent. ingress.backendService can be nginx to keep the bundled Nginx pod as a last-hop reverse proxy. The HTTPRoute always targets the Artifactory service directly.
4. Routes attach only from the Gateway's own namespace. The Gateway sets allowedRoutes.namespaces.from: Same.

Enable ingress and gatewayApi together during migration. Both resource sets are created and both paths work, so you can shift DNS gradually and roll back by repointing DNS rather than redeploying.

Verify the Deployment

PROGRAMMED must be True before traffic flows. An unattached HTTPRoute reports a parentRef condition explaining why.

kubectl get gateway --namespace artifactory
kubectl describe gateway --namespace artifactory
kubectl describe httproute --namespace artifactory

Point DNS at the Gateway address, then check platform health. A healthy platform returns HTTP 200 with {"code": "OK"}.

curl https://artifactory.example.com/router/api/v1/system/readiness

To inspect what the chart will create without deploying, render locally. The --api-versions flag simulates the CRDs being present.

helm template artifactory jfrog/artifactory \
  --api-versions "gateway.networking.k8s.io/v1" \
  --values values.yaml \
  --show-only templates/gateway-api/gateway.yaml \
  --show-only templates/gateway-api/httproute.yaml

Troubleshooting

Limitations

• JFrog validated only NGINX Gateway Fabric. Other conformant controllers should handle core routing and TLS, but are untested.
• No backendService: nginx equivalent. The bundled Nginx pod cannot serve as a last-hop reverse proxy.
• Filters apply only to the router path rule. The artifactoryPath rule receives none, so rewrites and proxy settings do not apply to /artifactory/ traffic. Ingress differs, applying location-snippets to every generated path.
• Cross-namespace routes are not supported. The Gateway uses allowedRoutes.namespaces.from: Same.
• Extension filter contents are not validated by the chart. extensionFilter.spec passes through unchanged, so errors surface as controller-side failures rather than Helm errors.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• JFrog Platform Installation with NGINX Ingress Controller
• Ingress Behind Another Load Balancer
• Configure Nginx Service and Load Balancer for Helm
• Nginx SSL Termination at the Load Balancer
• Load Balancer
• Establish TLS in Artifactory and JFrog Platform