How can I add annotations to the NGF data plane Service without manually editing the Service?

[jinhee6930]

(I used a translator. The senten)

Hello,
I’m currently using NGINX Gateway Fabric and trying to configure annotations on the data plane Service in a declarative way.
According to the documentation below, it looks like spec.kubernetes.service.annotations can be used in the NginxProxy resource:
https://docs.nginx.com/nginx-gateway-fabric/how-to/data-plane-configuration/#configure-infrastructure-related-settings

kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config-test
spec:
  kubernetes:
    deployment:
      container:
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
      pod:
        terminationGracePeriodSeconds: 90
      replicas: 2
    service:
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
      type: LoadBalancer
      loadBalancerIP: "192.87.9.1"
EOF

However, when I check the API reference:
https://docs.nginx.com/nginx-gateway-fabric/reference/api/#gateway.nginx.org%2fv1alpha2.ServiceSpec
I don’t see any field related to annotations under ServiceSpec.

When I try to create the NginxProxy resource with service annotations, I get the following error:

Error from server (BadRequest): error when creating "STDIN": NginxProxy in version "v1alpha2" cannot be handled as a NginxProxy: strict decoding error: unknown field "spec.config", unknown field "spec.kubernetes.service.annotations"

My questions:
Is it currently supported to configure annotations on the NGF data plane Service via NginxProxy?
If not, is the documentation outdated, or is this feature planned for a future release?
From an operational perspective, we manage multiple clusters and systems, so manually modifying the Service with kubectl edit svc is not a viable option.
Any guidance or clarification would be greatly appreciated.

Thank you!

[sjberman]

@jinhee6930 Looks like the docs are incorrect, we'll fix that.

You can set annotations either in the Gateway's infrastructure settings or using a patch in the NginxProxy API.

[jinhee6930]

Thank you!
I used a patch in NginxProxy API.

apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-nginxproxy-config-gateway
  namespace: nginx-gateway
spec:
  kubernetes:
    service:
      type: LoadBalancer
      patches:
      - type: StrategicMerge
        value:
          metadata:
            annotations:
              loadbalancer.nhncloud/loadbalancer-name: NGINX-FABRIC-LB
              loadbalancer.nhncloud/member-subnet-id: xxx-xxxx-xxxx-xxxx-xxx
              loadbalancer.openstack.org/subnet-id: xxx-xxx-xxx-xxx-xx
              service.beta.kubernetes.io/openstack-internal-load-balancer: "true"
(omission ...)

k get svc ngf-gateway-nginx -o yaml
apiVersion: v1
kind: Service
metadata:
  annotations:
    gateway.nginx.org/internal-managed-annotation-keys: loadbalancer.nhncloud/loadbalancer-name,loadbalancer.nhncloud/member-subnet-id,loadbalancer.openstack.org/subnet-id,service.beta.kubernetes.io/openstack-internal-load-balancer
    loadbalancer.nhncloud/loadbalancer-name: NGINX-FABRIC-LB
    loadbalancer.nhncloud/member-subnet-id: xxx-xxxx-xxxx-xxxx-xxx
    loadbalancer.openstack.org/subnet-id: xxx-xxx-xxx-xxx-xx
    service.beta.kubernetes.io/openstack-internal-load-balancer: "true"
  creationTimestamp: "2025-12-19T07:27:31Z"
(omission ...)

For reference, I also tried using Gateway's infrastructure settings method, and it worked fine as well.