Addressed PR review comments: require username in adminSecretFileRef, rename to FileRef, use fabric8 mock server, remove AWS references, updated unit tests and docs

Author: Fred Campos

docs/cluster-connection.md

@@ -33,7 +33,8 @@ The referenced secret must be of type `kubernetes.io/basic-auth` and contain the
 |--------|----------|----------------------------------------------------------------|----------|
 | `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.
+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
 
@@ -68,17 +69,62 @@ spec:
     #connectTimeout: "10" # Timeout in seconds for connection attempts
 ```
 
-#### Using a file reference (`adminSecretFileRef`)
+### 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: my-postgres-connection
+  name: quarkus-postgres-connection
 spec:
   adminSecretFileRef:
-    path: "/mnt/db-password"
+    path: "/mnt/secrets/db-credentials.json"
   host: localhost
   port: 5432
   database: postgres
 ```
+

docs/docker-environment.md

@@ -43,8 +43,8 @@ For the `postgresql` Dev Service, you can generate the necessary Custom Resource
 
 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).
+- **`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.
 
@@ -88,65 +88,6 @@ 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

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

@@ -10,14 +10,14 @@
 ///
 /// This class is used wherever a CRD spec needs to point to a specific file
 /// The [#path] field identifies the file location
-/// inside the secret.
+/// within the container.
 ///
 /// ### Example usage in a CR manifest
 ///
 /// ```yaml
 ///  spec:
 ///     adminSecretFileRef:
-///         path: "/mnt/db-password"
+///         path: "/mnt/secrets/db-credentials.json"
 /// ```
 @Getter
 @Setter

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

@@ -16,58 +16,63 @@
 @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
     ) {
-        ClusterConnectionSpec spec = clusterConnection.getSpec();
+        var spec = clusterConnection.getSpec();
         if (spec.getAdminSecretRef() != null) {
             return getSecretRefCredentials(
                     kubernetesClient,
-                    clusterConnection.getSpec().getAdminSecretRef(),
+                    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(ResourceFileRef fileRef) {
+    public Credentials getSecretFileRefCredentials(FileRef fileRef) {
         var path = Path.of(fileRef.getPath());
 
         if (!Files.exists(path)) {
-            throw new IllegalStateException("AWS Secrets Manager file not found [path=%s]".formatted(path));
+            throw new IllegalStateException("Credential file not found [path=%s]".formatted(path));
         }
 
         try {
             var content = Files.readString(path);
-            var objectMapper = new ObjectMapper();
-            var json = objectMapper.readTree(content);
+            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("AWS Secrets Manager file is missing required field '%s' [path=%s]".formatted(
+                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 AWS Secrets Manager file [path=%s]".formatted(path), e);
+            throw new IllegalStateException("Failed to read Credential file [path=%s]".formatted(path), e);
         }
     }
 

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/core/ResourceFileRef.java

@@ -5,12 +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.ResourceFileRef;
+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;
@@ -44,10 +45,10 @@ public class ClusterConnectionSpec {
     private String database = "postgres";
 
     @io.fabric8.generator.annotation.Nullable
-    private ResourceRef adminSecretRef;
+    private @Nullable ResourceRef adminSecretRef;
 
     @io.fabric8.generator.annotation.Nullable
-    private ResourceFileRef adminSecretFileRef;
+    private @Nullable FileRef adminSecretFileRef;
 
     @io.fabric8.generator.annotation.Nullable
     private Map<String, String> parameters = new HashMap<>();

operator/src/main/java/it/aboutbits/postgresql/crd/clusterconnection/ClusterConnectionSpec.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);
@@ -116,7 +135,7 @@ protected ClusterConnection create(int index) {
     }
 
     private String getName() {
-        if (withName != null) {
+    if (withName != null) {
             return withName;
         }
 
@@ -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;
         }