JFrog Platform Installation with NGINX Ingress Controller

Expose the JFrog Platform through an NGINX Ingress Controller you manage yourself instead of the Nginx pod bundled with the chart. Set artifactory.nginx.enabled: false to disable the bundled pod and artifactory.ingress.enabled: true to make the chart create an Ingress your controller picks up.

Use this when you already run an ingress controller for other workloads, want one external IP shared across applications, or terminate TLS at the ingress layer by policy.

Before You Begin

You need the following.

• Kubernetes 1.27+ or later, and Helm 3.17+ or later.
• Cluster-admin permission to install an ingress controller in its own namespace.
• A DNS record pointing your hostname at the ingress controller's external address. Docker subdomain access also needs a wildcard record.
• A TLS secret of type kubernetes.io/tls in the JFrog Platform namespace, unless you deploy the non-TLS configuration.

Then confirm which controller you run, because two different products share the name "NGINX Ingress Controller" and they read different annotation prefixes.

This page uses the F5 controller and nginx.org/ annotations throughout. On the community controller, translate them using Community Controller Equivalents.

Step 1: Install the NGINX Ingress Controller

Install with snippet support enabled.

helm repo add nginx https://helm.nginx.com/stable
helm repo update

helm install nginx-ingress nginx/nginx-ingress \
  --namespace nginx-ingress --create-namespace \
  --set controller.enableSnippets=true

Get the external address for your DNS record.

kubectl get service nginx-ingress-controller \
  --namespace nginx-ingress \
  --output jsonpath='{.status.loadBalancer.ingress[0]}'

Get the registered ingress class name. Your className value must match it exactly.

kubectl get ingressclass

Step 2: Choose Your Configuration

All three configurations disable the bundled Nginx pod, route / to the JFrog Router on port 8082, and route /artifactory/ directly to Artifactory on port 8081. They differ only in TLS and Docker access.

Examples nest values under artifactory:, the form the jfrog-platform chart uses. For the standalone artifactory or artifactory-ha chart, remove that wrapper and shift the remaining keys left one level.

Configuration 1: TLS Enabled

Terminates TLS at the ingress with a certificate you supply. Docker clients use repository paths.

artifactory:
  nginx:
    enabled: false

  ingress:
    enabled: true
    defaultBackend:
      enabled: true
    hosts:
      - artifactory.example.com
    routerPath: /
    artifactoryPath: /artifactory/
    className: "nginx"
    annotations:
      nginx.org/client-max-body-size: "0"
      nginx.org/proxy-read-timeout: "600"
      nginx.org/proxy-send-timeout: "600"
      nginx.org/location-snippets: |
        rewrite ^/(v2)/token /artifactory/api/docker/null/v2/token;
        rewrite ^/(v2)/([^\/]*)(/.*) /artifactory/api/docker/$2/$1$3;
    tls:
      - secretName: artifactory-tls
        hosts:
          - artifactory.example.com

client-max-body-size: "0" disables the body size check entirely. Artifact uploads have no predictable upper bound, so any finite limit eventually rejects a legitimate push with HTTP 413. The 600 second timeouts cover transfers that exceed the NGINX default of 60 seconds.

location-snippets applies to every path the chart generates, both routerPath and artifactoryPath. The Gateway API differs here. It attaches filters only to the router path rule, so these rewrites stop applying to /artifactory/ traffic if you migrate later.

Configuration 2: Without TLS

Serves plain HTTP. Use only for testing, or when a load balancer upstream terminates TLS.

Take Configuration 1 and make two changes: drop the tls block entirely, and add one annotation.

    annotations:
      nginx.org/redirect-to-https: "false"

redirect-to-https: "false" is defensive here rather than required. With no tls block, the controller generates no redirect at all, so plain HTTP already works without it.

Keep it anyway. It starts mattering in two cases:

• A load balancer upstream terminates TLS and sets X-Forwarded-Proto: https, and you enabled forwarded header support. See Ingress Behind Another Load Balancer.
• You later add a tls block. The controller then emits return 301 https://$host:443$request_uri for HTTP requests, and this annotation suppresses it.

Configuration 3: Docker Subdomain Access

Lets Docker clients address repositories as subdomains such as docker-local.artifactory.example.com. The server-snippets block extracts the repository from the hostname and location-snippets rewrites the request to the matching Artifactory Docker API path.

artifactory:
  nginx:
    enabled: false

  ingress:
    enabled: true
    defaultBackend:
      enabled: false
    hosts:
      - artifactory.example.com
      - '*.artifactory.example.com'
    routerPath: /
    artifactoryPath: /artifactory/
    className: "nginx"
    annotations:
      nginx.org/client-max-body-size: "0"
      nginx.org/proxy-read-timeout: "2400s"
      nginx.org/proxy-send-timeout: "2400s"
      nginx.org/proxy-buffers: "40 128k"
      nginx.org/proxy-busy-buffers-size: "128k"
      nginx.org/server-snippets: |
        set $repo "docker";
        if ($host ~* "^(?<captured_repo>.+)\.artifactory\.example\.com$") {
          set $repo $captured_repo;
        }
      nginx.org/location-snippets: |
        rewrite ^/(v1|v2)/(.*) /artifactory/api/docker/$repo/$1/$2 break;
        rewrite ^/(v1|v2)/ /artifactory/api/docker/$repo/$1/ break;
        proxy_set_header X-JFrog-Override-Base-Url $scheme://$host;
    tls:
      - secretName: artifactory-tls
        hosts:
          - artifactory.example.com
          - "*.artifactory.example.com"

Replace artifactory.example.com everywhere it appears, including the two occurrences inside the server-snippets regular expression, which escapes each dot as \. to match literal dots.

The 2400s timeouts exceed the 600 used elsewhere because subdomain routing adds a rewrite hop and large layer transfers can outlast the shorter limit. The proxy-buffers values cover the larger response headers Docker manifest requests produce.

This configuration needs four things the others do not.

1. Artifactory set to the Subdomain access method. See Set the Artifactory Docker Access Method.
2. A wildcard TLS certificate covering both artifactory.example.com and *.artifactory.example.com. TLS is negotiated against the subdomain before any HTTP routing happens. An apex-only certificate therefore fails the handshake on every subdomain. Without a wildcard certificate, use repository paths instead.
3. A wildcard DNS record for *.artifactory.example.com pointing at the controller's external address.
4. The X-JFrog-Override-Base-Url header, already in the block above. It pins the base URL Artifactory uses for absolute URLs in Docker API responses. Treat it as insurance: both controllers forward Host and X-Forwarded-* by default, from which Artifactory already derives the correct URL. It matters when an upstream proxy drops or rewrites those headers, or when Artifactory's configured Base URL differs from the hostname clients use.

Set the Artifactory Docker Access Method

Artifactory defaults to the repository path method. It embeds the repository name in the upload URLs it returns to Docker clients. The subdomain rewrite already derives the repository from the hostname, so it prepends the name a second time and the resulting path is invalid.

Set the method to Subdomain in Administration > Reverse Proxy, or through the REST API.

curl -u admin:<password> \
  "https://artifactory.example.com/artifactory/api/system/configuration/webServer" \
  --output webserver.json

# change "dockerReverseProxyMethod" to "SUBDOMAIN" in webserver.json, then:
curl -u admin:<password> -X POST \
  -H "Content-Type: application/json" \
  --data @webserver.json \
  "https://artifactory.example.com/artifactory/api/system/configuration/webServer"

Confirm it took effect.

curl -s -u admin:<password> \
  "https://artifactory.example.com/artifactory/api/system/configuration/webServer" \
  | grep dockerReverseProxyMethod

Step 3: Deploy the JFrog Platform

Generate and safely store the master and join keys before your first install. Every later upgrade needs the same values.

export MASTER_KEY=$(openssl rand -hex 32)
export JOIN_KEY=$(openssl rand -hex 32)

Save your chosen configuration as values.yaml and deploy.

helm repo add jfrog https://charts.jfrog.io
helm repo update

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

Step 4: Verify the Deployment

Confirm the Ingress exists and your controller assigned it an address, and that the annotations arrived intact.

kubectl get ingress --namespace jfrog-platform
kubectl describe ingress --namespace jfrog-platform

Check platform health through the ingress. The readiness endpoint covers all platform microservices, not just Artifactory, and returns HTTP 200 with {"code": "OK"} when healthy.

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

For a per-service breakdown when readiness fails, use /router/api/v1/system/health. See Load Balancer for the full endpoint list.

If you configured Docker subdomain access, verify it separately.

docker login docker-local.artifactory.example.com

Troubleshooting

Community Controller Equivalents

To use the Kubernetes community controller instead of F5, translate the annotations.

Enabling snippets also takes more work there. F5 needs one flag; the community controller needs two, because it treats snippet annotations as a privilege-escalation risk and rejects them at the admission webhook.

Without the second flag, kubectl apply fails immediately rather than failing silently. Confirmed on community controller v1.15.1; older versions may need only the first flag. Raise the risk level only if your cluster policy permits snippets, since they allow arbitrary NGINX configuration from any namespace that can create an Ingress.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Kubernetes Gateway API Configuration for Artifactory
• 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