From c66ef10d72a6adf08f8420caf8e738f5afbd63cd Mon Sep 17 00:00:00 2001 From: Balakoteswara Panchakshari Date: Wed, 19 Feb 2025 23:57:14 +0530 Subject: [PATCH 1/4] fix: updated the k8s documentation for NIM v2.19.0 release --- .../nim/kubernetes/access-webui-helm.md | 2 +- ...high-availability-network-load-balancer.md | 4 +- .../deploy/kubernetes/deploy-using-helm.md | 186 ++++++++---------- 3 files changed, 86 insertions(+), 106 deletions(-) diff --git a/content/includes/nim/kubernetes/access-webui-helm.md b/content/includes/nim/kubernetes/access-webui-helm.md index d85d7dcab..3ecc2d3fd 100644 --- a/content/includes/nim/kubernetes/access-webui-helm.md +++ b/content/includes/nim/kubernetes/access-webui-helm.md @@ -23,4 +23,4 @@ You can access the NGINX Instance Manager web interface using the external IP ad For example, `https://10.108.57.167/ui`. - This IP address might not be reachable, depending on how the Kubernetes cluster networking was configured. If so, the `apigw` service type can be changed to a more suitable option, such as `LoadBalancer`, by changing the [Configurable Helm Setting]({{< relref "/nim/deploy/kubernetes/helm-config-settings.md" >}}) value for `nms-hybrid.apigw.service.type` . + This IP address might not be reachable, depending on how the Kubernetes cluster networking was configured. If so, the `apigw` service type can be changed to a more suitable option, such as `LoadBalancer`, by changing the [Configurable Helm Setting]({{< relref "/nim/deploy/kubernetes/helm-config-settings.md" >}}) value for `apigw.service.type`. diff --git a/content/nginx/deployment-guides/amazon-web-services/high-availability-network-load-balancer.md b/content/nginx/deployment-guides/amazon-web-services/high-availability-network-load-balancer.md index 9fcf9544f..31940a2be 100644 --- a/content/nginx/deployment-guides/amazon-web-services/high-availability-network-load-balancer.md +++ b/content/nginx/deployment-guides/amazon-web-services/high-availability-network-load-balancer.md @@ -248,7 +248,7 @@ The deployed solution in these instructions uses six EC2 instances. Two instance *Step‑by‑step* instructions for creating EC2 instances and installing NGINX Open Source and NGINX Plus are available. Refer to our deployment guide, [Creating Amazon EC2 Instances for NGINX Open Source and NGINX Plus]({{< ref "/nginx/deployment-guides/amazon-web-services/ec2-instances-for-nginx.md" >}}). -{{< note >}} When installing NGINX Open Source or NGINX Plus, you connect to each instance over SSH. To save time, leave the SSH connection to each instance open after installing the software. This way, you can reuse the connection when configuring the instance. {{< note >}} +{{< note >}} When installing NGINX Open Source or NGINX Plus, you connect to each instance over SSH. To save time, leave the SSH connection to each instance open after installing the software. This way, you can reuse the connection when configuring the instance. {{< /note >}} Assign the following names to the instances, then install the indicated NGINX software. The screenshot below shows the resulting **Instances** table. @@ -303,7 +303,7 @@ You can automate set up of the six instances described in these instructions. Au These scripts also create a new set of networking rules and security group settings. These rules and settings help avoid conflicts with any pre‑existing network settings. After you run the scripts, continue to the [instructions for creating an AWS NLB](#nlb-configure). No further setup is required. -{{< note >}} These scripts also create a new VPC. They do not use the default VPC described in the [instructions in our Deployment Guide]({{< ref "/nginx/deployment-guides/amazon-web-services/ec2-instances-for-nginx.md >}}). {{< /note >}} +{{< note >}} These scripts also create a new VPC. They do not use the default VPC described in the [instructions in our Deployment Guide]({{< ref "/nginx/deployment-guides/amazon-web-services/ec2-instances-for-nginx.md" >}}). {{< /note >}} To run the scripts, follow these instructions: diff --git a/content/nim/deploy/kubernetes/deploy-using-helm.md b/content/nim/deploy/kubernetes/deploy-using-helm.md index 2e17d59b1..887d23a03 100644 --- a/content/nim/deploy/kubernetes/deploy-using-helm.md +++ b/content/nim/deploy/kubernetes/deploy-using-helm.md @@ -55,20 +55,30 @@ Create a Docker registry secret on the cluster, using the JWT token as the usern - **Kubernetes**: + ```shell + kubectl create namespace nms + ``` + ```shell kubectl create secret docker-registry regcred \ --docker-server=private-registry.nginx.com \ --docker-username= \ - --docker-password=none + --docker-password=none \ + -n nms ``` - **OpenShift**: + ```shell + oc new-project nms + ``` + ```shell oc create secret docker-registry regcred \ --docker-server=private-registry.nginx.com \ --docker-username= \ - --docker-password=none + --docker-password=none \ + -n nms ``` {{< warning >}} @@ -84,13 +94,13 @@ To confirm the secret is created: - **Kubernetes**: ```shell - kubectl get secret regcred --output=yaml + kubectl get secret regcred --output=yaml -n nms ``` - **OpenShift**: ```shell - oc get secret regcred --output=yaml + oc get secret regcred --output=yaml -n nms ``` @@ -127,37 +137,36 @@ The `values.yaml` file customizes the Helm chart installation without modifying {{< see-also >}} For details on creating a secret, see Kubernetes [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). {{}} ```yaml - nms-hybrid: - imagePullSecrets: - - name: regcred - apigw: - image: - repository: private-registry.nginx.com/nms/apigw - tag: - core: - image: - repository: private-registry.nginx.com/nms/core - tag: - dpm: - image: - repository: private-registry.nginx.com/nms/dpm - tag: - ingestion: - image: - repository: private-registry.nginx.com/nms/ingestion - tag: - integrations: - image: - repository: private-registry.nginx.com/nms/integrations - tag: - secmon: - image: - repository: private-registry.nginx.com/nms/secmon - tag: - utility: - image: - repository: private-registry.nginx.com/nms/utility - tag: + imagePullSecrets: + - name: regcred + apigw: + image: + repository: private-registry.nginx.com/nms/apigw + tag: + core: + image: + repository: private-registry.nginx.com/nms/core + tag: + dpm: + image: + repository: private-registry.nginx.com/nms/dpm + tag: + ingestion: + image: + repository: private-registry.nginx.com/nms/ingestion + tag: + integrations: + image: + repository: private-registry.nginx.com/nms/integrations + tag: + secmon: + image: + repository: private-registry.nginx.com/nms/secmon + tag: + utility: + image: + repository: private-registry.nginx.com/nms/utility + tag: ``` 2. Save and close the `values.yaml` file. @@ -169,65 +178,24 @@ The `values.yaml` file customizes the Helm chart installation without modifying If deploying on OpenShift, include this setting in the `values.yaml` file: ```yaml -nms-hybrid: - openshift: - enabled: true +openshift: + enabled: true ``` ### How OpenShift handles security constraints When `openshift.enabled: true` is set in the `values.yaml` file, the NGINX Instance Manager deployment automatically creates a **custom Security Context Constraint (SCC)** and links it to the Service Account used by all pods. -By default, OpenShift enforces strict security policies that require containers to run as **non-root** users. The NGINX Instance Manager deployment needs specific user IDs (UIDs) for certain services, such as **1000** for `nms` and **101** for `nginx` and `clickhouse`. Since the default SCCs do not allow these UIDs, a **custom SCC** is created. This ensures that the deployment can run with the necessary permissions while maintaining OpenShift’s security standards. +By default, OpenShift enforces strict security policies that require containers to run as **non-root** users. The NGINX Instance Manager deployment needs specific user IDs (UIDs) for certain services, such as **1000** for `nms` and **101** for `nginx` and `clickhouse`. Since the default SCCs do not allow these UIDs, a **custom SCC** is created. This ensures that the deployment can run with the necessary permissions while maintaining OpenShift’s security standards. The custom SCC allows these UIDs by setting the `runAsUser` field, which controls which users can run containers. + +{{< note >}} If you’re encountering errors with the custom [Security Context Constraints](https://docs.openshift.com/container-platform/4.15/authentication/managing-security-context-constraints.html), it may be due to insufficient permissions to access the Security Context Constraints resource. Please contact a Cluster Administrator to request access, either via a ClusterRoleBinding or by adjusting your user role. {{< /note >}} -The custom SCC allows these UIDs by setting the `runAsUser` field, which controls which users can run containers. To verify that the SCC has been created, run: +To verify that the custom SCC has been created, run only after installing the helm chart: ```shell oc get scc nms-restricted-v2-scc --output=yaml ``` - ---- - - -To apply network policies for NGINX Instance Manager, ensure Kubernetes has a [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) installed before the Helm chart installation. - -By default, the following network policies will be created in the release namespace: - -- **Kubernetes**: - - ```shell - kubectl get netpol -n nms - ``` - -- **OpenShift**: - - ```shell - oc get netpol -n nms - ``` - - **Output** - - ```text - NAME POD-SELECTOR AGE - apigw app.kubernetes.io/name=apigw 4m47s - clickhouse app.kubernetes.io/name=clickhouse 4m47s - core app.kubernetes.io/name=core 4m47s - dpm app.kubernetes.io/name=dpm 4m47s - ingestion app.kubernetes.io/name=ingestion 4m47s - integrations app.kubernetes.io/name=integrations 4m47s - secmon app.kubernetes.io/name=secmon 4m47s - utility app.kubernetes.io/name=integrations 4m47s - ``` - -To disable network policies, update the `values.yaml` file: - -```yaml -networkPolicies: - # Set this to true to enable network policies for NGINX Instance Manager. - enabled: false -``` - --- ## Install the chart @@ -239,19 +207,19 @@ Run the `helm install` command to deploy NGINX Instance Manager: {{< important >}} Remember to save the password for future use. Only the encrypted password is stored, and there's no way to recover or reset it if lost. {{< /important >}} -(Optional) Replace `` with the desired chart version. If omitted, the latest version will be installed. +(Optional) Replace `` with the desired chart version. If omitted, the latest version will be installed. At present, only version 2.19.0 is supported. ```shell helm install -n nms \ ---set nms-hybrid.adminPasswordHash=$(openssl passwd -6 'YourPassword123#') \ -nms nginx-stable/nms \ +--set adminPasswordHash=$(openssl passwd -6 'YourPassword123#') \ +nms nginx-stable/nms-hybrid \ --create-namespace \ -f \ [--version ] \ --wait ``` -To help you choose the right NGINX Instance Manager chart version, see the table in: +To help you choose the right NGINX Instance Manager chart version, refer to the table (applicable for NIM versions up to v2.18.0) in: {{< include "nim/kubernetes/nms-chart-supported-module-versions.md" >}} @@ -289,14 +257,16 @@ To upgrade: 1. [Update the Helm repository list](#add-helm-repository). 1. [Adjust your `values.yaml` file](#create-a-helm-deployment-values.yaml-file) if needed. -1. To upgrade the NGINX instance deployment, run the following command. This command updates the `nms` deployment with a new version from the `nginx-stable/nms` repository. It also hashes the provided password and uses the `values.yaml` file at the path you specify. +1. To upgrade the NGINX Instance Manager deployment, run the following command. This command updates the `nms` deployment with a new version from the `nginx-stable/nms-hybrid` repository. It also hashes the provided password and uses the `values.yaml` file at the path you specify. + +(Optional) Replace `` with the desired chart version. If omitted, the latest version will be installed. At present, only version 2.19.0 is supported. ```bash helm upgrade -n nms \ - --set nms-hybrid.adminPasswordHash=$(openssl passwd -6 'YourPassword123#') \ - nms nginx-stable/nms \ + --set adminPasswordHash=$(openssl passwd -6 'YourPassword123#') \ + nms nginx-stable/nms-hybrid \ -f \ - [--version ] \ + [--version ] \ --wait ``` @@ -327,20 +297,30 @@ To apply network policies for NGINX Instance Manager, ensure Kubernetes has a [n By default, the following network policies will be created in the release namespace: -```shell -kubectl get netpol -n nms -``` +- **Kubernetes**: -```text -NAME POD-SELECTOR AGE -apigw app.kubernetes.io/name=apigw 4m47s -clickhouse app.kubernetes.io/name=clickhouse 4m47s -core app.kubernetes.io/name=core 4m47s -dpm app.kubernetes.io/name=dpm 4m47s -ingestion app.kubernetes.io/name=ingestion 4m47s -integrations app.kubernetes.io/name=integrations 4m47s -utility app.kubernetes.io/name=integrations 4m47s -``` + ```shell + kubectl get netpol -n nms + ``` + +- **OpenShift**: + + ```shell + oc get netpol -n nms + ``` + **Output**: + + ```text + NAME POD-SELECTOR AGE + apigw app.kubernetes.io/name=apigw 4m47s + clickhouse app.kubernetes.io/name=clickhouse 4m47s + core app.kubernetes.io/name=core 4m47s + dpm app.kubernetes.io/name=dpm 4m47s + ingestion app.kubernetes.io/name=ingestion 4m47s + integrations app.kubernetes.io/name=integrations 4m47s + secmon app.kubernetes.io/name=secmon 4m47s + utility app.kubernetes.io/name=integrations 4m47s + ``` To disable network policies, update the `values.yaml` file: From 9c59acd1e11fb1ba5bf6354cbeacb9f48e558a2b Mon Sep 17 00:00:00 2001 From: Balakoteswara Panchakshari Date: Thu, 20 Feb 2025 00:23:50 +0530 Subject: [PATCH 2/4] fix: addressed review comments --- content/nim/deploy/kubernetes/deploy-using-helm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nim/deploy/kubernetes/deploy-using-helm.md b/content/nim/deploy/kubernetes/deploy-using-helm.md index 887d23a03..22ae2b2cd 100644 --- a/content/nim/deploy/kubernetes/deploy-using-helm.md +++ b/content/nim/deploy/kubernetes/deploy-using-helm.md @@ -190,7 +190,7 @@ By default, OpenShift enforces strict security policies that require containers {{< note >}} If you’re encountering errors with the custom [Security Context Constraints](https://docs.openshift.com/container-platform/4.15/authentication/managing-security-context-constraints.html), it may be due to insufficient permissions to access the Security Context Constraints resource. Please contact a Cluster Administrator to request access, either via a ClusterRoleBinding or by adjusting your user role. {{< /note >}} -To verify that the custom SCC has been created, run only after installing the helm chart: +To verify that the custom SCC has been created, after installing the helm chart, run: ```shell oc get scc nms-restricted-v2-scc --output=yaml @@ -207,7 +207,7 @@ Run the `helm install` command to deploy NGINX Instance Manager: {{< important >}} Remember to save the password for future use. Only the encrypted password is stored, and there's no way to recover or reset it if lost. {{< /important >}} -(Optional) Replace `` with the desired chart version. If omitted, the latest version will be installed. At present, only version 2.19.0 is supported. +(Optional) Replace `` with the desired chart version. If omitted, the latest version will be installed. Currently only version 2.19.0 is supported. ```shell helm install -n nms \ From a1384dca4743104082c275edeb3f821421959010 Mon Sep 17 00:00:00 2001 From: Balakoteswara Panchakshari Date: Thu, 20 Feb 2025 00:31:49 +0530 Subject: [PATCH 3/4] fix: addressed review comments --- content/nim/deploy/kubernetes/deploy-using-helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nim/deploy/kubernetes/deploy-using-helm.md b/content/nim/deploy/kubernetes/deploy-using-helm.md index 22ae2b2cd..2916e3afd 100644 --- a/content/nim/deploy/kubernetes/deploy-using-helm.md +++ b/content/nim/deploy/kubernetes/deploy-using-helm.md @@ -259,7 +259,7 @@ To upgrade: 1. [Adjust your `values.yaml` file](#create-a-helm-deployment-values.yaml-file) if needed. 1. To upgrade the NGINX Instance Manager deployment, run the following command. This command updates the `nms` deployment with a new version from the `nginx-stable/nms-hybrid` repository. It also hashes the provided password and uses the `values.yaml` file at the path you specify. -(Optional) Replace `` with the desired chart version. If omitted, the latest version will be installed. At present, only version 2.19.0 is supported. +(Optional) Replace `` with the desired chart version. If omitted, the latest version will be installed. Currently only version 2.19.0 is supported. ```bash helm upgrade -n nms \ From 8e772ae5af2edb02777f1e3570e210fe00db1fdc Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 20 Feb 2025 06:07:16 -0800 Subject: [PATCH 4/4] Apply suggestions from code review --- content/nim/deploy/kubernetes/deploy-using-helm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nim/deploy/kubernetes/deploy-using-helm.md b/content/nim/deploy/kubernetes/deploy-using-helm.md index 2916e3afd..7a0de5a95 100644 --- a/content/nim/deploy/kubernetes/deploy-using-helm.md +++ b/content/nim/deploy/kubernetes/deploy-using-helm.md @@ -188,7 +188,7 @@ When `openshift.enabled: true` is set in the `values.yaml` file, the NGINX Insta By default, OpenShift enforces strict security policies that require containers to run as **non-root** users. The NGINX Instance Manager deployment needs specific user IDs (UIDs) for certain services, such as **1000** for `nms` and **101** for `nginx` and `clickhouse`. Since the default SCCs do not allow these UIDs, a **custom SCC** is created. This ensures that the deployment can run with the necessary permissions while maintaining OpenShift’s security standards. The custom SCC allows these UIDs by setting the `runAsUser` field, which controls which users can run containers. -{{< note >}} If you’re encountering errors with the custom [Security Context Constraints](https://docs.openshift.com/container-platform/4.15/authentication/managing-security-context-constraints.html), it may be due to insufficient permissions to access the Security Context Constraints resource. Please contact a Cluster Administrator to request access, either via a ClusterRoleBinding or by adjusting your user role. {{< /note >}} +{{< note >}} If you’re encountering errors with the custom [Security Context Constraints](https://docs.redhat.com/en/documentation/openshift_container_platform/4.15/html/authentication_and_authorization/managing-pod-security-policies), you may not have permissions to access the Security Context Constraints resource. Please contact a Cluster Administrator to request access, either through a cluster role binding or by adjusting your user role. {{< /note >}} To verify that the custom SCC has been created, after installing the helm chart, run: @@ -219,7 +219,7 @@ nms nginx-stable/nms-hybrid \ --wait ``` -To help you choose the right NGINX Instance Manager chart version, refer to the table (applicable for NIM versions up to v2.18.0) in: +To help you choose the right NGINX Instance Manager chart version, see the following table (through version v2.18.0): {{< include "nim/kubernetes/nms-chart-supported-module-versions.md" >}}