mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
add enablement procedure
This commit is contained in:
Jesse Dohmann
committed by
openshift-cherrypick-robot
openshift-cherrypick-robot
parent
2afbaf58e3
commit
d7ed8ae128
239
modules/nw-ingress-gateway-api-enable.adoc
Normal file
239
modules/nw-ingress-gateway-api-enable.adoc
Normal file
@@ -0,0 +1,239 @@
|
||||
// Modules included in the following assemblies:
|
||||
//
|
||||
// * networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="nw-ingress-gateway-api-enable_{context}"]
|
||||
= Getting started with Gateway API for the Ingress Operator
|
||||
|
||||
When you create a GatewayClass as shown in the first step, it configures Gateway API for use on your cluster.
|
||||
|
||||
.Procedure
|
||||
|
||||
. Create a `GatewayClass` object:
|
||||
|
||||
.. Create a YAML file, `openshift-default.yaml`, that contains the following information:
|
||||
+
|
||||
.Example `GatewayClass` CR
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: gateway.networking.k8s.io/v1
|
||||
kind: GatewayClass
|
||||
metadata:
|
||||
name: openshift-default
|
||||
spec:
|
||||
controllerName: openshift.io/gateway-controller/v1 <1>
|
||||
----
|
||||
<1> The controller name.
|
||||
+
|
||||
[IMPORTANT]
|
||||
====
|
||||
The controller name must be exactly as shown for the Ingress Operator to manage it. If you set this field to anything else, the Ingress Operator ignores the `GatewayClass` object and all associated `Gateway`, `GRPCRoute`, and `HTTPRoute` objects. The controller name is tied to the implementation of Gateway API in {product-title}, and `openshift.io/gateway-controller/v1` is the only controller name allowed.
|
||||
====
|
||||
|
||||
.. Run the following command to create the `GatewayClass` resource:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc create -f openshift-default.yaml
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
gatewayclass.gateway.networking.k8s.io/openshift-default created
|
||||
----
|
||||
+
|
||||
During the creation of the `GatewayClass` resource, the Ingress Operator installs a lightweight version of {SMProductName}, an Istio custom resource, and a new deployment in the `openshift-ingress` namespace.
|
||||
|
||||
.. Optional: Verify that the new deployment, `istiod-openshift-gateway` is ready and available:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc get deployment -n openshift-ingress
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
NAME READY UP-TO-DATE AVAILABLE AGE
|
||||
istiod-openshift-gateway 1/1 1 1 55s
|
||||
router-default 2/2 2 2 6h4m
|
||||
----
|
||||
|
||||
. Create a secret by running the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc -n openshift-ingress create secret tls gwapi-wildcard --cert=wildcard.crt --key=wildcard.key
|
||||
----
|
||||
|
||||
. Get the domain of the Ingress Operator by running the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ DOMAIN=$(oc get ingresses.config/cluster -o jsonpath={.spec.domain})
|
||||
----
|
||||
|
||||
. Create a `Gateway` object:
|
||||
|
||||
.. Create a YAML file, `example-gateway.yaml`, that contains the following information:
|
||||
+
|
||||
.Example `Gateway` CR
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: gateway.networking.k8s.io/v1
|
||||
kind: Gateway
|
||||
metadata:
|
||||
name: example-gateway
|
||||
namespace: openshift-ingress <1>
|
||||
spec:
|
||||
gatewayClassName: openshift-default <2>
|
||||
listeners:
|
||||
- name: https <3>
|
||||
hostname: "*.gwapi.${DOMAIN}" <4>
|
||||
port: 443
|
||||
protocol: HTTPS
|
||||
tls:
|
||||
mode: Terminate
|
||||
certificateRefs:
|
||||
- name: gwapi-wildcard <5>
|
||||
allowedRoutes:
|
||||
namespaces:
|
||||
from: All
|
||||
----
|
||||
<1> The `Gateway` object must be created in the `openshift-ingress` namespace.
|
||||
<2> The `Gateway` object must reference the name of the previously created `GatewayClass` object.
|
||||
<3> The HTTPS listener listens for HTTPS requests that match a subdomain of the cluster domain. You use this listener to configure ingress to your applications by using Gateway API `HTTPRoute` resources.
|
||||
<4> The hostname must be a subdomain of the Ingress Operator domain. If you use a domain, the listener tries to serve all traffic in that domain.
|
||||
<5> The name of the previously created secret.
|
||||
|
||||
.. Apply the resource by running the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc apply -f example-gateway.yaml
|
||||
----
|
||||
|
||||
.. Optional: When you create a `Gateway` object, {SMProductName} automatically provisions a deployment and service with the same name. Verify this by running the following commands:
|
||||
*** To verify the deployment, run the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc get deployment -n openshift-ingress example-gateway-openshift-default
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
NAME READY UP-TO-DATE AVAILABLE AGE
|
||||
example-gateway-openshift-default 1/1 1 1 25s
|
||||
----
|
||||
*** To verify the service, run the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc get service -n openshift-ingress example-gateway-openshift-default
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
example-gateway-openshift-default LoadBalancer 10.1.2.3 <external_ipname> <port_info> 47s
|
||||
----
|
||||
|
||||
.. Optional: The Ingress Operator automatically creates a `DNSRecord` CR using the hostname from the listeners, and adds the label `gateway.networking.k8s.io/gateway-name=example-gateway`. Verify the status of the DNS record by running the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc -n openshift-ingress get dnsrecord -l gateway.networking.k8s.io/gateway-name=example-gateway -o yaml
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,yaml]
|
||||
----
|
||||
kind: DNSRecord
|
||||
...
|
||||
status:
|
||||
...
|
||||
zones:
|
||||
- conditions:
|
||||
- message: The DNS provider succeeded in ensuring the record
|
||||
reason: ProviderSuccess
|
||||
status: "True"
|
||||
type: Published
|
||||
dnsZone:
|
||||
tags:
|
||||
...
|
||||
- conditions:
|
||||
- message: The DNS provider succeeded in ensuring the record
|
||||
reason: ProviderSuccess
|
||||
status: "True"
|
||||
type: Published
|
||||
dnsZone:
|
||||
id: ...
|
||||
----
|
||||
|
||||
. Create an `HTTPRoute` resource that directs requests to your already-created namespace and application called `example-app/example-app`:
|
||||
|
||||
.. Create a YAML file, `example-route.yaml`, that contains the following information:
|
||||
+
|
||||
.Example `HTTPRoute` CR
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: gateway.networking.k8s.io/v1
|
||||
kind: HTTPRoute
|
||||
metadata:
|
||||
name: example-route
|
||||
namespace: example-app-ns <1>
|
||||
spec:
|
||||
parentRefs: <2>
|
||||
- name: example-gateway
|
||||
namespace: openshift-ingress
|
||||
hostnames: ["example.gwapi.${DOMAIN}"] <3>
|
||||
rules:
|
||||
- backendRefs: <4>
|
||||
- name: example-app <5>
|
||||
port: 8443
|
||||
----
|
||||
<1> The namespace you are deploying your application.
|
||||
<2> This field must point to the `Gateway` object you previously configured.
|
||||
<3> The hostname must match the one specified in the `Gateway` object. In this case, the listeners use a wildcard hostname.
|
||||
<4> This field specifies the backend references that point to your service.
|
||||
<5> The name of the `Service` for your application.
|
||||
|
||||
.. Apply the resource by running the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc apply -f example-route.yaml
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
httproute.gateway.networking.k8s.io/example-route created
|
||||
----
|
||||
|
||||
.Verification
|
||||
|
||||
. Verify that the `Gateway` object is deployed and has the condition `Programmed` by running the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc wait -n openshift-ingress --for=condition=Programmed gateways.gateway.networking.k8s.io example-gateway
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
gateway.gateway.networking.k8s.io/example-gateway condition met
|
||||
----
|
||||
|
||||
. Send a request to the configured `HTTPRoute` object hostname:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ curl -I --cacert <local cert file> https://example.gwapi.${DOMAIN}:443
|
||||
----
|
||||
@@ -8,9 +8,9 @@
|
||||
|
||||
The Ingress Operator manages the lifecycle of Gateway API CRDs in a way that enables other vendor implementations to make use of CRDs defined in an {product-title} cluster.
|
||||
|
||||
In some situations, the Gateway API provides one or more fields that a vendor implementation does not support, but that implementation is otherwise compatible in schema with the rest of the fields. These "dead fields" can result in disrupted Ingress workloads, improperly provisioned applications and services, and security related issues. Because {product-title} uses a specific version of Gateway API CRDs, any use of third-party implementations of Gateway API must conform to the {product-title} implementation to ensure that all fields work as expected.
|
||||
In some situations, Gateway API provides one or more fields that a vendor implementation does not support, but that implementation is otherwise compatible in schema with the rest of the fields. These "dead fields" can result in disrupted Ingress workloads, improperly provisioned applications and services, and security related issues. Because {product-title} uses a specific version of Gateway API CRDs, any use of third-party implementations of Gateway API must conform to the {product-title} implementation to ensure that all fields work as expected.
|
||||
|
||||
Any CRDs created within an {product-title} {product-version} cluster are compatibly versioned and maintained by the Ingress Operator. If CRDs are already present but were not previously managed by the Ingress Operator, the Ingress Operator checks whether these configurations are compatible with the Gateway API version supported by {product-title}, and creates an admin-gate that requires your acknowledgment of CRD succession.
|
||||
Any CRDs created within an {product-title} {product-version} cluster are compatibly versioned and maintained by the Ingress Operator. If CRDs are already present but were not previously managed by the Ingress Operator, the Ingress Operator checks whether these configurations are compatible with Gateway API version supported by {product-title}, and creates an admin-gate that requires your acknowledgment of CRD succession.
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
|
||||
@@ -4,13 +4,13 @@
|
||||
|
||||
:_mod-docs-content-type: CONCEPT
|
||||
[id="nw-ingress-gateway-api-overview_{context}"]
|
||||
= Overview of the Gateway API
|
||||
= Overview of Gateway API
|
||||
|
||||
The Gateway API is an open source, community-managed, Kubernetes networking mechanism. It focuses on routing within the transport layer, L4, and the application layer, L7, for clusters. A variety of vendors offer many link:https://gateway-api.sigs.k8s.io/implementations/[implementations of Gateway API].
|
||||
Gateway API is an open source, community-managed, Kubernetes networking mechanism. It focuses on routing within the transport layer, L4, and the application layer, L7, for clusters. A variety of vendors offer many link:https://gateway-api.sigs.k8s.io/implementations/[implementations of Gateway API].
|
||||
|
||||
The project is an effort to provide a standardized ecosystem by using a portable API with broad community support. By integrating Gateway API functionality into the Ingress Operator, it enables a networking solution that aligns with existing community and upstream development efforts.
|
||||
|
||||
The Gateway API extends the functionality of the Ingress Operator to handle more granular cluster traffic and routing configurations. With these capabilities, you can create instances of Gateway APIs custom resource definitions (CRDs). For {product-title} clusters, the Ingress Operator creates the following resources:
|
||||
Gateway API extends the functionality of the Ingress Operator to handle more granular cluster traffic and routing configurations. With these capabilities, you can create instances of Gateway APIs custom resource definitions (CRDs). For {product-title} clusters, the Ingress Operator creates the following resources:
|
||||
|
||||
Gateway:: This resource describes how traffic can be translated to services within the cluster. For example, a specific load balancer configuration.
|
||||
GatewayClass:: This resource defines a set of `Gateway` objects that share a common configuration and behavior. For example, two separate `GatewayClass` objects might be created to distinguish a set of `Gateway` resources used for public or private applications.
|
||||
@@ -18,19 +18,19 @@ HTTPRoute:: This resource specifies the routing behavior of HTTP requests from a
|
||||
GRPCRoute:: This resource specifies the routing behavior of gRPC requests.
|
||||
ReferenceGrant:: This resource enables cross-namespace references. For example, it enables routes to forward traffic to backends that are in a different namespace.
|
||||
|
||||
In {product-title}, the implementation of the Gateway API is based on `gateway.networking.k8s.io/v1`, and all fields in this version are supported.
|
||||
In {product-title}, the implementation of Gateway API is based on `gateway.networking.k8s.io/v1`, and all fields in this version are supported.
|
||||
|
||||
[id="gateway-api-benefits_{context}"]
|
||||
== Benefits of the Gateway API
|
||||
The Gateway API provides the following benefits:
|
||||
== Benefits of Gateway API
|
||||
Gateway API provides the following benefits:
|
||||
|
||||
* Portability: While {product-title} uses HAProxy to improve Ingress performance, Gateway API does not rely on vendor-specific annotations to provide certain behavior. To get comparable performance as HAProxy, the `Gateway` objects need to be horizontally scaled or their associated nodes need to be vertically scaled.
|
||||
* 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 admins 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.
|
||||
|
||||
[id="gateway-api-limitations_{context}"]
|
||||
== Limitations of the Gateway API
|
||||
The Gateway API has the following limitations:
|
||||
== Limitations of Gateway API
|
||||
Gateway API has the following limitations:
|
||||
|
||||
* Version incompatibilites: 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.
|
||||
* Version incompatibilities: 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.
|
||||
|
||||
@@ -17,6 +17,8 @@ include::modules/nw-ingress-gateway-api-overview.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/nw-ingress-gateway-api-implementation.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/nw-ingress-gateway-api-enable.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/nw-ingress-gateway-api-deployment-topologies.adoc[leveloffset=+1]
|
||||
|
||||
.Additional resources
|
||||
|
||||
Reference in New Issue
Block a user