Skip to content

Commit 7d523ae

Browse files
pleshakovpleshakov
authored
Move parts of the README into separate docs (#187)
1 parent bd7d4b6 commit 7d523ae

File tree

6 files changed

+150
-146
lines changed

6 files changed

+150
-146
lines changed

‎README.md

Lines changed: 4 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -7,147 +7,8 @@ NGINX Kubernetes Gateway is an open-source project that provides an implementati
77
> Warning: This project is actively in development (pre-alpha feature state) and should not be deployed in a production environment.
88
> All APIs, SDKs, designs, and packages are subject to change.
99
10-
# Run NGINX Kubernetes Gateway
10+
## Run NGINX Kubernetes Gateway
1111

12-
## Prerequisites
13-
14-
Before you can build and run the NGINX Kubernetes Gateway, make sure you have the following software installed on your machine:
15-
- [git](https://git-scm.com/)
16-
- [GNU Make](https://www.gnu.org/software/software.html)
17-
- [Docker](https://www.docker.com/) v18.09+
18-
- [kubectl](https://kubernetes.io/docs/tasks/tools/)
19-
20-
## Build the image
21-
22-
1. Clone the repo and change into the `nginx-kubernetes-gateway` directory:
23-
24-
```
25-
git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git
26-
cd nginx-kubernetes-gateway
27-
```
28-
29-
1. Build the image:
30-
31-
```
32-
make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container
33-
```
34-
35-
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`.
36-
37-
1. Push the image to your container registry:
38-
39-
```
40-
docker push myregistry.example.com/nginx-kubernetes-gateway:0.0.1
41-
```
42-
43-
Make sure to substitute `myregistry.example.com/nginx-kubernetes-gateway` with your private registry.
44-
45-
## Deploy NGINX Kubernetes Gateway
46-
47-
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.
48-
49-
1. Load the NGINX Kubernetes Gateway image onto your kind cluster:
50-
51-
```
52-
kind load docker-image nginx-kubernetes-gateway:0.0.1
53-
```
54-
55-
Make sure to substitute the image name with the name of the image you built.
56-
57-
1. Install the Gateway CRDs:
58-
59-
```
60-
kubectl apply -k "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.0"
61-
```
62-
63-
1. Create the nginx-gateway namespace:
64-
65-
```
66-
kubectl apply -f deploy/manifests/namespace.yaml
67-
```
68-
69-
1. Create the njs-modules configmap:
70-
71-
```
72-
kubectl create configmap njs-modules --from-file=internal/nginx/modules/src/httpmatches.js -n nginx-gateway
73-
```
74-
75-
1. Create the GatewayClass resource:
76-
77-
```
78-
kubectl apply -f deploy/manifests/gatewayclass.yaml
79-
```
80-
81-
1. Deploy the NGINX Kubernetes Gateway:
82-
83-
Before deploying, make sure to update the Deployment spec in `nginx-gateway.yaml` to reference the image you built.
84-
85-
```
86-
kubectl apply -f deploy/manifests/nginx-gateway.yaml
87-
```
88-
89-
1. Confirm the NGINX Kubernetes Gateway is running in `nginx-gateway` namespace:
90-
91-
```
92-
kubectl get pods -n nginx-gateway
93-
NAME READY STATUS RESTARTS AGE
94-
nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s
95-
```
96-
97-
## Expose NGINX Kubernetes Gateway
98-
99-
You can gain access to NGINX Kubernetes Gateway by creating a `NodePort` Service or a `LoadBalancer` Service.
100-
101-
### Create a NodePort Service
102-
103-
Create a service with type `NodePort`:
104-
105-
```
106-
kubectl apply -f deploy/manifests/service/nodeport.yaml
107-
```
108-
109-
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.
110-
111-
### Create a LoadBalancer Service
112-
113-
Create a service with type `LoadBalancer` using the appropriate manifest for your cloud provider.
114-
115-
- For GCP or Azure:
116-
117-
```
118-
kubectl apply -f deploy/manifests/service/loadbalancer.yaml
119-
```
120-
121-
Lookup the public IP of the load balancer:
122-
123-
```
124-
kubectl get svc nginx-gateway -n nginx-gateway
125-
```
126-
127-
Use the public IP of the load balancer to access NGINX Kubernetes Gateway.
128-
129-
- For AWS:
130-
131-
```
132-
kubectl apply -f deploy/manifests/service/loadbalancer-aws-nlb.yaml
133-
```
134-
135-
In AWS, the NLB DNS name will be reported by Kubernetes in lieu of a public IP. To get the DNS name run:
136-
137-
```
138-
kubectl get svc nginx-gateway -n nginx-gateway
139-
```
140-
141-
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:
142-
143-
```
144-
nslookup <dns-name>
145-
```
146-
147-
# Test NGINX Kubernetes Gateway
148-
149-
To test the NGINX Kubernetes Gateway run:
150-
151-
```
152-
make unit-test
153-
```
12+
1. [Build](docs/building-the-image.md) the NGINX Kubernetes Gateway container image.
13+
2. [Install](docs/installation.md) NGINX Kubernetes Gateway.
14+
3. Deploy various [examples](examples).

‎docs/building-the-image.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Building the Image
2+
3+
## Prerequisites
4+
5+
Before you can build the NGINX Kubernetes Gateway, make sure you have the following software installed on your machine:
6+
- [git](https://git-scm.com/)
7+
- [GNU Make](https://www.gnu.org/software/software.html)
8+
- [Docker](https://www.docker.com/) v18.09+
9+
10+
## Steps
11+
12+
1. Clone the repo and change into the `nginx-kubernetes-gateway` directory:
13+
14+
```
15+
git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git
16+
cd nginx-kubernetes-gateway
17+
```
18+
19+
1. Build the image:
20+
21+
```
22+
make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container
23+
```
24+
25+
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`.
26+
27+
1. Push the image to your container registry:
28+
29+
```
30+
docker push myregistry.example.com/nginx-kubernetes-gateway:0.0.1
31+
```
32+
33+
Make sure to substitute `myregistry.example.com/nginx-kubernetes-gateway` with your registry.

‎docs/installation.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Installation
2+
3+
## Prerequisites
4+
5+
Before you can install the NGINX Kubernetes Gateway, make sure you have the following software installed on your machine:
6+
- [kubectl](https://kubernetes.io/docs/tasks/tools/)
7+
8+
## Deploy the Gateway
9+
10+
> Note: NGINX Kubernetes Gateway can only run in the `nginx-gateway` namespace. This limitation will be addressed in the future releases.
11+
12+
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.
13+
14+
1. Load the NGINX Kubernetes Gateway image onto your kind cluster:
15+
16+
```
17+
kind load docker-image nginx-kubernetes-gateway:0.0.1
18+
```
19+
20+
Make sure to substitute the image name with the name of the image you built.
21+
22+
1. Install the Gateway CRDs:
23+
24+
```
25+
kubectl apply -k "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.0"
26+
```
27+
28+
1. Create the nginx-gateway namespace:
29+
30+
```
31+
kubectl apply -f deploy/manifests/namespace.yaml
32+
```
33+
34+
1. Create the njs-modules configmap:
35+
36+
```
37+
kubectl create configmap njs-modules --from-file=internal/nginx/modules/src/httpmatches.js -n nginx-gateway
38+
```
39+
40+
1. Create the GatewayClass resource:
41+
42+
```
43+
kubectl apply -f deploy/manifests/gatewayclass.yaml
44+
```
45+
46+
1. Deploy the NGINX Kubernetes Gateway:
47+
48+
Before deploying, make sure to update the Deployment spec in `nginx-gateway.yaml` to reference the image you built.
49+
50+
```
51+
kubectl apply -f deploy/manifests/nginx-gateway.yaml
52+
```
53+
54+
1. Confirm the NGINX Kubernetes Gateway is running in `nginx-gateway` namespace:
55+
56+
```
57+
kubectl get pods -n nginx-gateway
58+
NAME READY STATUS RESTARTS AGE
59+
nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s
60+
```
61+
62+
## Expose NGINX Kubernetes Gateway
63+
64+
You can gain access to NGINX Kubernetes Gateway by creating a `NodePort` Service or a `LoadBalancer` Service.
65+
66+
### Create a NodePort Service
67+
68+
Create a service with type `NodePort`:
69+
70+
```
71+
kubectl apply -f deploy/manifests/service/nodeport.yaml
72+
```
73+
74+
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.
75+
76+
### Create a LoadBalancer Service
77+
78+
Create a service with type `LoadBalancer` using the appropriate manifest for your cloud provider.
79+
80+
- For GCP or Azure:
81+
82+
```
83+
kubectl apply -f deploy/manifests/service/loadbalancer.yaml
84+
```
85+
86+
Lookup the public IP of the load balancer, which is reported in the `EXTERNAL-IP` column in the output of the following command:
87+
88+
```
89+
kubectl get svc nginx-gateway -n nginx-gateway
90+
```
91+
92+
Use the public IP of the load balancer to access NGINX Kubernetes Gateway.
93+
94+
- For AWS:
95+
96+
```
97+
kubectl apply -f deploy/manifests/service/loadbalancer-aws-nlb.yaml
98+
```
99+
100+
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:
101+
102+
```
103+
kubectl get svc nginx-gateway -n nginx-gateway
104+
```
105+
106+
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:
107+
108+
```
109+
nslookup <dns-name>
110+
```

‎examples/advanced-routing/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ The cafe application consists of four services: `coffee-v1-svc`, `coffee-v2-svc`
1111

1212
## 1. Deploy NGINX Kubernetes Gateway
1313

14-
1. Follow the [installation instructions](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/README.md#run-nginx-gateway) to deploy NGINX Gateway.
14+
1. Follow the [installation instructions](/docs/installation.md) to deploy NGINX Gateway.
1515

1616
1. Save the public IP address of NGINX Kubernetes Gateway into a shell variable:
1717

‎examples/cafe-example/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ In this example we deploy NGINX Kubernetes Gateway, a simple web application, an
66

77
## 1. Deploy NGINX Kubernetes Gateway
88

9-
1. Follow the [installation instructions](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/README.md#run-nginx-gateway) to deploy NGINX Gateway.
9+
1. Follow the [installation instructions](/docs/installation.md) to deploy NGINX Gateway.
1010

1111
1. Save the public IP address of NGINX Kubernetes Gateway into a shell variable:
1212

‎examples/https-termination/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ In this example we expand on the simple [cafe-example](../cafe-example) by addin
66

77
## 1. Deploy NGINX Kubernetes Gateway
88

9-
1. Follow the [installation instructions](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/README.md#run-nginx-gateway) to deploy NGINX Gateway.
9+
1. Follow the [installation instructions](/docs/installation.md) to deploy NGINX Gateway.
1010

1111
1. Save the public IP address of NGINX Kubernetes Gateway into a shell variable:
1212

0 commit comments

Comments
 (0)