Add adminSecretFileRef as alternative to adminSecretRef for file-based credentials in ClusterConnection

.gitignore

@@ -60,3 +60,5 @@ gradle-app.setting
 
 # Quinoa
 .quinoa/
+
+**/out/

docs/cluster-connection.md

@@ -7,13 +7,16 @@ Other Custom Resources (like `Database`, `Role`, `Schema`, `Grant`, `DefaultPriv
 
 ## Spec
 
-| Field            | Type                | Description                                                           | Required | Mutable |
-|------------------|---------------------|-----------------------------------------------------------------------|----------|---------|
-| `host`           | `string`            | The hostname of the PostgreSQL instance.                              | Yes      | Yes     |
-| `port`           | `integer`           | The port of the PostgreSQL instance (1-65535).                        | Yes      | Yes     |
-| `database`       | `string`            | The database to connect to (usually `postgres` for admin operations). | Yes      | Yes     |
-| `adminSecretRef` | `ResourceRef`       | Reference to the Kubernetes Secret containing the admin credentials.  | Yes      | Yes     |
-| `parameters`     | `map[string]string` | Additional connection parameters.                                     | No       | Yes     |
+| Field               | Type                | Description                                                           | Required | Mutable |
+|---------------------|---------------------|-----------------------------------------------------------------------|----------|---------|
+| `host`              | `string`            | The hostname of the PostgreSQL instance.                              | Yes      | Yes     |
+| `port`              | `integer`           | The port of the PostgreSQL instance (1-65535).                        | Yes      | Yes     |
+| `database`          | `string`            | The database to connect to (usually `postgres` for admin operations). | Yes      | Yes     |
+| `adminSecretRef`    | `ResourceRef`       | Reference to the Kubernetes Secret containing the admin credentials.  | No       | Yes     |
+| `adminSecretFileRef`| `ResourceFileRef`   | Reference to a file containing the admin credentials.                 | No       | Yes     |
+| `parameters`        | `map[string]string` | Additional connection parameters.                                     | No       | Yes     |
+
+> **Note:** Exactly one of `adminSecretRef` or `adminSecretFileRef` must be provided.
 
 ### ResourceRef (`adminSecretRef`)
 
@@ -24,7 +27,18 @@ Other Custom Resources (like `Database`, `Role`, `Schema`, `Grant`, `DefaultPriv
 
 The referenced secret must be of type `kubernetes.io/basic-auth` and contain the keys `username` and `password`.
 
-### Example
+### ResourceFileRef (`adminSecretFileRef`)
+
+| Field  | Type     | Description                                                    | Required |
+|--------|----------|----------------------------------------------------------------|----------|
+| `path` | `string` | The path to the file containing the admin credentials.         | Yes      |
+
+Use this option when the credentials are mounted as a file instead of a Kubernetes Secret. The file must be a JSON object with the keys `username` and `password`, for example `{"username": "postgres", "password": "password"}`.
+
+
+### Examples
+
+#### Using a Kubernetes Secret (`adminSecretRef`)
 
 ```yaml
 apiVersion: v1
@@ -54,3 +68,63 @@ spec:
     #sslmode: "require" # Enforce SSL encryption
     #connectTimeout: "10" # Timeout in seconds for connection attempts
 ```
+
+### Using a file reference (`adminSecretFileRef`)
+
+Instead of a Kubernetes Secret, you can mount a JSON credentials file into the operator pod and reference its path. This is useful when credentials are managed externally.
+
+#### File format
+
+The file must contain JSON with the following fields:
+
+```json
+{
+  "username": "root",
+  "password": "password"
+}
+```
+
+- `password` **required**
+- `username` **required**
+
+#### Mount the credentials file
+
+The file must be accessible inside the operator pod at the path specified in `adminSecretFileRef.path`. Mount it using a Volume and VolumeMount on the operator Deployment:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: postgresql-operator
+spec:
+  template:
+    spec:
+      containers:
+        - name: operator
+          volumeMounts:
+            - name: db-credentials
+              mountPath: /mnt/secrets
+              readOnly: true
+      volumes:
+        - name: db-credentials
+          secret:
+            secretName: db-credentials-secret
+```
+
+> **Note:** The volume source can be any type that provides a file.
+
+> **Note:** The Helm chart does not support extra volumes yet. 
+
+```yaml
+apiVersion: postgresql.aboutbits.it/v1
+kind: ClusterConnection
+metadata:
+  name: quarkus-postgres-connection
+spec:
+  adminSecretFileRef:
+    path: "/mnt/secrets/db-credentials.json"
+  host: localhost
+  port: 5432
+  database: postgres
+```
+

docs/docker-environment.md

@@ -39,7 +39,16 @@ users:
 
 ## 2. Create PostgreSQL Connection and Secret
 
-For the `postgresql` Dev Service, you can generate the necessary Custom Resources to test the Operator:
+For the `postgresql` Dev Service, you can generate the necessary Custom Resources to test the Operator.
+
+A `ClusterConnection` requires admin credentials, which can be provided in one of two ways:
+
+- **`adminSecretRef`** references a Kubernetes `basic-auth` Secret (username + password).
+- **`adminSecretFileRef`** references a JSON file mounted into the operator pod.
+
+Exactly one of these must be specified.
+
+### Using a Kubernetes Secret (`adminSecretRef`)
 
 1. From the Dev UI, get the `postgresql` Dev Service properties (username, password, host, port).
 2. Convert the `postgresql` Dev Service properties to a **Basic Auth Secret** and a **ClusterConnection** CR instance.

docs/terraform.md

@@ -95,7 +95,7 @@ Every optional field of every Custom Resource is affected, in particular:
 
 | Custom Resource     | Optional fields                                                                                |
 |---------------------|------------------------------------------------------------------------------------------------|
-| `ClusterConnection` | `parameters`, `adminSecretRef.namespace`                                                       |
+| `ClusterConnection` | `parameters`, `adminSecretRef`, `adminSecretRef.namespace`, `adminSecretFileRef`               |
 | `Database`          | `owner`, `reclaimPolicy`, `clusterRef.namespace`                                               |
 | `Schema`            | `owner`, `reclaimPolicy`, `clusterRef.namespace`                                               |
 | `Role`              | `comment`, `passwordSecretRef`, `flags` (including `flags.validUntil`), `clusterRef.namespace` |

operator/build.gradle.kts

@@ -62,6 +62,7 @@ dependencies {
      */
     testImplementation("io.quarkus:quarkus-junit")
     testImplementation("io.quarkus:quarkus-junit-mockito")
+    testImplementation("io.fabric8:kubernetes-server-mock")
     testImplementation("org.awaitility:awaitility")
     testImplementation(libs.assertj)
     testImplementation(libs.datafaker)

operator/src/main/java/it/aboutbits/postgresql/core/FileRef.java

@@ -0,0 +1,34 @@
+package it.aboutbits.postgresql.core;
+
+import io.fabric8.generator.annotation.Required;
+import io.fabric8.generator.annotation.ValidationRule;
+import lombok.Getter;
+import lombok.Setter;
+import org.jspecify.annotations.NullMarked;
+
+/// A reference to a file inside
+///
+/// This class is used wherever a CRD spec needs to point to a specific file
+/// The [#path] field identifies the file location
+/// within the container.
+///
+/// ### Example usage in a CR manifest
+///
+/// ```yaml
+///  spec:
+///     adminSecretFileRef:
+///         path: "/mnt/secrets/db-credentials.json"
+/// ```
+@Getter
+@Setter
+@NullMarked
+public class FileRef {
+    /// The path to the file.
+    /// Must not be blank.
+    @Required
+    @ValidationRule(
+            value = "self.trim().size() > 0",
+            message = "The path must not be empty."
+    )
+    private String path = "";
+}

operator/src/main/java/it/aboutbits/postgresql/core/KubernetesService.java

@@ -1,29 +1,79 @@
 package it.aboutbits.postgresql.core;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
 import io.fabric8.kubernetes.client.KubernetesClient;
 import it.aboutbits.postgresql.crd.clusterconnection.ClusterConnection;
+import it.aboutbits.postgresql.crd.clusterconnection.ClusterConnectionSpec;
 import jakarta.inject.Singleton;
 import org.jspecify.annotations.NullMarked;
 
+import java.io.IOException;
 import java.nio.charset.Charset;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.Base64;
 
 @Singleton
 @NullMarked
 public final class KubernetesService {
+    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
     public static final String SECRET_TYPE_BASIC_AUTH = "kubernetes.io/basic-auth";
     public static final String SECRET_DATA_BASIC_AUTH_USERNAME_KEY = "username";
     public static final String SECRET_DATA_BASIC_AUTH_PASSWORD_KEY = "password";
 
-    public Credentials getSecretRefCredentials(
+    public Credentials getAdminCredentials(
             KubernetesClient kubernetesClient,
             ClusterConnection clusterConnection
     ) {
-        return getSecretRefCredentials(
-                kubernetesClient,
-                clusterConnection.getSpec().getAdminSecretRef(),
-                clusterConnection.getMetadata().getNamespace()
-        );
+        var spec = clusterConnection.getSpec();
+        if (spec.getAdminSecretRef() != null) {
+            return getSecretRefCredentials(
+                    kubernetesClient,
+                    spec.getAdminSecretRef(),
+                    clusterConnection.getMetadata().getNamespace()
+            );
+        } else if (spec.getAdminSecretFileRef() != null) {
+            return getSecretFileRefCredentials(spec.getAdminSecretFileRef());
+        }
+
+        throw new IllegalStateException("Exactly one of 'adminSecretRef' or 'adminSecretFileRef' must be provided");
+    }
+
+    public Credentials getSecretFileRefCredentials(FileRef fileRef) {
+        var path = Path.of(fileRef.getPath());
+
+        if (!Files.exists(path)) {
+            throw new IllegalStateException("Credential file not found [path=%s]".formatted(path));
+        }
+
+        try {
+            var content = Files.readString(path);
+            var json = OBJECT_MAPPER.readTree(content);
+
+            var usernameNode = json.get(SECRET_DATA_BASIC_AUTH_USERNAME_KEY);
+            var username = usernameNode != null && !usernameNode.isNull()
+                    ? usernameNode.asText()
+                    : null;
+            if (username == null) {
+                throw new IllegalStateException("Credential file is missing required field '%s' [path=%s]".formatted(
+                        SECRET_DATA_BASIC_AUTH_USERNAME_KEY,
+                        path
+                ));
+            }
+
+            var passwordNode = json.get(SECRET_DATA_BASIC_AUTH_PASSWORD_KEY);
+            if (passwordNode == null || passwordNode.isNull()) {
+                throw new IllegalStateException("Credential file is missing required field '%s' [path=%s]".formatted(
+                        SECRET_DATA_BASIC_AUTH_PASSWORD_KEY,
+                        path
+                ));
+            }
+
+            return new Credentials(username, passwordNode.asText());
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to read Credential file [path=%s]".formatted(path), e);
+        }
     }
 
     public Credentials getSecretRefCredentials(

operator/src/main/java/it/aboutbits/postgresql/core/PostgreSQLContextFactory.java

@@ -34,7 +34,7 @@ public CloseableDSLContext getDSLContext(
             ClusterConnection clusterConnection,
             String database
     ) throws DataAccessException {
-        var credentials = kubernetesService.getSecretRefCredentials(
+        var credentials = kubernetesService.getAdminCredentials(
                 kubernetesClient,
                 clusterConnection
         );

operator/src/main/java/it/aboutbits/postgresql/crd/clusterconnection/ClusterConnectionSpec.java

@@ -5,11 +5,13 @@
 import io.fabric8.generator.annotation.Min;
 import io.fabric8.generator.annotation.Required;
 import io.fabric8.generator.annotation.ValidationRule;
+import it.aboutbits.postgresql.core.FileRef;
 import it.aboutbits.postgresql.core.ResourceRef;
 import it.aboutbits.postgresql.core.schema_customizer.HostCustomizer;
 import lombok.Getter;
 import lombok.Setter;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -18,6 +20,10 @@
 @Setter
 @SchemaCustomizer(value = HostCustomizer.class, input = "host")
 @NullMarked
+@ValidationRule(
+        value = "(has(self.adminSecretRef) ? 1 : 0) + (has(self.adminSecretFileRef) ? 1 : 0) == 1",
+        message = "Exactly one of 'adminSecretRef' or 'adminSecretFileRef' must be provided"
+)
 public class ClusterConnectionSpec {
     @Required
     @ValidationRule(
@@ -38,8 +44,11 @@ public class ClusterConnectionSpec {
     )
     private String database = "postgres";
 
-    @Required
-    private ResourceRef adminSecretRef = new ResourceRef();
+    @io.fabric8.generator.annotation.Nullable
+    private @Nullable ResourceRef adminSecretRef;
+
+    @io.fabric8.generator.annotation.Nullable
+    private @Nullable FileRef adminSecretFileRef;
 
     @io.fabric8.generator.annotation.Nullable
     private Map<String, String> parameters = new HashMap<>();

operator/src/test/java/it/aboutbits/postgresql/_support/testdata/persisted/creator/ClusterConnectionCreate.java

@@ -4,6 +4,7 @@
 import io.fabric8.kubernetes.client.KubernetesClient;
 import it.aboutbits.postgresql._support.testdata.base.TestDataCreator;
 import it.aboutbits.postgresql._support.testdata.persisted.Given;
+import it.aboutbits.postgresql.core.FileRef;
 import it.aboutbits.postgresql.core.ResourceRef;
 import it.aboutbits.postgresql.crd.clusterconnection.ClusterConnection;
 import it.aboutbits.postgresql.crd.clusterconnection.ClusterConnectionSpec;
@@ -41,6 +42,11 @@ public class ClusterConnectionCreate extends TestDataCreator<ClusterConnection>
 
     private @Nullable ResourceRef withAdminSecretRef;
 
+    private @Nullable FileRef withAdminSecretFileRef;
+
+    @Setter(AccessLevel.NONE)
+    private boolean withoutAdminSecret = false;
+
     private @Nullable String withApplicationName;
 
     public ClusterConnectionCreate(
@@ -61,6 +67,16 @@ public ClusterConnectionCreate withoutNamespace() {
         return this;
     }
 
+    public ClusterConnectionCreate withAdminSecretFileRef(FileRef fileRef) {
+        this.withAdminSecretFileRef = fileRef;
+        return this;
+    }
+
+    public ClusterConnectionCreate withoutAdminSecret() {
+        this.withoutAdminSecret = true;
+        return this;
+    }
+
     @Override
     protected ClusterConnection create(int index) {
         // given
@@ -81,6 +97,9 @@ protected ClusterConnection create(int index) {
         spec.setPort(getPort());
         spec.setDatabase(getDatabase());
         spec.setAdminSecretRef(getAdminSecretRef());
+        if (withAdminSecretFileRef != null) {
+            spec.setAdminSecretFileRef(withAdminSecretFileRef);
+        }
         spec.setParameters(getParameters());
 
         item.setSpec(spec);
@@ -154,7 +173,11 @@ private String getDatabase() {
         return withDatabase;
     }
 
-    private ResourceRef getAdminSecretRef() {
+    private @Nullable ResourceRef getAdminSecretRef() {
+        if (withoutAdminSecret) {
+            return null;
+        }
+
         if (withAdminSecretRef != null) {
             return withAdminSecretRef;
         }