Connect to NGINX One Console

This document explains how to connect F5 NGINX Ingress Controller to F5 NGINX One Console using NGINX Agent. Connecting NGINX Ingress Controller to NGINX One Console enables centralized monitoring of all controller instances.

Once connected, you’ll see a read-only configuration of NGINX Ingress Controller. For each instance, you can review:

  • Read-only configuration file
  • Unmanaged SSL/TLS certificates for Control Planes

Before you begin

Before connecting NGINX Ingress Controller to NGINX One Console, you need to create a Kubernetes Secret with the data plane key. Use the following command:

kubectl create secret generic dataplane-key \
  --from-literal=dataplane.key=<Your Dataplane Key> \
  -n <namespace>

When you create a Kubernetes Secret, use the same namespace where NGINX Ingress Controller is running. If you use -watch-namespace or watch-secret-namespace arguments with NGINX Ingress Controller, you need to add the dataplane key secret to the watched namespaces. This secret will take approximately 60 - 90 seconds to reload on the pod.

Note: You can also create a data plane key through the NGINX One Console. Once loggged in, select Manage > Control Planes > Add Control Plane, and follow the steps shown.

Deploy NGINX Ingress Controller with NGINX Agent

Edit your values.yaml file to enable NGINX Agent and configure it to connect to NGINX One Console:

nginxAgent:
  enable: true
  dataplaneKeySecretName: "<data_plane_key_secret_name>"

The dataplaneKeySecretName is used to authenticate the agent with NGINX One Console. See the NGINX One Console Docs for instructions on how to generate your dataplane key from the NGINX One Console.

Follow the Installation with Helm instructions to deploy NGINX Ingress Controller.

Add the following flag to the Deployment/DaemonSet file of NGINX Ingress Controller:

args:
- -agent=true

Create a ConfigMap with an nginx-agent.conf file:

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-agent-config
  namespace: <namespace>
data:
  nginx-agent.conf: |-
    log:
      # set log level (error, info, debug; default "info")
      level: info
      # set log path. if empty, don't log to file.
      path: ""
  
    allowed_directories:
      - /etc/nginx
      - /usr/lib/nginx/modules
  
    features:
      - certificates
      - connection
      - metrics
      - file-watcher
  
    ## command server settings
    command:
      server:
        host: product.connect.nginx.com
        port: 443
      auth:
        tokenpath: "/etc/nginx-agent/secrets/dataplane.key"
      tls:
        skip_verify: false

Make sure to set the namespace in the nginx-agent.config to the same namespace as NGINX Ingress Controller. Mount the ConfigMap to the Deployment/DaemonSet file of NGINX Ingress Controller:

volumeMounts:
- name: nginx-agent-config
  mountPath: /etc/nginx-agent/nginx-agent.conf
  subPath: nginx-agent.conf
- name: dataplane-key
  mountPath: /etc/nginx-agent/secrets
volumes:
- name: nginx-agent-config
  configMap:
    name: nginx-agent-config
- name: dataplane-key
  secret:
    secretName: "<data_plane_key_secret_name>"

Follow the Installation with Manifests instructions to deploy NGINX Ingress Controller.

Verify a connection to NGINX One Console

After deploying NGINX Ingress Controller with NGINX Agent, you can verify the connection to NGINX One Console. Log in to your F5 Distributed Cloud Console account. Select NGINX One > Visit Service. In the dashboard, go to Manage > Instances. You should see your instances listed by name. The instance name matches both the hostname and the pod name.

Troubleshooting

If you encounter issues connecting your instances to NGINX One Console, try the following commands:

Check the NGINX Agent version:

kubectl exec -it -n <namespace> <nginx_ingress_pod_name> -- nginx-agent -v

If nginx-agent version is v3, continue with the following steps. Otherwise, make sure you are using an image that does not include NGINX App Protect.

Check the NGINX Agent configuration:

kubectl exec -it -n <namespace> <nginx_ingress_pod_name> -- cat /etc/nginx-agent/nginx-agent.conf

Check NGINX Agent logs:

kubectl exec -it -n <namespace> <nginx_ingress_pod_name> -- nginx-agent

Select the instance associated with your deployment of NGINX Ingress Controller. Under the Details tab, you’ll see information associated with:

  • Unmanaged SSL/TLS certificates for Control Planes
  • Configuration recommendations

Under the Configuration tab, you’ll see a read-only view of the configuration files.