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

.gitignore

@@ -60,3 +60,6 @@ gradle-app.setting
 
 # Quinoa
 .quinoa/
+
+generated/out/
+operator/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,17 @@ 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 credentials are mounted as a file (e.g. via AWS Secrets Manager) instead of a Kubernetes Secret.
+
+### Examples
+
+#### Using a Kubernetes Secret (`adminSecretRef`)
 
 ```yaml
 apiVersion: v1
@@ -54,3 +67,18 @@ spec:
     #sslmode: "require" # Enforce SSL encryption
     #connectTimeout: "10" # Timeout in seconds for connection attempts
 ```
+
+#### Using a file reference (`adminSecretFileRef`)
+
+```yaml
+apiVersion: postgresql.aboutbits.it/v1
+kind: ClusterConnection
+metadata:
+  name: my-postgres-connection
+spec:
+  adminSecretFileRef:
+    path: "/mnt/db-password"
+  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 (e.g. from AWS Secrets Manager).
+
+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.
@@ -79,6 +88,65 @@ spec:
   database: postgres
 ```
 
+### 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 (e.g. AWS Secrets Manager).
+
+#### File format
+
+The file must contain JSON with the following fields:
+
+```json
+{
+  "username": "root",
+  "password": "password"
+}
+```
+
+- `password` — **required**
+- `username` — optional (can be omitted)
+
+#### 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 (e.g. a Kubernetes Secret, a CSI volume from AWS Secrets Manager, or a ConfigMap for testing).
+
+#### Example ClusterConnection
+
+```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
+```
+
 ![Established Cluster Connection](images/established-cluster-connection.png)
 
 ## 3. Create a Role

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` |

gradle.properties

@@ -13,3 +13,6 @@ quarkusPlatformGroupId=io.quarkus.platform
 quarkusPlatformArtifactId=quarkus-bom
 quarkusPlatformVersion=3.35.3
 systemProp.quarkus.analytics.disabled=true
+
+# Workaround for Windows: avoid forked process where -D args with {{ }} get mangled by cmd.exe
+systemProp.gradle.quarkus.gradle-worker.no-process=true

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

@@ -1,11 +1,16 @@
 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
@@ -19,11 +24,51 @@ public Credentials getSecretRefCredentials(
             KubernetesClient kubernetesClient,
             ClusterConnection clusterConnection
     ) {
-        return getSecretRefCredentials(
-                kubernetesClient,
-                clusterConnection.getSpec().getAdminSecretRef(),
-                clusterConnection.getMetadata().getNamespace()
-        );
+        ClusterConnectionSpec spec = clusterConnection.getSpec();
+        if (spec.getAdminSecretRef() != null) {
+            return getSecretRefCredentials(
+                    kubernetesClient,
+                    clusterConnection.getSpec().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(ResourceFileRef fileRef) {
+        var path = Path.of(fileRef.getPath());
+
+        if (!Files.exists(path)) {
+            throw new IllegalStateException("AWS Secrets Manager file not found [path=%s]".formatted(path));
+        }
+
+        try {
+            var content = Files.readString(path);
+            var objectMapper = new ObjectMapper();
+            var json = objectMapper.readTree(content);
+
+            var usernameNode = json.get(SECRET_DATA_BASIC_AUTH_USERNAME_KEY);
+            var username = usernameNode != null && !usernameNode.isNull()
+                    ? usernameNode.asText()
+                    : null;
+
+            var passwordNode = json.get(SECRET_DATA_BASIC_AUTH_PASSWORD_KEY);
+            if (passwordNode == null || passwordNode.isNull()) {
+                throw new IllegalStateException("AWS Secrets Manager 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 AWS Secrets Manager file [path=%s]".formatted(path), e);
+        }
     }
 
     public Credentials getSecretRefCredentials(

operator/src/main/java/it/aboutbits/postgresql/core/ResourceFileRef.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 an AWS Secrets Manager secret.
+///
+/// This class is used wherever a CRD spec needs to point to a specific file
+/// within an AWS secret. The [#path] field identifies the file location
+/// inside the secret.
+///
+/// ### Example usage in a CR manifest
+///
+/// ```yaml
+///  spec:
+///     adminSecretFileRef:
+///         path: "/mnt/db-password"
+/// ```
+@Getter
+@Setter
+@NullMarked
+public class ResourceFileRef {
+    /// The path to the file inside the AWS Secrets Manager secret.
+    /// 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/crd/clusterconnection/ClusterConnectionSpec.java

@@ -5,6 +5,7 @@
 import io.fabric8.generator.annotation.Min;
 import io.fabric8.generator.annotation.Required;
 import io.fabric8.generator.annotation.ValidationRule;
+import it.aboutbits.postgresql.core.ResourceFileRef;
 import it.aboutbits.postgresql.core.ResourceRef;
 import it.aboutbits.postgresql.core.schema_customizer.HostCustomizer;
 import lombok.Getter;
@@ -18,6 +19,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 +43,11 @@ public class ClusterConnectionSpec {
     )
     private String database = "postgres";
 
-    @Required
-    private ResourceRef adminSecretRef = new ResourceRef();
+    @io.fabric8.generator.annotation.Nullable
+    private ResourceRef adminSecretRef;
+
+    @io.fabric8.generator.annotation.Nullable
+    private ResourceFileRef adminSecretFileRef;
 
     @io.fabric8.generator.annotation.Nullable
     private Map<String, String> parameters = new HashMap<>();