From 67c61f61e4d71c4be155d3b5afdd6dbde579e32e Mon Sep 17 00:00:00 2001 From: Craig Box Date: Sat, 11 May 2024 10:37:49 +1200 Subject: [PATCH] Update and standardise admonitions (#3066) * Update and standardise admonitions * how you like that, search and replace? --- site-src/api-types/backendtlspolicy.md | 6 ++- site-src/api-types/gateway.md | 6 ++- site-src/api-types/gatewayclass.md | 8 ++-- site-src/api-types/grpcroute.md | 8 ++-- site-src/api-types/httproute.md | 19 ++++++---- site-src/api-types/referencegrant.md | 6 ++- site-src/blog/2021/introducing-v1alpha2.md | 2 +- site-src/concepts/api-overview.md | 44 ++++++++++++---------- site-src/concepts/use-cases.md | 10 +++-- site-src/contributing/style-guide.md | 16 ++++---- site-src/guides/backend-protocol.md | 6 ++- site-src/guides/grpc-routing.md | 2 +- site-src/guides/tcp.md | 2 +- site-src/guides/tls.md | 2 +- site-src/index.md | 6 +-- site-src/mesh/index.md | 8 ++-- 16 files changed, 87 insertions(+), 64 deletions(-) diff --git a/site-src/api-types/backendtlspolicy.md b/site-src/api-types/backendtlspolicy.md index cbaba3a40c..df44306796 100644 --- a/site-src/api-types/backendtlspolicy.md +++ b/site-src/api-types/backendtlspolicy.md @@ -1,8 +1,10 @@ # BackendTLSPolicy -??? example "Experimental Channel in v1.0.0+" +??? example "Experimental Channel since v1.0.0" - The `BackendTLSPolicy` resource is Alpha and part of the Experimental Channel in `v1.0.0+`. + The `BackendTLSPolicy` resource is Alpha and has been part of + the Experimental Channel since `v1.0.0`. For more information on release + channels, refer to our [versioning guide](/concepts/versioning). [BackendTLSPolicy][backendtlspolicy] is a Gateway API type for specifying the TLS configuration of the connection from the Gateway to a backend pod/s via the Service API object. diff --git a/site-src/api-types/gateway.md b/site-src/api-types/gateway.md index 17a8293425..d670cf5629 100644 --- a/site-src/api-types/gateway.md +++ b/site-src/api-types/gateway.md @@ -1,8 +1,10 @@ # Gateway -??? success "Standard Channel in v0.5.0+" +??? success "Standard Channel since v0.5.0" - The `Gateway` resource is Beta and part of the Standard Channel in `v0.5.0+`. + The `Gateway` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). A `Gateway` is 1:1 with the lifecycle of the configuration of infrastructure. When a user creates a `Gateway`, some load balancing infrastructure is diff --git a/site-src/api-types/gatewayclass.md b/site-src/api-types/gatewayclass.md index d30368b072..263dc60ebc 100644 --- a/site-src/api-types/gatewayclass.md +++ b/site-src/api-types/gatewayclass.md @@ -1,8 +1,10 @@ # GatewayClass -??? success "Standard Channel in v0.5.0+" - - The `GatewayClass` resource is Beta and part of the Standard Channel in `v0.5.0+`. +??? success "Standard Channel since v0.5.0" + + The `GatewayClass` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). [GatewayClass][gatewayclass] is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can diff --git a/site-src/api-types/grpcroute.md b/site-src/api-types/grpcroute.md index 1cb81da0e2..cf8be7fe45 100644 --- a/site-src/api-types/grpcroute.md +++ b/site-src/api-types/grpcroute.md @@ -1,10 +1,10 @@ # GRPCRoute -??? example "Experimental Channel in v0.6.0+" +??? success "Standard Channel since v1.1.0" - The `GRPCRoute` resource is Alpha and part of the Experimental Channel in - `v0.6.0+`. For more information on release channels, refer to the [related - documentation](/concepts/versioning). + The `GRPCRoute` resource is GA and has been part of the Standard Channel since + `v1.1.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). [GRPCRoute][grpcroute] is a Gateway API type for specifying routing behavior of gRPC requests from a Gateway listener to an API object, i.e. Service. diff --git a/site-src/api-types/httproute.md b/site-src/api-types/httproute.md index 8de0ebd9b5..f31c98718b 100644 --- a/site-src/api-types/httproute.md +++ b/site-src/api-types/httproute.md @@ -1,8 +1,10 @@ # HTTPRoute -??? success "Standard Channel in v0.5.0+" +??? success "Standard Channel since v0.5.0" - The `HTTPRoute` resource is Beta and part of the Standard Channel in `v0.5.0+`. + The `HTTPRoute` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). [HTTPRoute][httproute] is a Gateway API type for specifying routing behavior of HTTP requests from a Gateway listener to an API object, i.e. Service. @@ -225,9 +227,11 @@ on `weight` and other fields. #### Timeouts (optional) -??? example "Experimental Channel in v1.0.0+" +??? example "Experimental Channel since v1.0.0" - HTTPRoute timeouts are part of the Experimental Channel in `v1.0.0+`. + HTTPRoute timeouts have been part of the Experimental Channel since `v1.0.0`. + For more information on release channels, refer to our + [versioning guide](/concepts/versioning). HTTPRoute Rules include a `Timeouts` field. If unspecified, timeout behavior is implementation-specific. @@ -250,10 +254,11 @@ Reference the [timeouts][timeouts] API documentation for additional details. ##### Backend Protocol -??? example "Experimental Channel in v1.0.0+" - - This concept is part of the Experimental Channel in `v1.0.0+`. +??? example "Experimental Channel since v1.0.0" + This concept has been part of the Experimental Channel since `v1.0.0`. + For more information on release channels, refer to our + [versioning guide](/concepts/versioning). Some implementations may require the [backendRef][backendRef] to be labeled explicitly in order to route traffic using a certain protocol. For Kubernetes diff --git a/site-src/api-types/referencegrant.md b/site-src/api-types/referencegrant.md index 118fd390c2..31f4e18761 100644 --- a/site-src/api-types/referencegrant.md +++ b/site-src/api-types/referencegrant.md @@ -1,8 +1,10 @@ # ReferenceGrant -??? success "Standard Channel in v0.6.0+" +??? success "Standard Channel since v0.6.0" - The `ReferenceGrant` resource is Beta and part of the Standard Channel in `v0.6.0+`. + The `ReferenceGrant` resource is Beta and part of the + Standard Channel since `v0.6.0`. For more information on release + channels, refer to our [versioning guide](/concepts/versioning). !!! note This resource was originally named "ReferencePolicy". It was renamed diff --git a/site-src/blog/2021/introducing-v1alpha2.md b/site-src/blog/2021/introducing-v1alpha2.md index 3219b23e6e..e623f5e5cd 100644 --- a/site-src/blog/2021/introducing-v1alpha2.md +++ b/site-src/blog/2021/introducing-v1alpha2.md @@ -63,7 +63,7 @@ This is covered in more detail in [GEP 724](/geps/gep-709/). The `ReferenceGrant` resource described below is currently only included in the "Experimental" channel of Gateway API. For more information on release - channels, refer to the [related documentation](/concepts/versioning). + channels, refer to our [versioning guide](/concepts/versioning). It is quite challenging to cross namespace boundaries in a safe manner. With Gateway API, we had several key feature requests that required this capability. diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index e14525580f..779377ee9a 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -31,10 +31,11 @@ the cluster. ### GatewayClass -??? success "Standard Channel in v0.5.0+" - The `GatewayClass` resource is GA and has been part of the Standard Channel in - `v0.5.0+`. For more information on release channels, refer to the [related - documentation](/concepts/versioning). +??? success "Standard Channel since v0.5.0" + + The `GatewayClass` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). GatewayClass defines a set of Gateways that share a common configuration and behaviour. Each GatewayClass will be handled by a single controller, although @@ -55,10 +56,11 @@ IngressClass object. ### Gateway -??? success "Standard Channel in v0.5.0+" +??? success "Standard Channel since v0.5.0" + The `Gateway` resource is GA and has been part of the Standard Channel since - `v0.5.0`. For more information on release channels, refer to the [related - documentation](/concepts/versioning). + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). A Gateway describes how traffic can be translated to Services within the cluster. That is, it defines a request for a way to translate traffic from @@ -94,10 +96,11 @@ types may be added to the API in future. #### HTTPRoute -??? success "Standard Channel in v0.5.0+" - The `HTTPRoute` resource is GA and has been part of the Standard Channel in - `v0.5.0+`. For more information on release channels, refer to the [related - documentation](/concepts/versioning). +??? success "Standard Channel since v0.5.0" + + The `HTTPRoute` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). HTTPRoute is for multiplexing HTTP or terminated HTTPS connections. It's intended for use in cases where you want to inspect the HTTP stream and use HTTP request data @@ -106,11 +109,11 @@ modifying them in-flight. #### TLSRoute -??? example "Experimental Channel in v0.3.0+" +??? example "Experimental Channel since v0.3.0" The `TLSRoute` resource is Alpha and has been part of the Experimental - Channel since `v0.3.0+`. For more information on release channels, refer to - the [related documentation](/concepts/versioning). + Channel since `v0.3.0`. For more information on release channels, refer to + our [versioning guide](/concepts/versioning). TLSRoute is for multiplexing TLS connections, discriminated via SNI. It's intended for where you want to use the SNI as the main routing method, and are not interested @@ -119,11 +122,11 @@ connection is proxied without any inspection to the backend. #### TCPRoute and UDPRoute -??? example "Experimental Channel in v0.3.0+" +??? example "Experimental Channel since v0.3.0" The `TCPRoute` and `UDPRoute` resources are Alpha and have been part of the Experimental Channel since `v0.3.0`. For more information on release - channels, refer to the [related documentation](/concepts/versioning). + channels, refer to our [versioning guide](/concepts/versioning). TCPRoute (and UDPRoute) are intended for use for mapping one or more ports to a single backend. In this case, there is no discriminator you can @@ -135,11 +138,11 @@ is passed through to the backend. #### GRPCRoute -??? example "Experimental Channel in v0.6.0+" +??? success "Standard Channel since v1.1.0" - The `GRPCRoute` resource is Alpha and has been part of the Experimental - Channel since `v0.6.0`. For more information on release channels, refer to - the [related documentation](/concepts/versioning). + The `GRPCRoute` resource is GA and has been part of the Standard Channel since + `v1.1.0`. For more information on release channels, refer to our [versioning + guide](/concepts/versioning). GRPCRoute is for idiomatically routing gRPC traffic. Gateways supporting GRPCRoute are required to support HTTP/2 without an initial upgrade from HTTP/1, @@ -213,6 +216,7 @@ The following is required for a Route to be attached to a Gateway: #### Referencing Gateways ??? example "Experimental Channel" + The `Port` field described below is currently only included in the "Experimental" channel of Gateway API. For more information on release channels, refer to the [related documentation](/concepts/versioning/#adding-experimental-fields). diff --git a/site-src/concepts/use-cases.md b/site-src/concepts/use-cases.md index c6ed59284b..5a8fc12e89 100644 --- a/site-src/concepts/use-cases.md +++ b/site-src/concepts/use-cases.md @@ -30,10 +30,11 @@ separately.) ## Basic [north/south] use case -??? success "Standard Channel in v0.8.0+" +??? success "Standard Channel since v0.8.0" The [north/south] use case is fully supported by the Standard Channel - in `v0.8.0+`. + since `v0.8.0`. For more information on release + channels, refer to our [versioning guide](/concepts/versioning). Ana has created a microservice application which she wants to run in Kubernetes. Her application will be used by clients outside the cluster, and @@ -88,10 +89,11 @@ rollouts](/guides/traffic-splitting)). ## Multiple applications behind a single Gateway -??? success "Standard Channel in v0.8.0+" +??? success "Standard Channel since v0.8.0" The [north/south] use case is fully supported by the Standard Channel - in `v0.8.0+`. + since `v0.8.0`. For more information on release + channels, refer to our [versioning guide](/concepts/versioning). This is remarkably similar to the [basic north/south use case](#basic-northsouth-use-case), but there are multiple application teams: diff --git a/site-src/contributing/style-guide.md b/site-src/contributing/style-guide.md index 2b193d11b9..162d17d860 100644 --- a/site-src/contributing/style-guide.md +++ b/site-src/contributing/style-guide.md @@ -20,15 +20,17 @@ Wherever possible, we try to clearly state which release channel a resource or feature is currently included in, and which version it was introduced to that channel. To accomplish that, we use admonitions that look like this: -??? success "Standard Channel in v0.5.0+" +??? success "Standard Channel since v0.5.0" + The `HTTPRoute` resource is GA and has been part of the Standard Channel - since `v0.5.0`. For more information on release channels, refer to the - [related documentation](/concepts/versioning). + since `v0.5.0`. For more information on release channels, refer to our + [versioning guide](/concepts/versioning). + +??? example "Experimental Channel since v0.3.0" -??? example "Experimental Channel in v0.6.0+" - The `GRPCRoute` resource is Alpha and has been part of the Experimental - Channel since `v0.6.0`. For more information on release channels, refer to - the [related documentation](/concepts/versioning). + The `TLSRoute` resource is Alpha and has been part of the Experimental + Channel since `v0.3.0`. For more information on release channels, refer to + our [versioning guide](/concepts/versioning). ## Diagrams In many cases, diagrams are the best way to explain a concept. Unfortunately diff --git a/site-src/guides/backend-protocol.md b/site-src/guides/backend-protocol.md index c562bdf44a..e39f7c073c 100644 --- a/site-src/guides/backend-protocol.md +++ b/site-src/guides/backend-protocol.md @@ -1,8 +1,10 @@ # Backend Protocol -??? example "Experimental Channel in v1.0.0+" +??? example "Experimental Channel since v1.0.0" - This concept is part of the Experimental Channel in `v1.0.0+`. + This concept has been part of the Experimental Channel since `v1.0.0`. + For more information on release channels, refer to our + [versioning guide](/concepts/versioning). Not all implementations of Gateway API support automatic protocol selection. In some cases protocols are disabled without an explicit opt-in. diff --git a/site-src/guides/grpc-routing.md b/site-src/guides/grpc-routing.md index 4ed7992dd5..01d6fc747f 100644 --- a/site-src/guides/grpc-routing.md +++ b/site-src/guides/grpc-routing.md @@ -4,7 +4,7 @@ The `GRPCRoute` resource described below is currently only included in the "Experimental" channel of Gateway API. For more information on release - channels, refer to the [related documentation](/concepts/versioning). + channels, refer to our [versioning guide](/concepts/versioning). The [GRPCRoute resource](/api-types/grpcroute) allows you to match on gRPC traffic and direct it to Kubernetes backends. This guide shows how the GRPCRoute matches diff --git a/site-src/guides/tcp.md b/site-src/guides/tcp.md index 1c56c4f199..e1e66e8e4d 100644 --- a/site-src/guides/tcp.md +++ b/site-src/guides/tcp.md @@ -2,7 +2,7 @@ The `TCPRoute` resource described below is currently only included in the "Experimental" channel of Gateway API. For more information on release - channels, refer to the [related documentation](/concepts/versioning). + channels, refer to our [versioning guide](/concepts/versioning). Gateway API is designed to work with multiple protocols and [TCPRoute][tcproute] is one such route which allows for managing [TCP][tcp] traffic. diff --git a/site-src/guides/tls.md b/site-src/guides/tls.md index 2cb0baf7ab..28dc3deaeb 100644 --- a/site-src/guides/tls.md +++ b/site-src/guides/tls.md @@ -14,7 +14,7 @@ implementation(s) you're using with Gateway API. The `TLSRoute` and `BackendTLSPolicy` resources described below are currently only included in the "Experimental" channel of Gateway API. For more information on release - channels, refer to the [related documentation](/concepts/versioning). + channels, refer to our [versioning guide](/concepts/versioning). ## Client/Server and TLS diff --git a/site-src/index.md b/site-src/index.md index 540a5abf86..4863482305 100644 --- a/site-src/index.md +++ b/site-src/index.md @@ -25,7 +25,7 @@ same configuration. ## Gateway API for Ingress -??? success "Standard in v0.5.0+" +??? success "Standard Channel since v0.5.0" Gateway, GatewayClass, and HTTPRoute have been part of the Standard Channel of Gateway API since v0.5.0 and are considered stable APIs. For more @@ -54,10 +54,10 @@ resources), in the same cluster. ## Gateway API for Service Mesh (the [GAMMA initiative](/mesh/gamma)) -??? example "Standard in v1.2.0+" +??? success "Standard Channel since v1.2.0" The [GAMMA initiative](/mesh/gamma) work for supporting service mesh use cases - is part of the Standard Channel of Gateway API since v1.2.0 and are considered stable APIs. For more + has been part of the Standard Channel since v1.2.0 and are considered stable APIs. For more information refer to our [versioning guide](/concepts/versioning). Things are a bit different when using Gateway API to manage a [service diff --git a/site-src/mesh/index.md b/site-src/mesh/index.md index 87371a303f..3d4e07130b 100644 --- a/site-src/mesh/index.md +++ b/site-src/mesh/index.md @@ -1,11 +1,11 @@ # Gateway API for Service Mesh -??? example "Experimental in v0.8.0+" +??? success "Standard Channel since v1.2.0" - Gateway API support for service mesh use cases is _experimental_ in `v0.8.0+`. - It is possible that it will change; we do not recommend it in production - at this point. + The [GAMMA initiative](/mesh/gamma) work for supporting service mesh use cases + has been part of the Standard Channel since v1.2.0 and are considered stable APIs. For more + information refer to our [versioning guide](/concepts/versioning). The "[GAMMA initiative](/mesh/gamma)" refers to the group that is defining how Gateway API can be used for Service Mesh. To date, this group has been able to