feat: add IPv6/dual-stack support for agent bind host and UI probes

[go-faustino]

Summary

On IPv6-first Kubernetes clusters (e.g., EKS with IPv6 pod networking), kagent deployments fail health checks because:

1. Agent pods bind to 0.0.0.0 (IPv4 only), so probes sent to the pod's IPv6 address get connection refused
2. UI nginx only has listen 8080 (IPv4), so it is unreachable on its IPv6 pod address
3. UI probes use hardcoded httpGet which kubelet sends to the pod IP — on IPv6-first clusters this fails
4. A2A server constructs listen addresses via host + ":" + port, producing invalid addresses for IPv6 literals (e.g., :::8080 instead of [::]:8080)

Changes

1. Fix A2A server address construction (go/adk/pkg/a2a/server/server.go):

• Replace config.Host + ":" + config.Port with net.JoinHostPort(config.Host, config.Port)
• This properly brackets IPv6 literals (e.g., [::]:8080), which is required for net.Listen to parse the address correctly
• Without this fix, setting --host :: on agent pods would produce :::8080 and fail to start

2. Configurable agent bind host (controller.agentDeployment.host):

• New Helm value flows through the controller ConfigMap (DEFAULT_AGENT_BIND_HOST) → CLI flag (--default-agent-bind-host) → resolveInlineDeployment()
• Defaults to "0.0.0.0" — fully backward compatible
• Set to "::" for dual-stack (IPv4 + IPv6) support on agent deployments managed by the controller

3. Overridable nginx config (ui.nginxConfig):

• When set, a ConfigMap is created and mounted over /etc/nginx/nginx.conf
• Allows adding listen [::]:8080; for dual-stack without modifying the container image
• Empty by default — the baked-in nginx.conf is used, so IPv4-only clusters are unaffected

4. Configurable UI probes (ui.startupProbe / ui.readinessProbe):

• When empty (default), existing httpGet probes are rendered — no change for existing users
• IPv6 clusters can override with exec-based probes if needed

Design note: why ui.nginxConfig instead of modifying ui/conf/nginx.conf directly

The most obvious fix for the UI's IPv6 issue would be to add listen [::]:8080; directly to the baked-in nginx.conf. However, this would break clusters where IPv6 is disabled at the kernel level (ipv6.disable=1 boot param or net.ipv6.conf.all.disable_ipv6=1 sysctl). In those environments, nginx would fail to start with:

bind() to [::]:8080 failed (97: Address family not supported by protocol)

Since we can't know at image build time whether the target cluster supports IPv6, the safe approach is to keep the default nginx.conf IPv4-only and let users opt in to dual-stack via ui.nginxConfig.

That said, if the project considers IPv6-disabled kernels out of scope (they're increasingly rare in modern Kubernetes), adding listen [::]:8080; directly to the default config would be simpler. Happy to adjust based on project preference.

Files changed

File	Change
go/adk/pkg/a2a/server/server.go	Use net.JoinHostPort for proper IPv6 address formatting
go/core/internal/controller/translator/agent/adk_api_translator.go	Add DefaultAgentBindHost variable
go/core/internal/controller/translator/agent/deployments.go	Use DefaultAgentBindHost instead of hardcoded "0.0.0.0"
go/core/pkg/app/app.go	Register --default-agent-bind-host CLI flag
helm/kagent/templates/controller-configmap.yaml	Conditionally emit DEFAULT_AGENT_BIND_HOST
helm/kagent/templates/ui-deployment.yaml	Make probes overridable; mount nginx ConfigMap when provided
helm/kagent/templates/ui-nginx-configmap.yaml	New: ConfigMap for custom nginx.conf
helm/kagent/values.yaml	Add controller.agentDeployment.host, ui.startupProbe, ui.readinessProbe, ui.nginxConfig
helm/kagent/tests/controller-deployment_test.yaml	Tests for bind host ConfigMap rendering
helm/kagent/tests/ui-deployment_test.yaml	Tests for default/custom probes and nginx config mount

Testing

• Go unit tests pass (go test ./internal/controller/translator/agent/..., go test ./pkg/app/...)
• go build ./... passes for both go/core and go/adk
• Helm unit tests added for all features
• Verified in production on IPv6-first EKS clusters

Usage example

# values.yaml for IPv6-first clusters
controller:
  agentDeployment:
    host: "::"  # dual-stack binding for agent pods

ui:
  # Override nginx config for dual-stack listening
  nginxConfig: |
    pid /tmp/nginx.pid;
    error_log /dev/stderr;
    events { worker_connections 1024; }
    http {
      client_body_temp_path /tmp/nginx/client_temp;
      proxy_temp_path /tmp/nginx/proxy_temp;
      fastcgi_temp_path /tmp/nginx/fastcgi_temp;
      uwsgi_temp_path /tmp/nginx/uwsgi_temp;
      scgi_temp_path /tmp/nginx/scgi_temp;
      access_log /dev/stdout;
      upstream kagent_ui { server 127.0.0.1:8001; }
      upstream kagent_ws_backend { server 127.0.0.1:8081; }
      upstream kagent_backend { server 127.0.0.1:8083; }
      map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
      }
      server {
        listen 8080;
        listen [::]:8080;
        server_name localhost;
        location /a2a/ { proxy_pass http://kagent_ui/a2a/; proxy_http_version 1.1; proxy_read_timeout 600s; }
        location / { proxy_pass http://kagent_ui; proxy_http_version 1.1; }
        location /health { return 200 'OK'; }
        location /api/ { proxy_pass http://kagent_backend/api/; proxy_http_version 1.1; }
        location /api/ws/ { proxy_pass http://kagent_ws_backend/api/ws/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_read_timeout 300s; }
      }
    }
  # Optional: override probes if exec-based probes are needed
  startupProbe:
    exec:
      command: ["curl", "-sf", "http://[::1]:8080/health"]
    initialDelaySeconds: 5
    periodSeconds: 3
    failureThreshold: 30
  readinessProbe:
    exec:
      command: ["curl", "-sf", "http://[::1]:8080/health"]
    periodSeconds: 10

Fixes #1642

[Copilot]

Pull request overview

This PR adds Helm- and controller-level configurability to support IPv6-first / dual-stack Kubernetes clusters by making the agent bind host and UI probes customizable.

Changes:

• Introduces controller.agentDeployment.host Helm value that flows through controller ConfigMap/env → controller flag --default-agent-bind-host → agent deployment args.
• Adds ui.startupProbe / ui.readinessProbe Helm values to allow overriding the UI container probes (while keeping current httpGet probes as the default).
• Adds Helm unit tests validating ConfigMap rendering and default/overridden probe behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
go/core/internal/controller/translator/agent/adk_api_translator.go	Adds global DefaultAgentBindHost defaulting to 0.0.0.0.
go/core/internal/controller/translator/agent/deployments.go	Uses DefaultAgentBindHost instead of hardcoded "0.0.0.0" for --host.
go/core/pkg/app/app.go	Registers --default-agent-bind-host so env/ConfigMap can override it.
helm/kagent/templates/controller-configmap.yaml	Conditionally emits DEFAULT_AGENT_BIND_HOST when Helm value is non-empty.
helm/kagent/templates/ui-deployment.yaml	Renders overridable startup/readiness probes with defaults preserved.
helm/kagent/values.yaml	Documents/adds new Helm values for agent bind host and UI probe overrides.
helm/kagent/tests/controller-deployment_test.yaml	Tests ConfigMap emission behavior for DEFAULT_AGENT_BIND_HOST.
helm/kagent/tests/ui-deployment_test.yaml	Tests default httpGet probes and custom exec probe overrides.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[TOMOFUMI-KONDO]

@go-faustino
As I was assigned the issue, I have reviewed the PR overall.
I noted several things below:

1. Is overriding probes necessary?

When the ui pod has an ipv6 primary address, the httpGet probe targets that ipv6 address, so the existing probes seem to work.

I don't think it's a bad idea to allow customisation of probe settings. However, rather than intending them specifically for the ipv6 pod, it feels that it's for general flexibility.

2. supervisord.conf has the hard-coded HOSTNAME="0.0.0.0. Does it need to be fixed?

[go-faustino]

@TOMOFUMI-KONDO — thanks for taking the time to review this, really appreciate it. Both great points.

1. Probe overrides

You're absolutely right — once nginx is properly listening on IPv6 (via the ui.nginxConfig override or a future direct fix to nginx.conf), the default httpGet probes should work fine since kubelet will hit the pod IP and nginx will respond on either stack. The probe overrides aren't really an IPv6-specific fix.

I've updated the framing accordingly: they're there for general flexibility (e.g., custom health check paths, different thresholds, exec-based probes for edge cases), not specifically for IPv6. It's a small, non-invasive addition, so I'd lean toward keeping it — but happy to drop it if you think it adds unnecessary surface area.

2. supervisord.conf HOSTNAME="0.0.0.0"

Nice catch! You're right that it's hardcoded to IPv4. That said, looking at the architecture, it shouldn't actually cause IPv6 issues in practice:

• The Next.js server (port 8001) is only accessed via nginx's proxy_pass http://127.0.0.1:8001
• Kubelet/ALB probes hit nginx on port 8080, never Node.js directly
• Since the loopback interface always has both IPv4 and IPv6 on Linux, the 127.0.0.1:8001 proxy connection works regardless of the pod's external address family

So it's not strictly needed for IPv6 support, but it's cleaner to fix for consistency. I'll make HOSTNAME configurable via an environment variable so it can be overridden without modifying the image — same pattern as the nginx config.

I'll push the updates shortly.

Also — I want to acknowledge that you were already assigned to #1642 and had offered to work on it. I jumped ahead because of some urgency on our side, but I genuinely appreciate your review and input. If you'd like to be included as a co-author on the final commit, I'd be happy to add you — just let me know. And of course, feel free to take any of these changes in a different direction if you prefer.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[TOMOFUMI-KONDO]

@go-faustino
Thank you for responding to the review.

1. Probe overrides

I just wanted to confirm the necessity of changing the probes. As you said, it's a small and non-invasive addition, so I think it's fine to keep it.

2. supervisord.conf HOSTNAME="0.0.0.0"

Thank you for the update to make it configurable. It would be better to be able to override the supervisord.conf and its HOSTNAME for an ipv6-only environment.

It's no problem that you worked on the issue. I'm glad to see such a great PR.
However, I have no authority to approve the PR. I would like the maintainers to review it too.

[EItanya]

Hey there, thanks so much for this awesome change, going to take a look today :)

[EItanya]

Just out of curiosity, why did you add full overwrites of the config files, rather than just fix the individual binds in them with template variables?

[go-faustino]

Just out of curiosity, why did you add full overwrites of the config files, rather than just fix the individual binds in them with template variables?

@EItanya Thanks for your review!

You can see the rationale for the overwrites on the design note on the PR body. Basically, it aims to be fully backwards compatible with clusters that have IPv6 disabled at the kernel level. But, as mentioned in the note, we can simplify this if it is not considered an issue. Let me know how you'd prefer the implementation to look like.

EDIT: Re-reading your question, I think I misunderstood — you're not asking why opt-in vs baked-in, but rather why a full config blob override instead of targeted Helm values.

If that's the case: we could replace ui.nginxConfig / ui.supervisordConfig (which take the entire file as a string) with small, focused values like:

ui:
  nginx:
    ipv6Enabled: false     # when true, adds `listen [::]:8080;` to the default config
  supervisord:
    hostname: "0.0.0.0"   # set to "::" for dual-stack

The nginx.conf and supervisord.conf would become Helm-templated ConfigMaps (always rendered, always mounted), with just the bind-related lines conditionally injected. No full-file override needed.

This would be much cleaner for the IPv6 use case — users just flip ui.nginx.ipv6Enabled: true instead of copy-pasting an entire nginx.conf. The trade-off is less flexibility for unrelated customizations, but that could be a separate feature if needed.

Is that more along the lines of what you had in mind?

[EItanya]

Just out of curiosity, why did you add full overwrites of the config files, rather than just fix the individual binds in them with template variables?

@EItanya Thanks for your review!

You can see the rationale for the overwrites on the design note on the PR body. Basically, it aims to be fully backwards compatible with clusters that have IPv6 disabled at the kernel level. But, as mentioned in the note, we can simplify this if it is not considered an issue. Let me know how you'd prefer the implementation to look like.

EDIT: Re-reading your question, I think I misunderstood — you're not asking why opt-in vs baked-in, but rather why a full config blob override instead of targeted Helm values.

If that's the case: we could replace ui.nginxConfig / ui.supervisordConfig (which take the entire file as a string) with small, focused values like:

ui:
  nginx:
    ipv6Enabled: false     # when true, adds `listen [::]:8080;` to the default config
  supervisord:
    hostname: "0.0.0.0"   # set to "::" for dual-stack

The nginx.conf and supervisord.conf would become Helm-templated ConfigMaps (always rendered, always mounted), with just the bind-related lines conditionally injected. No full-file override needed.

This would be much cleaner for the IPv6 use case — users just flip ui.nginx.ipv6Enabled: true instead of copy-pasting an entire nginx.conf. The trade-off is less flexibility for unrelated customizations, but that could be a separate feature if needed.

Is that more along the lines of what you had in mind?

Yes that's much more along the lines of what I was thinking. I was even thinking about a top-level ipv6 enabled flag

[go-faustino]

@EItanya Refactored as discussed — pushed a new commit that replaces the full config overrides with targeted Helm templating behind a single top-level flag:

ipv6:
  enabled: true

When enabled, this controls all three IPv6 touch points:

• nginx: adds listen [::]:8080; to the templated config
• supervisord: sets HOSTNAME="::" for the Next.js server
• controller: sets DEFAULT_AGENT_BIND_HOST="::" for agent pods

The nginx.conf and supervisord.conf are now always-rendered Helm-templated ConfigMaps (always mounted), with only the bind-related lines conditionally injected. No more full-file blob overrides.

Explicit controller.agentDeployment.host still takes precedence over the flag for cases where someone wants a custom bind address.

All 155 helm unit tests pass, including new tests for the flag behavior.

[EItanya]

@EItanya Refactored as discussed — pushed a new commit that replaces the full config overrides with targeted Helm templating behind a single top-level flag:

ipv6:
  enabled: true

When enabled, this controls all three IPv6 touch points:

• nginx: adds listen [::]:8080; to the templated config
• supervisord: sets HOSTNAME="::" for the Next.js server
• controller: sets DEFAULT_AGENT_BIND_HOST="::" for agent pods

The nginx.conf and supervisord.conf are now always-rendered Helm-templated ConfigMaps (always mounted), with only the bind-related lines conditionally injected. No more full-file blob overrides.

Explicit controller.agentDeployment.host still takes precedence over the flag for cases where someone wants a custom bind address.

All 155 helm unit tests pass, including new tests for the flag behavior.

Awesome, can you move the original nginx.conf and supervisord.conf into helm/template/files and use those rather than redefining. I also find files easier to deal with than inlined configmap values

[go-faustino]

@EItanya Done — moved the config content into helm/kagent/files/nginx.conf and helm/kagent/files/supervisord.conf, and the ConfigMap templates now load them via tpl(.Files.Get ...). The IPv6 conditionals still work through Helm templating inside the files.

Much cleaner to read and maintain this way, agreed.

[EItanya]

Can you please delete the old .conf files, and address the one nit, then we'll be good to go!

[EItanya]

Can you combine the 2 configmaps, I don't think we need 2

[go-faustino]

Done — merged both into a single ui-config ConfigMap with nginx.conf and supervisord.conf as data keys. The deployment now references one volume source with two subPath mounts.

[go-faustino]

@EItanya Both addressed — pushed two commits:

1. Merge ConfigMaps (449ebe88): Combined the nginx and supervisord ConfigMaps into a single ui-config ConfigMap.
2. Delete old .conf files (43c2d8ae): Removed ui/conf/nginx.conf, ui/conf/supervisord.conf, and the COPY lines from the Dockerfile. This commit is separate so it can be dropped if you'd rather keep the baked-in defaults — without them, the container image requires the configs to be mounted externally (which the Helm chart always does, but standalone docker run would need them provided via volume mounts).

All 158 helm unit tests pass.