docs: review and update all documentation for v0.1.0 release

- Add CHANGELOG.md with v0.1.0 entry covering all 4 API groups and 20 CRDs
- Document new certSecretRef field for external TLS verification in README
  and Helm chart README; clarify MissingExternalTLSCert condition
- Correct credential documentation: list all three options (SecretRef,
  username/password, inline) and note external components require explicit creds
- Fix external-searchdb-example.yaml: add TLS Secret and certSecretRef to
  satisfy the new MissingExternalTLSCert validation gate
- Fix example files: storageConfig (was storage), heapSize (was jvmHeapSize),
  remove invalid replicas field on Server/TimeSeries/Search components
- Fix connectionRef in examples to reference AxonOpsConnection CR not a Secret;
  add AxonOpsConnection CR definitions to all three example files
- Fix MetricAlertFilters field: dc (was dataCenter)
- Fix CRD count in Helm chart README: 20 (was 19)

Author: digiserg

CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-04-09
+
+Initial public release of the AxonOps Kubernetes Operator.
+
+### Added
+
+#### Infrastructure (`core.axonops.com`)
+- `AxonOpsPlatform` CRD — deploys and manages the full AxonOps server stack (axon-server, axon-dash, axondb-timeseries, axondb-search) from a single declarative resource
+- `AxonOpsConnection` CRD — stores reusable AxonOps API credentials referenced by alert and backup CRDs
+- Internal database components: operator-managed StatefulSets with automatic credential generation and TLS certificate provisioning via cert-manager
+- External database support: connect axon-server to user-managed Cassandra and Elasticsearch/OpenSearch clusters
+- TLS for external connections: `spec.*.external.tls.certSecretRef` — required when `tls.enabled=true` and `tls.insecureSkipVerify=false`; omitting it sets `Ready=False` with reason `MissingExternalTLSCert`
+- `spec.imageRegistry` — global registry override for all default component images (on-premises support)
+- `spec.initImage` — configurable init container image (default: `docker.io/library/busybox:1.37.0`)
+- `spec.pause` — halts reconciliation without deleting owned resources
+- Startup ordering: Server waits for databases to be ready; Dashboard waits for Server
+- Config rolling updates via checksum annotations on pod templates
+- Ingress and Gateway API support for Server (agent and API endpoints) and Dashboard
+- `spec.server.license.secretRef` / `spec.server.license.key` for license configuration
+- `spec.server.config` for additional axon-server configuration (merged into generated config)
+
+#### Alerting and operations (`alerts.axonops.com`)
+- `AxonOpsMetricAlert` — metric threshold alert rules
+- `AxonOpsLogAlert` — log pattern alert rules
+- `AxonOpsAlertRoute` — alert routing to notification channels
+- `AxonOpsAlertEndpoint` — integration endpoint definitions (PagerDuty, Slack, email, OpsGenie, etc.)
+- `AxonOpsHealthcheckHTTP` — HTTP endpoint healthchecks
+- `AxonOpsHealthcheckTCP` — TCP port healthchecks
+- `AxonOpsHealthcheckShell` — shell script healthchecks
+- `AxonOpsDashboardTemplate` — declarative dashboard management
+- `AxonOpsAdaptiveRepair` — adaptive Cassandra repair configuration
+- `AxonOpsScheduledRepair` — cron-based Cassandra scheduled repairs
+- `AxonOpsCommitlogArchive` — commitlog archive settings
+- `AxonOpsSilenceWindow` — alert silence windows
+- `AxonOpsLogCollector` — log collector configuration
+
+#### Backups (`backups.axonops.com`)
+- `AxonOpsBackup` — Cassandra scheduled snapshot backups with S3, SFTP, and Azure Blob storage support; inline and SecretRef credential patterns
+
+#### Kafka (`kafka.axonops.com`)
+- `AxonOpsKafkaTopic` — Kafka topic lifecycle and configuration management
+- `AxonOpsKafkaACL` — Kafka ACL entry management
+- `AxonOpsKafkaConnector` — Kafka Connect connector management
+
+#### Operator infrastructure
+- OpenTelemetry tracing support (OTLP exporter, configurable via environment variables)
+- Prometheus metrics endpoint with RBAC protection (port 8443, HTTPS)
+- Periodic drift detection on all controllers
+- Leader election support for multi-replica deployments
+- Namespace-scoped watch (`--watch-namespaces` flag)
+- Helm chart published to `oci://ghcr.io/axonops/charts/axonops-operator`
+- Kustomize-based installation (`make deploy`)
+- Convenience RBAC helper roles (`rbacHelpers.enable=true` in Helm values)
+
+### Security
+- All AxonOps API URL path segments escaped with `url.PathEscape()` to prevent path injection
+- `errors.As` used throughout for safe API error type discrimination
+- Controller metrics served over HTTPS with RBAC-protected scraping endpoint
+
+### Known limitations
+- Defaulting webhooks are not yet implemented; all components require explicit configuration (`enabled: true` must be set)
+- No conversion webhooks; only `v1alpha1` is available
+- External database credentials are not auto-generated; `authentication.secretRef` or inline credentials are required
+- `BuildHostURL` hardcodes `https://`, ignoring the `protocol` field in `AxonOpsConnection`
+- A new AxonOps API client is created on every reconciliation (no connection reuse)
+- Ingress and Gateway resources are not cleaned up automatically when disabled after initial creation
+
+[0.1.0]: https://github.com/axonops/axonops-operator/releases/tag/v0.1.0

DEVELOPMENT.md

@@ -461,9 +461,10 @@ Add RBAC markers in the controller file alongside the `Reconcile` method. `make
 The `AxonAuthentication` struct defines credential priority for database components:
 
 1. `SecretRef` — reference to an existing Kubernetes Secret (highest priority)
-2. Auto-generated random credentials via `generateRandomPassword` (default fallback)
+2. `Username` / `Password` — inline credentials specified directly in the CR
+3. Auto-generated random credentials via `generateRandomPassword` (default fallback for internal components only)
 
-> **Note:** Inline `username` / `password` fields are not yet supported. Use `secretRef` or rely on auto-generation.
+> **Note:** Auto-generation applies only to internal (operator-managed) components. External components (`spec.*.external.hosts` set) require explicit credentials via `secretRef` or inline `username`/`password`.
 
 The generated password meets complexity requirements: at least one uppercase letter, one digit, and one special character.
 

README.md

@@ -148,11 +148,17 @@ spec:
     external:
       hosts:
         - https://elasticsearch.example.com:9200
+      tls:
+        enabled: true
+        insecureSkipVerify: true   # Set to false and add certSecretRef for full TLS verification
+        # certSecretRef: elasticsearch-tls  # Secret with ca.crt, tls.crt, tls.key
     authentication:
       secretRef: elasticsearch-credentials  # Secret with AXONOPS_SEARCH_USER / AXONOPS_SEARCH_PASSWORD
   dashboard: {}
 ```
 
+> **TLS verification:** When `tls.enabled=true` and `tls.insecureSkipVerify=false`, you must also set `tls.certSecretRef` to the name of a Secret containing `ca.crt`, `tls.crt`, and `tls.key`. Without it, the operator sets `Ready=False` with reason `MissingExternalTLSCert`.
+
 ### Alert management
 
 Create an `AxonOpsConnection` once per namespace, then reference it from alert resources.
@@ -214,12 +220,13 @@ Each component can operate in **internal** (operator-managed) or **external** (u
 
 ### Authentication
 
-For each database component, the operator uses credentials in this priority order:
+For internal (operator-managed) database components, credentials are resolved in this priority order:
 
-1. `authentication.secretRef` — reference an existing Secret
-2. Auto-generated — operator creates and manages a Secret with random credentials
+1. `authentication.secretRef` — reference an existing Secret containing `AXONOPS_DB_USER` / `AXONOPS_DB_PASSWORD` (or `AXONOPS_SEARCH_USER` / `AXONOPS_SEARCH_PASSWORD` for Search)
+2. `authentication.username` / `authentication.password` — inline credentials in the CR
+3. Auto-generated — operator creates and manages a Secret with random credentials
 
-> **Note:** Inline `authentication.username` / `authentication.password` fields are not yet supported. Use `secretRef` or rely on auto-generation.
+> **Note:** External components (those with `spec.*.external.hosts` set) require explicit credentials. Auto-generation does not apply to external database connections. Set `authentication.secretRef` or `authentication.username`/`authentication.password` when using external hosts.
 
 ### Ingress and Gateway API
 

charts/axonops-operator/README.md

@@ -37,7 +37,7 @@ kubectl get crd | grep axonops.com
 
 ## Custom Resource Definitions
 
-The operator introduces 19 CRDs across four API groups.
+The operator introduces 20 CRDs across four API groups.
 
 ### `core.axonops.com/v1alpha1`
 
@@ -103,7 +103,7 @@ spec:
 
 ### Deploy the AxonOps stack with external databases
 
-Use this form when Cassandra and Elasticsearch are managed outside the operator.
+Use this form when Cassandra and Elasticsearch are managed outside the operator. External components require explicit credentials — auto-generation does not apply.
 
 ```yaml
 apiVersion: core.axonops.com/v1alpha1
@@ -119,17 +119,25 @@ spec:
       hosts:
         - cassandra-node1.example.com:9042
         - cassandra-node2.example.com:9042
+      tls:
+        enabled: false
     authentication:
-      secretRef: cassandra-credentials
+      secretRef: cassandra-credentials   # Secret with AXONOPS_DB_USER / AXONOPS_DB_PASSWORD
   search:
     external:
       hosts:
         - https://elasticsearch.example.com:9200
+      tls:
+        enabled: true
+        insecureSkipVerify: true   # Set to false and add certSecretRef for full TLS verification
+        # certSecretRef: elasticsearch-tls  # Secret with ca.crt, tls.crt, tls.key
     authentication:
-      secretRef: elasticsearch-credentials
+      secretRef: elasticsearch-credentials  # Secret with AXONOPS_SEARCH_USER / AXONOPS_SEARCH_PASSWORD
   dashboard: {}
 ```
 
+> **TLS verification:** When `tls.enabled=true` and `tls.insecureSkipVerify=false`, you must set `tls.certSecretRef` to the name of a Secret containing `ca.crt`, `tls.crt`, and `tls.key`. Without it, the operator sets `Ready=False` with reason `MissingExternalTLSCert`.
+
 ### Configure an API connection and alert rule
 
 `AxonOpsConnection` provides credentials for all other CRDs in the same namespace. `tokenType` is auto-detected from the host: cloud hosts (`dash.axonops.cloud`, `dash.axonopsdev.com`) default to `Bearer`; self-hosted instances default to `AxonApi`. Set it explicitly to override.

config/samples/external-searchdb-example.yaml

@@ -8,6 +8,21 @@ stringData:
   AXONOPS_SEARCH_USER: admin
   AXONOPS_SEARCH_PASSWORD: "your-secure-password-here"
 ---
+# TLS certificate secret for verifying the external Search endpoint.
+# Required when tls.enabled=true and tls.insecureSkipVerify=false.
+# The Secret must contain ca.crt, tls.crt, and tls.key.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: external-search-tls
+  namespace: default
+type: kubernetes.io/tls
+data:
+  # Base64-encoded PEM values:
+  ca.crt: <base64-encoded-ca-cert>
+  tls.crt: <base64-encoded-client-cert>
+  tls.key: <base64-encoded-client-key>
+---
 apiVersion: core.axonops.com/v1alpha1
 kind: AxonOpsPlatform
 metadata:
@@ -23,8 +38,12 @@ spec:
       tls:
         enabled: true
         insecureSkipVerify: false
+        # certSecretRef is required when insecureSkipVerify is false.
+        # Omitting it will set Ready=False with reason MissingExternalTLSCert.
+        certSecretRef: external-search-tls
     authentication:
-      # Use an existing secret with credentials
+      # Use an existing secret with credentials.
+      # External Search requires explicit credentials — they are not auto-generated.
       secretRef: external-search-credentials
 
   # Server configuration

examples/axonops/README.md

@@ -38,11 +38,8 @@ kubectl port-forward -n axonops svc/server-dashboard 3000:3000
 **Use Case**: Production deployments with high availability
 
 **Features**:
-- Multi-replica setup (HA):
-  - Server: 3 replicas
-  - TimeSeries: 3 replicas
-  - Search: 2 replicas
-  - Dashboard: 2 replicas
+- Larger resource allocations for TimeSeries, Search, and Dashboard components
+- Dashboard replicas set to 2 (the only component that supports the `replicas` field)
 - TLS certificates via cert-manager and Let's Encrypt
 - Proper resource requests/limits
 - 100Gi Server, 500Gi TimeSeries, 250Gi Search storage
@@ -79,12 +76,12 @@ kubectl apply -f examples/axonops/medium.yaml
 **Use Case**: Enterprise deployments with advanced features
 
 **Features**:
-- Ultra-HA setup (5x Server, 5x TimeSeries, 3x Search, 3x Dashboard)
+- Full-scale setup (TimeSeries, Search, Dashboard StatefulSets/Deployments with large resource allocations)
 - Gateway API (Istio) instead of Ingress
 - Advanced TLS with Vault issuer
 - Large storage: 500Gi Server, 1Ti TimeSeries, 500Gi Search
-- JVM tuning (16GB heap for TimeSeries)
-- Multi-cluster support (Cassandra US-East, Kafka)
+- JVM tuning (16GB heap for TimeSeries via `heapSize`)
+- Multi-cluster monitoring support (Cassandra US-East, Kafka)
 - Sophisticated alert routing:
   - PagerDuty, Slack, OpsGenie integration
   - Different routing for Critical/Warning/Info
@@ -144,7 +141,6 @@ vault write pki/roles/kubernetes \
 spec:
   server:
     orgName: "Organization Name"        # Required
-    replicas: 3                         # Number of server instances
     repository:
       image: "..."                      # Docker image
       tag: "..."                        # Image tag
@@ -156,8 +152,10 @@ spec:
       limits:
         cpu: "4"
         memory: "8Gi"
-    storage:
-      size: "100Gi"
+    storageConfig:                      # PersistentVolumeClaimSpec
+      resources:
+        requests:
+          storage: "100Gi"
       storageClassName: "fast-ssd"
     apiIngress:                         # Optional
       enabled: true
@@ -180,7 +178,7 @@ spec:
 ```yaml
 spec:
   dashboard:
-    replicas: 2
+    replicas: 2                         # Only dashboard supports replicas
     repository:
       image: "..."
       tag: "..."
@@ -198,15 +196,17 @@ spec:
 ```yaml
 spec:
   timeSeries:
-    replicas: 3
-    storage:
-      size: "500Gi"
+    heapSize: "16384M"                  # JVM heap size (e.g., "1024M", "4G")
+    storageConfig:                      # PersistentVolumeClaimSpec
+      resources:
+        requests:
+          storage: "500Gi"
       storageClassName: "premium-ssd"
-    jvmHeapSize: "16g"                  # JVM heap tuning
   search:
-    replicas: 2
-    storage:
-      size: "250Gi"
+    storageConfig:
+      resources:
+        requests:
+          storage: "250Gi"
       storageClassName: "premium-ssd"
 ```
 
@@ -273,8 +273,10 @@ kubectl describe certificate axonops-api-tls -n axonops-prod
 ```yaml
 spec:
   timeSeries:
-    storage:
-      size: "1Ti"  # Increase to 1TB
+    storageConfig:
+      resources:
+        requests:
+          storage: "1Ti"  # Increase to 1TB
 ```
 
 ### Adjust resource limits
@@ -294,15 +296,15 @@ spec:
 ```yaml
 spec:
   timeSeries:
-    storage:
+    storageConfig:
       storageClassName: "fast-nvme"
 ```
 
 ### Configure custom JVM heap
 ```yaml
 spec:
   timeSeries:
-    jvmHeapSize: "32g"  # For large deployments
+    heapSize: "32768M"  # For large deployments (e.g., 32GB)
 ```
 
 ---