From 5b354eb8d02804d2ce6c95b3a018616159c4bdef Mon Sep 17 00:00:00 2001 From: Dean Coakley Date: Wed, 1 Jul 2020 12:12:20 +0100 Subject: [PATCH] Fix multiple KIC deploys via helm --- deployments/helm-chart/README.md | 64 ++++++++++++++++- .../transportserver.yaml} | 6 +- .../virtualserver.yaml} | 6 +- .../virtualserverroute.yaml} | 6 +- deployments/helm-chart/templates/crds.yaml | 7 ++ .../installation/installation-with-helm.md | 68 ++++++++++++++++++- 6 files changed, 144 insertions(+), 13 deletions(-) rename deployments/helm-chart/{templates/controller-ts-definition.yaml => crds/transportserver.yaml} (95%) rename deployments/helm-chart/{templates/controller-vs-definition.yaml => crds/virtualserver.yaml} (99%) rename deployments/helm-chart/{templates/controller-vsr-definition.yaml => crds/virtualserverroute.yaml} (99%) create mode 100644 deployments/helm-chart/templates/crds.yaml diff --git a/deployments/helm-chart/README.md b/deployments/helm-chart/README.md index dd556fbdb8..906cd9fd63 100644 --- a/deployments/helm-chart/README.md +++ b/deployments/helm-chart/README.md @@ -15,10 +15,26 @@ This chart deploys the NGINX Ingress controller in your Kubernetes cluster. ## Installing the Chart +### Installing the CRDs + +By default, Helm installs a number of custom resource definitions (CRDs). Those CRDs are required for the VirtualServer, VirtualServerRoute and TransportServer custom resources. + +If you do not use those resources (which corresponds to `controller.enableCustomResources` set to `false`), you can skip the installation of the CRDs: + +* Using Helm 3.x client: + + Specify `--skip-crds` for the helm install command. + +* Using a Helm 2.x client: + + Set `controller.enableCustomResources` to `false`. + +> **Note**: If the CRDs are already installed in the cluster, Helm will skip the CRDs installation. + ### Installing via Helm Repository 1. Add NGINX Helm repository: - ``` + ```console $ helm repo add nginx-edge https://helm.nginx.com/edge $ helm repo update ``` @@ -92,8 +108,38 @@ This chart deploys the NGINX Ingress controller in your Kubernetes cluster. > **Tip**: List all releases using `helm list` +## Upgrading the Chart + +### Upgrading the CRDs + +Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, run the following command to upgrade the CRDs: + +```console +$ kubectl apply -f crds/ +``` + +> **Note**: Make sure to check the [release notes](https://www.github.com/nginxinc/kubernetes-ingress/releases) for a new release for any special upgrade procedures. + +### Upgrading the Release + +To upgrade the release `my-release` + +* Using Helm 3.x client: + + ```console + $ helm upgrade my-release + ``` + +* Using Helm 2.x client: + + ```console + $ helm upgrade -n my-release + ``` + ## Uninstalling the Chart +### Uninstalling the Release + To uninstall/delete the release `my-release` * Using Helm 3.x client: @@ -110,6 +156,22 @@ To uninstall/delete the release `my-release` The command removes all the Kubernetes components associated with the chart and deletes the release. +### Uninstalling the CRDs + +Uninstalling the release does not remove the CRDs. To remove the CRDs, run: + +```console +$ kubectl delete crds transportservers.k8s.nginx.org virtualservers.k8s.nginx.org virtualserverroutes.k8s.nginx.org +``` + +> **Note**: The following command will delete all the corresponding custom resources in your cluster across all namespaces. Please ensure there are no custom resources that you want to keep and there are no other Ingress Controller releases running in the cluster. + +## Running Multiple Ingress Controllers + +If you are running multiple Ingress Controller releases in your cluster with enabled custom resources, the releases will share a single version of the CRDs. As a result, make sure that the Ingress Controller versions match the version of the CRDs. Additionally, when uninstalling a release, ensure that you don’t remove the CRDs until there are no other Ingress Controller releases running in the cluster. + +See [running multiple ingress controllers](https://docs.nginx.com/nginx-ingress-controller/installation/running-multiple-ingress-controllers/) for more details. + ## Configuration The following tables lists the configurable parameters of the NGINX Ingress controller chart and their default values. diff --git a/deployments/helm-chart/templates/controller-ts-definition.yaml b/deployments/helm-chart/crds/transportserver.yaml similarity index 95% rename from deployments/helm-chart/templates/controller-ts-definition.yaml rename to deployments/helm-chart/crds/transportserver.yaml index cefee61914..689eb32613 100644 --- a/deployments/helm-chart/templates/controller-ts-definition.yaml +++ b/deployments/helm-chart/crds/transportserver.yaml @@ -1,10 +1,11 @@ -{{- if .Values.controller.enableCustomResources }} apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: name: transportservers.k8s.nginx.org labels: - {{- include "nginx-ingress.labels" . | nindent 4 }} + app.kubernetes.io/name: "nginx-ingress" + annotations: + "helm.sh/hook": crd-install spec: group: k8s.nginx.org versions: @@ -76,4 +77,3 @@ spec: type: integer service: type: string -{{- end }} diff --git a/deployments/helm-chart/templates/controller-vs-definition.yaml b/deployments/helm-chart/crds/virtualserver.yaml similarity index 99% rename from deployments/helm-chart/templates/controller-vs-definition.yaml rename to deployments/helm-chart/crds/virtualserver.yaml index 7aa9a38bfd..15acf73136 100644 --- a/deployments/helm-chart/templates/controller-vs-definition.yaml +++ b/deployments/helm-chart/crds/virtualserver.yaml @@ -1,10 +1,11 @@ -{{- if .Values.controller.enableCustomResources }} apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: name: virtualservers.k8s.nginx.org labels: - {{- include "nginx-ingress.labels" . | nindent 4 }} + app.kubernetes.io/name: "nginx-ingress" + annotations: + "helm.sh/hook": crd-install spec: group: k8s.nginx.org versions: @@ -648,4 +649,3 @@ spec: type: string state: type: string -{{- end }} diff --git a/deployments/helm-chart/templates/controller-vsr-definition.yaml b/deployments/helm-chart/crds/virtualserverroute.yaml similarity index 99% rename from deployments/helm-chart/templates/controller-vsr-definition.yaml rename to deployments/helm-chart/crds/virtualserverroute.yaml index 502cabcb55..ddcdcbdc2e 100644 --- a/deployments/helm-chart/templates/controller-vsr-definition.yaml +++ b/deployments/helm-chart/crds/virtualserverroute.yaml @@ -1,10 +1,11 @@ -{{- if .Values.controller.enableCustomResources }} apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: name: virtualserverroutes.k8s.nginx.org labels: - {{- include "nginx-ingress.labels" . | nindent 4 }} + app.kubernetes.io/name: "nginx-ingress" + annotations: + "helm.sh/hook": crd-install spec: group: k8s.nginx.org versions: @@ -632,4 +633,3 @@ spec: type: string state: type: string -{{- end }} diff --git a/deployments/helm-chart/templates/crds.yaml b/deployments/helm-chart/templates/crds.yaml new file mode 100644 index 0000000000..0557f404e2 --- /dev/null +++ b/deployments/helm-chart/templates/crds.yaml @@ -0,0 +1,7 @@ +{{- if .Values.controller.enableCustomResources }} +{{- range $path, $bytes := .Files.Glob "crds/*.yaml" }} +{{ $.Files.Get $path }} +--- +{{- end }} +{{- end }} + diff --git a/docs-web/installation/installation-with-helm.md b/docs-web/installation/installation-with-helm.md index 154f9672a8..c11bb7fa7a 100644 --- a/docs-web/installation/installation-with-helm.md +++ b/docs-web/installation/installation-with-helm.md @@ -13,17 +13,33 @@ This document describes how to install the NGINX Ingress Controller in your Kube ## Installing the Chart +### Installing the CRDs + +By default, Helm installs a number of custom resource definitions (CRDs). Those CRDs are required for the VirtualServer, VirtualServerRoute and TransportServer custom resources. + +If you do not use those resources (which corresponds to `controller.enableCustomResources` set to `false`), you can skip the installation of the CRDs: + +* Using Helm 3.x client: + + Specify `--skip-crds` for the helm install command. + +* Using a Helm 2.x client: + + Set `controller.enableCustomResources` to `false`. + +> **Note**: If the CRDs are already installed in the cluster, Helm will skip the CRDs installation. + ### Installing via Helm Repository 1. Add NGINX Helm repository: - ``` + ```console $ helm repo add nginx-edge https://helm.nginx.com/edge $ helm repo update ``` 2. To install the chart with the release name my-release (my-release is the name that you choose): - * Using Helm 3.x client: + * Using Helm 3.x client: For NGINX: ```console @@ -47,7 +63,7 @@ This document describes how to install the NGINX Ingress Controller in your Kube $ helm install --name my-release nginx-edge/nginx-ingress --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true ``` -## Installing Using Chart Sources +### Installing Using Chart Sources 1. Clone the Ingress controller repo: ```console @@ -89,8 +105,38 @@ This document describes how to install the NGINX Ingress Controller in your Kube > **Tip**: List all releases using `helm list` +## Upgrading the Chart + +### Upgrading the CRDs + +Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, run the following command to upgrade the CRDs: + +```console +$ kubectl apply -f crds/ +``` + +> **Note**: Make sure to check the [release notes](https://www.github.com/nginxinc/kubernetes-ingress/releases) for a new release for any special upgrade procedures. + +### Upgrading the Release + +To upgrade the release `my-release` + +* Using Helm 3.x client: + + ```console + $ helm upgrade my-release + ``` + +* Using Helm 2.x client: + + ```console + $ helm upgrade -n my-release + ``` + ## Uninstalling the Chart +### Uninstalling the Release + To uninstall/delete the release `my-release` * Using Helm 3.x client: @@ -107,6 +153,22 @@ To uninstall/delete the release `my-release` The command removes all the Kubernetes components associated with the chart and deletes the release. +### Uninstalling the CRDs + +Uninstalling the release does not remove the CRDs. To remove the CRDs, run: + +```console +$ kubectl delete crds transportservers.k8s.nginx.org virtualservers.k8s.nginx.org virtualserverroutes.k8s.nginx.org +``` + +> **Note**: The following command will delete all the corresponding custom resources in your cluster across all namespaces. Please ensure there are no custom resources that you want to keep and there are no other Ingress Controller releases running in the cluster. + +## Running Multiple Ingress Controllers + +If you are running multiple Ingress Controller releases in your cluster with enabled custom resources, the releases will share a single version of the CRDs. As a result, make sure that the Ingress Controller versions match the version of the CRDs. Additionally, when uninstalling a release, ensure that you don’t remove the CRDs until there are no other Ingress Controller releases running in the cluster. + +See [running multiple ingress controllers](/nginx-ingress-controller/installation/running-multiple-ingress-controllers/) for more details. + ## Configuration The following tables lists the configurable parameters of the NGINX Ingress controller chart and their default values.