helm upgrade --install kong-operator kong/kong-operator -n kong-system \
--create-namespace \
--set image.tag=2.2 \
--set env.ENABLE_CONTROLLER_KONNECT=trueSet the Host header sent to a Service
Uses:
Kong Operator
Deployment Platform
Related Documentation
Related Resources
Minimum Version
Kong Operator - 2.2
TL;DR
Annotate the Kubernetes Service with konghq.com/host-header: "your-hostname". Kong Gateway will use this value as the Host header when forwarding requests upstream instead of the Pod IP address.
Prerequisites
Kong Konnect
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
- The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
-
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
Kong Operator running
-
Add the Kong Helm charts:
helm repo add kong https://charts.konghq.com helm repo update -
Install Kong Operator using Helm:
helm upgrade --install kong-operator kong/kong-operator -n kong-system \ --create-namespace \ --set image.tag=2.2If you want cert-manager to issue and rotate the admission and conversion webhook certificates, install cert-manager to your cluster and enable cert-manager integration by passing the following argument while installing, in the next step:
--set global.webhooks.options.certManager.enabled=trueIf you do not enable this, the chart will generate and inject self-signed certificates automatically. We recommend enabling cert-manager to manage the lifecycle of these certificates. Kong Operator needs a certificate authority to sign the certificate for mTLS communication between the control plane and the data plane. This is handled automatically by the Helm chart. If you need to provide a custom CA certificate, refer to the
certificateAuthoritysection in thevalues.yamlof the Helm chart to learn how to create and reference your own CA certificate.
This tutorial doesn’t require a license, but you can add one using KongLicense. This assumes that your license is available in ./license.json.
echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongLicense
metadata:
name: kong-license
rawLicenseString: '$(cat ./license.json)'
" | kubectl apply -f -Create a KonnectAPIAuthConfiguration resource
kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -
echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
name: konnect-api-auth
namespace: kong
spec:
type: token
token: "'$KONNECT_TOKEN'"
serverURL: us.api.konghq.com
' | kubectl apply -f -Create a KonnectGatewayControlPlane resource
echo '
kind: KonnectGatewayControlPlane
apiVersion: konnect.konghq.com/v1alpha2
metadata:
name: gateway-control-plane
namespace: kong
spec:
createControlPlaneRequest:
name: gateway-control-plane
konnect:
authRef:
name: konnect-api-auth
' | kubectl apply -f -Create Gateway resources
Create the kong namespace:
kubectl create namespace kongCreate the GatewayConfiguration, GatewayClass, and Gateway resources with basic configuration:
echo '
apiVersion: gateway-operator.konghq.com/v2beta1
kind: GatewayConfiguration
metadata:
name: gateway-configuration
namespace: kong
spec:
dataPlaneOptions:
deployment:
podTemplateSpec:
spec:
containers:
- image: kong/kong-gateway:3.14
name: proxy
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: gateway-class
spec:
controllerName: konghq.com/gateway-operator
parametersRef:
group: gateway-operator.konghq.com
kind: GatewayConfiguration
name: gateway-configuration
namespace: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: kong
namespace: kong
spec:
gatewayClassName: gateway-class
listeners:
- name: http
port: 80
protocol: HTTP' | kubectl apply -f -Create a Service and a Route
-
Run the following command to create a sample httpbin Service:
kubectl apply -f https://developer.konghq.com/manifests/kic/httpbin-service.yaml -n kong -
Create an
HTTPRouteresource:echo ' apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: httpbin-route namespace: kong annotations: konghq.com/strip-path: "true" konghq.com/preserve-host: "false" spec: parentRefs: - name: kong rules: - matches: - path: type: PathPrefix value: /httpbin backendRefs: - name: httpbin kind: Service port: 80' | kubectl apply -f -
By default, Kong Gateway sets the Host header to the IP address of the individual Pod it forwards the request to. Some upstream services perform host-based virtual hosting or access control and require a specific Host header value. You can override this behavior using the konghq.com/host-header annotation.
Check the default behavior
-
Get the Gateway’s external IP address:
export PROXY_IP=$(kubectl get gateway kong -n kong -o jsonpath='{.status.addresses[0].value}') -
Send a request to the
/headersendpoint, which returns all request headers received by the upstream service:curl -s $PROXY_IP/httpbin/headersThe response shows the headers the upstream received. The
Hostheader will contain the Pod IP address assigned by Kong Gateway:{ "headers": { "Host": "10.0.0.5", ... } }
Annotate the Service
Annotate the httpbin Service to set a custom Host header:
kubectl annotate service httpbin -n kong \
konghq.com/host-header="internal.example.com"Validate
Send the same request again:
curl -s $PROXY_IP/httpbin/headersThe Host header in the upstream request now reflects the configured value:
{
"headers": {
"Host": "internal.example.com",
...
}
}Note: If the client-side
Hostheader must be preserved instead, use thekonghq.com/preserve-host: "true"annotation on theHTTPRouteorIngressresource. Whenpreserve-hostis set totrue, it takes precedence overkonghq.com/host-header.