Skip to content

Commit cacec1d

Browse files
cloudnullcloudnull
authored
chore(nginx-gw): update docs to make it simpler to deploy (#858)
This change makes the nginx-gateway simpler to deploy by creating and documenting scripts that do all the lifting for our users. Signed-off-by: Kevin Carter <[email protected]>
1 parent 4f5a781 commit cacec1d

File tree

3 files changed

+129
-191
lines changed

3 files changed

+129
-191
lines changed

‎bin/install-nginx-gateway.sh‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#!/bin/bash
2+
# shellcheck disable=SC2124,SC2145,SC2294
3+
4+
GLOBAL_OVERRIDES_DIR="/etc/genestack/helm-configs/global_overrides"
5+
SERVICE_CONFIG_DIR="/etc/genestack/helm-configs/nginx-gateway-fabric"
6+
BASE_OVERRIDES="/opt/genestack/base-helm-configs/nginx-gateway-fabric/helm-overrides.yaml"
7+
NGINX_VERSION="1.4.0"
8+
HELM_CMD="helm upgrade --install nginx-gateway-fabric oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
9+
--create-namespace \
10+
--namespace=nginx-gateway \
11+
--post-renderer /etc/genestack/kustomize/kustomize.sh \
12+
--post-renderer-args gateway/overlay \
13+
--version ${NGINX_VERSION}"
14+
15+
HELM_CMD+=" -f ${BASE_OVERRIDES}"
16+
17+
for dir in "$GLOBAL_OVERRIDES_DIR" "$SERVICE_CONFIG_DIR"; do
18+
if compgen -G "${dir}/*.yaml" > /dev/null; then
19+
for yaml_file in "${dir}"/*.yaml; do
20+
# Avoid re-adding the base override file if present in the service directory
21+
if [ "${yaml_file}" != "${BASE_OVERRIDES}" ]; then
22+
HELM_CMD+=" -f ${yaml_file}"
23+
fi
24+
done
25+
fi
26+
done
27+
28+
HELM_CMD+=" $@"
29+
30+
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v${NGINX_VERSION}" | kubectl apply -f -
31+
32+
kubectl apply -f /opt/genestack/manifests/nginx-gateway/nginx-gateway-namespace.yaml
33+
34+
echo "Executing Helm command:"
35+
echo "${HELM_CMD}"
36+
eval "${HELM_CMD}"

‎bin/setup-nginx-gateway.sh‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
#!/bin/bash
2+
# shellcheck disable=SC2045,SC2124,SC2145,SC2164,SC2236,SC2294
3+
4+
if [ -z "${ACME_EMAIL}" ]; then
5+
read -rp "Enter a valid email address for use with ACME, press enter to skip: " ACME_EMAIL
6+
fi
7+
8+
if [ -z "${GATEWAY_DOMAIN}" ]; then
9+
echo "The domain name for the gateway is required, if you do not have a domain name press enter to use the default"
10+
read -rp "Enter the domain name for the gateway [cluster.local]: " GATEWAY_DOMAIN
11+
export GATEWAY_DOMAIN=${GATEWAY_DOMAIN:-cluster.local}
12+
fi
13+
14+
if [ -z "${GATEWAY_DOMAIN}" ]; then
15+
echo "Gateway domain is required"
16+
exit 1
17+
fi
18+
19+
kubectl kustomize /etc/genestack/kustomize/gateway/nginx-gateway-fabric | kubectl apply -f -
20+
21+
echo "Waiting for the gateway to be programmed"
22+
kubectl -n nginx-gateway wait --timeout=5m gateways.gateway.networking.k8s.io flex-gateway --for=condition=Programmed
23+
24+
if [ ! -z "${ACME_EMAIL}" ]; then
25+
cat <<EOF | kubectl apply -f -
26+
apiVersion: cert-manager.io/v1
27+
kind: ClusterIssuer
28+
metadata:
29+
name: letsencrypt-prod
30+
spec:
31+
acme:
32+
server: https://acme-v02.api.letsencrypt.org/directory
33+
email: ${ACME_EMAIL}
34+
privateKeySecretRef:
35+
name: letsencrypt-prod
36+
solvers:
37+
- http01:
38+
gatewayHTTPRoute:
39+
parentRefs:
40+
- group: gateway.networking.k8s.io
41+
kind: Gateway
42+
name: flex-gateway
43+
namespace: nginx-gateway
44+
EOF
45+
46+
kubectl patch --namespace nginx-gateway \
47+
--type merge \
48+
--patch-file /etc/genestack/gateway-api/gateway-letsencrypt.yaml \
49+
gateway flex-gateway
50+
51+
kubectl rollout restart deployment cert-manager --namespace cert-manager
52+
fi
53+
54+
sudo mkdir -p /etc/genestack/gateway-api/routes
55+
for route in $(ls -1 /opt/genestack/etc/gateway-api/routes); do
56+
sed "s/your.domain.tld/${GATEWAY_DOMAIN}/g" "/opt/genestack/etc/gateway-api/routes/${route}" > "/tmp/${route}"
57+
sudo mv -v "/tmp/${route}" "/etc/genestack/gateway-api/routes/${route}"
58+
done
59+
60+
kubectl apply -f /etc/genestack/gateway-api/routes
61+
62+
sudo mkdir -p /etc/genestack/gateway-api/listeners
63+
for listener in $(ls -1 /opt/genestack/etc/gateway-api/listeners); do
64+
sed "s/your.domain.tld/${GATEWAY_DOMAIN}/g" "/opt/genestack/etc/gateway-api/listeners/${listener}" > "/tmp/${listener}"
65+
sudo mv -v "/tmp/${listener}" "/etc/genestack/gateway-api/listeners/${listener}"
66+
done
67+
68+
kubectl patch -n nginx-gateway gateway flex-gateway \
69+
--type='json' \
70+
--patch="$(jq -s 'flatten | .' /etc/genestack/gateway-api/listeners/*)"
71+
72+
echo "Setup Complete"

‎docs/infrastructure-nginx-gateway-api.md‎

Lines changed: 21 additions & 191 deletions
Original file line numberDiff line numberDiff line change
@@ -8,220 +8,50 @@ hide:
88
The [NGINX Gateway Fabric](https://github.com/nginxinc/nginx-gateway-fabric) is an open-source project that provides an
99
implementation of the Gateway API using NGINX as the data plane.
1010

11-
## Install the Gateway API Resource from Kubernetes
11+
## Installation
1212

13-
=== "Stable _(Recommended)_"
13+
Run the helm command to install NGINX Gateway.
1414

15-
``` shell
16-
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.4.0" | kubectl apply -f -
17-
```
18-
19-
=== "Experimental"
20-
21-
The experimental version of the Gateway API is available in the `v1.6.1` checkout. Use with caution.
15+
??? example "Run the NGINX Gateway deployment Script `/opt/genestack/bin/install-nginx-gateway.sh`"
2216

2317
``` shell
24-
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.1" | kubectl apply -f -
18+
--8<-- "bin/install-nginx-gateway.sh"
2519
```
2620

27-
## Install the NGINX Gateway Fabric controller
28-
29-
The NGINX Gateway Fabric controller is a Kubernetes controller that manages the Gateway API resources.
30-
31-
### Create the Namespace
32-
33-
``` shell
34-
kubectl apply -f /opt/genestack/manifests/nginx-gateway/nginx-gateway-namespace.yaml
35-
```
36-
37-
!!! tip
38-
39-
If attempting to perform an **upgrade** of an existing Gateway API deployment, note that the Helm install does not automatically upgrade the CRDs for
40-
this resource. To upgrade them, refer to the process outlined by the
41-
[Nginx upgrade documentation](https://docs.nginx.com/nginx-gateway-fabric/installation/installing-ngf/helm/#upgrade-nginx-gateway-fabric-crds). You
42-
can safely ignore this note for new installations.
43-
44-
=== "Stable _(Recommended)_"
45-
46-
Edit the file `/etc/genestack/helm-configs/nginx-gateway-fabric/helm-overrides.yaml`.
47-
48-
!!! example "Create an empty override file"
21+
The install script will deploy NGINX Gateway to the `nginx-gateway` namespace via Helm.
4922

50-
If no overrides are needed, create an empty file.
23+
## Setup
5124

52-
``` shell
53-
echo "---" | tee /etc/genestack/helm-configs/nginx-gateway-fabric/helm-overrides.yaml
54-
```
25+
??? example "Run the NGINX Gateway setup Script `/opt/genestack/bin/setup-nginx-gateway.sh`"
5526

5627
``` shell
57-
pushd /opt/genestack/submodules/nginx-gateway-fabric/charts || exit 1
58-
helm upgrade --install nginx-gateway-fabric ./nginx-gateway-fabric \
59-
--namespace=nginx-gateway \
60-
--create-namespace \
61-
-f /opt/genestack/base-helm-configs/nginx-gateway-fabric/helm-overrides.yaml \
62-
-f /etc/genestack/helm-configs/nginx-gateway-fabric/helm-overrides.yaml \
63-
--post-renderer /etc/genestack/kustomize/kustomize.sh \
64-
--post-renderer-args gateway/overlay
65-
popd || exit 1
28+
--8<-- "bin/setup-nginx-gateway.sh"
6629
```
6730

68-
=== "Experimental"
69-
70-
The experimental version of the Gateway API is available in the `v1.6.1` checkout. Use with caution.
71-
72-
Update the submodule with the experimental version of the Gateway API.
73-
74-
Edit the file `/etc/genestack/helm-configs/nginx-gateway-fabric/helm-overrides.yaml`.
75-
76-
!!! example "Create the experimental override file"
77-
78-
``` yaml
79-
---
80-
nginxGateway:
81-
replicaCount: 3
82-
gwAPIExperimentalFeatures:
83-
enable: true
84-
service:
85-
## The externalTrafficPolicy of the service. The value Local preserves the client source IP.
86-
externalTrafficPolicy: Cluster
87-
## The annotations of the NGINX Gateway Fabric service.
88-
annotations:
89-
"metallb.universe.tf/address-pool": "gateway-api-external"
90-
"metallb.universe.tf/allow-shared-ip": "openstack-external-svc"
91-
```
92-
93-
Run the helm command to install the experimental version of the Gateway API.
94-
95-
``` shell
96-
helm upgrade --install nginx-gateway-fabric oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
97-
--create-namespace \
98-
--namespace=nginx-gateway \
99-
-f /etc/genestack/helm-configs/nginx-gateway-fabric/helm-overrides.yaml \
100-
--post-renderer /etc/genestack/kustomize/kustomize.sh \
101-
--post-renderer-args gateway/overlay \
102-
--version 1.6.1
103-
```
104-
105-
Once deployed ensure a system rollout has been completed for Cert Manager.
106-
107-
``` shell
108-
kubectl rollout restart deployment cert-manager --namespace cert-manager
109-
```
110-
111-
## Create the shared gateway resource
112-
113-
``` shell
114-
kubectl kustomize /etc/genestack/kustomize/gateway/nginx-gateway-fabric | kubectl apply -f -
115-
```
116-
117-
## Deploy with Let's Encrypt Certificates
118-
119-
By default, certificates are issued by an instance of the selfsigned-cluster-issuer. This section focuses on replacing that with a
120-
Let's Encrypt issuer to ensure valid certificates are deployed in our cluster.
121-
122-
[![asciicast](https://asciinema.org/a/h7npXnDjkSpn3uQtuQwWG9zju.svg)](https://asciinema.org/a/h7npXnDjkSpn3uQtuQwWG9zju)
123-
124-
### Apply the Let's Encrypt Cluster Issuer
125-
126-
Before we can have Cert Manager start coordinating Let's Encrypt certificate
127-
requests for us, we need to add an ACME issuer with a valid, monitored
128-
email (for expiration reminders and other important ACME related information).
129-
130-
``` yaml
131-
read -p "Enter a valid email address for use with ACME: " ACME_EMAIL; \
132-
cat <<EOF | kubectl apply -f -
133-
apiVersion: cert-manager.io/v1
134-
kind: ClusterIssuer
135-
metadata:
136-
name: letsencrypt-prod
137-
spec:
138-
acme:
139-
server: https://acme-v02.api.letsencrypt.org/directory
140-
email: ${ACME_EMAIL}
141-
privateKeySecretRef:
142-
name: letsencrypt-prod
143-
solvers:
144-
- http01:
145-
gatewayHTTPRoute:
146-
parentRefs:
147-
- group: gateway.networking.k8s.io
148-
kind: Gateway
149-
name: flex-gateway
150-
namespace: nginx-gateway
151-
EOF
152-
```
153-
154-
!!! note
31+
The setup script will ask the following questions:
15532

156-
It is also possible to use cert-manager to create [self-signed CA for Gateway API](https://docs.rackspacecloud.com/gateway-api-ca-issuer/)
33+
* Enter a valid email address for use with ACME, press enter to skip"
34+
* Enter the domain name for the gateway"
15735

158-
## Patch Gateway with valid listeners
36+
These values will be used to generate a certificate for the gateway and set the routes used within the flex-gateway,
37+
typically for OpenStack. This script can also be fully automated by providing the required values as arguments.
15938

160-
By default, a generic Gateway is created using a hostname of `*.cluster.local`. To add specific hostnames/listeners to the gateway, you can either
161-
create a patch or update the gateway YAML to include your specific hostnames and then apply the patch/update. Each listener must have a
162-
unique name.
163-
164-
??? abstract "An example patch file you can modify to include your own domain name can be found at `/opt/genestack/etc/gateway-api/listeners/gateway-api/http-wildcard-listener.json`"
165-
166-
``` json
167-
--8<-- "etc/gateway-api/listeners/http-wildcard-listener.json"
168-
```
169-
170-
!!! example "Example modifying the Gateway listener patches"
39+
!!! example "Run the NGINX Gateway setup Script with arguments"
17140

17241
``` shell
173-
mkdir -p /etc/genestack/gateway-api/listeners
174-
for listener in $(ls -1 /opt/genestack/etc/gateway-api/listeners); do
175-
sed 's/your.domain.tld/<YOUR_DOMAIN>/g' /opt/genestack/etc/gateway-api/listeners/$listener > /etc/genestack/gateway-api/listeners/$listener
176-
done
42+
ACME_EMAIL="[email protected]" GATEWAY_DOMAIN="your.domain.tld" /opt/genestack/bin/setup-nginx-gateway.sh
17743
```
17844

179-
``` shell
180-
kubectl patch -n nginx-gateway gateway flex-gateway \
181-
--type='json' \
182-
--patch="$(jq -s 'flatten | .' /etc/genestack/gateway-api/listeners/*)"
183-
```
184-
185-
## Apply Related Gateway routes
45+
## Validation
18646

187-
Another example with most of the OpenStack services is located at `/opt/genestack/etc/gateway-api/routes/http-wildcard-listener.yaml`. Similarly, you must modify
188-
and apply them as shown below, or apply your own.
189-
190-
??? abstract "Example routes file"
191-
192-
``` yaml
193-
--8<-- "etc/gateway-api/routes/http-wildcard-listener.yaml"
194-
```
195-
196-
All routes can be found at `/etc/genestack/gateway-api/routes`.
197-
198-
!!! example "Example modifying all available Gateway routes with `your.domain.tld`"
199-
200-
``` shell
201-
mkdir -p /etc/genestack/gateway-api/routes
202-
for route in $(ls -1 /opt/genestack/etc/gateway-api/routes); do
203-
sed 's/your.domain.tld/<YOUR_DOMAIN>/g' /opt/genestack/etc/gateway-api/routes/$route > /etc/genestack/gateway-api/routes/$route
204-
done
205-
```
47+
At this point, flex-gateway has a listener pointed to the port 80 matching *.your.domain.tld hostname. The
48+
HTTPRoute resource configures routes for this gateway. Here, we match all path and simply pass any request
49+
from the matching hostname to kube-prometheus-stack-prometheus backend service.
20650

20751
``` shell
208-
kubectl apply -f /etc/genestack/gateway-api/routes
52+
kubectl -n openstack get httproute
20953
```
21054

211-
## Patch Gateway with Let's Encrypt Cluster Issuer
212-
213-
??? abstract "Example patch to enable LetsEncrypt `/etc/genestack/gateway-api/gateway-letsencrypt.yaml`"
214-
215-
``` yaml
216-
--8<-- "etc/gateway-api/gateway-letsencrypt.yaml"
217-
```
218-
21955
``` shell
220-
kubectl patch --namespace nginx-gateway \
221-
--type merge \
222-
--patch-file /etc/genestack/gateway-api/gateway-letsencrypt.yaml \
223-
gateway flex-gateway
56+
kubectl -n nginx-gateway get gateways.gateway.networking.k8s.io flex-gateway
22457
```
225-
226-
At this point, flex-gateway has a listener pointed to the port 80 matching *.your.domain.tld hostname. The HTTPRoute resource configures routes
227-
for this gateway. Here, we match all path and simply pass any request from the matching hostname to kube-prometheus-stack-prometheus backend service.

0 commit comments

Comments
 (0)