docs: Complements to the Gateway API ingress guide #25734 (#25739)

Signed-off-by: Quentin Ågren <quentin.agren@gmail.com>
2026-02-20 01:28:45 +01:00 · 2026-01-10 17:03:44 +01:00
parent dab6f3bfae
commit e6825529ab
1 changed files with 137 additions and 19 deletions
--- a/docs/operator-manual/ingress.md
+++ b/docs/operator-manual/ingress.md
@@ -12,7 +12,7 @@ There are several ways how Ingress can be configured.

 The Ambassador Edge Stack can be used as a Kubernetes ingress controller with [automatic TLS termination](https://www.getambassador.io/docs/latest/topics/running/tls/#host) and routing capabilities for both the CLI and the UI.

-The API server should be run with TLS disabled. Edit the `argocd-server` deployment to add the `--insecure` flag to the argocd-server command, or simply set `server.insecure: "true"` in the `argocd-cmd-params-cm` ConfigMap [as described here](server-commands/additional-configuration-method.md). Given the `argocd` CLI includes the port number in the request `host` header, 2 Mappings are required. 
+The API server should be run with TLS disabled. Edit the `argocd-server` deployment to add the `--insecure` flag to the argocd-server command, or simply set `server.insecure: "true"` in the `argocd-cmd-params-cm` ConfigMap [as described here](server-commands/additional-configuration-method.md). Given the `argocd` CLI includes the port number in the request `host` header, 2 Mappings are required.
 Note: Disabling TLS in not required if you are using grpc-web

 ### Option 1: Mapping CRD for Host-based Routing
@@ -494,7 +494,7 @@ resources:

 patches:
 - path: ./patch.yml
-``` 
+```

 And following lines as patch.yml

@@ -878,15 +878,15 @@ http {
 }
 ```

-## Cilium Gateway API Example
+## Gateway API Example

-This section provides a working example of using Cilium Gateway API with Argo CD, including HTTP and gRPC routes.
+This section discusses using Gateway API to expose the Argo CD server in various TLS configurations,
+accomodating both HTTP and gRPC traffic, possibly using HTTP/2.

-### Prerequisites
+### TLS termination at the Gateway

- API server run with TLS disabled (set `server.insecure: "true"` in argocd-cmd-params-cm ConfigMap)
-
-### Gateway Example
+Assume the following cluster-wide `Gateway` resource,
+that terminates the TLS conection with a certificate stored in a `Secret` in the same namespace:

 ```yaml
 apiVersion: gateway.networking.k8s.io/v1
@@ -894,17 +894,12 @@ kind: Gateway
 metadata:
  name: cluster-gateway
  namespace: gateway
-  annotations:
-    cert-manager.io/issuer: cloudflare-dns-issuer
 spec:
-  gatewayClassName: cilium
-  addresses:
-    - type: IPAddress
-      value: "192.168.0.130"
+  gatewayClassName: example
  listeners:
    - protocol: HTTPS
      port: 443
-      name: https-cluster
+      name: https
      hostname: "*.local.example.com"
      allowedRoutes:
        namespaces:
@@ -917,7 +912,38 @@ spec:
            group: ""
 ```

-### HTTPRoute Example
+To automate certificate management, `cert-manager` supports [gateway annotations](https://cert-manager.io/docs/usage/gateway/).
+
+#### Securing traffic between Argo CD and the gateway
+
+If your security requirements allow it, the Argo CD API server can be run with TLS disabled: pass the `--insecure` flag to the `argocd-server` command,
+or set `server.insecure: "true"` in the `argocd-cmd-params-cm` ConfigMap [as described here](server-commands/additional-configuration-method.md).
+
+It is also possible to keep TLS enabled, encrypting traffic between the gateway and the Argo CD API server, by using a [BackendTLSPolicy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/).
+Consult the [Upstream TLS](https://gateway-api.sigs.k8s.io/guides/tls/#upstream-tls) documentation for more details.
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: BackendTLSPolicy
+metadata:
+  name: tls-upstream-auth
+  namespace: argocd
+spec:
+  targetRefs:
+    - kind: Service
+      name: argocd-server
+      group: ""
+  validation:
+    caCertificateRefs:
+      - kind: ConfigMap
+        name: argocd-server-ca-cert
+        group: ""
+    hostname: argocd-server.argocd.svc.cluster.local
+```
+
+
+#### Routing HTTP requests
+
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
@@ -928,6 +954,7 @@ spec:
  parentRefs:
    - name: cluster-gateway
      namespace: gateway
+      sectionName: https
  hostnames:
    - "argocd.local.example.com"
  rules:
@@ -940,7 +967,45 @@ spec:
            value: /
 ```

-### GRPCRoute Example
+#### Routing gRPC requests
+
+The `argocd` CLI operates at full capability when using gRPC over HTTP/2 to communicate with the API server, falling back to HTTP/1.1. (`--grpc-web` flag).
+
+gRPC can be configured using a `GRPCRoute`, and HTTP/2 requested as the application protocol on the `argocd-server` service:
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: GRPCRoute
+metadata:
+  name: argocd-grpc-route
+  namespace: argocd
+spec:
+  parentRefs:
+    - name: cluster-gateway
+      namespace: gateway
+      sectionName: https
+  hostnames:
+    - "grpc.argocd.local.example.com"
+  rules:
+    - backendRefs:
+        - name: argocd-server
+          port: 443
+```
+
+And in Argo CD's `values.yaml` (or [directly](https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol) in the service manifest):
+```
+server:
+  service:
+    # Enable gRPC over HTTP/2
+    servicePortHttpsAppProtocol: kubernetes.io/h2c
+```
+
+##### Routing gRPC and HTTP on through the same domain
+
+Although officially [discouraged](https://gateway-api.sigs.k8s.io/api-types/grpcroute/#cross-serving),
+attaching the `HTTPRoute` and `GRPCRoute` to the same domain may be supported by some implementations.
+Matching requests headers become necessary to disambiguate the destination, as shown below:
+
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1
 kind: GRPCRoute
@@ -952,7 +1017,7 @@ spec:
    - name: cluster-gateway
      namespace: gateway
  hostnames:
-    - "argocd.local.example.com"
+    - "grpc.argocd.local.example.com"
  rules:
    - backendRefs:
        - name: argocd-server
@@ -962,4 +1027,57 @@ spec:
            - name: Content-Type
              type: RegularExpression
              value: "^application/grpc.*$"
-```
+```
+
+### TLS passthrough
+
+TLS can also be configured to terminate at the Argo CD API server.
+
+This require attaching a `TLSRoute` to the gateway,
+which is part of the [Experimental](https://gateway-api.sigs.k8s.io/reference/1.4/specx/) Gateway API CRDs.
+
+```yaml
+kind: Gateway
+metadata:
+  name: cluster-gateway
+  namespace: gateway
+spec:
+  gatewayClassName: example
+  listeners:
+  - name: tls
+    port: 443
+    protocol: TLS
+    hostname: "argocd.example.com"
+    allowedRoutes:
+      namespaces:
+        from: All
+      kinds:
+        - kind: TLSRoute
+    tls:
+      mode: Passthrough
+```
+
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: TLSRoute
+metadata:
+  namespace: argocd
+  name: argocd-server-tlsroute
+spec:
+  parentRefs:
+  - name: cluster-gateway
+    namespace: gateway
+    sectionName: tls
+  hostnames:
+  - argocd.example.com
+  rules:
+  - backendRefs:
+    - name: argocd-server
+      port: 443
+```
+
+The TLS certificates are implicit here,
+and found by the Argo CD server in the `argocd-server-tls` secret.
+
+Note that `cert-manager` does not support generating certificates for passthrough gateway listeners.