From b79f5d94377354b58fd042cb2217928671da0662 Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Thu, 13 Jul 2023 12:33:48 -0600 Subject: [PATCH 1/2] Fix docs to make copying commands easier Problem: Commands and their output were saved in the same block, making it difficult for users to simply copy the commands. Solution: Separate commands and their output into separate blocks in the documentation. --- README.md | 2 +- conformance/README.md | 46 ++++++++++--------- .../provisioner/{provisioner.md => README.md} | 6 ++- .../control-data-plane-separation/design.md | 4 +- docs/building-the-image.md | 8 ++-- docs/developer/quickstart.md | 4 ++ docs/installation.md | 34 ++++++++------ docs/resource-validation.md | 16 +++++-- docs/running-on-kind.md | 4 +- examples/advanced-routing/README.md | 34 ++++++++++---- examples/cafe-example/README.md | 22 +++++---- examples/cross-namespace-routing/README.md | 37 +++++++++------ examples/http-header-filter/README.md | 14 ++++-- examples/https-termination/README.md | 41 +++++++++++------ examples/traffic-splitting/README.md | 16 ++++--- internal/mode/static/nginx/modules/README.md | 12 ++--- 16 files changed, 186 insertions(+), 114 deletions(-) rename conformance/provisioner/{provisioner.md => README.md} (98%) diff --git a/README.md b/README.md index 9f54e833b5..5f273de4d5 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ The SBOMs for the binaries are available in the releases page. The SBOMs are gen The SBOM for the Docker image is available in the [GitHub Container](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway) repository. The SBOM is generated using [syft](https://github.com/anchore/syft) and stored as an attestation in the image manifest. For example to retrieve the SBOM for `linux/amd64` and analyze it using [grype](https://github.com/anchore/grype) you can run the following command: -``` +```shell $ docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype ``` diff --git a/conformance/README.md b/conformance/README.md index a65bb21b71..8ea9fc32b6 100644 --- a/conformance/README.md +++ b/conformance/README.md @@ -11,9 +11,11 @@ List available commands: -```bash -$ make +```shell +make +``` +``` build-nkg-image Build NKG container and load it and NGINX container on configured kind cluster build-test-runner-image Build conformance test runner image cleanup-conformance-tests Clean up conformance tests fixtures @@ -50,18 +52,18 @@ update-nkg-manifest Update the NKG deployment manifest image name and ### Step 1 - Create a kind Cluster -```bash -$ make create-kind-cluster +```shell +make create-kind-cluster ``` ### Step 2 - Install Nginx Kubernetes Gateway to configured kind cluster #### *Option 1* Build and install Nginx Kubernetes Gateway from local to configured kind cluster -```bash -$ make install-nkg-local-build +```shell +make install-nkg-local-build ``` #### *Option 2* Install Nginx Kubernetes Gateway from local already built image to configured kind cluster -```bash -$ make install-nkg-local-no-build +```shell +make install-nkg-local-no-build ``` **Note:** You can optionally skip the actual *build* step. However, if choosing this option, the following step *must* be completed manually *before* the build step: @@ -80,34 +82,36 @@ this option, the following step *must* be completed manually *before* the build #### *Option 3* Install Nginx Kubernetes Gateway from edge to configured kind cluster You can also skip the build NKG image step and prepare the environment to instead use the `edge` image -```bash -$ make install-nkg-edge +```shell +make install-nkg-edge ``` ### Step 3 - Build conformance test runner image -```bash -$ make build-test-runner-image +```shell +make build-test-runner-image ``` ### Step 4 - Run Gateway conformance tests -```bash -$ make run-conformance-tests +```shell +make run-conformance-tests ``` ### Step 5 - Cleanup the conformance test fixtures and uninstall Nginx Kubernetes Gateway -```bash -$ make cleanup-conformance-tests -$ make uninstall-nkg +```shell +make cleanup-conformance-tests +``` +```shell +make uninstall-nkg ``` ### Step 6 - Revert changes to the NKG deployment manifest **Optional** Not required if using `edge` image **Warning**: `make undo-image-update` will hard reset changes to the deploy/manifests/deployment.yaml file! -```bash -$ make undo-image-update +```shell +make undo-image-update ``` ### Step 7 - Delete kind cluster -```bash -$ make delete-kind-cluster +```shell +make delete-kind-cluster ``` diff --git a/conformance/provisioner/provisioner.md b/conformance/provisioner/README.md similarity index 98% rename from conformance/provisioner/provisioner.md rename to conformance/provisioner/README.md index 8ff118dc4e..aa2a507420 100644 --- a/conformance/provisioner/provisioner.md +++ b/conformance/provisioner/README.md @@ -28,12 +28,14 @@ How to deploy: 1. Follow the [installation](/docs/installation.md) instructions up until the Deploy the NGINX Kubernetes Gateway Step to deploy prerequisites for both the static mode Deployments and the provisioner. 1. Deploy provisioner: - ``` + ```shell kubectl apply -f conformance/provisioner/provisioner.yaml ``` 1. Confirm the provisioner is running in nginx-gateway namespace: - ``` + ```shell kubectl get pods -n nginx-gateway + ``` + ``` NAME READY STATUS RESTARTS AGE nginx-gateway-provisioner-6c9d9fdcb8-b2pf8 1/1 Running 0 11m ``` diff --git a/design/control-data-plane-separation/design.md b/design/control-data-plane-separation/design.md index 0f503be9c5..0bf0c9f28a 100644 --- a/design/control-data-plane-separation/design.md +++ b/design/control-data-plane-separation/design.md @@ -748,7 +748,7 @@ configurations, we can work with them to add bigger config files to the test sui Config Push Benchmarks: -```bash +```shell cpu: Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz BenchmarkNginxConfig/../testdata/configs/bigger/1k.conf-2 1000000000 0.005241 ns/op 0 B/op 0 allocs/op BenchmarkNginxConfig/../testdata/configs/bigger/2k.conf-2 1000000000 0.01087 ns/op 0 B/op 0 allocs/op @@ -762,7 +762,7 @@ BenchmarkGetConfigFiles/GetConfigFiles#03-2 1000000000 Config Zip and Unzip Benchmarks: -```bash +```shell BenchmarkZipConfig/Zip_config../testdata/configs/bigger/1k.conf-2 1000000000 0.0001852 ns/op 0 B/op 0 allocs/op BenchmarkZipConfig/Zip_config../testdata/configs/bigger/2k.conf-2 1000000000 0.0000663 ns/op 0 B/op 0 allocs/op BenchmarkZipConfig/Zip_config../testdata/configs/bigger/3k.conf-2 1000000000 0.0000674 ns/op 0 B/op 0 allocs/op diff --git a/docs/building-the-image.md b/docs/building-the-image.md index 6700e192bb..eb8067239c 100644 --- a/docs/building-the-image.md +++ b/docs/building-the-image.md @@ -11,14 +11,16 @@ Before you can build the NGINX Kubernetes Gateway, make sure you have the follow 1. Clone the repo and change into the `nginx-kubernetes-gateway` directory: - ``` + ```shell git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git + ``` + ```shell cd nginx-kubernetes-gateway ``` 1. Build the image: - ``` + ```shell make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container ``` @@ -26,7 +28,7 @@ Before you can build the NGINX Kubernetes Gateway, make sure you have the follow 1. Push the image to your container registry: - ``` + ```shell docker push myregistry.example.com/nginx-kubernetes-gateway:edge ``` diff --git a/docs/developer/quickstart.md b/docs/developer/quickstart.md index a5a272328a..2328eed358 100644 --- a/docs/developer/quickstart.md +++ b/docs/developer/quickstart.md @@ -26,7 +26,11 @@ Follow these steps to set up your development environment. ```shell git clone https://github.com//nginx-kubernetes-gateway.git + ``` + ```shell cd nginx-kubernetes-gateway + ``` + ```shell make deps ``` diff --git a/docs/installation.md b/docs/installation.md index 5e32f797bc..306799a0bb 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -12,57 +12,61 @@ This guide walks you through how to install NGINX Kubernetes Gateway on a generi 1. Clone the repo and change into the `nginx-kubernetes-gateway` directory: - ``` + ```shell git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git + ``` + ```shell cd nginx-kubernetes-gateway ``` 1. Install the Gateway API resources from the standard channel (the CRDs and the validating webhook): - ``` + ```shell kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.7.1/standard-install.yaml ``` 1. Create the nginx-gateway Namespace: - ``` + ```shell kubectl apply -f deploy/manifests/namespace.yaml ``` 1. Create the njs-modules ConfigMap: - ``` + ```shell kubectl create configmap njs-modules --from-file=internal/mode/static/nginx/modules/src/httpmatches.js -n nginx-gateway ``` 1. Create the ConfigMap with the main NGINX configuration file: - ``` + ```shell kubectl apply -f deploy/manifests/nginx-conf.yaml ``` 1. Configure RBAC: - ``` + ```shell kubectl apply -f deploy/manifests/rbac.yaml ``` 1. Create the GatewayClass resource: - ``` + ```shell kubectl apply -f deploy/manifests/gatewayclass.yaml ``` 1. Deploy the NGINX Kubernetes Gateway: - ``` + ```shell kubectl apply -f deploy/manifests/deployment.yaml ``` 1. Confirm the NGINX Kubernetes Gateway is running in `nginx-gateway` namespace: - ``` + ```shell kubectl get pods -n nginx-gateway + ``` + ``` NAME READY STATUS RESTARTS AGE nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s ``` @@ -80,7 +84,7 @@ You can gain access to NGINX Kubernetes Gateway by creating a `NodePort` Service Create a Service with type `NodePort`: -``` +```shell kubectl apply -f deploy/manifests/service/nodeport.yaml ``` @@ -92,13 +96,13 @@ Create a Service with type `LoadBalancer` using the appropriate manifest for you - For GCP or Azure: - ``` + ```shell kubectl apply -f deploy/manifests/service/loadbalancer.yaml ``` Lookup the public IP of the load balancer, which is reported in the `EXTERNAL-IP` column in the output of the following command: - ``` + ```shell kubectl get svc nginx-gateway -n nginx-gateway ``` @@ -106,19 +110,19 @@ Create a Service with type `LoadBalancer` using the appropriate manifest for you - For AWS: - ``` + ```shell kubectl apply -f deploy/manifests/service/loadbalancer-aws-nlb.yaml ``` In AWS, the NLB DNS name will be reported by Kubernetes in lieu of a public IP in the `EXTERNAL-IP` column. To get the DNS name run: - ``` + ```shell kubectl get svc nginx-gateway -n nginx-gateway ``` In general, you should rely on the NLB DNS name, however for testing purposes you can resolve the DNS name to get the IP address of the load balancer: - ``` + ```shell nslookup ``` diff --git a/docs/resource-validation.md b/docs/resource-validation.md index e5a0b0da19..721fd20d4d 100644 --- a/docs/resource-validation.md +++ b/docs/resource-validation.md @@ -52,8 +52,10 @@ The Kubernetes API server validates Gateway API resources against the OpenAPI sc For example, if you create an HTTPRoute with an invalid hostname `cafe.!@#$%example.com`, the API server will reject it with the following error: -``` +```shell kubectl apply -f coffee-route.yaml +``` +``` The HTTPRoute "coffee" is invalid: spec.hostnames[0]: Invalid value: "cafe.!@#$%example.com": spec.hostnames[0] in body should match '^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$' ``` @@ -67,8 +69,10 @@ It validates Gateway API resources using advanced rules unavailable in the OpenA you create a Gateway resource with a TCP listener that configures a hostname, the webhook will reject it with the following error: -``` +```shell kubectl apply -f prod-gateway.yaml +``` +``` Error from server: error when creating "prod-gateway.yaml": admission webhook "validate.gateway.networking.k8s.io" denied the request: spec.listeners[1].hostname: Forbidden: should be empty for protocol TCP ``` @@ -84,8 +88,10 @@ performs the validation *after* the Kubernetes API server accepts the resource. Below is an example of how NKG rejects an invalid resource (a Gateway resource with a TCP listener that configures a hostname) with a Kubernetes event: -``` +```shell kubectl describe gateway prod-gateway +``` +``` . . . Events: Type Reason Age From Message @@ -114,8 +120,10 @@ This step catches the following cases of invalid values: Below is an example of how NGK rejects an invalid resource. The validation error is reported via the status: -``` +```shell kubectl describe httproutes.gateway.networking.k8s.io coffee +``` +``` . . . Status: Parents: diff --git a/docs/running-on-kind.md b/docs/running-on-kind.md index 7018363e3f..33297f3e62 100644 --- a/docs/running-on-kind.md +++ b/docs/running-on-kind.md @@ -11,7 +11,7 @@ This guide walks you through how to run NGINX Kubernetes Gateway on a [kind](htt Create a cluster with `kind`. You can follow their [instructions](https://kind.sigs.k8s.io/docs/user/quick-start/#creating-a-cluster), or run the following make command at the root of the repository: -``` +```shell make create-kind-cluster ``` @@ -23,7 +23,7 @@ Follow the [installation](./installation.md) instructions to deploy NGINX Kubern Forward local ports 8080 and 8443 to ports 80 and 443 of the nginx-gateway Pod: -``` +```shell kubectl -n nginx-gateway port-forward 8080:80 8443:443 ``` diff --git a/examples/advanced-routing/README.md b/examples/advanced-routing/README.md index 369cb8005c..6faa75973d 100644 --- a/examples/advanced-routing/README.md +++ b/examples/advanced-routing/README.md @@ -29,14 +29,16 @@ The cafe application consists of four Services: `coffee-v1-svc`, `coffee-v2-svc` 1. Create the coffee and the tea Deployments and Services: - ``` + ```shell kubectl apply -f cafe.yaml ``` 1. Check that the Pods are running in the `default` namespace: - ``` + ```shell kubectl -n default get pods + ``` + ``` NAME READY STATUS RESTARTS AGE coffee-v1-75869cf7ff-vlfpq 1/1 Running 0 17m coffee-v2-67499ff985-2k6cc 1/1 Running 0 17m @@ -48,13 +50,13 @@ The cafe application consists of four Services: `coffee-v1-svc`, `coffee-v2-svc` 1. Create the `Gateway`: - ``` + ```shell kubectl apply -f gateway.yaml ``` 1. Create the `HTTPRoute` resources: - ``` + ```shell kubectl apply -f cafe-routes.yaml ``` @@ -66,8 +68,10 @@ We will use `curl` to send requests to the `/coffee` and `/tea` endpoints of the Send a request with the header `version:v2` and confirm that the response comes from `coffee-v2-svc`: -```bash +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -H "version:v2" +``` +``` Server address: 10.116.2.67:8080 Server name: coffee-v2-67499ff985-gw6vt ... @@ -75,8 +79,10 @@ Server name: coffee-v2-67499ff985-gw6vt Send a request with the query parameter `TEST=v2` and confirm that the response comes from `coffee-v2-svc`: -```bash +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee?TEST=v2 +``` +``` Server address: 10.116.2.67:8080 Server name: coffee-v2-67499ff985-gw6vt ... @@ -84,8 +90,10 @@ Server name: coffee-v2-67499ff985-gw6vt Send a request without the header or the query parameter and confirm the response comes from `coffee-v1-svc`: -```bash +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee +``` +``` Server address: 10.116.2.70:8080 Server name: coffee-v1-75869cf7ff-vlfpq ... @@ -95,8 +103,10 @@ Server name: coffee-v1-75869cf7ff-vlfpq Send a POST request and confirm that the response comes from `tea-post-svc`: -```bash +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea -X POST +``` +``` Server address: 10.116.2.72:8080 Server name: tea-post-648dfcdd6c-2rlqb ... @@ -104,8 +114,10 @@ Server name: tea-post-648dfcdd6c-2rlqb Send a GET request and confirm that the response comes from `tea-svc`: -```bash +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea +``` +``` Server address: 10.116.3.30:8080 Server name: tea-6fb46d899f-hjzwr ... @@ -115,8 +127,10 @@ The `/tea` endpoint has routing rules configured for GET and POST requests. If y Send a PUT request and confirm the 404 Not Found response: -```bash +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea -X PUT +``` +``` 404 Not Found diff --git a/examples/cafe-example/README.md b/examples/cafe-example/README.md index 0e6f1210ca..dbb8e65a09 100644 --- a/examples/cafe-example/README.md +++ b/examples/cafe-example/README.md @@ -24,14 +24,16 @@ In this example we deploy NGINX Kubernetes Gateway, a simple web application, an 1. Create the coffee and the tea Deployments and Services: - ``` + ```shell kubectl apply -f cafe.yaml ``` 1. Check that the Pods are running in the `default` namespace: - ``` + ```shell kubectl -n default get pods + ``` + ``` NAME READY STATUS RESTARTS AGE coffee-6f4b79b975-2sb28 1/1 Running 0 12s tea-6fb46d899f-fm7zr 1/1 Running 0 12s @@ -41,13 +43,13 @@ In this example we deploy NGINX Kubernetes Gateway, a simple web application, an 1. Create the `Gateway`: - ``` + ```shell kubectl apply -f gateway.yaml ``` 1. Create the `HTTPRoute` resources: - ``` + ```shell kubectl apply -f cafe-routes.yaml ``` @@ -57,16 +59,20 @@ To access the application, we will use `curl` to send requests to the `coffee` a To get coffee: -``` +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee +``` +``` Server address: 10.12.0.18:80 Server name: coffee-7586895968-r26zn ``` To get tea: -``` +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea +``` +``` Server address: 10.12.0.19:80 Server name: tea-7cd44fcb4d-xfw2x ``` @@ -78,7 +84,7 @@ change an HTTPRoute's hostname to something that matches this wildcard and still For example, run the following command to open your editor and change the HTTPRoute's hostname to `foo.example.com`. -``` +```shell kubectl -n default edit httproute tea ``` @@ -88,7 +94,7 @@ Likewise, if you change the Gateway listener's hostname to something else, you c For example, run the following to open your editor and change the Gateway listener's hostname to `bar.example.com`: -``` +```shell kubectl -n default edit gateway gateway ``` diff --git a/examples/cross-namespace-routing/README.md b/examples/cross-namespace-routing/README.md index f2fa523bf8..97a6c533b9 100644 --- a/examples/cross-namespace-routing/README.md +++ b/examples/cross-namespace-routing/README.md @@ -25,14 +25,16 @@ in a different namespace from our HTTPRoutes. 1. Create the cafe namespace and cafe application: - ``` + ```shell kubectl apply -f cafe-ns-and-app.yaml ``` 1. Check that the Pods are running in the `cafe` namespace: - ``` + ```shell kubectl -n cafe get pods + ``` + ``` NAME READY STATUS RESTARTS AGE coffee-6f4b79b975-2sb28 1/1 Running 0 12s tea-6fb46d899f-fm7zr 1/1 Running 0 12s @@ -42,18 +44,18 @@ in a different namespace from our HTTPRoutes. 1. Create the `Gateway`: - ``` + ```shell kubectl apply -f gateway.yaml ``` 1. Create the `HTTPRoute` resources: - ``` + ```shell kubectl apply -f cafe-routes.yaml ``` 1. Create the `ReferenceGrant`: - ``` + ```shell kubectl apply -f reference-grant.yaml ``` This ReferenceGrant allows all HTTPRoutes in the `default` namespace to reference all Services in the `cafe` @@ -65,16 +67,20 @@ To access the application, we will use `curl` to send requests to the `coffee` a To get coffee: -``` +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee +``` +``` Server address: 10.12.0.18:80 Server name: coffee-7586895968-r26zn ``` To get tea: -``` +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea +``` +``` Server address: 10.12.0.19:80 Server name: tea-7cd44fcb4d-xfw2x ``` @@ -84,14 +90,15 @@ Server name: tea-7cd44fcb4d-xfw2x To restrict access to Services in the `cafe` Namespace, we can delete the ReferenceGrant we created in Step 3: -``` +```shell kubectl delete -f reference-grant.yaml ``` Now, if we try to access the application over HTTP, we will get an internal server error: -``` +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea - +``` +``` 500 Internal Server Error @@ -103,9 +110,10 @@ curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT You can also check the conditions of the HTTPRoutes `coffee` and `tea` to verify that the reference is not permitted: -``` +```shell kubectl describe httproute coffee - +``` +``` Condtions: Message: Backend ref to Service cafe/coffee not permitted by any ReferenceGrant Observed Generation: 1 @@ -115,9 +123,10 @@ Condtions: Controller Name: k8s-gateway.nginx.org/nginx-gateway-controller ``` -``` +```shell kubectl describe httproute tea - +``` +``` Condtions: Message: Backend ref to Service cafe/tea not permitted by any ReferenceGrant Observed Generation: 1 diff --git a/examples/http-header-filter/README.md b/examples/http-header-filter/README.md index 6267b7f73d..c5dbe520a8 100644 --- a/examples/http-header-filter/README.md +++ b/examples/http-header-filter/README.md @@ -25,14 +25,16 @@ headers to the request. 1. Create the headers Deployment and Service: - ``` + ```shell kubectl apply -f headers.yaml ``` 1. Check that the Pod is running in the `default` namespace: - ``` + ```shell kubectl -n default get pods + ``` + ``` NAME READY STATUS RESTARTS AGE headers-6f4b79b975-2sb28 1/1 Running 0 12s ``` @@ -41,13 +43,13 @@ headers to the request. 1. Create the `Gateway`: - ``` + ```shell kubectl apply -f gateway.yaml ``` 1. Create the `HTTPRoute` resources: - ``` + ```shell kubectl apply -f echo-route.yaml ``` @@ -58,8 +60,10 @@ our request. Notice our configured header values can be seen in the `requestHeaders` section below, and that the `User-Agent` header is absent. -``` +```shell curl -s --resolve echo.example.com:$GW_PORT:$GW_IP http://echo.example.com:$GW_PORT/headers -H "My-Cool-Header:my-client-value" -H "My-Overwrite-Header:dont-see-this" +``` +``` Headers: header 'Accept-Encoding' is 'compress' header 'My-cool-header' is 'my-client-value, this-is-an-appended-value' diff --git a/examples/https-termination/README.md b/examples/https-termination/README.md index 0fda433006..cff35339a8 100644 --- a/examples/https-termination/README.md +++ b/examples/https-termination/README.md @@ -27,14 +27,16 @@ reference a Secret in a different Namespace. 1. Create the coffee and the tea Deployments and Services: - ``` + ```shell kubectl apply -f cafe.yaml ``` 1. Check that the Pods are running in the `default` namespace: - ``` + ```shell kubectl -n default get pods + ``` + ``` NAME READY STATUS RESTARTS AGE coffee-6f4b79b975-2sb28 1/1 Running 0 12s tea-6fb46d899f-fm7zr 1/1 Running 0 12s @@ -43,7 +45,7 @@ reference a Secret in a different Namespace. ## 3. Configure HTTPS Termination and Routing 1. Create the Namespace `certificate` and a Secret with a TLS certificate and key: - ``` + ```shell kubectl apply -f certificate-ns-and-cafe-secret.yaml ``` @@ -51,7 +53,7 @@ reference a Secret in a different Namespace. > **Important**: This certificate and key are for demo purposes only. 1. Create the `ReferenceGrant`: - ``` + ```shell kubectl apply -f reference-grant.yaml ``` @@ -59,7 +61,7 @@ reference a Secret in a different Namespace. the `certificate` namespace. 1. Create the `Gateway` resource: - ``` + ```shell kubectl apply -f gateway.yaml ``` @@ -68,7 +70,7 @@ reference a Secret in a different Namespace. * `https` listener for HTTPS traffic. It terminates TLS connections using the `cafe-secret` we created in step 1. 1. Create the `HTTPRoute` resources: - ``` + ```shell kubectl apply -f cafe-routes.yaml ``` @@ -105,8 +107,10 @@ will use curl's `--include` option to print the response headers (we are interes To get a redirect for coffee: -``` +```shell curl --resolve cafe.example.com:$GW_HTTP_PORT:$GW_IP http://cafe.example.com:$GW_HTTP_PORT/coffee --include +``` +``` HTTP/1.1 302 Moved Temporarily ... Location: https://cafe.example.com:443/coffee @@ -115,8 +119,10 @@ Location: https://cafe.example.com:443/coffee To get a redirect for tea: -``` +```shell curl --resolve cafe.example.com:$GW_HTTP_PORT:$GW_IP http://cafe.example.com:$GW_HTTP_PORT/tea --include +``` +``` HTTP/1.1 302 Moved Temporarily ... Location: https://cafe.example.com:443/tea @@ -130,16 +136,20 @@ option to turn off certificate verification. To get coffee: -``` +```shell curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/coffee --insecure +``` +``` Server address: 10.12.0.18:80 Server name: coffee-7586895968-r26zn ``` To get tea: -``` +```shell curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/tea --insecure +``` +``` Server address: 10.12.0.19:80 Server name: tea-7cd44fcb4d-xfw2x ``` @@ -149,13 +159,15 @@ Server name: tea-7cd44fcb4d-xfw2x To restrict access to the `cafe-secret` in the `certificate` Namespace, we can delete the ReferenceGrant we created in Step 3: -``` +```shell kubectl delete -f reference-grant.yaml ``` Now, if we try to access the application over HTTPS, we will get a connection refused error: -``` +```shell curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/coffee --insecure -vvv +``` +``` ... curl: (7) Failed to connect to cafe.example.com port 443 after 0 ms: Connection refused ``` @@ -163,9 +175,10 @@ curl: (7) Failed to connect to cafe.example.com port 443 after 0 ms: Connection You can also check the conditions of the Gateway `https` Listener to verify the that the reference is not permitted: -``` +```shell kubectl describe gateway gateway - +``` +``` Name: https Conditions: Last Transition Time: 2023-06-26T20:23:56Z diff --git a/examples/traffic-splitting/README.md b/examples/traffic-splitting/README.md index 205554b9fe..5df6aff9d4 100644 --- a/examples/traffic-splitting/README.md +++ b/examples/traffic-splitting/README.md @@ -25,14 +25,16 @@ We will use `HTTPRoute` resources to split traffic between two versions of the a 1. Create the Cafe Deployments and Services: - ``` + ```shell kubectl apply -f cafe.yaml ``` 1. Check that the Pods are running in the `default` namespace: - ``` + ```shell kubectl -n default get pods + ``` + ``` NAME READY STATUS RESTARTS AGE coffee-v1-7c57c576b-rfjsh 1/1 Running 0 21m coffee-v2-698f66dc46-vcb6r 1/1 Running 0 21m @@ -42,13 +44,13 @@ We will use `HTTPRoute` resources to split traffic between two versions of the a 1. Create the `Gateway`: - ``` + ```shell kubectl apply -f gateway.yaml ``` 1. Create the `HTTPRoute` resources: - ``` + ```shell kubectl apply -f cafe-route.yaml ``` @@ -60,7 +62,7 @@ For example, the weights of 8 and 2, 16 and 4, or 32 and 8 all evaluate to the s To access the application, we will use `curl` to send requests to `/coffee`: -``` +```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee ``` @@ -85,13 +87,13 @@ of the `coffee-v2` backend to 80. Backends with equal weights will receive an eq 1. Apply the updated `HTTPRoute` resource: - ``` + ```shell kubectl apply -f cafe-route-equal-weight.yaml ``` 2. Test the application again: - ``` + ```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee ``` diff --git a/internal/mode/static/nginx/modules/README.md b/internal/mode/static/nginx/modules/README.md index 9626e86d87..6962bf78ed 100644 --- a/internal/mode/static/nginx/modules/README.md +++ b/internal/mode/static/nginx/modules/README.md @@ -39,7 +39,7 @@ To run unit tests against the [httpmatches](./src/httpmatches.js) modules you mu To run the unit tests: -```bash +```shell npm test ``` @@ -51,7 +51,7 @@ To debug on the command-line: - Set a breakpoint using the [debugger](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) statement. - Run the tests with the inspect argument: -```bash +```shell npx mocha inspect -r esm ``` @@ -71,19 +71,19 @@ You can add log statements to debug njs code at runtime. The following log funct Log at error level: -```bash +```shell r.error(string) ``` Log at info level: -```bash +```shell r.log(string) ``` Log at warn level: -```bash +```shell r.warn(string) ``` @@ -91,6 +91,6 @@ r.warn(string) This project uses [prettier](https://prettier.io/) to lint and format the JavaScript code. To format the code run: -```bash +```shell npm run format ``` From e8b4983445bb429e4140f466ef1f002eb5fed598 Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Thu, 13 Jul 2023 15:50:42 -0600 Subject: [PATCH 2/2] More suggestions --- README.md | 2 +- conformance/README.md | 20 ++++++++++---------- conformance/provisioner/README.md | 2 +- docs/building-the-image.md | 4 +--- docs/developer/quickstart.md | 14 ++++++-------- docs/developer/testing.md | 2 +- docs/installation.md | 2 +- docs/running-on-kind.md | 2 +- examples/advanced-routing/README.md | 2 +- examples/cafe-example/README.md | 2 +- examples/cross-namespace-routing/README.md | 6 +++--- examples/http-header-filter/README.md | 4 ++-- examples/https-termination/README.md | 14 +++++++------- examples/traffic-splitting/README.md | 6 +++--- 14 files changed, 39 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 5f273de4d5..024b1b87ce 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ The SBOM for the Docker image is available in the [GitHub Container](https://git For example to retrieve the SBOM for `linux/amd64` and analyze it using [grype](https://github.com/anchore/grype) you can run the following command: ```shell -$ docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype +docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype ``` ## Contacts diff --git a/conformance/README.md b/conformance/README.md index 8ea9fc32b6..629ed8e42d 100644 --- a/conformance/README.md +++ b/conformance/README.md @@ -52,17 +52,17 @@ update-nkg-manifest Update the NKG deployment manifest image name and ### Step 1 - Create a kind Cluster -```shell +```makefile make create-kind-cluster ``` ### Step 2 - Install Nginx Kubernetes Gateway to configured kind cluster #### *Option 1* Build and install Nginx Kubernetes Gateway from local to configured kind cluster -```shell +```makefile make install-nkg-local-build ``` #### *Option 2* Install Nginx Kubernetes Gateway from local already built image to configured kind cluster -```shell +```makefile make install-nkg-local-no-build ``` **Note:** You can optionally skip the actual *build* step. However, if choosing @@ -82,36 +82,36 @@ this option, the following step *must* be completed manually *before* the build #### *Option 3* Install Nginx Kubernetes Gateway from edge to configured kind cluster You can also skip the build NKG image step and prepare the environment to instead use the `edge` image -```shell +```makefile make install-nkg-edge ``` ### Step 3 - Build conformance test runner image -```shell +```makefile make build-test-runner-image ``` ### Step 4 - Run Gateway conformance tests -```shell +```makefile make run-conformance-tests ``` ### Step 5 - Cleanup the conformance test fixtures and uninstall Nginx Kubernetes Gateway -```shell +```makefile make cleanup-conformance-tests ``` -```shell +```makefile make uninstall-nkg ``` ### Step 6 - Revert changes to the NKG deployment manifest **Optional** Not required if using `edge` image **Warning**: `make undo-image-update` will hard reset changes to the deploy/manifests/deployment.yaml file! -```shell +```makefile make undo-image-update ``` ### Step 7 - Delete kind cluster -```shell +```makefile make delete-kind-cluster ``` diff --git a/conformance/provisioner/README.md b/conformance/provisioner/README.md index aa2a507420..bb5be928be 100644 --- a/conformance/provisioner/README.md +++ b/conformance/provisioner/README.md @@ -35,7 +35,7 @@ How to deploy: ```shell kubectl get pods -n nginx-gateway ``` - ``` + ```console NAME READY STATUS RESTARTS AGE nginx-gateway-provisioner-6c9d9fdcb8-b2pf8 1/1 Running 0 11m ``` diff --git a/docs/building-the-image.md b/docs/building-the-image.md index eb8067239c..40c2dfca3e 100644 --- a/docs/building-the-image.md +++ b/docs/building-the-image.md @@ -13,14 +13,12 @@ Before you can build the NGINX Kubernetes Gateway, make sure you have the follow ```shell git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git - ``` - ```shell cd nginx-kubernetes-gateway ``` 1. Build the image: - ```shell + ```makefile make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container ``` diff --git a/docs/developer/quickstart.md b/docs/developer/quickstart.md index 2328eed358..8781c523bf 100644 --- a/docs/developer/quickstart.md +++ b/docs/developer/quickstart.md @@ -26,11 +26,9 @@ Follow these steps to set up your development environment. ```shell git clone https://github.com//nginx-kubernetes-gateway.git - ``` - ```shell cd nginx-kubernetes-gateway ``` - ```shell + ```makefile make deps ``` @@ -40,7 +38,7 @@ Follow these steps to set up your development environment. To build the binary, run the make build command from the project's root directory: -```shell +```makefile make build ``` @@ -50,7 +48,7 @@ This command will build the binary and output it to the `/build/.out` directory. To build an NGINX Kubernetes Gateway container image from source run the following make command: -```shell +```makefile make TAG=$(whoami) container ``` @@ -60,7 +58,7 @@ This will build the docker image `nginx-kubernetes-gateway:`. 1. Create a `kind` cluster: - ```shell + ```makefile make create-kind-cluster ``` @@ -91,7 +89,7 @@ To make sure NKG is running properly, try out the [examples](/examples). To run all the unit tests, run the make unit-test command from the project's root directory: -```shell +```makefile make unit-test ``` @@ -105,7 +103,7 @@ To run Gateway API conformance tests, please follow the instructions on [this](/ To lint the code, run the following make command from the project's root directory: -```shell +```makefile make lint ``` diff --git a/docs/developer/testing.md b/docs/developer/testing.md index 6cd0c0b61c..8d124024dc 100644 --- a/docs/developer/testing.md +++ b/docs/developer/testing.md @@ -44,7 +44,7 @@ promoting efficient refactoring and continuous development. To run the unit tests, run the make unit-test command from the project's root directory: -```shell +```makefile make unit-test ``` diff --git a/docs/installation.md b/docs/installation.md index 306799a0bb..1b90541fa7 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -66,7 +66,7 @@ This guide walks you through how to install NGINX Kubernetes Gateway on a generi ```shell kubectl get pods -n nginx-gateway ``` - ``` + ```console NAME READY STATUS RESTARTS AGE nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s ``` diff --git a/docs/running-on-kind.md b/docs/running-on-kind.md index 33297f3e62..ad7b5671ed 100644 --- a/docs/running-on-kind.md +++ b/docs/running-on-kind.md @@ -11,7 +11,7 @@ This guide walks you through how to run NGINX Kubernetes Gateway on a [kind](htt Create a cluster with `kind`. You can follow their [instructions](https://kind.sigs.k8s.io/docs/user/quick-start/#creating-a-cluster), or run the following make command at the root of the repository: -```shell +```makefile make create-kind-cluster ``` diff --git a/examples/advanced-routing/README.md b/examples/advanced-routing/README.md index 6faa75973d..fabd77d957 100644 --- a/examples/advanced-routing/README.md +++ b/examples/advanced-routing/README.md @@ -38,7 +38,7 @@ The cafe application consists of four Services: `coffee-v1-svc`, `coffee-v2-svc` ```shell kubectl -n default get pods ``` - ``` + ```console NAME READY STATUS RESTARTS AGE coffee-v1-75869cf7ff-vlfpq 1/1 Running 0 17m coffee-v2-67499ff985-2k6cc 1/1 Running 0 17m diff --git a/examples/cafe-example/README.md b/examples/cafe-example/README.md index dbb8e65a09..f01224feb2 100644 --- a/examples/cafe-example/README.md +++ b/examples/cafe-example/README.md @@ -33,7 +33,7 @@ In this example we deploy NGINX Kubernetes Gateway, a simple web application, an ```shell kubectl -n default get pods ``` - ``` + ```console NAME READY STATUS RESTARTS AGE coffee-6f4b79b975-2sb28 1/1 Running 0 12s tea-6fb46d899f-fm7zr 1/1 Running 0 12s diff --git a/examples/cross-namespace-routing/README.md b/examples/cross-namespace-routing/README.md index 97a6c533b9..7d1bdb3674 100644 --- a/examples/cross-namespace-routing/README.md +++ b/examples/cross-namespace-routing/README.md @@ -34,7 +34,7 @@ in a different namespace from our HTTPRoutes. ```shell kubectl -n cafe get pods ``` - ``` + ```console NAME READY STATUS RESTARTS AGE coffee-6f4b79b975-2sb28 1/1 Running 0 12s tea-6fb46d899f-fm7zr 1/1 Running 0 12s @@ -113,7 +113,7 @@ You can also check the conditions of the HTTPRoutes `coffee` and `tea` to verify ```shell kubectl describe httproute coffee ``` -``` +```console Condtions: Message: Backend ref to Service cafe/coffee not permitted by any ReferenceGrant Observed Generation: 1 @@ -126,7 +126,7 @@ Condtions: ```shell kubectl describe httproute tea ``` -``` +```console Condtions: Message: Backend ref to Service cafe/tea not permitted by any ReferenceGrant Observed Generation: 1 diff --git a/examples/http-header-filter/README.md b/examples/http-header-filter/README.md index c5dbe520a8..56b7b62f6b 100644 --- a/examples/http-header-filter/README.md +++ b/examples/http-header-filter/README.md @@ -34,7 +34,7 @@ headers to the request. ```shell kubectl -n default get pods ``` - ``` + ```console NAME READY STATUS RESTARTS AGE headers-6f4b79b975-2sb28 1/1 Running 0 12s ``` @@ -63,7 +63,7 @@ is absent. ```shell curl -s --resolve echo.example.com:$GW_PORT:$GW_IP http://echo.example.com:$GW_PORT/headers -H "My-Cool-Header:my-client-value" -H "My-Overwrite-Header:dont-see-this" ``` -``` +```console Headers: header 'Accept-Encoding' is 'compress' header 'My-cool-header' is 'my-client-value, this-is-an-appended-value' diff --git a/examples/https-termination/README.md b/examples/https-termination/README.md index cff35339a8..2832af3ebe 100644 --- a/examples/https-termination/README.md +++ b/examples/https-termination/README.md @@ -36,7 +36,7 @@ reference a Secret in a different Namespace. ```shell kubectl -n default get pods ``` - ``` + ```console NAME READY STATUS RESTARTS AGE coffee-6f4b79b975-2sb28 1/1 Running 0 12s tea-6fb46d899f-fm7zr 1/1 Running 0 12s @@ -110,7 +110,7 @@ To get a redirect for coffee: ```shell curl --resolve cafe.example.com:$GW_HTTP_PORT:$GW_IP http://cafe.example.com:$GW_HTTP_PORT/coffee --include ``` -``` +```console HTTP/1.1 302 Moved Temporarily ... Location: https://cafe.example.com:443/coffee @@ -122,7 +122,7 @@ To get a redirect for tea: ```shell curl --resolve cafe.example.com:$GW_HTTP_PORT:$GW_IP http://cafe.example.com:$GW_HTTP_PORT/tea --include ``` -``` +```console HTTP/1.1 302 Moved Temporarily ... Location: https://cafe.example.com:443/tea @@ -139,7 +139,7 @@ To get coffee: ```shell curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/coffee --insecure ``` -``` +```console Server address: 10.12.0.18:80 Server name: coffee-7586895968-r26zn ``` @@ -149,7 +149,7 @@ To get tea: ```shell curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/tea --insecure ``` -``` +```console Server address: 10.12.0.19:80 Server name: tea-7cd44fcb4d-xfw2x ``` @@ -167,7 +167,7 @@ Now, if we try to access the application over HTTPS, we will get a connection re ```shell curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/coffee --insecure -vvv ``` -``` +```console ... curl: (7) Failed to connect to cafe.example.com port 443 after 0 ms: Connection refused ``` @@ -178,7 +178,7 @@ You can also check the conditions of the Gateway `https` Listener to verify the ```shell kubectl describe gateway gateway ``` -``` +```console Name: https Conditions: Last Transition Time: 2023-06-26T20:23:56Z diff --git a/examples/traffic-splitting/README.md b/examples/traffic-splitting/README.md index 5df6aff9d4..c8e00526d0 100644 --- a/examples/traffic-splitting/README.md +++ b/examples/traffic-splitting/README.md @@ -34,7 +34,7 @@ We will use `HTTPRoute` resources to split traffic between two versions of the a ```shell kubectl -n default get pods ``` - ``` + ```console NAME READY STATUS RESTARTS AGE coffee-v1-7c57c576b-rfjsh 1/1 Running 0 21m coffee-v2-698f66dc46-vcb6r 1/1 Running 0 21m @@ -68,14 +68,14 @@ curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT 80% of the responses will come from `coffee-v1`: -``` +```console Server address: 10.12.0.18:80 Server name: coffee-v1-7c57c576b-rfjsh ``` 20% of the responses will come from `coffee-v2`: -``` +```console Server address: 10.12.0.19:80 Server name: coffee-v2-698f66dc46-vcb6r ```