feat: helm standards

Author: loks0n

README.md

@@ -9,70 +9,75 @@ The Better Stack Operator keeps Better Stack monitors in sync with Kubernetes by
 - **Lifecycle management** – Finalizers ensure remote monitors are removed when their CRs are deleted, preventing orphaned resources.
 - **Status you can trust** – `Ready`, `CredentialsAvailable`, and `Synced` conditions expose reconciliation health.
 
-## Helm Install
+## Install with Helm
 
-Once a release is tagged (`vX.Y.Z`), the publish workflow builds and pushes a chart to:
+Published charts live at `oci://ghcr.io/loks0n/betterstack-operator/helm/betterstack-operator`.
 
-```
-oci://ghcr.io/loks0n/betterstack-operator/helm/betterstack-operator
-```
+### 1. Provide Better Stack credentials
 
-Install/update the operator with:
+Choose how the controller should access the API token:
 
-```bash
-helm upgrade --install betterstack-operator \
-  oci://ghcr.io/loks0n/betterstack-operator/helm/betterstack-operator \
-  --namespace betterstack-operator --create-namespace \
-  --wait
-```
+- **Chart-managed secret** – let the release create the secret in its namespace (default `betterstack-operator`).
 
-Create the `betterstack-credentials` secret before running the chart (see Quick Start step 2).
+  ```bash
+  helm upgrade --install betterstack-operator \
+    oci://ghcr.io/loks0n/betterstack-operator/helm/betterstack-operator \
+    --namespace betterstack-operator --create-namespace \
+    --set credentials.secret.create=true \
+    --set-file credentials.secret.value=./betterstack-token.txt \
+    --wait
+  ```
 
-## Quick Start
+  Swap `--set-file` for `--set credentials.secret.value=$TOKEN` if you prefer piping the token directly from an environment variable or secret store.
 
-1. **Fetch dependencies and (optionally) build**
+- **Bring-your-own secret** – pre-create it and point the chart at it:
 
-   ```bash
-   go mod tidy
-   go build ./...
-   ```
+  ```bash
+  kubectl create secret generic betterstack-operator-credentials \
+    --from-literal=api-key=REPLACE_ME \
+    -n betterstack-operator
+
+  helm upgrade --install betterstack-operator \
+    oci://ghcr.io/loks0n/betterstack-operator/helm/betterstack-operator \
+    --namespace betterstack-operator --create-namespace \
+    --set credentials.existingSecret=betterstack-operator-credentials \
+    --wait
+  ```
 
-2. **Create an API token secret**
+The chart-generated secret defaults to `betterstack-operator-credentials`. Whichever path you choose, the secret must exist in every namespace where you define `BetterStackMonitor` objects.
 
-   ```bash
-   kubectl create secret generic betterstack-credentials \
-     --from-literal=api-key=REPLACE_ME \
-     -n default
-   ```
+### 2. Create monitors
 
-3. **Install CRD, RBAC, and controller**
+Apply one of the sample CRs to verify the install:
 
-   ```bash
-   kubectl apply -f config/crd/bases/monitoring.betterstack.io_betterstackmonitors.yaml
-   kubectl apply -f config/rbac/service_account.yaml
-   kubectl apply -f config/rbac/role.yaml
-   kubectl apply -f config/rbac/role_binding.yaml
-   kubectl apply -k config/manager
-   ```
+```bash
+kubectl apply -f config/samples/monitoring_v1alpha1_betterstackmonitor_https.yaml
+kubectl apply -f config/samples/monitoring_v1alpha1_betterstackmonitor_keyword.yaml
+kubectl apply -f config/samples/monitoring_v1alpha1_betterstackmonitor_tcp.yaml
+```
 
-4. **Create a monitor resource**
+Check reconciliation status and debug events with:
 
-   Choose one (or more) of the sample manifests:
+```bash
+kubectl get betterstackmonitors.monitoring.betterstack.io -A
+kubectl describe betterstackmonitor demo-monitor
+```
 
-   ```bash
-   kubectl apply -f config/samples/monitoring_v1alpha1_betterstackmonitor_https.yaml
-   kubectl apply -f config/samples/monitoring_v1alpha1_betterstackmonitor_keyword.yaml
-   kubectl apply -f config/samples/monitoring_v1alpha1_betterstackmonitor_tcp.yaml
-   ```
+Deleting a `BetterStackMonitor` automatically deletes the remote Better Stack monitor thanks to controller finalizers.
 
-5. **Inspect status**
+### Configuration highlights
 
-   ```bash
-   kubectl get betterstackmonitors.monitoring.betterstack.io -A
-   kubectl describe betterstackmonitor demo-monitor
-   ```
+See `helm/betterstack-operator/values.yaml` for the full list. Frequently tuned values include:
 
-Deleting the `BetterStackMonitor` automatically deletes the remote Better Stack monitor.
+- `credentials.existingSecret` – reference a pre-created secret instead of letting the chart manage one.
+- `credentials.secret.*` – control chart-managed secret creation (name override, key, annotations, inline value).
+- `imagePullSecrets` – add registry credentials when pulling the operator image.
+- `podAnnotations`, `podLabels`, `podSecurityContext`, `containerSecurityContext` – attach metadata or adjust pod/container security posture.
+- `nodeSelector`, `tolerations`, `affinity` – steer the operator onto matching nodes.
+- `namespace` – pin all resources to a specific namespace (defaults to the release namespace).
+- `manager.*` – adjust controller ports, enable/disable leader election, and pass extra arguments.
+- `rbac.create` – disable default RBAC when running with pre-provisioned roles.
+- `crds.install` – set to `false` when CRDs are installed out-of-band (e.g., via GitOps).
 
 ## Spec Reference (excerpt)
 
@@ -99,13 +104,34 @@ See `api/v1alpha1/betterstackmonitor_types.go` for the full schema and commentar
 
 ## Troubleshooting
 
-- `CredentialsAvailable=False` – Confirm the referenced secret exists and contains the API key.
-- `Synced=False` – The Better Stack API rejected the payload; inspect the condition message for validation errors.
-- `Ready=True` – The latest spec was successfully applied.
+- `CredentialsAvailable=False` – confirm the referenced secret exists and contains the API key in the expected key.
+- `Synced=False` – the Better Stack API rejected the payload; inspect the condition message for validation errors.
+- `Ready=True` – the latest spec was successfully applied.
 
 Enable verbose logging with `--zap-log-level=debug` in the manager deployment for extra context.
 
-## Testing
+## Manual installation (development)
+
+The manifests under `config/` are primarily for hacking on the controller:
+
+```bash
+kubectl apply -f config/crd/bases/monitoring.betterstack.io_betterstackmonitors.yaml
+kubectl apply -f config/rbac/service_account.yaml
+kubectl apply -f config/rbac/role.yaml
+kubectl apply -f config/rbac/role_binding.yaml
+kubectl apply -k config/manager
+```
+
+You still need to create a matching secret in the target namespace before running the manager locally or via these raw manifests.
+
+## Development
+
+- Module path: `loks0n/betterstack-operator`.
+- API types live under `api/v1alpha1`; controller logic is in `controllers/betterstackmonitor_controller.go`.
+- The Better Stack API client lives in `pkg/betterstack`.
+- E2E helpers are in `test/e2e`, relying on `kind`, `kubectl`, and a Better Stack test token.
+
+### Testing
 
 - **Unit tests**
 
@@ -122,11 +148,4 @@ Enable verbose logging with `--zap-log-level=debug` in the manager deployment fo
 
   The e2e test boots a Kind cluster, installs the CRD and controller, applies a richly populated `BetterStackMonitor`, and asserts (via the Better Stack API) that create/update/delete operations are reflected remotely. The test cleans up the remote monitor, but run it only against non-production credentials.
 
-## Development Notes
-
-- Module path: `loks0n/betterstack-operator`.
-- API types live under `api/v1alpha1`; controller logic is in `controllers/betterstackmonitor_controller.go`.
-- The Better Stack API client (create/update/get/list/delete) resides in `pkg/betterstack`.
-- E2E helpers are in `test/e2e`, relying on `kind`, `kubectl`, and genuine Better Stack credentials.
-
 Contributions, issues, and ideas are welcome!

config/samples/monitoring_v1alpha1_betterstackmonitor_https.yaml

@@ -35,5 +35,5 @@ spec:
     - name: X-Monitor-Source
       value: betterstack-operator
   apiTokenSecretRef:
-    name: betterstack-credentials
+    name: betterstack-operator-credentials
     key: api-key

config/samples/monitoring_v1alpha1_betterstackmonitor_keyword.yaml

@@ -27,5 +27,5 @@ spec:
   maintenanceTo: "01:00:00"
   maintenanceTimezone: Europe/London
   apiTokenSecretRef:
-    name: betterstack-credentials
+    name: betterstack-operator-credentials
     key: api-key

config/samples/monitoring_v1alpha1_betterstackmonitor_tcp.yaml

@@ -24,5 +24,5 @@ spec:
   maintenanceTo: "04:00:00"
   maintenanceTimezone: America/New_York
   apiTokenSecretRef:
-    name: betterstack-credentials
+    name: betterstack-operator-credentials
     key: api-key

helm/betterstack-operator/templates/deployment.yaml

@@ -18,14 +18,29 @@ spec:
       labels:
         app.kubernetes.io/name: {{ include "betterstack-operator.name" . }}
         app.kubernetes.io/instance: {{ .Release.Name }}
+        {{- with .Values.podLabels }}{{ toYaml . | nindent 8 }}{{- end }}
+      {{- with .Values.podAnnotations }}
+      annotations:
+{{ toYaml . | nindent 8 }}
+      {{- end }}
     spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+{{ toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.podSecurityContext }}
+      securityContext:
+{{ toYaml . | nindent 8 }}
+      {{- end }}
       serviceAccountName: {{ default (include "betterstack-operator.fullname" .) .Values.serviceAccount.name }}
       containers:
         - name: manager
           image: "{{ .Values.image.repository }}:{{ default .Chart.AppVersion .Values.image.tag }}"
           imagePullPolicy: {{ .Values.image.pullPolicy }}
           args:
             - "--leader-elect={{ .Values.manager.leaderElection }}"
+            - "--metrics-bind-address=:{{ .Values.manager.metricsPort }}"
+            - "--health-probe-bind-address=:{{ .Values.manager.healthProbePort }}"
             {{- range $arg := .Values.manager.extraArgs }}
             - {{ $arg | quote }}
             {{- end }}
@@ -42,9 +57,21 @@ spec:
             httpGet:
               path: /healthz
               port: healthz
+          {{- with .Values.containerSecurityContext }}
           securityContext:
-            allowPrivilegeEscalation: false
-            runAsNonRoot: true
-            runAsUser: 65532
+{{ toYaml . | nindent 12 }}
+          {{- end }}
           resources:
 {{ toYaml .Values.resources | indent 12 }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+{{ toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+{{ toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+{{ toYaml . | nindent 8 }}
+      {{- end }}

helm/betterstack-operator/templates/secret.yaml

@@ -0,0 +1,22 @@
+{{- $existing := .Values.credentials.existingSecret -}}
+{{- if and (not $existing) .Values.credentials.secret.create }}
+{{- $name := default (printf "%s-credentials" (include "betterstack-operator.fullname" .)) .Values.credentials.secret.name -}}
+{{- $key := default "api-key" .Values.credentials.secret.key -}}
+{{- $value := required "credentials.secret.value must be set when credentials.secret.create is true" .Values.credentials.secret.value -}}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ $name }}
+  namespace: {{ include "betterstack-operator.namespace" . }}
+  labels:
+    app.kubernetes.io/name: {{ include "betterstack-operator.name" . }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- with .Values.credentials.secret.annotations }}
+  annotations:
+{{ toYaml . | nindent 4 }}
+{{- end }}
+type: Opaque
+stringData:
+  {{ $key }}: {{ $value | quote }}
+{{- end }}

helm/betterstack-operator/templates/serviceaccount.yaml

@@ -8,4 +8,8 @@ metadata:
     app.kubernetes.io/name: {{ include "betterstack-operator.name" . }}
     app.kubernetes.io/instance: {{ .Release.Name }}
     app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- with .Values.serviceAccount.annotations }}
+  annotations:
+{{ toYaml . | nindent 4 }}
+{{- end }}
 {{- end }}

helm/betterstack-operator/values.yaml

@@ -3,16 +3,22 @@ image:
   tag: ""
   pullPolicy: IfNotPresent
 
+imagePullSecrets: []
+
 nameOverride: ""
 fullnameOverride: ""
 
 namespace: ""
 
 replicaCount: 1
 
+podAnnotations: {}
+podLabels: {}
+
 serviceAccount:
   create: true
   name: ""
+  annotations: {}
 
 resources:
   requests:
@@ -22,9 +28,22 @@ resources:
     cpu: 300m
     memory: 256Mi
 
+podSecurityContext: {}
+
+containerSecurityContext:
+  allowPrivilegeEscalation: false
+  runAsNonRoot: true
+  runAsUser: 65532
+
+nodeSelector: {}
+
+tolerations: []
+
+affinity: {}
+
 manager:
   leaderElection: true
-  metricsPort: 8443
+  metricsPort: 8080
   healthProbePort: 8081
   extraArgs: []
 
@@ -33,3 +52,12 @@ rbac:
 
 crds:
   install: true
+
+credentials:
+  existingSecret: ""
+  secret:
+    create: false
+    name: ""
+    key: api-key
+    value: ""
+    annotations: {}