### Install Dependencies Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/README-mkdocs-linking.md Install the necessary Python libraries, `python-frontmatter` and `PyYAML`, using pip. ```bash pip install python-frontmatter PyYAML ``` -------------------------------- ### Setup KinD Cluster for Conformance Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/reports/v1.5/agentgateway-agentgateway/README.md Execute the setup script to bootstrap a KinD cluster with all necessary components for running conformance tests. ```sh ./controller/test/setup/setup-kind-ci.sh ``` -------------------------------- ### Inline Configuration Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-709/index.md This YAML example demonstrates an alternative to ReferenceGrant for representing cross-namespace relationships inline within an HTTPRoute and Service. ```yaml kind: HTTPRoute metadata: name: foo namespace: foo spec: rules: - matches: - path: /bar forwardTo: backend: - name: bar namespace: bar --- kind: Service metadata: name: baz namespace: baz annotations: gateway.networking.k8s.io/accept-forwarding-from: bar ``` -------------------------------- ### GRPCRouteMatch Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1016/index.md This example demonstrates how to configure a GRPCRouteMatch to match a gRPC request based on its service and a specific header. ```yaml match: method: type: Exact service: "foo" headers: - name: "version" value "v1" ``` -------------------------------- ### Example Conformance Report (v0.9.0) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709/index.md An example of a `ConformanceReport` for version v0.9.0 of an implementation, detailing HTTP profile results. ```yaml apiVersion: v1alpha1 kind: ConformanceReport implementation: organization: acme project: operator url: https://acme.com contact: - @acme/maintainers version: v0.9.0 date: "2023-02-28 20:29:41+00:00" gatewayAPIVersion: v0.8.0 gatewayAPIChannel: standard mode: default profiles: - name: http core: result: success summary: "some core functionality passed" statistics: passed: 18 skipped: 2 failed: 0 skippedTests: - CoreTest8 - CoreTest15 extended: result: success summary: "some extended features supported" statistics: passed: 8 skipped: 0 failed: 0 supportedFeatures: - ExtendedFeature1 - ExtendedFeature2 unsupportedFeatures: - ExtendedFeature3 - ExtendedFeature4 - ExtendedFeature5 ``` -------------------------------- ### Example Conformance Report (v1.0.0) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709/index.md An example of a `ConformanceReport` for version v1.0.0 of an implementation, showing HTTP and TCP profile results. ```yaml apiVersion: v1alpha1 kind: ConformanceReport implementation: organization: acme project: operator url: https://acme.com contact: - @acme/maintainers version: v1.0.0 date: "2023-06-1 20:29:41+00:00" gatewayAPIVersion: v1.0.0 gatewayAPIChannel: experimental mode: default profiles: - name: http core: result: success summary: "all core functionality passed" statistics: passed: 20 skipped: 0 failed: 0 extended: result: success summary: "all extended features supported" statistics: passed: 8 skipped: 0 failed: 0 supportedFeatures: - ExtendedFeature1 - ExtendedFeature2 - ExtendedFeature3 unsupportedFeatures: - ExtendedFeature4 - ExtendedFeature5 - name: tcp core: result: success summary: "all core functionality passed" statistics: passed: 4 skipped: 0 failed: 0 extended: result: skipped summary: "some extended features supported" statistics: passed: 2 skipped: 0 failed: 0 supportedFeatures: - ExtendedFeature1 - ExtendedFeature2 unsupportedFeatures: - ExtendedFeature3 ``` -------------------------------- ### Gateway Listener Status Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1713/index.md Example status of a Gateway listener, indicating acceptance and programming. ```yaml listeners: - name: gw-8080 conditions: - type: Accepted status: "True" reason: Accepted - type: Programmed status: "True" reason: Programmed AttachedListenerSets: 1 ``` -------------------------------- ### Install Netcat for UDP Communication Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/echo-basic/udpechoserver/README.md Install the netcat-traditional package within the jump pod to facilitate UDP communication. ```bash apt update apt install netcat-traditional ``` -------------------------------- ### ServiceBinding resource example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1294/index.md This example demonstrates the structure of a ServiceBinding resource, which can be used to bind traffic to an existing Service and define routing rules. ```yaml kind: ServiceBinding metadata: name: foo_binding spec: parentRefs: - kind: Service name: foo --- spec: parentRefs: - kind: ServiceBinding name: foo_binding rules: backendRefs: - kind: Service name: foo weight: 90 - kind: Service name: foo_v2 weight: 10 ``` -------------------------------- ### Install Gateway API Standard Channel Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/guides/getting-started/introduction.md Installs the standard release channel of Gateway API, which includes GA and beta resources. Use this command with kubectl. ```bash kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/standard-install.yaml ``` -------------------------------- ### TCPRoute Example with Address Matching Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-735/index.md Illustrates a TCPRoute configuration using address matching for source and destination IP addresses, including a named address type. This example demonstrates the practical application of AddressRouteMatches. ```yaml apiVersion: gateway.networking.k8s.io/v1alpha2 kind: TCPRoute metadata: name: matching spec: rules: - matches: - sourceAddresses: - value: "192.168.1.1" - value: "FE80::0202:B3FF:FE1E:8329" - type: NamedAddress value: "my-custom-name" destinationAddresses: - value: "10.96.0.1" backendRefs: - name: my-service port: 8080 ``` -------------------------------- ### GitHub Milestone Description Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/RELEASE_MANAGEMENT.md Example of how to format the description for a GitHub Milestone, including assigning the release manager, listing new experimental and graduated features, and specifying a feature freeze date. This helps communicate release themes and important notes to the community. ```console release-manager: @ This milestone introduces the following new experimental features: * * * This milestone graduates the following features: * * feature-freeze: ``` -------------------------------- ### GRPCRoute Rule Matches Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/reference/api-types/grpcroute.md Illustrates a GRPCRoute rule with matches based on gRPC method and headers. ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: GRPCRoute ... spec: rules: - matches: - method: service: com.example.User method: Login headers: - name: version value: "2" - method: service: com.example.v2.User method: Login ``` -------------------------------- ### Client GET Request for Simple CORS Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1767/index.md Example of a client GET request to a resource configured for simple CORS. The 'Origin' header is included to trigger CORS handling. ```http GET /resource/foo HTTP/1.1 Host: http.route.cors.com Origin: https://foo.example ``` -------------------------------- ### Build and Serve Documentation Locally Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/contributing/devguide.md Install Hugo and run this command to manually preview documentation changes locally. ```shell make docs ``` -------------------------------- ### Gateway Response for Simple CORS Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1767/index.md Example of a gateway response to a simple cross-origin GET request. It includes CORS headers like 'Access-Control-Allow-Origin'. ```http HTTP/1.1 200 OK Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, HEAD, POST Access-Control-Allow-Headers: Accept,Accept-Language,Content-Language,Content-Type,Range ``` -------------------------------- ### Combine Query Params with Path Matching Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/guides/user-guides/http-query-param-matching.md Match requests based on both query parameters and URL path prefix. This example routes to infra-backend-v1 if 'animal=whale' and the path starts with '/path1'. ```yaml - matches: - path: type: PathPrefix value: /path1 queryParams: - name: animal value: whale backendRefs: - name: infra-backend-v1 port: 8080 ``` -------------------------------- ### Configure Conformance Tests with Supported Features (Golang Library) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709/index.md Initialize and run the conformance test suite using `suite.New` by specifying supported features instead of unsupported ones. ```go cSuite, err := suite.New(suite.Options{ GatewayClassName: "acme", Profiles: sets.New( HTTP, TCP, ), SupportedFeatures: sets.New( suite.SupportHTTPRouteMethodMatching, ), // other options }) ``` -------------------------------- ### AllowMethods Configuration Example (Specific Methods) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1767/index.md Specifies allowed HTTP methods for CORS requests, returned in the Access-Control-Allow-Methods header. Methods are case-sensitive. Safelisted methods (GET, HEAD, POST) are always allowed. ```go AllowMethods []HTTPMethod `json:"allowMethods,omitempty"` ``` -------------------------------- ### Run Conformance Tests via Command Line (Layer7 Profile) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709/index.md Execute the conformance test suite using the `go test` command with specific arguments for gateway class and conformance profile. ```console $ go test ./conformance/... -args -gateway-class=acme -conformance-profile=Layer7 ``` -------------------------------- ### Run Conformance Tests via Command Line (Extended Profiles) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709/index.md Execute the conformance test suite using the `go test` command with multiple extended conformance profiles and unsupported features. ```console $ go test ./conformance/... -args \ -gateway-class=acme \ -conformance-profiles=HTTP,TCP \ -unsupported-features=HTTPResponseHeaderModification,HTTPRouteMethodMatching,HTTPRouteQueryParamMatching, ``` -------------------------------- ### Combine Path, Header, and Query Params Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/guides/user-guides/http-query-param-matching.md Match requests using a combination of path, header, and query parameters. This example routes to infra-backend-v3 if the path starts with '/path2', the 'version' header is 'two', and 'animal=whale'. ```yaml - matches: - path: type: PathPrefix value: /path2 headers: - name: version value: two queryParams: - name: animal value: whale backendRefs: - name: infra-backend-v3 port: 8080 ``` -------------------------------- ### Gateway and HTTPRoute Configuration for Traffic Matching Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/docs/concepts/traffic-matching.md This example demonstrates a Gateway with two HTTP listeners, one for a specific hostname and another for a wildcard. It also shows two HTTPRoutes, one attached to the specific listener and another to the wildcard listener, illustrating how traffic is directed based on hostname and path matching. ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: example-com namespace: default spec: listeners: - name: specific hostname: specific.example.com protocol: HTTP port: 80 - name: wildcard hostname: *.example.com protocol: HTTP port: 80 --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: specific namespace: default spec: parentRefs: - name: example-com rules: - matches: - path: type: Exact value: /specific backendRefs: - name: specific port: 8080 --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: wildcard namespace: default spec: parentRefs: - name: example-com rules: - matches: - path: type: prefix value: / backendRefs: - name: prefix port: 8080 ``` -------------------------------- ### GRPCRoute Status Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/reference/api-types/grpcroute.md Example illustrating the status of a GRPCRoute, showing its acceptance by a specific Gateway. ```APIDOC ## Examples The following example indicates GRPCRoute "grpc-example" has been accepted by Gateway "gw-example" in namespace "gw-example-ns": ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: GRPCRoute metadata: name: grpc-example ... status: parents: - parentRefs: name: gw-example namespace: gw-example-ns conditions: - type: Accepted status: "True" ``` ``` -------------------------------- ### Bootstrap KinD Cluster Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/reports/v1.5/kgateway/README.md Set up a KinD cluster with all necessary components installed using the provided make command. ```sh make setup-base ``` -------------------------------- ### Clone Repository and Setup Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/reports/v1.5/varnish-software-varnish-gateway/README.md Clone the Varnish Gateway repository, checkout a specific version, and create a kind cluster with Gateway API CRDs. ```bash git clone https://github.com/varnish/gateway cd gateway git checkout v0.20.0 make kind-create ``` -------------------------------- ### Run Conformance Tests (Default Mode) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/reports/v1.5/envoy-gateway/README.md Execute the experimental conformance tests using the default controller namespace deployment mode. ```bash KUBE_DEPLOY_PROFILE=default CONFORMANCE_REPORT_PATH=conformance-report-k8s.yaml make experimental-conformance ``` -------------------------------- ### Run Conformance Tests (Gateway Namespace Mode) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/reports/v1.5/envoy-gateway/README.md Execute the experimental conformance tests using the gateway namespace deployment mode. ```bash KUBE_DEPLOY_PROFILE=gateway-namespace-mode CONFORMANCE_REPORT_PATH=conformance-report-k8s.yaml make experimental-conformance ``` -------------------------------- ### Simple Cross-Origin GET Request Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1767/index.md A client sends a simple GET request with an Origin header for cross-origin access. ```http GET /resource/foo HTTP/1.1 Host: http.route.cors.com Origin: https://foo.example ``` -------------------------------- ### Load and Run WASM Wizard Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/static/wizard/index.html Fetches the 'main.wasm' file, instantiates it using WebAssembly, and runs the Go program. Includes error handling for loading and execution. ```javascript const statusEl = document.getElementById('wizard-data-status'); statusEl.textContent = 'Loading…'; const go = new Go(); fetch('main.wasm') .then(function (r) { if (!r.ok) throw new Error('main.wasm not found (404). Run: make wizard-wasm'); return WebAssembly.instantiateStreaming(r, go.importObject); }) .then(function (result) { go.run(result.instance); }) .catch(function (err) { statusEl.textContent = err.message || 'Could not load wizard. Run: make wizard-wasm. Then serve from site/static/wizard/ (e.g. cd site/static/wizard && python3 -m http.server 8000) and open http://localhost:8000/'; document.getElementById('recommend-btn').disabled = false; window.wizardResize(); }); ``` -------------------------------- ### Example UDP Echo Server Response Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/echo-basic/udpechoserver/README.md This is an example of the JSON response received after sending a UDP message to the echo server. ```json {"request":"Hello World\n","namespace":"default","ingress":"","service":"udp-echo","pod":"udp-echo-0"} ``` -------------------------------- ### Configure Conformance Tests as Golang Library (Extended Profiles) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709/index.md Initialize and run the conformance test suite within your Golang project using `suite.New` with multiple extended profiles and unsupported features specified. ```go cSuite, err := suite.New(suite.Options{ GatewayClassName: "acme", Profiles: sets.New( HTTP, TCP, ), UnsupportedFeatures: sets.New( suite.SupportHTTPResponseHeaderModification, suite.SupportHTTPRouteMethodMatching, suite.SupportHTTPRouteQueryParamMatching, ), // other options }) require.NoError(t, err, "misconfigured conformance test suite") cSuite.Setup(t) for i := 0; i < len(tests.ConformanceTests); i++ { test := tests.ConformanceTests[i] test.Run(t, cSuite) } ``` -------------------------------- ### Build and Deploy Varnish Gateway Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/reports/v1.5/varnish-software-varnish-gateway/README.md Build the operator and chaperone images, load them into the kind cluster, and deploy the Varnish Gateway. ```bash make docker make kind-load make kind-deploy ``` -------------------------------- ### Configure Conformance Tests as Golang Library (Layer7 Profile) Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709/index.md Initialize and run the conformance test suite within your Golang project using the `suite.New` function with specified options for gateway class and profiles. ```go cSuite, err := suite.New(suite.Options{ GatewayClassName: "acme", Profiles: sets.New(Layer7), // other options }) require.NoError(t, err, "misconfigured conformance test suite") cSuite.Setup(t) for i := 0; i < len(tests.ConformanceTests); i++ { test := tests.ConformanceTests[i] test.Run(t, cSuite) } ``` -------------------------------- ### UDPRoute Accepted Status Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/reference/api-types/udproute.md This example shows how a UDPRoute is marked as 'Accepted' by a specific Gateway. It indicates that the Gateway controller has processed and acknowledged the UDPRoute. ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: UDPRoute metadata: name: udp-example ... status: parents: - parentRef: name: gw-example namespace: gw-example-ns conditions: - type: Accepted status: "True" ``` -------------------------------- ### Run Conformance Tests Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/reports/v1.5/kgateway/README.md Execute the conformance tests for kgateway using the make command. ```sh make conformance ``` -------------------------------- ### Ingress Resource Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/guides/getting-started/migrating-from-ingress.md An example Ingress resource defining TLS termination, TLS redirect annotation, and routing rules for multiple hostnames and paths. ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: example-ingress annotations: example-ingress-controller.example.org/tls-redirect: "True" spec: ingressClassName: prod tls: - hosts: - foo.example.com - bar.example.com secretName: example-com rules: - host: foo.example.com http: paths: - path: / pathType: Prefix backend: service: name: foo-app port: number: 80 - path: /orders pathType: Prefix backend: service: name: foo-orders-app port: number: 80 - host: bar.example.com http: paths: - path: / pathType: Prefix backend: service: name: bar-app port: number: 80 ``` -------------------------------- ### Mermaid Diagram Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/contributing/style-guide.md Embed Mermaid diagrams directly in documentation for maintainable and visually clear explanations of concepts. This example shows a basic flowchart. ```mermaid flowchart TD Start --> Stop ``` -------------------------------- ### Install Gateway API Experimental Channel Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/guides/getting-started/introduction.md Installs the experimental release channel of Gateway API, including experimental resources and fields. Use this command with kubectl. ```bash kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml ``` -------------------------------- ### Prepare Documentation Script Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/README-mkdocs-linking.md Execute the `--prepare` command to scan the documentation directory, inject missing page IDs into frontmatter, and update the `hack/page_id_map.json` file. ```bash PYTHONPATH=hack python3 hack/mkdocs_linking.py --prepare ``` -------------------------------- ### AllowOrigins Configuration Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1767/index.md Configures the Access-Control-Allow-Origin header. Supports wildcard '*' or specific origins. When credentials are allowed, the origin must match exactly. ```go AllowOrigins []string `json:"allowOrigins,omitempty"` ``` -------------------------------- ### HTTPRoute for foo.example.com Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/site/content/en/guides/user-guides/http-routing.md This HTTPRoute resource matches traffic for 'foo.example.com' and forwards requests starting with '/login' to the 'foo-svc' Kubernetes Service. It demonstrates host and path-based matching. ```yaml apiVersion: gateway.networking.k8s.io/v1beta1 kind: HTTPRoute metadata: name: foo-route namespace: default spec: parentRefs: - name: prod-web hostnames: - foo.example.com rules: - matches: - path: type: PathPrefix value: /login backendRefs: - name: foo-svc port: 8080 ``` -------------------------------- ### Install and Use Kubernetes Release Notes Generator Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/RELEASE.md Installs the release-notes tool and generates changelog entries for a specific repository and branch. Ensure you have a GitHub token set. ```bash go install k8s.io/release/cmd/release-notes@latest export GITHUB_TOKEN=your_token_here release-notes generate \ --repo gateway-api --org kubernetes-sigs \ --branch release-1.X \ --start-sha EXAMPLE_COMMIT --end-sha EXAMPLE_COMMIT \ --repo-path . \ --output relnotes.md ``` -------------------------------- ### CORS Response Headers Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1767/index.md Example of cross-origin response headers added by the server after a successful request. These headers inform the client about allowed origins, credentials, methods, and more. ```http Access-Control-Allow-Origin: https://foo.example Access-Control-Allow-Credentials: true Access-Control-Allow-Methods: GET, PUT, POST, DELETE, PATCH, OPTIONS Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization Access-Control-Expose-Headers: Content-Security-Policy ``` -------------------------------- ### Actual Cross-Origin Request Example Source: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1767/index.md An example of an actual cross-origin request that would follow a successful preflight check. Includes essential headers like Origin and Authorization. ```http PUT /resource/foo HTTP/1.1 Host: http.route.cors.com Keep-Alive: timeout=5, max=1000 Origin: https://foo.example Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l ```