feat(helm): support existing token Secret (SOPS) and scope token RBAC to (#497)

Author: sandipanpanda

docs/existing-secret-sops.md

@@ -0,0 +1,71 @@
+# Use an existing Secret for the token (SOPS / GitOps)
+
+Instead of putting `clusterToken` / `patToken` in your values, point the chart
+at a Secret you manage. You encrypt only that Secret with
+[SOPS](https://github.com/getsops/sops); your values file stays token-free.
+
+## The one flag that matters
+
+Take the helm command from the dashboard's **Connect cluster** button and add:
+
+```
+--set zxporter.existingSecret.name=<your-secret-name>
+```
+
+That's it — the chart then reads the token from your Secret instead of creating
+its own, and no token ever appears in the helm command or values.
+
+## Steps (SOPS + age)
+
+```bash
+export NS=devzero-system
+
+# 1. Create the SOPS-encrypted Secret (encrypt only the data; commit the .enc.yaml).
+age-keygen -o key.txt                      # prints: Public key: age1xxxx...
+cat > zxporter-token.secret.yaml <<'EOF'
+apiVersion: v1
+kind: Secret
+metadata:
+  name: zxporter-token
+type: Opaque
+stringData:
+  PAT_TOKEN: "dzp_your_pat"                 # or CLUSTER_TOKEN: "..."
+EOF
+sops --encrypt --age age1xxxx... --encrypted-regex '^(data|stringData)$' \
+  zxporter-token.secret.yaml > zxporter-token.secret.enc.yaml
+rm zxporter-token.secret.yaml
+
+# 2. Apply it into the namespace (server-side keeps plaintext out of annotations).
+kubectl create namespace $NS --dry-run=client -o yaml | kubectl apply -f -
+SOPS_AGE_KEY_FILE=$PWD/key.txt sops --decrypt zxporter-token.secret.enc.yaml \
+  | kubectl apply --server-side -n $NS -f -
+
+# 3. Run the dashboard's Connect-cluster helm command with the extra flag:
+#      --set zxporter.existingSecret.name=zxporter-token
+```
+
+**GitOps:** commit `zxporter-token.secret.enc.yaml` and let Argo CD (KSOPS /
+`argocd-vault-plugin`) or Flux (`decryption.provider: sops`) decrypt it at sync
+time; set `zxporter.existingSecret.name` in the HelmRelease/Application values.
+
+## Values
+
+```yaml
+zxporter:
+  existingSecret:
+    name: ""                       # your Secret; empty = use clusterToken/patToken
+    clusterTokenKey: "CLUSTER_TOKEN"
+    patTokenKey: "PAT_TOKEN"
+```
+
+Provide one token — `CLUSTER_TOKEN` or `PAT_TOKEN`. Only used when
+`useSecretForToken: true` (the default).
+
+## Gotchas
+
+- **Secret must exist in the release namespace before install** (`secretKeyRef`
+  is namespace-local).
+- **Name must differ from `tokenSecretName`** (default `devzero-zxporter-token`) —
+  the chart manages that one itself. The chart fails fast if they match.
+- **Wrong/missing key = no auth, no crash** (keys are `optional`). Check pod logs
+  for `no URL or token was configured`.

helm-chart/zxporter/templates/NOTES.txt

@@ -7,14 +7,23 @@ To learn more about the release, try:
   $ helm status {{ .Release.Name }}  -n {{ .Release.Namespace }}
   $ helm get all {{ .Release.Name }}  -n {{ .Release.Namespace }}
 
-{{- if and (not .Values.zxporter.clusterToken) (not .Values.zxporter.patToken) }}
+{{- if and (not .Values.zxporter.clusterToken) (not .Values.zxporter.patToken) (not (dig "existingSecret" "name" "" .Values.zxporter)) }}
 
 NOTE: No authentication token configuration detected.
 
 ZXPorter requires either a cluster token or PAT token to authenticate with the DevZero platform.
 Please configure one of the following:
 1. Set zxporter.clusterToken with your cluster token from the DevZero dashboard
 2. Set zxporter.patToken with your Personal Access Token for automatic token exchange (recommended for production)
+3. Set zxporter.existingSecret.name to a pre-existing Secret (in this namespace) holding CLUSTER_TOKEN and/or PAT_TOKEN (recommended for SOPS/GitOps)
+
+{{- end }}
+{{- if dig "existingSecret" "name" "" .Values.zxporter }}
+
+NOTE: Using pre-existing token Secret "{{ dig "existingSecret" "name" "" .Values.zxporter }}".
+Ensure it exists in namespace {{ .Release.Namespace }} and contains at least one of:
+  - {{ dig "existingSecret" "clusterTokenKey" "CLUSTER_TOKEN" .Values.zxporter }} (cluster token)
+  - {{ dig "existingSecret" "patTokenKey" "PAT_TOKEN" .Values.zxporter }} (PAT token)
 
 {{- end }}
 

helm-chart/zxporter/templates/_helpers.tpl

@@ -52,10 +52,15 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 Validate required configuration
 */}}
 {{- define "zxporter.validateConfig" -}}
-  {{- if and (empty .Values.zxporter.clusterToken) (empty .Values.zxporter.patToken) -}}
-    {{- fail "ERROR: Either zxporter.clusterToken or zxporter.patToken must be provided. Please set one of these values in your values file." -}}
+  {{- if and (empty .Values.zxporter.clusterToken) (empty .Values.zxporter.patToken) (empty (dig "existingSecret" "name" "" .Values.zxporter)) -}}
+    {{- fail "ERROR: A token must be provided. Set one of zxporter.clusterToken, zxporter.patToken, or zxporter.existingSecret.name (a pre-existing Secret holding the token)." -}}
   {{- end -}}
-  
+
+  {{- $existingName := dig "existingSecret" "name" "" .Values.zxporter -}}
+  {{- if and $existingName (eq $existingName .Values.zxporter.tokenSecretName) -}}
+    {{- fail (printf "ERROR: zxporter.existingSecret.name (%q) must not equal zxporter.tokenSecretName. The chart creates and writes to that runtime Secret itself, so reusing the name would collide on install and let the controller overwrite your managed Secret." .Values.zxporter.tokenSecretName) -}}
+  {{- end -}}
+
   {{- if empty .Values.zxporter.kubeContextName -}}
     {{- fail "ERROR: zxporter.kubeContextName is required. Please provide a unique identifier for your cluster." -}}
   {{- end -}}

helm-chart/zxporter/templates/deployment.yaml

@@ -60,6 +60,26 @@ spec:
                 fieldRef:
                   fieldPath: metadata.namespace
           {{- if .Values.zxporter.useSecretForToken }}
+          {{- $existingName := dig "existingSecret" "name" "" .Values.zxporter }}
+          {{- if $existingName }}
+            # Tokens sourced from a pre-existing (e.g. SOPS-managed) Secret.
+            # Both keys are optional so a Secret with only one of them is valid.
+            # CLUSTER_TOKEN is taken from this Secret rather than the runtime Secret;
+            # after a PAT exchange the controller still recovers the exchanged token
+            # from the runtime Secret via the Kubernetes API (see custom.go).
+            - name: CLUSTER_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ $existingName }}
+                  key: {{ dig "existingSecret" "clusterTokenKey" "CLUSTER_TOKEN" .Values.zxporter }}
+                  optional: true
+            - name: PAT_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ $existingName }}
+                  key: {{ dig "existingSecret" "patTokenKey" "PAT_TOKEN" .Values.zxporter }}
+                  optional: true
+          {{- else }}
             - name: CLUSTER_TOKEN
               valueFrom:
                 secretKeyRef:
@@ -74,6 +94,7 @@ spec:
                   key: PAT_TOKEN
             {{- end }}
           {{- end }}
+          {{- end }}
           livenessProbe:
             httpGet:
               path: /healthz

helm-chart/zxporter/templates/secret-credentials.yaml

@@ -1,4 +1,5 @@
 {{- if .Values.zxporter.useSecretForToken }}
+{{- if not (dig "existingSecret" "name" "" .Values.zxporter) }}
 {{- if or .Values.zxporter.clusterToken .Values.zxporter.patToken }}
 # Input credentials Secret (user-managed)
 # Contains initial PAT/CLUSTER tokens provided by user
@@ -19,4 +20,5 @@ data:
   PAT_TOKEN: {{ .Values.zxporter.patToken | b64enc | quote }}
   {{- end }}
 {{- end }}
+{{- end }}
 {{- end }}

helm-chart/zxporter/templates/zxporter-rbac.yaml

@@ -221,39 +221,6 @@ rules:
   - list
   - watch
   - update
-{{- if .Values.zxporter.useSecretForToken }}
-# Secret access for cluster token persistence when useSecretForToken is enabled
-
-# General Secret create permission (needed to create runtime token secret)
-- apiGroups:
-  - ""
-  resources:
-  - secrets
-  verbs:
-  - create
-
-# Read-only access to credentials Secret (user-provided PAT/CLUSTER tokens)
-- apiGroups:
-  - ""
-  resourceNames:
-  - {{ .Values.zxporter.tokenCredentialsSecretName }}
-  resources:
-  - secrets
-  verbs:
-  - get
-
-# Read/write access to runtime token Secret (exchanged tokens)
-- apiGroups:
-  - ""
-  resourceNames:
-  - {{ .Values.zxporter.tokenSecretName }}
-  resources:
-  - secrets
-  verbs:
-  - get
-  - patch
-  - update
-{{- end }}
 # Core Kubernetes resources (READ-ONLY monitoring)
 - apiGroups:
   - ""

helm-chart/zxporter/values.yaml

@@ -43,6 +43,29 @@ zxporter:
   logLevel: "error"
   # Disable GPU metrics collection (set to "true" for clusters without GPUs)
   disableGPUMetrics: ""
+  # Point to a pre-existing Secret that already holds the auth token(s), instead of
+  # passing clusterToken/patToken through this values file. This is intended for
+  # GitOps/SOPS workflows where you want to encrypt only the Secret, not the whole
+  # values file.
+  #
+  # When existingSecret.name is set:
+  #   - the chart does NOT create the credentials Secret (you manage it yourself)
+  #   - the controller sources PAT_TOKEN and/or CLUSTER_TOKEN from this Secret
+  #   - it satisfies the "a token is required" validation
+  #
+  # Requirements:
+  #   - The Secret must already exist in the release namespace (secretKeyRef is
+  #     namespace-local) before the controller pod starts.
+  #   - It must contain at least one of the keys below. Both env vars are injected
+  #     with optional=true, so a Secret with only one key is fine.
+  #   - Only meaningful when useSecretForToken=true.
+  existingSecret:
+    # Name of the pre-existing Secret. Leave empty to use clusterToken/patToken above.
+    name: ""
+    # Key within the Secret holding the cluster token (direct-token installs).
+    clusterTokenKey: "CLUSTER_TOKEN"
+    # Key within the Secret holding the PAT token (PAT-exchange installs).
+    patTokenKey: "PAT_TOKEN"
   # Resource names for token storage (configurable for different environments)
   # Input credentials Secret: Contains initial PAT/CLUSTER tokens (user-managed)
   tokenCredentialsSecretName: "devzero-zxporter-credentials"