TL;DR

In Flagger's Canary resources, the hosts field can be safely omitted without affecting functionality.

Even when integrating with the Gateway API, you can simply configure gatewayRefs without specifying the hosts field, and HTTPRoutes will be generated correctly, allowing canary releases to function properly.

Background and Purpose

When using Flagger for canary releases with Gateway API integration, you typically specify the hosts field as follows:

spec:
  service:
    port: 9898
    targetPort: 9898
    hosts:
      - podinfo.example.com
    gatewayRefs:
      - name: gateway-name
        namespace: gateway-namespace

However, it wasn't clear whether the hosts field is mandatory or what happens when it's omitted. This article investigates the behavior when the hosts field is omitted.

Environment

The following environment was used for testing:

  • Kubernetes: Kind cluster
  • Gateway API: Envoy Gateway
  • Flagger: Latest version

Testing Procedure

The following steps can be reproduced using kubectl commands.

1. Create a Gateway Resource

First, create a basic Gateway resource:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
kubectl apply -f gateway.yaml

2. Create the Initial Deployment

Deploy a test application (podinfo):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: podinfo
  labels:
    app: podinfo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: podinfo
  template:
    metadata:
      labels:
        app: podinfo
    spec:
      containers:
      - name: podinfo
        image: stefanprodan/podinfo:6.0.0
        imagePullPolicy: IfNotPresent
        ports:
        - name: http
          containerPort: 9898
          protocol: TCP
        resources:
          limits:
            cpu: 500m
            memory: 256Mi
          requests:
            cpu: 100m
            memory: 64Mi
        livenessProbe:
          httpGet:
            path: /healthz
            port: 9898
          initialDelaySeconds: 5
          timeoutSeconds: 5
        readinessProbe:
          httpGet:
            path: /readyz
            port: 9898
          initialDelaySeconds: 5
          timeoutSeconds: 5
kubectl apply -f deployment.yaml

3. Create a Canary Resource Without the hosts Field

This is the core of our test. Create a Canary resource without the hosts field:

apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
  name: podinfo
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: podinfo
  progressDeadlineSeconds: 60
  service:
    port: 9898
    targetPort: 9898
    # hosts field is omitted
    gatewayRefs:
      - name: eg
        namespace: default  # Change to match your actual namespace
  analysis:
    interval: 1s
    threshold: 5
    maxWeight: 50
    stepWeight: 10
kubectl apply -f canary.yaml

4. Check the Canary Resource Status

Verify that the Canary resource has been initialized correctly:

kubectl get canary podinfo

Example output:

NAME      STATUS        WEIGHT   LASTTRANSITIONTIME
podinfo   Initialized   0        2025-04-15T07:05:52Z

Also, check that the HTTPRoute has been generated correctly:

kubectl get httproute podinfo

Example output:

NAME      HOSTNAMES   AGE
podinfo               2m

Note that the HOSTNAMES field is empty, indicating that no specific hostnames are set because we omitted the hosts field.

5. Verify HTTP Requests

Identify the service created by Envoy Gateway and send a request to it:

# Get the service name
SERVICE_NAME=$(kubectl get service -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-namespace=default -o jsonpath='{.items[0].metadata.name}')
echo "Service name: ${SERVICE_NAME}"

# Send an HTTP request using curl
kubectl run curl-test --image=curlimages/curl --restart=Never -i --rm -- \
  curl -v http://${SERVICE_NAME}.envoy-gateway-system.svc.cluster.local

Example output (excerpt):

Service name: envoy-default-eg-xxxxxxxx
{
  "hostname": "podinfo-primary-xxxxxxxxxx-xxxxx",
  "version": "6.0.0",
  "message": "greetings from podinfo v6.0.0",
  ...
}

This confirms that we can access the application through the Gateway even without specifying the hosts field.

6. Update the Version

Next, update the Deployment to deploy a new version:

kubectl patch deployment podinfo -p '{"spec":{"template":{"spec":{"containers":[{"name":"podinfo","image":"stefanprodan/podinfo:6.1.0"}]}}}}'

7. Monitor the Canary Release Progress

Check that Flagger is progressing with the canary release:

kubectl get canary podinfo -w

Example output:

NAME      STATUS      WEIGHT   LASTTRANSITIONTIME
podinfo   Progressing 0        2025-04-15T07:06:10Z
podinfo   Progressing 10       2025-04-15T07:06:20Z
podinfo   Progressing 20       2025-04-15T07:06:30Z
...
podinfo   Promoting   50       2025-04-15T07:07:00Z
...
podinfo   Succeeded   0        2025-04-15T07:07:20Z

8. Verify HTTP Requests After Update

Finally, confirm that we can access the updated version:

# Get the service name
SERVICE_NAME=$(kubectl get service -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-namespace=default -o jsonpath='{.items[0].metadata.name}')

# Send an HTTP request using curl
kubectl run curl-test-after-update --image=curlimages/curl --restart=Never -i --rm -- \
  curl -v http://${SERVICE_NAME}.envoy-gateway-system.svc.cluster.local

Example output (excerpt):

{
  "hostname": "podinfo-primary-xxxxxxxxxx-xxxxx",
  "version": "6.1.0",
  "message": "greetings from podinfo v6.1.0",
  ...
}

Test Results

Our testing confirmed the following:

  1. Creating a Canary resource without the hosts field was successful
  2. The HTTPRoute was generated correctly and reached the Accepted status
  3. We could access the application through the Gateway
  4. After updating the Deployment, the canary release progressed normally and eventually completed promotion
  5. We could access the new version (v6.1.0) after the update

This confirms that the hosts field in Flagger's Canary resources is not mandatory and can be omitted without affecting functionality.

Conclusion

When integrating Flagger with the Gateway API, the hosts field is optional. If you don't need routing based on specific hostnames, you can simply specify gatewayRefs to achieve canary releases with a simpler configuration.

References