Skip to content
CTRL K
    Docs Standalone Kubernetes Tutorials Standalone Kubernetes Models Blog Enterprise Community Get Started GitHub

    HTTPS

    Create an HTTPS listener on your agentgateway proxy so that your proxy listens for secured HTTPS traffic.

    Before you begin

    1. Deploy the httpbin sample app.

    2. Make sure that you have the OpenSSL version of openssl, not LibreSSL. The openssl version must be at least 1.1.

      1. Check the openssl version that is installed. If you see LibreSSL in the output, continue to the next step.

        openssl version

      2. Install the OpenSSL version (not LibreSSL). For example, you might use Homebrew.

        brew install openssl

      3. Review the output of the OpenSSL installation for the path of the binary file. You can choose to export the binary to your path, or call the entire path whenever the following steps use an openssl command.

        • For example, openssl might be installed along the following path: /usr/local/opt/openssl@3/bin/
        • To run commands, you can append the path so that your terminal uses this installed version of OpenSSL, and not the default LibreSSL. /usr/local/opt/openssl@3/bin/openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650...

    3. Decide whether to set up a listener inline on the Gateway resource or as a separate ListenerSet resource. For more information, see the Listener overview.

    Create a TLS certificate

    1. Create a directory to store your TLS credentials in.

      mkdir example_certs

    2. Create a self-signed root certificate. The following command creates a root certificate that is valid for a year and can serve any hostname. You use this certificate to sign the server certificate for the gateway later. For other command options, see the OpenSSL docs.

      # root cert
openssl req -x509 -sha256 \
-nodes -days 365 \
-newkey rsa:2048 \
-subj '/O=any domain/CN=*' \
-keyout example_certs/root.key \
-out example_certs/root.crt

    3. Create an OpenSSL configuration that matches the HTTPS hostname you plan to use. This example assumes that you want to use example.com as your domain. To use a different one, replace every example.com reference with the base domain that you want your listener to serve.

      cat <<'EOF' > example_certs/gateway.cnf
[ req ]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
req_extensions = req_ext
[ dn ]
CN = *.example.com
O = any domain
[ req_ext ]
subjectAltName = @alt_names
[ alt_names ]
DNS.1 = *.example.com
DNS.2 = example.com
EOF

    4. Use the configuration and root certificate to create and sign the gateway certificate.

      openssl req -new -nodes -keyout example_certs/gateway.key -out example_certs/gateway.csr -config example_certs/gateway.cnf
openssl x509 -req -sha256 -days 365 \
  -CA example_certs/root.crt -CAkey example_certs/root.key -set_serial 0 \
  -in example_certs/gateway.csr -out example_certs/gateway.crt \
  -extfile example_certs/gateway.cnf -extensions req_ext

    5. Create a Kubernetes secret to store your server TLS certificate. You create the secret in the same cluster and namespace that the gateway will be deployed to.

      kubectl create secret tls -n agentgateway-system https \
  --key example_certs/gateway.key \
  --cert example_certs/gateway.crt
kubectl label secret https example=httpbin-https --namespace agentgateway-system

    Set up an HTTPS listener

    Set up an HTTPS listener on your Gateway.

    1. Create a Gateway resource with an HTTPS listener. The following Gateway listener terminates incoming TLS traffic on port 443 by using the TLS certificates that you created earlier.

      kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: https
  namespace: agentgateway-system
  labels:
    example: httpbin-https
spec:
  gatewayClassName: agentgateway
  listeners:
  - protocol: HTTPS
    port: 8443
    name: https
    tls:
      mode: Terminate
      certificateRefs:
        - name: https
          kind: Secret
    allowedRoutes:
      namespaces:
        from: All
EOF

      Review the following table to understand this configuration.

      SettingDescription
      spec.gatewayClassNameThe name of the Kubernetes GatewayClass that you want to use to configure the Gateway. When you set up agentgateway, a default GatewayClass is set up for you.
      spec.listenersConfigure the listeners for this Gateway. The Gateway can serve HTTPS routes from any namespace.
      spec.listeners.tls.modeThe TLS mode that you want to use for incoming requests. In this example, HTTPS requests are terminated at the Gateway and the unencrypted request is forwarded to the service in the cluster.
      spec.listeners.tls.certificateRefsThe Kubernetes secret that holds the TLS certificate and key for the Gateway. The Gateway uses these credentials to establish the TLS connection with a client, and to decrypt incoming HTTPS requests.

    2. Check the status of the Gateway to make sure that your configuration is accepted. Note that in the output, a NoConflicts status of False indicates that the Gateway is accepted and does not conflict with other Gateway configuration.

      kubectl get gateway https -n agentgateway-system -o yaml

    3. Create an HTTPRoute resource for the httpbin app that is served by the Gateway or ListenerSet that you created.

      kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-https
  namespace: httpbin
  labels:
    example: httpbin-https
spec:
  hostnames:
    - https.example.com
  parentRefs:
    - name: https
      namespace: agentgateway-system
  rules:
    - backendRefs:
        - name: httpbin
          port: 8000
EOF

    4. Verify that the HTTPRoute is applied successfully.

      kubectl get httproute/httpbin-https -n httpbin -o yaml

      Example output: Notice in the status section that the parentRef is either the Gateway or the ListenerSet, depending on how you attached the HTTPRoute.

      ...
status:
...
  parentRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: https
    namespace: agentgateway-system

    5. Verify that the listener now has a route attached.

      kubectl get gateway -n agentgateway-system https -o yaml

      Example output:

      ...
listeners:
- attachedRoutes: 1

    6. Get the external address of the gateway and save it in an environment variable.

      export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system https -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS

    7. Send a request to the httpbin app and verify that you see the TLS handshake and you get back a 200 HTTP response code.

      curl -vik --resolve "https.example.com:8443:${INGRESS_GW_ADDRESS}" https://https.example.com:8443/status/200

      Example output:

      * Added https.example.com:443:172.18.0.5 to DNS cache
* Hostname https.example.com was found in DNS cache
*   Trying 172.18.0.5:443...
* Connected to https.example.com (172.18.0.5) port 443
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF
* ALPN: server accepted h2
* Server certificate:
*  subject: CN=*.example.com; O=any domain
*  issuer: O=any domain; CN=*
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://https.example.com:443/status/200
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: https.example.com]
* [HTTP/2] [1] [:path: /status/200]
* [HTTP/2] [1] [user-agent: curl/8.7.1]
* [HTTP/2] [1] [accept: */*]
> GET /status/200 HTTP/2
> Host: https.example.com
> User-Agent: curl/8.7.1
> Accept: */*
> 
* Request completely sent off
< HTTP/2 200 
HTTP/2 200 
...

    Cleanup

    You can remove the resources that you created in this guide.
    kubectl delete -A gateways,httproutes,secret -l example=httpbin-https
rm -rf example_certs
    HTTP mTLS (FrontendTLS)
    Was this page helpful?
    Agentgateway assistant

    Ask me anything about agentgateway configuration, features, or usage.

    Note: AI-generated content might contain errors; please verify and test all returned information.

    Tip: one topic per conversation gives the best results. Use the + button in the chat header to start a new conversation.

    Switching topics? Starting a new conversation improves accuracy.
    ↑↓ navigate ↵ select esc dismiss

    What could be improved?

    Your feedback helps us improve assistant answers and identify docs gaps we should fix.

    Need more help? Join us on Discord: https://discord.gg/y9efgEmppm

    Want to use your own agent? Add the Solo MCP server to query our docs directly. Get started here: https://search.solo.io/.