Manage HAProxy Unified Gateway logs

The HAProxy Unified Gateway controller’s Deployment manifest, controller.yaml, sets the startup argument --hugconf-crd, which references a HugConf custom resource to load. By default, it uses one named haproxy-unified-gateway/hugconf. The job of that resource is to customize the controller’s behavior, including its log settings.

Set logging options with HugConf Jump to heading #

With a HugConf resource, you can customize the verbosity of the logs that the HAProxy Unified Gateway controller produces.

• Define which categories of logs to produce.
• Set the logging level for each category.

For example, to enable info-level logging of interactions with the Kubernetes API and debug-level logging for the load balancer’s operations, apply the following settings:

1. Create a file named hugconf.yaml and add the following:

   hugconf.yaml
   yaml
   apiVersion: gate.v3.haproxy.org/v3
   kind: HugConf
   metadata:
     name: hugconf
     namespace: haproxy-unified-gateway
   spec:
     logging:
       categoryLevelList:
       - category: k8s
         level: Info
       - category: haproxycfg
         level: Debug
       defaultLevel: Debug

   hugconf.yaml
   yaml
   apiVersion: gate.v3.haproxy.org/v3
   kind: HugConf
   metadata:
     name: hugconf
     namespace: haproxy-unified-gateway
   spec:
     logging:
       categoryLevelList:
       - category: k8s
         level: Info
       - category: haproxycfg
         level: Debug
       defaultLevel: Debug

   This will create or update a HugConf resource named hugconf in the haproxy-unified-gateway namespace. In this file:

   • categoryLevelList defines the list of logging categories you want to include in the logs. In this example, the list includes k8s for K8s API interactions and haproxycfg for load balancer operations.
   • Each entry has its own logging level. For k8s, we set the level to Info and for haproxycfg we set it to Debug.
   • If you don’t specify a level for a logging category, its level is inherited from the value set by defaultLevel.

2. Apply the configuration:

   nix
   kubectl apply -f hugconf.yaml

   nix
   kubectl apply -f hugconf.yaml

   output
   text
   hugconf.gate.v3.haproxy.org/hugconf created

   output
   text
   hugconf.gate.v3.haproxy.org/hugconf created

View the controller logs Jump to heading #

To view the logs for the HAProxy Unified Gateway pod, issue the following command:

nix
kubectl logs -n haproxy-unified-gateway \
$(kubectl get pods -A \
  | awk '/haproxy-unified-gateway/ && !/default/ && /Running/' \
  | awk 'NR==1{print $2}') $@

nix
kubectl logs -n haproxy-unified-gateway \
$(kubectl get pods -A \
  | awk '/haproxy-unified-gateway/ && !/default/ && /Running/' \
  | awk 'NR==1{print $2}') $@

This will show all of the logs generated within the pod that you specifed in your HugConf configuration. Depending on your settings, this may include the controller’s logs, the load balancer logs, and others.

output
text
2025-11-19T12:28:37.482Z [pebble] {"type":"security","datetime":"2025-11-19T12:28:37Z","level":"WARN","event":"sys_startup:1000","description":"Starting daemon","appid":"pebble"}
2025-11-19T12:28:37.483Z [pebble] Started daemon.
2025-11-19T12:28:37.503Z [pebble] POST /v1/services 6.039014ms 202 (http+unix)
2025-11-19T12:28:37.509Z [pebble] Service "hug" starting: /var/lib/pebble/default/run-hug
2025-11-19T12:28:37.512Z [pebble] Service "haproxy" starting: /var/lib/pebble/default/run-haproxy
2025-11-19T12:28:37.520Z [hug] Memory limit for HUG: 853MiB
2025-11-19T12:28:37.523Z [haproxy] Memory limit for HAProxy: 1706MiB
2025-11-19T12:28:37.678Z [haproxy] [NOTICE]   (19) : Initializing new worker (33)
2025-11-19T12:28:37.685Z [haproxy] [NOTICE]   (33) : haproxy version is 3.2.8-9200f39
2025-11-19T12:28:38.086Z [hug]   _
2025-11-19T12:28:38.086Z [hug]  | |__   __ _ _ __  _ __ _____  ___   _
2025-11-19T12:28:38.086Z [hug]  | '_ \ / _` | '_ \| '__/ _ \ \/ / | | |
2025-11-19T12:28:38.086Z [hug]  | | | | (_| | |_) | | | (_) >  <| |_| |
2025-11-19T12:28:38.086Z [hug]  |_| |_|\__,_| .__/|_|  \___/_/\_\\__, |
2025-11-19T12:28:38.086Z [hug]              |_| __ _          _  |___/        _
2025-11-19T12:28:38.086Z [hug]   _   _ _ __ (_)/ _(_) ___  __| |   __ _  __ _| |_ _____      ____ _ _   _
2025-11-19T12:28:38.086Z [hug]  | | | | '_ \| | |_| |/ _ \/ _` |  / _` |/ _` | __/ _ \ \ /\ / / _` | | | |
2025-11-19T12:28:38.086Z [hug]  | |_| | | | | |  _| |  __/ (_| | | (_| | (_| | ||  __/\ V  V / (_| | |_| |
2025-11-19T12:28:38.086Z [hug]   \__,_|_| |_|_|_| |_|\___|\__,_|  \__, |\__,_|\__\___| \_/\_/ \__,_|\__, |
2025-11-19T12:28:38.086Z [hug]                                    |___/                             |___/
2025-11-19T12:28:38.086Z [hug] 
2025-11-19T12:28:38.086Z [hug] HAProxy unified gateway v0.7.0
2025-11-19T12:28:38.086Z [hug] built-from github.com/haproxytech/haproxy-unified-gateway
2025-11-19T12:28:38.107Z [haproxy] [NOTICE]   (19) : Loading success.
2025-11-19T12:28:38.429Z [hug] {"time":"2025-11-19T12:28:38.426379208Z","level":"INFO","msg":"Starting EventSource","controller":"GatewayApiCRD","controllerGroup":"apiextensions.k8s.io","controllerKind":"CustomResourceDefinition","source":"kind source: *v1.PartialObjectMetadata","category":"k8s","sourceFile":{"file":"/go/pkg/mod/github.com/go-logr/logr@v1.4.3/logr.go","line":280}}
...

output
text
2025-11-19T12:28:37.482Z [pebble] {"type":"security","datetime":"2025-11-19T12:28:37Z","level":"WARN","event":"sys_startup:1000","description":"Starting daemon","appid":"pebble"}
2025-11-19T12:28:37.483Z [pebble] Started daemon.
2025-11-19T12:28:37.503Z [pebble] POST /v1/services 6.039014ms 202 (http+unix)
2025-11-19T12:28:37.509Z [pebble] Service "hug" starting: /var/lib/pebble/default/run-hug
2025-11-19T12:28:37.512Z [pebble] Service "haproxy" starting: /var/lib/pebble/default/run-haproxy
2025-11-19T12:28:37.520Z [hug] Memory limit for HUG: 853MiB
2025-11-19T12:28:37.523Z [haproxy] Memory limit for HAProxy: 1706MiB
2025-11-19T12:28:37.678Z [haproxy] [NOTICE]   (19) : Initializing new worker (33)
2025-11-19T12:28:37.685Z [haproxy] [NOTICE]   (33) : haproxy version is 3.2.8-9200f39
2025-11-19T12:28:38.086Z [hug]   _
2025-11-19T12:28:38.086Z [hug]  | |__   __ _ _ __  _ __ _____  ___   _
2025-11-19T12:28:38.086Z [hug]  | '_ \ / _` | '_ \| '__/ _ \ \/ / | | |
2025-11-19T12:28:38.086Z [hug]  | | | | (_| | |_) | | | (_) >  <| |_| |
2025-11-19T12:28:38.086Z [hug]  |_| |_|\__,_| .__/|_|  \___/_/\_\\__, |
2025-11-19T12:28:38.086Z [hug]              |_| __ _          _  |___/        _
2025-11-19T12:28:38.086Z [hug]   _   _ _ __ (_)/ _(_) ___  __| |   __ _  __ _| |_ _____      ____ _ _   _
2025-11-19T12:28:38.086Z [hug]  | | | | '_ \| | |_| |/ _ \/ _` |  / _` |/ _` | __/ _ \ \ /\ / / _` | | | |
2025-11-19T12:28:38.086Z [hug]  | |_| | | | | |  _| |  __/ (_| | | (_| | (_| | ||  __/\ V  V / (_| | |_| |
2025-11-19T12:28:38.086Z [hug]   \__,_|_| |_|_|_| |_|\___|\__,_|  \__, |\__,_|\__\___| \_/\_/ \__,_|\__, |
2025-11-19T12:28:38.086Z [hug]                                    |___/                             |___/
2025-11-19T12:28:38.086Z [hug] 
2025-11-19T12:28:38.086Z [hug] HAProxy unified gateway v0.7.0
2025-11-19T12:28:38.086Z [hug] built-from github.com/haproxytech/haproxy-unified-gateway
2025-11-19T12:28:38.107Z [haproxy] [NOTICE]   (19) : Loading success.
2025-11-19T12:28:38.429Z [hug] {"time":"2025-11-19T12:28:38.426379208Z","level":"INFO","msg":"Starting EventSource","controller":"GatewayApiCRD","controllerGroup":"apiextensions.k8s.io","controllerKind":"CustomResourceDefinition","source":"kind source: *v1.PartialObjectMetadata","category":"k8s","sourceFile":{"file":"/go/pkg/mod/github.com/go-logr/logr@v1.4.3/logr.go","line":280}}
...

Use the explain command Jump to heading #

Use the kubectl explain command to see the full list of fields supported by the HugConf CRD:

nix
kubectl explain hugconf --api-version=gate.v3.haproxy.org/v3 --recursive

nix
kubectl explain hugconf --api-version=gate.v3.haproxy.org/v3 --recursive

output
text
GROUP:      gate.v3.haproxy.org
KIND:       HugConf
VERSION:    v3  
DESCRIPTION:
    HugConf is a specification for a the controller related configuration
   
FIELDS:
  apiVersion	<string>
  kind	<string>
  ...
  spec	<Object> -required-
    logging	<Object> -required-
      categoryLevelList	<[]Object>
        category	<string> -required-
        enum: k8s, gate, status, haproxycfg, ....
        level	<string> -required-
        enum: Debug, Info, Warn, Error, ....
      defaultLevel	<string>
      enum: Debug, Info, Warn, Error, ....

output
text
GROUP:      gate.v3.haproxy.org
KIND:       HugConf
VERSION:    v3  
DESCRIPTION:
    HugConf is a specification for a the controller related configuration
   
FIELDS:
  apiVersion	<string>
  kind	<string>
  ...
  spec	<Object> -required-
    logging	<Object> -required-
      categoryLevelList	<[]Object>
        category	<string> -required-
        enum: k8s, gate, status, haproxycfg, ....
        level	<string> -required-
        enum: Debug, Info, Warn, Error, ....
      defaultLevel	<string>
      enum: Debug, Info, Warn, Error, ....

You can examine fields in more detail by providing the specific field in the command, for example, hugconf.spec.logging.defaultLevel:

nix
kubectl explain hugconf.spec.logging.defaultLevel --api-version=gate.v3.haproxy.org/v3 --recursive

nix
kubectl explain hugconf.spec.logging.defaultLevel --api-version=gate.v3.haproxy.org/v3 --recursive