ARTIFACTORY: Installing JFrog Platform with NGINX Ingress Controller

Introduction 

This document outlines the steps and configuration required to install the JFrog Artifactory using the official NGINX Ingress Controller. With the Kubernetes community ingress-nginx controller being deprecated, this guide validates nginx/nginx-ingress as a supported alternative and highlights the necessary changes from the previous ingress setup. It covers the installation of the NGINX Ingress Controller, updated Artifactory Helm configurations for both TLS and non-TLS deployments, optional self-signed certificate generation, and key considerations for a successful migration.

This document describes:

• Required changes compared to the old ingress configuration
  
• Installation of NGINX Ingress Controller
  
• Artifactory Helm values for TLS and non-TLS setups
  
• Optional steps to generate a self-signed TLS certificate

Resolution 

Old Ingress Configuration (Reference)

The following snippet represents the earlier ingress configuration that relied on Kubernetes ingress-nginx annotations:

nginx:
  enabled: false

ingress:
  enabled: true
  defaultBackend:
    enabled: true
  hosts:
    - <nginx-ingress-svc-external-hostname or dns hostname>
  routerPath: /
  artifactoryPath: /artifactory/
  className: "nginx"
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
    nginx.ingress.kubernetes.io/configuration-snippet: |
      rewrite ^/(v2)/token /artifactory/api/docker/null/v2/token;
      rewrite ^/(v2)/([^\/]*)(/.*) /artifactory/api/docker/$2/$1$3;
  tls:
  - secretName: nginx-tls
    hosts:
      - <nginx-ingress-svc-external-hostname or dns hostname>

Install NGINX Ingress Controller
Note: 

This step is performed and managed by the customer. JFrog does not install, configure, or manage, and has no control over it.

Install the official NGINX Ingress Controller using Helm. Snippet support must be explicitly enabled.

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

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

Note: 

This controller uses nginx.org/* annotations instead of nginx.ingress.kubernetes.io/*.


Install Artifactory

Install Artifactory using Helm.

helm install artifactory jfrog/artifactory \
  --namespace artifactory -f values.yaml

Below are the Helm values.yaml examples validated for Artifactory.

Option 1: With TLS Enabled

nginx:
  enabled: false

ingress:
  enabled: true
  defaultBackend:
    enabled: true
  hosts:
    - <nginx-ingress-svc-external-hostname or dns hostname>
  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: nginx-tls
    hosts:
      - <nginx-ingress-svc-external-hostname or dns hostname>

Option 2: Without TLS

nginx:
  enabled: false

ingress:
  enabled: true
  defaultBackend:
    enabled: true
  hosts:
    - <nginx-ingress-svc-external-hostname or dns hostname>
  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/redirect-to-https: "false"
    nginx.org/location-snippets: |
      rewrite ^/(v2)/token /artifactory/api/docker/null/v2/token;
      rewrite ^/(v2)/([^\/]*)(/.*) /artifactory/api/docker/$2/$1$3;

Explanation on the above used annotations:

nginx.org/client-max-body-size: "0" → Removes the request body size limit (allows unlimited upload size).
nginx.org/proxy-read-timeout: "600" → Sets the maximum time (in seconds) NGINX waits to read a response from the backend.
nginx.org/proxy-send-timeout: "600" → Sets the maximum time (in seconds) NGINX waits to send a request to the backend.
nginx.org/redirect-to-https: "false" → Disables automatic redirection from HTTP to HTTPS.
nginx.org/location-snippets → Injects custom NGINX rewrite rules to route Docker v2 registry and token requests to Artifactory.

Validate Artifactory Access

Verify that Artifactory is reachable through Istio by calling the system ping API:

curl http://<hostname>/artifactory/api/system/ping

A successful setup should return:

OK

Self-Signed TLS Certificate (Optional)
Note: 

This step is performed and managed by the user/customer. JFrog has no control over it.

If TLS is required and a CA-issued certificate is not available, a self-signed certificate can be generated as follows.

Step 1: Create SAN Configuration

cat > san.cnf <<EOF
[ req ]
default_bits       = 2048
prompt             = no
default_md         = sha256
req_extensions     = req_ext
distinguished_name = dn

[ dn ]
CN = artifactory.local

[ req_ext ]
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = <nginx-ingress-svc-external-hostname or dns hostname>
EOF

Step 2: Generate Certificate and Key

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout tls.key \
  -out tls.crt \
  -config san.cnf \
  -extensions req_ext

Step 3: Create Kubernetes TLS Secret

kubectl create secret tls nginx-tls \
  --cert=tls.crt \
  --key=tls.key \
  -n <namespace>

Notes & Considerations

• Docker registry traffic requires the rewrite rules defined in location-snippets.
  
• controller.enableSnippets=true is mandatory for custom rewrite rules.
  
• Ensure className: nginx matches the ingress class created by the controller.

For production, CA-signed certificates are recommended instead of self-signed ones.

NGINX Ingress Migration – Configuration Comparison

 

Conclusion

NGINX Ingress Controller works as a supported replacement for the deprecated ingress-nginx setup and has been validated with Artifactory for both TLS and non-TLS configurations. The migration requires only ingress annotation key changes, with no functional impact on routing or behavior, and no changes to the JFrog installation or deployment process are needed.