diff --git a/modules/configuring-automatic-address-assignment-gateway.adoc b/modules/configuring-automatic-address-assignment-gateway.adoc index 10c0ca43dd66..d2f11a36a786 100644 --- a/modules/configuring-automatic-address-assignment-gateway.adoc +++ b/modules/configuring-automatic-address-assignment-gateway.adoc @@ -13,11 +13,11 @@ When you create a gateway resource, you must configure it for automatic address * You have access to the cluster as a user with the `cluster-admin` role. * You have installed the {oc-first}. -* You have an existing `GatewayClass` resource, such as `openshift-default`. +* You have an existing `GatewayClass` custom resource, such as `openshift-default`. .Procedure -. Create a YAML file, such as `hello-gateway.yaml`, that defines your `Gateway` object without the addresses field: +. Create a YAML file, such as `hello-gateway.yaml`, that defines your `Gateway` object. + [source,yaml] ---- @@ -30,18 +30,21 @@ spec: gatewayClassName: openshift-default listeners: - name: http - hostname: "*.gwapi." + hostname: "*.gwapi." port: 80 protocol: HTTP allowedRoutes: namespaces: - from: All + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" ---- + -* `metadata.name`: The name of your `Gateway` object. The name must consist of a maximum of 63 lowercase alphanumeric characters or hyphens (`-`). The name must also start and end with an alphanumeric character. -* Replace `` with your actual cluster ingress domain (for example, `example.com`). -* The `spec.addresses` field is omitted from this configuration to ensure automatic assignment. -* The `gatewayClassName` dictates which controller provisions the address and populates the `status.addresses` field. +* `metadata.name`: Specify the name of your `Gateway` object. The name must consist of a maximum of 63 lowercase alphanumeric characters or hyphens (`-`). The name must also start and end with an alphanumeric character. +* `spec.listeners[].hostname`: Specify the listener hostname. Replace `` with your actual cluster ingress domain (for example, `example.com`). Setting a hostname limits which route hostnames can match this listener. +* `spec.listeners[].allowedRoutes.namespaces`: Allow route attachment only from namespaces that have the `shared-gateway-access: "true"` label. +* `spec.gatewayClassName`: Specify the gateway class whose controller provisions the address and populates the `status.addresses` field. . Apply the `Gateway` configuration by running the following command: + @@ -64,4 +67,4 @@ NAME CLASS ADDRESS PROGRAMMED AGE sample-gateway openshift-default True 6m16s ---- + -The `ADDRESS` column in the output displays the dynamically provisioned network address for your gateway. \ No newline at end of file +The `ADDRESS` column in the output displays the dynamically provisioned network address for your gateway. diff --git a/modules/configuring-listener-routing-security.adoc b/modules/configuring-listener-routing-security.adoc index d0c894fad6a2..e10fc6077368 100644 --- a/modules/configuring-listener-routing-security.adoc +++ b/modules/configuring-listener-routing-security.adoc @@ -9,45 +9,56 @@ [role="_abstract"] To ensure that your applications receive only authenticated and authorized traffic, you must specify the allowed protocols and ports for your gateway. If you are routing secure traffic, you must also configure TLS settings. You can define these parameters by configuring the `spec.listeners` field in your `Gateway` custom resource (CR). +[IMPORTANT] +==== +If your gateway is accessible from other namespaces, always configure the `spec.listeners[].allowedRoutes[].namespaces.selector` field with a selector for the permitted namespaces. By specifying a namespace selector, you prevent possible misuse or hijacking of the gateway from other namespaces. +==== + .Procedure -. Create or edit a `Gateway` YAML file to include your desired listener configuration. +. Create or edit a `Gateway` YAML file to include your listener configuration. + -- -The following example demonstrates a `Gateway` CR with two listeners, one for HTTP and one for HTTPS. For detailed descriptions of the listener fields, see xref:gateway-listener-configuration-reference_{context}[]. +The following example demonstrates a `Gateway` CR with two listeners, one for HTTP and one for HTTPS. For detailed descriptions of the listener fields, see "Gateway listener configuration reference". [source,yaml] ---- kind: Gateway apiVersion: gateway.networking.k8s.io/v1 metadata: -  name: -  namespace: openshift-ingress + name: + namespace: openshift-ingress spec: -  gatewayClassName: openshift-default -  listeners: -  - protocol: HTTP  -    port: 80 -    name: http -    allowedRoutes:  -      namespaces: -        from: Selector -        selector: -          matchLabels: -            env: "dev" -  - protocol: HTTPS  -    port: 443 -    name: https -    hostname: "*."  -    tls:  -      mode: Terminate -      certificateRefs: -        - name: -          kind: Secret -    allowedRoutes:  -      namespaces: -        from: All + gatewayClassName: openshift-default + listeners: + - protocol: HTTP + port: 80 + name: http + hostname: "*." + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + env: "dev" + - protocol: HTTPS + port: 443 + name: https + hostname: "*." + tls: + mode: Terminate + certificateRefs: + - name: + kind: Secret + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + env: "dev" ---- ++ +With this configuration, only `HTTPRoute` resources in namespaces that have the `env: "dev"` label can attach to these listeners. -- . Apply the `Gateway` CR by running the following command: @@ -55,4 +66,4 @@ spec: [source,terminal] ---- $ oc apply -f .yaml ----- \ No newline at end of file +---- diff --git a/modules/creating-httproute.adoc b/modules/creating-httproute.adoc index 8e5601a9152e..4506126dc0c9 100644 --- a/modules/creating-httproute.adoc +++ b/modules/creating-httproute.adoc @@ -39,7 +39,8 @@ spec: ---- + * You must include application hostnames and a `backendRef` rule that points to your backend service. -* If your `HTTPRoute` and `Gateway` CRs are deployed in different namespaces, the `Gateway` CR listener must be configured to allow cross-namespace routes. You must set `allowedRoutes.namespaces.from: All` in the `Gateway` CR. +* If your `HTTPRoute` and `Gateway` CRs are deployed in different namespaces, the `Gateway` CR listener must allow routes from the `HTTPRoute` namespace. You must configure the `spec.listeners.allowedRoutes.namespaces` field in the `Gateway` CR and specify a selector for trusted namespaces. +* The listener `hostname` on the parent `Gateway` CR must cover the hostnames in your `HTTPRoute` CR. For example, a listener hostname of `*.gwapi.apps.example.com` accepts an `HTTPRoute` hostname such as `app.gwapi.apps.example.com`, but rejects hostnames outside that domain. . Apply the `HTTPRoute` CR file to your cluster: + diff --git a/modules/gateway-api-benefits-limitations.adoc b/modules/gateway-api-benefits-limitations.adoc index acf0ea092100..617bd2748141 100644 --- a/modules/gateway-api-benefits-limitations.adoc +++ b/modules/gateway-api-benefits-limitations.adoc @@ -9,7 +9,8 @@ [role="_abstract"] To determine if Gateway API is the right routing solution for your cluster, review its benefits and limitations. The project is an effort to provide a standardized ecosystem by using a portable API with broad community support. Understanding these factors ensures your networking infrastructure aligns with your organizational needs and technical capabilities. -== Benefits +[id="gateway-api-benefits_{context}"] +== Gateway API Benefits Gateway API provides the following benefits: @@ -17,10 +18,11 @@ Gateway API provides the following benefits: * Separation of concerns: Gateway API uses a role-based approach to its resources, and more neatly fits into how a large organization structures its responsibilities and teams. Platform engineers might focus on `GatewayClass` resources, cluster administrators might focus on configuring `Gateway` resources, and application developers might focus on routing their services with `HTTPRoute` resources. * Extensibility: Additional functionality is developed as a standardized CRD. -== Limitations +[id="gateway-api-limitations_{context}"] +== Gateway API Limitations Gateway API has the following limitations: * Version incompatibilities: The Gateway API ecosystem changes rapidly, and some implementations do not work with others because their featureset is based on differing versions of Gateway API. * Resource overhead: While more flexible, Gateway API uses multiple resource types to achieve an outcome. For smaller applications, the simplicity of traditional Ingress might be a better fit. -* On-premise infrastructure dependencies: On-premise deployments, such as bare metal or VMware vSphere environments, do not automatically provision network load balancers or manage external DNS records. To use Gateway API on an on-premise platform, you must explicitly deploy a load balancer controller, such as MetalLB, and manually map your DNS records to the provisioned gateway address. \ No newline at end of file +* On-premise infrastructure dependencies: On-premise deployments, such as bare metal or VMware vSphere environments, do not automatically provision network load balancers or manage external DNS records. To use Gateway API on an on-premise platform, you must explicitly deploy a load balancer controller, such as MetalLB, and manually map your DNS records to the provisioned gateway address. diff --git a/modules/gateway-api-deployment-topologies.adoc b/modules/gateway-api-deployment-topologies.adoc index 76face7fd531..6d970d2b10dd 100644 --- a/modules/gateway-api-deployment-topologies.adoc +++ b/modules/gateway-api-deployment-topologies.adoc @@ -9,6 +9,7 @@ [role="_abstract"] To effectively organize and secure your routing infrastructure, you must choose an appropriate deployment topology for your cluster. Gateway API is designed to accommodate two topologies: shared gateways or dedicated gateways. You can choose a topology based on its own advantages and different security implications. +[id="dedicated-gateway_{context}"] == Dedicated gateway Routes and any load balancers or proxies are served from the same namespace. The `Gateway` object restricts routes to a particular application namespace. This is the default topology when deploying a Gateway API resource in {product-title}. @@ -31,7 +32,7 @@ spec: hostname: "example.com" ---- -If you do not set `spec.listeners[].allowedRoutes` for a `Gateway` resource, the system implicitly sets the `namespaces.from` field to the value of `Same`. +If you do not set `spec.listeners[].allowedRoutes` for a `Gateway` resource, the system implicitly sets the `namespaces.from` field to the value of `Same`. The following example shows the associated `HTTPRoute` resource, `sales-db`, which attaches to the dedicated `Gateway` object: @@ -51,11 +52,12 @@ spec: rules: - backendRefs: - name: sales-db - ¦ port: 8080 + port: 8080 ---- The `HTTPRoute` resource must have the name of the `Gateway` object as the value for its `parentRefs` field to attach to the gateway. The system implicitly assumes that the route exists in the same namespace as the `Gateway` object. +[id="shared-gateway_{context}"] == Shared gateway Routes are served from multiple namespaces or multiple hostnames. The `Gateway` object allows routes from application namespaces by using the `spec.listeners.allowedRoutes.namespaces` field. @@ -80,8 +82,8 @@ spec: namespaces: from: Selector selector: - ¦ matchLabels: - ¦ shared-gateway-access: "true" + matchLabels: + shared-gateway-access: "true" ---- The following examples show the allowed namespaces for the `devops-gateway` resource: @@ -108,7 +110,7 @@ In this example, two `HTTPRoute` resources, `dev-portal` and `ops-home`, are in [source,yaml] ---- -apiVersion: v1 +apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: dev-portal @@ -122,7 +124,7 @@ spec: - name: dev-portal port: 8080 --- -apiVersion: v1 +apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: ops-home @@ -137,4 +139,4 @@ spec: port: 8080 ---- -With a shared gateway topology, the routes must specify the namespace of the `Gateway` object it wants to attach to. Multiple `Gateway` objects can be deployed and shared across namespaces. When there are multiple shared gateways, this topology becomes conceptually similar to Ingress Controller sharding. \ No newline at end of file +With a shared gateway topology, the routes must specify the namespace of the `Gateway` object it wants to attach to. Multiple `Gateway` objects can be deployed and shared across namespaces. When there are multiple shared gateways, this topology becomes conceptually similar to Ingress Controller sharding. diff --git a/modules/gateway-listener-configuration-reference.adoc b/modules/gateway-listener-configuration-reference.adoc index 1fca033194f7..a9923071b4c1 100644 --- a/modules/gateway-listener-configuration-reference.adoc +++ b/modules/gateway-listener-configuration-reference.adoc @@ -18,10 +18,10 @@ Defines the list of listeners for the gateway. You can customize this field with Defines the network port and protocol. For example, `protocol: HTTP` accepts HTTP traffic on port `80`, and `protocol: HTTPS` accepts HTTPS traffic on port `443`. `listeners.hostname`:: -Defines the hostnames that the listener matches for incoming requests. For example, it can match only requests for hostnames ending in `` (such as `www.`). If no hostname is specified, the gateway routes any traffic that can attach to it. +Defines the hostnames that the listener matches for incoming requests. For example, it can match only requests for hostnames ending in `` (such as `www.` or `*.gwapi.`). Always set a hostname on each listener. If no hostname is specified, any route that can attach to the listener can claim arbitrary hostnames, which can allow hostname or domain hijacking. `listeners.tls`:: Specifies the TLS settings for secure communication, including the mode (currently, only `Terminate` is supported on {product-title}) and the Kubernetes secret containing the certificate keypair. For example, TLS is terminated at the gateway using a certificate stored in a Kubernetes `Secret` called ``. You must ensure that the specified Kubernetes secret exists before you create the `Gateway` CR. `listeners.allowedRoutes`:: -Controls which `Route` resources can attach to this listener. For example, an HTTP listener might only allow `HTTPRoute` resources from namespaces that have the `env: "dev"` label (using `Selector`), while an HTTPS listener might allow `HTTPRoute` resources from any namespace to attach (using `All`). Setting `allowedRoutes.namespaces.from: Same` is not supported; routes from the same namespace as the gateway are always allowed. \ No newline at end of file +Controls which `Route` resources can attach to this listener. For example, an HTTP listener might only allow `HTTPRoute` resources from namespaces that have the `env: "dev"` label (using `Selector`). Setting `allowedRoutes.namespaces.from: Same` is not supported; routes from the same namespace as the gateway are always allowed. Do not use `.spec.listeners[].allowedRoutes.namespaces.from=All` because this is insecure and can allow hostname or domain hijacking.