doc upgrade path for v2 breaking change

.github/workflows/miniziti.yml

@@ -43,9 +43,9 @@ jobs:
       - name: install ziti cli
         uses: supplypike/setup-bin@v4
         with:
-          uri: https://github.com/openziti/ziti/releases/download/v1.2.0/ziti-linux-amd64-1.2.0.tar.gz
+          uri: https://github.com/openziti/ziti/releases/download/v1.4.3/ziti-linux-amd64-1.4.3.tar.gz
           name: ziti
-          version: 1.2.0
+          version: 1.4.3
 
       # this is the kubernetes quickstart script from
       # https://openziti.io/docs/learn/quickstarts/network/local-kubernetes
@@ -59,9 +59,13 @@ jobs:
       - name: Run miniziti with latest release charts
         if: vars.SKIP_MINIKUBE_LATEST_CHARTS != 'true'
         run: miniziti start --no-hosts --verbose
+        env:
+          MINIZITI_TIMEOUT_SECS: 300
 
       - name: Upgrade miniziti with charts from this branch
         run: miniziti start --no-hosts --verbose --charts ./charts
+        env:
+          MINIZITI_TIMEOUT_SECS: 300
 
       - name: Verify the Console is Available
         shell: bash

charts/ziti-controller/README.md

@@ -16,14 +16,64 @@ helm repo add openziti https://docs.openziti.io/helm-charts/
 
 This chart runs a Ziti controller in Kubernetes.
 
-It uses the custom resources provided by [cert-manager](https://cert-manager.io/docs/installation/) and [trust-manager](https://cert-manager.io/docs/projects/trust-manager/#installation), i.e., Issuer, Certificate, and Bundle. It is a limitation of Trust Manager to have one instance per cluster and one namespace from which trust Bundle inputs may be sourced, so a single Ziti controller may occupy the cluster unless your use case allows for controllers from multiple networks to share a namespace. You must set the Trust Manager's "trust namespace" to the namespace of the Ziti controller so that it will be able to build trust Bundle resources from Ziti's root CA cert(s).
+### Mutual TLS
 
-Ziti's TLS server ports must be published with a TLS passthrough. This may be done with a Traefik IngressRouteTCP, Gateway API TLSRoute, Ingress, NodePort, LoadBalancer, etc. The ctrl plane and management API share the client API's TLS listener by default, so there's one TCP port by default that must be published with TLS passthrough enabled.
+Ziti's TLS server ports must be published with a TLS passthrough to allow the controller to validate the client certificates from routers and identities. This may be done with a Traefik IngressRouteTCP, Gateway API TLSRoute, Ingress, NodePort, LoadBalancer, etc. The ctrl plane and management API share the client API's TLS listener by default, so there's one TCP port by default that must be published with TLS passthrough enabled.
+
+### Certificates
 
 It is not normally necessary to obtain publicly trusted certificates for Ziti's TLS servers. Ziti manages the trust relationships between the controller and routers and clients independent of the web's root authorities. See the [Alternative Web Server Certificates](#alternative-web-server-certificates) section for more information.
 
+### Deployment
+
 The deployment must have exactly one replica.
 
+### Custom Resources
+
+This chart requires the custom resources provided by [cert-manager](https://cert-manager.io/docs/installation/) and [trust-manager](https://cert-manager.io/docs/projects/trust-manager/#installation), i.e., Issuer, Certificate, and Bundle. It is a limitation of Trust Manager to have one instance per cluster and one namespace from which trust Bundle inputs may be sourced, so a single Ziti controller may occupy the cluster unless your use case allows for controllers from multiple networks to share a namespace. You must set the Trust Manager's "trust namespace" to the namespace of the Ziti controller so that it will be able to compose a trust Bundle resource from Ziti's root CA cert(s).
+
+```bash
+helm repo add jetstack https://charts.jetstack.io
+
+helm upgrade --install cert-manager jetstack/cert-manager \
+    --namespace cert-manager --create-namespace \
+    --set crds.enabled=true
+
+kubectl create namespace ziti
+helm upgrade --install trust-manager jetstack/trust-manager \
+    --namespace cert-manager \
+    --set crds.keep=false \
+    --set app.trust.namespace=ziti
+```
+
+### Breaking Change
+
+Version 2 of this chart introduces a breaking change. You must decouple cert-manager and trust-manager from the Ziti controller chart if they were previously installed as subcharts. This allows them to be upgraded and configured independently of the Ziti controller chart.
+
+**Symptom**
+
+> Error: Unable to continue with install: CustomResourceDefinition "certificaterequests.cert-manager.io" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "cert-manager"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "cert-manager"
+
+**Cause**
+
+Cert Manager and Trust Manager are no longer included as subcharts. If you have version 1 of the chart installed and cert-manager or trust-manager were installed as subcharts in the same namespace as the Ziti controller, you can run `./files/chown-cert-manager.bash` to set the owner labels and annotations on existing cert-manager and trust-manager CRDs and resources, allowing them to be imported by a future cert-manager or trust-manager installation.
+
+**Solution**
+
+Assuming your future CM release is named "cert-manager," your TM release is named "trust-manager," both are installed in namespace "cert-manager," and your Ziti controller is installed in namespace "ziti," you can run the provided script to pave the way to installing the version 2 ziti-controller chart.
+
+```bash
+helm pull openziti/ziti-controller
+tar -xvf ziti-controller-*.tgz
+CM_NAMESPACE=cert-manager \
+CM_RELEASE_NAME=cert-manager \
+TM_NAMESPACE=cert-manager \
+ZITI_NAMESPACE=ziti \
+./ziti-controller/files/chown-cert-manager.bash
+```
+
+You must install cert-manager and trust-manager Operators and CRDs before installing version 2 of the ziti-controller chart. See the [Custom Resources](#custom-resources) section above for an example.
+
 ## NodePort Service Example
 
 | Value | Description |
@@ -46,10 +96,10 @@ Here's the YAML representation of the same set of input values.
 
 ```yaml
 clientApi:
-  advertisedHost: ctrl1.ziti.example.com
-  advertisedPort: 32171
-  service:
-    type: NodePort
+    advertisedHost: ctrl1.ziti.example.com
+    advertisedPort: 32171
+    service:
+        type: NodePort
 ```
 
 Visit the Ziti Administration Console (ZAC): https://ctrl1.ziti.example.com:32171/zac/

charts/ziti-controller/README.md.gotmpl

@@ -25,14 +25,64 @@ helm repo add openziti https://docs.openziti.io/helm-charts/
 
 This chart runs a Ziti controller in Kubernetes. 
 
-It uses the custom resources provided by [cert-manager](https://cert-manager.io/docs/installation/) and [trust-manager](https://cert-manager.io/docs/projects/trust-manager/#installation), i.e., Issuer, Certificate, and Bundle. It is a limitation of Trust Manager to have one instance per cluster and one namespace from which trust Bundle inputs may be sourced, so a single Ziti controller may occupy the cluster unless your use case allows for controllers from multiple networks to share a namespace. You must set the Trust Manager's "trust namespace" to the namespace of the Ziti controller so that it will be able to build trust Bundle resources from Ziti's root CA cert(s).
+### Mutual TLS
 
-Ziti's TLS server ports must be published with a TLS passthrough. This may be done with a Traefik IngressRouteTCP, Gateway API TLSRoute, Ingress, NodePort, LoadBalancer, etc. The ctrl plane and management API share the client API's TLS listener by default, so there's one TCP port by default that must be published with TLS passthrough enabled.
+Ziti's TLS server ports must be published with a TLS passthrough to allow the controller to validate the client certificates from routers and identities. This may be done with a Traefik IngressRouteTCP, Gateway API TLSRoute, Ingress, NodePort, LoadBalancer, etc. The ctrl plane and management API share the client API's TLS listener by default, so there's one TCP port by default that must be published with TLS passthrough enabled.
+
+### Certificates
 
 It is not normally necessary to obtain publicly trusted certificates for Ziti's TLS servers. Ziti manages the trust relationships between the controller and routers and clients independent of the web's root authorities. See the [Alternative Web Server Certificates](#alternative-web-server-certificates) section for more information.
 
+### Deployment
+
 The deployment must have exactly one replica.
 
+### Custom Resources
+
+This chart requires the custom resources provided by [cert-manager](https://cert-manager.io/docs/installation/) and [trust-manager](https://cert-manager.io/docs/projects/trust-manager/#installation), i.e., Issuer, Certificate, and Bundle. It is a limitation of Trust Manager to have one instance per cluster and one namespace from which trust Bundle inputs may be sourced, so a single Ziti controller may occupy the cluster unless your use case allows for controllers from multiple networks to share a namespace. You must set the Trust Manager's "trust namespace" to the namespace of the Ziti controller so that it will be able to compose a trust Bundle resource from Ziti's root CA cert(s).
+
+```bash
+helm repo add jetstack https://charts.jetstack.io
+
+helm upgrade --install cert-manager jetstack/cert-manager \
+    --namespace cert-manager --create-namespace \
+    --set crds.enabled=true
+
+kubectl create namespace ziti
+helm upgrade --install trust-manager jetstack/trust-manager \
+    --namespace cert-manager \
+    --set crds.keep=false \
+    --set app.trust.namespace=ziti
+```
+
+### Breaking Change
+
+Version 2 of this chart introduces a breaking change. You must decouple cert-manager and trust-manager from the Ziti controller chart if they were previously installed as subcharts. This allows them to be upgraded and configured independently of the Ziti controller chart.
+
+**Symptom**
+
+> Error: Unable to continue with install: CustomResourceDefinition "certificaterequests.cert-manager.io" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "cert-manager"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "cert-manager"
+
+**Cause**
+
+Cert Manager and Trust Manager are no longer included as subcharts. If you have version 1 of the chart installed and cert-manager or trust-manager were installed as subcharts in the same namespace as the Ziti controller, you can run `./files/chown-cert-manager.bash` to set the owner labels and annotations on existing cert-manager and trust-manager CRDs and resources, allowing them to be imported by a future cert-manager or trust-manager installation.
+
+**Solution**
+
+Assuming your future CM release is named "cert-manager," your TM release is named "trust-manager," both are installed in namespace "cert-manager," and your Ziti controller is installed in namespace "ziti," you can run the provided script to pave the way to installing the version 2 ziti-controller chart.
+
+```bash
+helm pull openziti/ziti-controller
+tar -xvf ziti-controller-*.tgz
+CM_NAMESPACE=cert-manager \
+CM_RELEASE_NAME=cert-manager \
+TM_NAMESPACE=cert-manager \
+ZITI_NAMESPACE=ziti \
+./ziti-controller/files/chown-cert-manager.bash
+```
+
+You must install cert-manager and trust-manager Operators and CRDs before installing version 2 of the ziti-controller chart. See the [Custom Resources](#custom-resources) section above for an example.
+
 ## NodePort Service Example
 
 | Value | Description |
@@ -55,10 +105,10 @@ Here's the YAML representation of the same set of input values.
 
 ```yaml
 clientApi:
-  advertisedHost: ctrl1.ziti.example.com
-  advertisedPort: 32171
-  service:
-    type: NodePort
+    advertisedHost: ctrl1.ziti.example.com
+    advertisedPort: 32171
+    service:
+        type: NodePort
 ```
 
 Visit the Ziti Administration Console (ZAC): https://ctrl1.ziti.example.com:32171/zac/

charts/ziti-controller/files/chown-cert-manager.bash

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+#
+# set owner labels and annotations for existing cert-manager and trust-manager CRDs and resources to allow a future
+# cert-manager and trust-manager Helm releases to import them
+#
+
+set -o errexit
+set -o pipefail
+set -o nounset
+
+: "${CM_NAMESPACE:=cert-manager}"
+: "${CM_RELEASE_NAME:=cert-manager}"
+: "${TM_NAMESPACE:=cert-manager}"
+: "${TM_RELEASE_NAME:=trust-manager}"
+: "${ZITI_NAMESPACE:=ziti}"
+
+# cert-manager CRDs, not trust-manager CRD
+while read
+do
+        kubectl annotate crds "$REPLY" --overwrite \
+                meta.helm.sh/release-name="${CM_RELEASE_NAME}" \
+                meta.helm.sh/release-namespace="${CM_NAMESPACE}"
+        kubectl label crds "$REPLY" \
+                app.kubernetes.io/managed-by=Helm
+done< <(kubectl get crds | grep -v 'bundles\.trust\.cert-manager\.io' | grep -w 'cert-manager\.io' | cut -f 1 -d ' ')
+
+# trust-manager CRD
+kubectl annotate crds bundles.trust.cert-manager.io --overwrite \
+        meta.helm.sh/release-name="${TM_RELEASE_NAME}" \
+        meta.helm.sh/release-namespace="${CM_NAMESPACE}"
+kubectl label crds bundles.trust.cert-manager.io \
+        app.kubernetes.io/managed-by=Helm
+
+# cluster-wide core resources to be imported by trust-manager
+for R in ClusterRole{,Binding} ValidatingWebhookConfiguration
+do
+        kubectl annotate "$R" "${TM_RELEASE_NAME}" --overwrite \
+                meta.helm.sh/release-name="${TM_RELEASE_NAME}" \
+                meta.helm.sh/release-namespace="${CM_NAMESPACE}"
+        kubectl label "$R" "${TM_RELEASE_NAME}" \
+                app.kubernetes.io/managed-by=Helm
+done
+
+# namespaced core resources to be imported by trust-manager
+for R in Role{,Binding}
+do
+        kubectl annotate -n "${ZITI_NAMESPACE}" "$R" "${TM_RELEASE_NAME}" --overwrite \
+                meta.helm.sh/release-name="${TM_RELEASE_NAME}" \
+                meta.helm.sh/release-namespace="${CM_NAMESPACE}"
+        kubectl label -n "${ZITI_NAMESPACE}" "$R" "${TM_RELEASE_NAME}" \
+                app.kubernetes.io/managed-by=Helm
+done