Skip to main content

IPv6 networking

GitGuardian self-hosted supports IPv4, IPv6, and dual-stack networking configurations for maximum flexibility in modern cloud and on-premises environments. IPv6 is available exclusively for Helm-based installations.

When to use IPv6

IPv6 support is useful when:

  • Your Kubernetes cluster is IPv6-only or dual-stack
  • You're migrating from IPv4 to IPv6
  • Cloud provider requirements (some AWS regions encourage IPv6-only)
  • Corporate security policies require IPv6

Quick start​

Helm values​

IPv6 support can activated via the Helm chart value network.ipFamily.

Your cluster setupUse network.ipFamilyNotes
IPv4-only (default)ipv4Backward compatible, no changes needed
IPv6-onlyipv6All services use IPv6 addresses only
Dual-stackdualstack or ipv6See platform-specific notes below

Platform-specific considerations​

AWS EKS​

EKS dual-stack limitation

AWS EKS does not support true dual-stack Kubernetes services. Even when your VPC is dual-stack, Kubernetes services must be either IPv4 or IPv6, not both.

Always use ipFamily: 'ipv6' on EKS, even when your VPC is dual-stack.

Your pods in a dual-stack EKS VPC can still reach both IPv4 and IPv6 external services (databases, Redis, APIs), but Kubernetes services themselves will only have IPv6 addresses.

Google GKE​

GKE fully supports dual-stack services where services receive both IPv4 and IPv6 addresses simultaneously.

Requirements:

  • GKE cluster with stack_type = "IPV4_IPV6"
  • Advanced Datapath (Dataplane V2) enabled
  • Kubernetes 1.28+

You can use any ipFamily value (ipv4, ipv6, or dualstack) based on your needs.

Azure AKS​

AKS supports dual-stack services similar to GKE. Services can have both IPv4 and IPv6 addresses.

You can use any ipFamily value based on your needs.

On-premises​

IPv6 support depends on your CNI plugin and cluster configuration:

CNI PluginIPv6 Support
Calico✅ Full support
Cilium✅ Full support
Flannel⚠️ Limited (IPv6-only, no dual-stack)
Weave Net⚠️ Experimental

We recommend testing your cluster's IPv6 capabilities before deploying in production.

Prerequisites​

Cluster requirements​

  1. Kubernetes 1.28+ (required for stable dual-stack support)

  2. IPv6-enabled cluster: Verify with:

    kubectl get nodes -o jsonpath='{.items[*].spec.podCIDRs}'

    You should see IPv6 CIDRs like 2001:db8::/64

  3. CNI plugin with IPv6 support: AWS VPC CNI, Calico, Cilium, etc.

PostgreSQL​

Your PostgreSQL must be IPv6-accessible:

Cloud providers:

  • AWS RDS: Set network_type = "DUAL"
  • Google Cloud SQL: IPv6 is automatically available
  • Azure Database for PostgreSQL: Enable IPv6 in networking settings

Self-hosted: Ensure listen_addresses includes IPv6:

# postgresql.conf
listen_addresses = '::'  # Listen on all IPv4 and IPv6 addresses

And configure pg_hba.conf for IPv6 connections:

host    all    all    2001:db8::/32    md5

Redis​

Your Redis must be IPv6-accessible:

Cloud providers:

  • AWS ElastiCache: Set network_type = "dual_stack"
  • Google Memorystore: IPv6 is automatically available for certain tiers. However, Memorystore for Redis instances is not compatible with IPv6.
  • Azure Cache for Redis: Enable IPv6 in networking settings

Self-hosted: Ensure Redis binds to IPv6:

# redis.conf
bind :: 0.0.0.0

Network connectivity​

Different IPv6 cluster configurations have different connectivity capabilities:

Cluster TypeCan reach IPv4 servicesCan reach IPv6 servicesCommon setup
Dual-stack✅ Yes✅ YesMost common, recommended
IPv6-only with NAT64/DNS64✅ Yes (via translation)✅ YesAWS EKS default
IPv6-only without NAT64❌ No✅ YesRare, not recommended
NAT64/DNS64

NAT64 and DNS64 enable IPv6-only pods to reach IPv4-only external services by translating IPv6 requests to IPv4. AWS EKS enables this by default for IPv6 clusters.

Configuration​

Helm values configuration​

Add the network.ipFamily configuration to your Helm values file:

IPv4-only (default)​

# No configuration needed - this is the default
network:
  ipFamily: 'ipv4'

IPv6-only​

network:
  ipFamily: 'ipv6'

# PostgreSQL and Redis must be IPv6-accessible
postgresql:
  host: '2001:db8::1234'  # IPv6 address or hostname with AAAA record
redis:
  main:
    host: '2001:db8::5678'

You must also configure Loki for IPv6. See Loki IPv6 configuration below.

Dual-stack (GKE/AKS)​

network:
  ipFamily: 'dualstack'

postgresql:
  host: 'postgres.example.com'  # Must have A or AAAA DNS record
redis:
  main:
    host: 'redis.example.com'

Loki IPv6 configuration is optional for dual-stack (components can use IPv4).

Loki IPv6 configuration​

Loki requires explicit IPv6 configuration in IPv6-only clusters because it uses memberlist for service discovery between components. Add this to your Helm values:

loki:
  loki:
    commonConfig:
      ring:
        instance_enable_ipv6: true
        kvstore:
          store: "memberlist"
    compactor:
      compactor_ring:
        instance_enable_ipv6: true
    distributor:
      ring:
        instance_enable_ipv6: true
    extraMemberlistConfig:
      bind_addr:
        - '::'
    frontend:
      instance_enable_ipv6: true
    index_gateway:
      ring:
        instance_enable_ipv6: true
    ingester:
      lifecycler:
        enable_inet6: true
    pattern_ingester:
      enabled: true
      lifecycler:
        enable_inet6: true
    query_scheduler:
      scheduler_ring:
        instance_enable_ipv6: true
    ruler:
      ring:
        instance_enable_ipv6: true
RequirementNotes
IPv6-onlyRequired - components cannot communicate without it
Dual-stackOptional - components can fall back to IPv4

Deployment​

Preflights

When your external databases are IPv6-ready, test connectivity using our preflights.

Upgrading existing IPv4 deployment​

To dual-stack (GKE/AKS - zero downtime)​

Dual-stack upgrades are seamless because existing IPv4 services continue working while IPv6 is added:

# values-ipv6.yaml
network:
  ipFamily: 'dualstack'
helm upgrade gitguardian gitguardian/gitguardian \
  --namespace gitguardian \
  -f values.yaml \
  -f values-ipv6.yaml

To IPv6-only (requires planning)​

Downtime required

Migrating to IPv6-only requires service disruption as IP addresses change.

  1. Backup your data
  2. Migrate PostgreSQL and Redis to IPv6
  3. Update Helm values: 
    network:
      ipFamily: 'ipv6'

    postgresql:
      host: '2001:db8::1234'  # New IPv6 address

    redis:
      main:
        host: '2001:db8::5678'  # New IPv6 address
  4. Deploy: 
    helm upgrade gitguardian gitguardian/gitguardian \
      --namespace gitguardian \
      -f values.yaml \
      -f values-ipv6.yaml
  5. Update DNS records to AAAA records
  6. Test connectivity

Validation​

After deployment, verify IPv6 is working:

Check service IP addresses​

kubectl get svc -n gitguardian -o wide

Services should show IPv6 addresses (e.g., 2001:db8:1234:5678::a) or both IPv4 and IPv6 for dual-stack.

Test connectivity​

# Get service IP and test health endpoint
SERVICE_IP=$(kubectl get svc internal-api -n gitguardian -o jsonpath='{.spec.clusterIP}')
kubectl run test-ipv6 --rm -it --image=curlimages/curl -- \
  curl -v "http://[$SERVICE_IP]:5050/api/v1/health"

Check application logs​

kubectl logs -n gitguardian deployment/webapp-internal-api --tail=50

Look for Gunicorn binding to [::] and no connection errors to PostgreSQL/Redis.

Troubleshooting​

Services not getting IPv6 addresses​

Symptoms: Services show <none> or only IPv4 addresses

Checklist:

  1. Verify cluster has IPv6 service CIDR: kubectl cluster-info dump | grep -i service-cluster-ip-range
  2. Check network.ipFamily is set correctly in Helm values
  3. For EKS, verify cluster was created with ip_family = "ipv6"

PostgreSQL connection failures​

Symptoms: could not translate host name to address

Checklist:

  1. Test connectivity: kubectl run test-pg --rm -it --image=postgres:16 -- psql -h 2001:db8::1234 -U gitguardian
  2. Verify DNS returns AAAA records (if using hostname)
  3. Check PostgreSQL listen_addresses includes ::
  4. Verify pg_hba.conf allows your IPv6 subnet

Redis connection failures​

Symptoms: ConnectionError: Error connecting to Redis

Checklist:

  1. Test connectivity: kubectl run test-redis --rm -it --image=redis:7 -- redis-cli -h 2001:db8::5678 PING
  2. Check Redis bind config includes ::
  3. Use correct URL format: redis://[2001:db8::5678]:6379 (brackets required for IPv6)

Nginx fails to start​

Symptoms: bind() to [::]:80 failed (99: Cannot assign requested address)

Solution: Your cluster doesn't support IPv6. Verify CNI plugin supports IPv6 or use network.ipFamily: 'ipv4'.

Application crashes with port parsing error​

Symptoms: '' is not a valid port number

Solution: Don't set both redis.main.url and redis.main.host. Use one or the other:

  • URL format: redis.main.url: 'redis://[2001:db8::5678]:6379'
  • Or host/port: redis.main.host: '2001:db8::5678' with redis.main.port: 6379

Loki fails to start or components can't communicate​

Symptoms: failed to join memberlist, no healthy instances in ring, or too many unhealthy instances in the ring

Solution: Ensure the complete Loki IPv6 configuration is applied. The most commonly missed setting is extraMemberlistConfig.bind_addr: ['::'].

After fixing configuration, restart Loki:

kubectl rollout restart deployment/loki-backend -n gitguardian
kubectl rollout restart statefulset/loki-write -n gitguardian
kubectl rollout restart statefulset/loki-read -n gitguardian

Ingress and load balancers​

AWS Application Load Balancer (ALB)​

ingress:
  controller: aws_alb
  annotations:
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/ip-address-type: dualstack
    alb.ingress.kubernetes.io/target-type: ip

Nginx Ingress Controller​

controller:
  service:
    ipFamilyPolicy: PreferDualStack
    ipFamilies: [IPv4, IPv6]

Istio Gateway​

kubectl patch svc istio-ingressgateway -n istio-system \
  -p '{"spec":{"ipFamilyPolicy":"PreferDualStack","ipFamilies":["IPv4","IPv6"]}}'

Performance considerations​

IPv6 has comparable performance to IPv4 with negligible latency difference. In IPv6-only clusters with NAT64/DNS64, expect ~5-10ms translation overhead when accessing IPv4-only external services.

Security considerations​

  • Firewall rules: Add ip6tables rules alongside your iptables rules
  • Network policies: Include IPv6 CIDRs in your Kubernetes NetworkPolicy ipBlock rules
  • TLS/SSL: Works identically to IPv4 (same certificates, protocols, and cipher suites)

Backward compatibility​

All IPv6 changes are 100% backward compatible. Existing IPv4 deployments continue working without changes—no Helm value changes or application code changes required unless you're enabling IPv6.

Cost optimization​

PlatformPotential savings
AWS EKS$40-100/month (no NAT Gateway or public IPv4 costs)
GCP GKEMinimal impact (IPv6 addresses are free)

Additional resources​

Support​

When reporting IPv6-related issues, please provide:

# Kubernetes version
kubectl version --short

# Cluster IP families
kubectl cluster-info dump | grep -i service-cluster-ip-range

# CNI plugin
kubectl get pods -n kube-system | grep -i cni

# Service configuration
kubectl get svc internal-api -n gitguardian -o yaml

# Pod logs
kubectl logs deployment/webapp-internal-api -n gitguardian --tail=100

# Helm values (redact sensitive information)
helm get values gitguardian -n gitguardian
Last updated on

Something we didn’t cover?

See our Roadmap
Subscribe on GitHub
Submit a request
API status