Skip to content

Commit cf62de5

Browse files
Update JWT install guide
1 parent 1d43a05 commit cf62de5

File tree

1 file changed

+113
-13
lines changed

1 file changed

+113
-13
lines changed

docs/content/installation/using-the-jwt-token-docker-secret.md

Lines changed: 113 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,51 +18,151 @@ This document explains how to use the NGINX Plus Ingress Controller image from t
1818
* For NGINX Ingress Controller, you must have the NGINX Ingress Controller subscription -- download the NGINX Plus Ingress Controller (per instance) JWT access token from [MyF5](https://my.f5.com).
1919
* To list the available image tags using the Docker registry API, you will also need to download the NGINX Plus Ingress Controller (per instance) certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) from [MyF5](https://my.f5.com).
2020

21+
## Order of steps to pull NGINX Ingress controller from F5 registry
22+
23+
1. Decide on what NGINX Ingress controller image you want to use. [NGINX Ingress controller images](https://docs.nginx.com/nginx-ingress-controller/technical-specifications/#images-with-nginx-plus "Available NGINX Ingress controller images")
24+
2. Log into MyF5 portal. [MyF5 portal login](https://myf5.com/ "MyF5 portal login"). Navigate to your subscription details, and locate your .cert, .key and .JWT file to download.
25+
3. Download the JWT token from the `MyF5` portal.
26+
4. Create kubernetes secret using the JWT token that is provided in the MyF5 portal.
27+
You can `cat` the contents of the JWT token and then store the output to use in the following steps. Make sure that there are no additional characters or extra whiespace that might have been accidently added. This will break authorization and prevent the NGINX Ingress controller image from being downloaded successfully.
28+
5. Modify your deployment (manifest or helm) to use the kubernetes secret created in step 4.
29+
6. Deploy NGINX Ingress controller into your kubernetes cluster and verify successful installation.
30+
31+
2132
## Using the JWT token in a Docker Config Secret
2233

23-
1. Create a `docker-registry` secret on the cluster using the JWT token as the username and `none` for password (password is unused). The name of the docker server is `private-registry.nginx.com`. Optionally namespace the secret.
34+
1. Create a kubernetes `docker-registry` secret type, on the cluster using the JWT token as the username and `none` for password (password is unused). The name of the docker server is `private-registry.nginx.com`.
2435

2536
```
2637
kubectl create secret docker-registry regcred --docker-server=private-registry.nginx.com --docker-username=<JWT Token> --docker-password=none [-n nginx-ingress]
2738
```
39+
In the above command, it is important that the `--docker-username=<JWT Token>` contains the contents of the token and is not pointing to the token itself. Ensure that when you copy the contents of the JWT token, there are no additional characters or extra whitepaces. This can invalidate the token and cause 401 errors when trying to authenticate to the registry.
2840

2941
2. Confirm the details of the created secret by running:
3042

3143
```bash
3244
kubectl get secret regcred --output=yaml
3345
```
3446

35-
3. You can now add this secret to a deployment spec or to a service account to apply to all deployments for a given SA spec. See the [Create a Pod that uses your Secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret) and [Add ImagePullSecrets to a service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account) documentation for more details.
47+
3. We are now going to use our newly created kubernetes secret in our `helm` and `manifest` deployments.
48+
49+
50+
### Manifest deployment
51+
52+
[Installling with Manfiets](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/)
53+
54+
Manifest deployment example:
55+
56+
```yaml
57+
spec:
58+
serviceAccountName: nginx-ingress
59+
imagePullSecrets:
60+
- name: regcred
61+
automountServiceAccountToken: true
62+
securityContext:
63+
seccompProfile:
64+
type: RuntimeDefault
65+
# fsGroup: 101 #nginx
66+
containers:
67+
- image: private-registry.nginx.com/nginx-ic/nginx-plus-ingress:3.1.1
68+
imagePullPolicy: IfNotPresent
69+
name: nginx-plus-ingress
70+
```
71+
72+
Notice `imagePullSecrets` and `containers.image` lines to represent our kubernetes secret as well as the registry and version of the NGINX Ingress controller we are going to deploy.
73+
74+
### Helm install method
75+
76+
If you are using `helm` to install, you can install using two methods. First is the `helm` sources method. [Helm sources install](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/#managing-the-chart-via-sources "helm source install")
77+
78+
1. Clone the nginxinc/kubernetes-ingress repository
79+
2. Change directory into deployents/helm-chart of the recently cloned repo.
80+
3. Modify the `values.yaml` file.
81+
82+
We want to set a few lines for NGINX Plus Ingress controller to be deployed.
83+
84+
1. Change to `nginxplus`
85+
2. Specify NGINX Ingress controller image to use.
86+
3. Specify a `imagePullSecretName` to pull from the private registry.
87+
88+
89+
### Ensure nginxplus is set to `true`
90+
```yaml
91+
## Deploys the Ingress Controller for NGINX Plus.
92+
nginxplus: true
93+
```
94+
95+
### Specify the image to be used for deployment
96+
97+
```yaml
98+
image:
99+
## The image repository of the Ingress Controller.
100+
repository: private-registry.nginx.com/nginx-ic/nginx-plus-ingress
101+
102+
## The tag of the
103+
tag: 3.1.1
104+
```
105+
106+
### Specify the `imagePullSecrets`
107+
108+
```yaml
109+
serviceAccount:
110+
## The annotations of the service account of the Ingress Controller pods.
111+
annotations: {}
112+
113+
## The name of the service account of the Ingress Controller pods. Used for RBAC.
114+
## Autogenerated if not set or set to "".
115+
# name: nginx-ingress
116+
117+
## The name of the secret containing docker registry credentials.
118+
## Secret must exist in the same namespace as the helm release.
119+
imagePullSecretName: regcred
120+
```
121+
122+
### Using the `helm` charts method:
123+
124+
This will install `NGINX Ingress controller` using the charts method, by defining specific settings using `set` on the command line.
125+
126+
```bash
127+
helm install my-release -n nginx-ingress oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.17.1 --set controller.image.repository=private-registry.nginx.com/nginx-ic/nginx-plus-ingress --set controller.image.tag=3.1.1 --set controller.nginxplus=true --set controller.serviceAccount.imagePullSecretName=regcred
128+
```
129+
130+
### Verify that NGINX Ingress controller was installed successfull
131+
132+
TODO: Add install output of successful install
133+
134+
135+
136+
## Checking the validation that the .crts/key and .jwt are able to successfully authenticate to the repo to pull NGINX Ingress controller images:
36137

37-
4. Update the deployment spec with the chosen image path. Choose the image from the [available images]({{< relref "/technical-specifications.md#images-with-nginx-plus" >}}).
138+
You can also use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for the repositories, e.g.:
38139

39-
5. You can use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for the repositories, e.g.:
40-
```
140+
```bash
41141
$ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
42142
{
43143
"name": "nginx-ic/nginx-plus-ingress",
44144
"tags": [
45-
"3.1.1-alpine",
46-
"3.1.1-ubi",
47-
"3.1.1"
145+
"3.1.0-alpine",
146+
"3.1.0-ubi",
147+
"3.1.0"
48148
]
49149
}
50150
51151
$ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
52152
{
53153
"name": "nginx-ic-nap/nginx-plus-ingress",
54154
"tags": [
55-
"3.1.1-ubi",
56-
"3.1.1"
155+
"3.1.0-ubi",
156+
"3.1.0"
57157
]
58158
}
59159
60160
$ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
61161
{
62162
"name": "nginx-ic-dos/nginx-plus-ingress",
63163
"tags": [
64-
"3.1.1-ubi",
65-
"3.1.1"
164+
"3.1.0-ubi",
165+
"3.1.0"
66166
]
67167
}
68-
```
168+
```

0 commit comments

Comments
 (0)