From 35ecbde77763b9014537990cb203db2b50b126f8 Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Tue, 16 Aug 2022 10:49:40 -0600 Subject: [PATCH 1/6] Move parts of the README into separate docs --- README.md | 147 +------------------------------------ docs/building-the-image.md | 33 +++++++++ docs/installation.md | 103 ++++++++++++++++++++++++++ 3 files changed, 140 insertions(+), 143 deletions(-) create mode 100644 docs/building-the-image.md create mode 100644 docs/installation.md diff --git a/README.md b/README.md index 417db21ab9..331bfc3bc1 100644 --- a/README.md +++ b/README.md @@ -7,147 +7,8 @@ NGINX Kubernetes Gateway is an open-source project that provides an implementati > Warning: This project is actively in development (pre-alpha feature state) and should not be deployed in a production environment. > All APIs, SDKs, designs, and packages are subject to change. -# Run NGINX Kubernetes Gateway +## Run NGINX Kubernetes Gateway -## Prerequisites - -Before you can build and run the NGINX Kubernetes Gateway, make sure you have the following software installed on your machine: -- [git](https://git-scm.com/) -- [GNU Make](https://www.gnu.org/software/software.html) -- [Docker](https://www.docker.com/) v18.09+ -- [kubectl](https://kubernetes.io/docs/tasks/tools/) - -## Build the image - -1. Clone the repo and change into the `nginx-kubernetes-gateway` directory: - - ``` - git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git - cd nginx-kubernetes-gateway - ``` - -1. Build the image: - - ``` - make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container - ``` - - Set the `PREFIX` variable to the name of the registry you'd like to push the image to. By default, the image will be named `nginx-kubernetes-gateway:0.0.1`. - -1. Push the image to your container registry: - - ``` - docker push myregistry.example.com/nginx-kubernetes-gateway:0.0.1 - ``` - - Make sure to substitute `myregistry.example.com/nginx-kubernetes-gateway` with your private registry. - -## Deploy NGINX Kubernetes Gateway - -You can deploy NGINX Kubernetes Gateway on an existing Kubernetes 1.16+ cluster. The following instructions walk through the steps for deploying on a [kind](https://kind.sigs.k8s.io/) cluster. - -1. Load the NGINX Kubernetes Gateway image onto your kind cluster: - - ``` - kind load docker-image nginx-kubernetes-gateway:0.0.1 - ``` - - Make sure to substitute the image name with the name of the image you built. - -1. Install the Gateway CRDs: - - ``` - kubectl apply -k "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.0" - ``` - -1. Create the nginx-gateway namespace: - - ``` - kubectl apply -f deploy/manifests/namespace.yaml - ``` - -1. Create the njs-modules configmap: - - ``` - kubectl create configmap njs-modules --from-file=internal/nginx/modules/src/httpmatches.js -n nginx-gateway - ``` - -1. Create the GatewayClass resource: - - ``` - kubectl apply -f deploy/manifests/gatewayclass.yaml - ``` - -1. Deploy the NGINX Kubernetes Gateway: - - Before deploying, make sure to update the Deployment spec in `nginx-gateway.yaml` to reference the image you built. - - ``` - kubectl apply -f deploy/manifests/nginx-gateway.yaml - ``` - -1. Confirm the NGINX Kubernetes Gateway is running in `nginx-gateway` namespace: - - ``` - kubectl get pods -n nginx-gateway - NAME READY STATUS RESTARTS AGE - nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s - ``` - -## Expose NGINX Kubernetes Gateway - -You can gain access to NGINX Kubernetes Gateway by creating a `NodePort` Service or a `LoadBalancer` Service. - -### Create a NodePort Service - -Create a service with type `NodePort`: - -``` -kubectl apply -f deploy/manifests/service/nodeport.yaml -``` - -A `NodePort` service will randomly allocate one port on every node of the cluster. To access NGINX Kubernetes Gateway, use an IP address of any node in the cluster along with the allocated port. - -### Create a LoadBalancer Service - -Create a service with type `LoadBalancer` using the appropriate manifest for your cloud provider. - -- For GCP or Azure: - - ``` - kubectl apply -f deploy/manifests/service/loadbalancer.yaml - ``` - - Lookup the public IP of the load balancer: - - ``` - kubectl get svc nginx-gateway -n nginx-gateway - ``` - - Use the public IP of the load balancer to access NGINX Kubernetes Gateway. - -- For AWS: - - ``` - 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. To get the DNS name run: - - ``` - 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: - - ``` - nslookup - ``` - -# Test NGINX Kubernetes Gateway - -To test the NGINX Kubernetes Gateway run: - -``` -make unit-test -``` +1. [Build](docs/building-the-image.md) the NGINX Kubernetes Gateway container image. +2. [Install](docs/installation.md) NGINX Kubernetes Gateway. +3. Deploy various [examples](examples). diff --git a/docs/building-the-image.md b/docs/building-the-image.md new file mode 100644 index 0000000000..35fad820e4 --- /dev/null +++ b/docs/building-the-image.md @@ -0,0 +1,33 @@ +# Building the Image + +## Prerequisites + +Before you can build the NGINX Kubernetes Gateway, make sure you have the following software installed on your machine: +- [git](https://git-scm.com/) +- [GNU Make](https://www.gnu.org/software/software.html) +- [Docker](https://www.docker.com/) v18.09+ + +## Steps + +1. Clone the repo and change into the `nginx-kubernetes-gateway` directory: + + ``` + git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git + cd nginx-kubernetes-gateway + ``` + +1. Build the image: + + ``` + make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container + ``` + + Set the `PREFIX` variable to the name of the registry you'd like to push the image to. By default, the image will be named `nginx-kubernetes-gateway:0.0.1`. + +1. Push the image to your container registry: + + ``` + docker push myregistry.example.com/nginx-kubernetes-gateway:0.0.1 + ``` + + Make sure to substitute `myregistry.example.com/nginx-kubernetes-gateway` with your private registry. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000000..009763bd14 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,103 @@ +# Installation + +## Deploy the Gateway + +You can deploy NGINX Kubernetes Gateway on an existing Kubernetes 1.16+ cluster. The following instructions walk through the steps for deploying on a [kind](https://kind.sigs.k8s.io/) cluster. + +1. Load the NGINX Kubernetes Gateway image onto your kind cluster: + + ``` + kind load docker-image nginx-kubernetes-gateway:0.0.1 + ``` + + Make sure to substitute the image name with the name of the image you built. + +1. Install the Gateway CRDs: + + ``` + kubectl apply -k "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.0" + ``` + +1. Create the nginx-gateway namespace: + + ``` + kubectl apply -f deploy/manifests/namespace.yaml + ``` + +1. Create the njs-modules configmap: + + ``` + kubectl create configmap njs-modules --from-file=internal/nginx/modules/src/httpmatches.js -n nginx-gateway + ``` + +1. Create the GatewayClass resource: + + ``` + kubectl apply -f deploy/manifests/gatewayclass.yaml + ``` + +1. Deploy the NGINX Kubernetes Gateway: + + Before deploying, make sure to update the Deployment spec in `nginx-gateway.yaml` to reference the image you built. + + ``` + kubectl apply -f deploy/manifests/nginx-gateway.yaml + ``` + +1. Confirm the NGINX Kubernetes Gateway is running in `nginx-gateway` namespace: + + ``` + kubectl get pods -n nginx-gateway + NAME READY STATUS RESTARTS AGE + nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s + ``` + +## Expose NGINX Kubernetes Gateway + +You can gain access to NGINX Kubernetes Gateway by creating a `NodePort` Service or a `LoadBalancer` Service. + +### Create a NodePort Service + +Create a service with type `NodePort`: + +``` +kubectl apply -f deploy/manifests/service/nodeport.yaml +``` + +A `NodePort` service will randomly allocate one port on every node of the cluster. To access NGINX Kubernetes Gateway, use an IP address of any node in the cluster along with the allocated port. + +### Create a LoadBalancer Service + +Create a service with type `LoadBalancer` using the appropriate manifest for your cloud provider. + +- For GCP or Azure: + + ``` + kubectl apply -f deploy/manifests/service/loadbalancer.yaml + ``` + + Lookup the public IP of the load balancer: + + ``` + kubectl get svc nginx-gateway -n nginx-gateway + ``` + + Use the public IP of the load balancer to access NGINX Kubernetes Gateway. + +- For AWS: + + ``` + 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. To get the DNS name run: + + ``` + 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: + + ``` + nslookup + ``` \ No newline at end of file From dfb89a58f9a13b4d70ee64835afd2f3b88a85ed6 Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Tue, 16 Aug 2022 15:44:36 -0600 Subject: [PATCH 2/6] Add kubectl as a prerequisite --- docs/installation.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/installation.md b/docs/installation.md index 009763bd14..179d3560d9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,5 +1,10 @@ # Installation +## Prerequisites + +Before you can install the NGINX Kubernetes Gateway, make sure you have the following software installed on your machine: +- [kubectl](https://kubernetes.io/docs/tasks/tools/) + ## Deploy the Gateway You can deploy NGINX Kubernetes Gateway on an existing Kubernetes 1.16+ cluster. The following instructions walk through the steps for deploying on a [kind](https://kind.sigs.k8s.io/) cluster. From cbbdc43d84ddfbfe3ba3f8f934b120bf929a3c98 Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Tue, 16 Aug 2022 16:01:38 -0600 Subject: [PATCH 3/6] Remove private --- docs/building-the-image.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/building-the-image.md b/docs/building-the-image.md index 35fad820e4..2a99bb4776 100644 --- a/docs/building-the-image.md +++ b/docs/building-the-image.md @@ -30,4 +30,4 @@ Before you can build the NGINX Kubernetes Gateway, make sure you have the follow docker push myregistry.example.com/nginx-kubernetes-gateway:0.0.1 ``` - Make sure to substitute `myregistry.example.com/nginx-kubernetes-gateway` with your private registry. \ No newline at end of file + Make sure to substitute `myregistry.example.com/nginx-kubernetes-gateway` with your registry. \ No newline at end of file From 974c4590b5890b05af76ab434d7b9dc027ffa05e Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Tue, 16 Aug 2022 16:10:25 -0600 Subject: [PATCH 4/6] Clarify about EXTERNAL-IP column --- docs/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 179d3560d9..4370f4ed9d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -81,7 +81,7 @@ Create a service with type `LoadBalancer` using the appropriate manifest for you kubectl apply -f deploy/manifests/service/loadbalancer.yaml ``` - Lookup the public IP of the load balancer: + Lookup the public IP of the load balancer, which is reported in the `EXTERNAL-IP` column in the output of the following command: ``` kubectl get svc nginx-gateway -n nginx-gateway @@ -95,7 +95,7 @@ Create a service with type `LoadBalancer` using the appropriate manifest for you 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. To get the DNS name run: + 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: ``` kubectl get svc nginx-gateway -n nginx-gateway From 74a70d7b5bd6582a7d44235c1b4f4304e5e63ec8 Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Wed, 17 Aug 2022 14:10:39 -0600 Subject: [PATCH 5/6] Add a note about nginx-gateway namespace --- docs/installation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/installation.md b/docs/installation.md index 4370f4ed9d..377caf8169 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -7,6 +7,8 @@ Before you can install the NGINX Kubernetes Gateway, make sure you have the foll ## Deploy the Gateway +> Note: NGINX Kubernetes Gateway can only run in the `nginx-gateway` namespace. This limitation will be addressed in the future releases. + You can deploy NGINX Kubernetes Gateway on an existing Kubernetes 1.16+ cluster. The following instructions walk through the steps for deploying on a [kind](https://kind.sigs.k8s.io/) cluster. 1. Load the NGINX Kubernetes Gateway image onto your kind cluster: From d79c8eaec592f3f2dbc1c269b741b239d023d21c Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Wed, 17 Aug 2022 14:37:21 -0600 Subject: [PATCH 6/6] Fix broken links --- examples/advanced-routing/README.md | 2 +- examples/cafe-example/README.md | 2 +- examples/https-termination/README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/examples/advanced-routing/README.md b/examples/advanced-routing/README.md index 00e7d5433d..8c4c0dd306 100644 --- a/examples/advanced-routing/README.md +++ b/examples/advanced-routing/README.md @@ -11,7 +11,7 @@ The cafe application consists of four services: `coffee-v1-svc`, `coffee-v2-svc` ## 1. Deploy NGINX Kubernetes Gateway -1. Follow the [installation instructions](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/README.md#run-nginx-gateway) to deploy NGINX Gateway. +1. Follow the [installation instructions](/docs/installation.md) to deploy NGINX Gateway. 1. Save the public IP address of NGINX Kubernetes Gateway into a shell variable: diff --git a/examples/cafe-example/README.md b/examples/cafe-example/README.md index df2d56bc5f..017cc5f177 100644 --- a/examples/cafe-example/README.md +++ b/examples/cafe-example/README.md @@ -6,7 +6,7 @@ In this example we deploy NGINX Kubernetes Gateway, a simple web application, an ## 1. Deploy NGINX Kubernetes Gateway -1. Follow the [installation instructions](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/README.md#run-nginx-gateway) to deploy NGINX Gateway. +1. Follow the [installation instructions](/docs/installation.md) to deploy NGINX Gateway. 1. Save the public IP address of NGINX Kubernetes Gateway into a shell variable: diff --git a/examples/https-termination/README.md b/examples/https-termination/README.md index eafd4e0436..e61f9ec4c0 100644 --- a/examples/https-termination/README.md +++ b/examples/https-termination/README.md @@ -6,7 +6,7 @@ In this example we expand on the simple [cafe-example](../cafe-example) by addin ## 1. Deploy NGINX Kubernetes Gateway -1. Follow the [installation instructions](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/README.md#run-nginx-gateway) to deploy NGINX Gateway. +1. Follow the [installation instructions](/docs/installation.md) to deploy NGINX Gateway. 1. Save the public IP address of NGINX Kubernetes Gateway into a shell variable: