Skip to content

Commit acfecfa

Browse files
ThoSapThoSap
committed
rework the ClusterConnection docs with the new file reference option
1 parent 465ee82 commit acfecfa

1 file changed

Lines changed: 116 additions & 82 deletions

File tree

‎docs/cluster-connection.md‎

Lines changed: 116 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ Other Custom Resources (like `Database`, `Role`, `Schema`, `Grant`, `DefaultPriv
77

88
## Spec
99

10-
| Field | Type | Description | Required | Mutable |
11-
|----------------------|----------------------|-----------------------------------------------------------------------|----------|---------|
12-
| `host` | `string` | The hostname of the PostgreSQL instance. | Yes | Yes |
13-
| `port` | `integer` | The port of the PostgreSQL instance (1-65535). | Yes | Yes |
14-
| `database` | `string` | The database to connect to (usually `postgres` for admin operations). | Yes | Yes |
15-
| `adminSecretRef` | `ResourceRef` | Reference to the Kubernetes Secret containing the admin credentials. | No | Yes |
16-
| `adminSecretFileRef` | `FileRef` | Reference to a file containing the admin credentials. | No | Yes |
17-
| `parameters` | `map[string]string` | Additional connection parameters. | No | Yes |
10+
| Field | Type | Description | Required | Mutable |
11+
|----------------------|---------------------|-----------------------------------------------------------------------|----------|---------|
12+
| `host` | `string` | The hostname of the PostgreSQL instance. | Yes | Yes |
13+
| `port` | `integer` | The port of the PostgreSQL instance (1-65535). | Yes | Yes |
14+
| `database` | `string` | The database to connect to (usually `postgres` for admin operations). | Yes | Yes |
15+
| `adminSecretRef` | `ResourceRef` | Reference to the Kubernetes Secret containing the admin credentials. | No | Yes |
16+
| `adminSecretFileRef` | `FileRef` | Reference to a file containing the admin credentials. | No | Yes |
17+
| `parameters` | `map[string]string` | Additional connection parameters. | No | Yes |
1818

1919
> **Note:** Exactly one of `adminSecretRef` or `adminSecretFileRef` must be provided.
2020
@@ -29,11 +29,12 @@ The referenced secret must be of type `kubernetes.io/basic-auth` and contain the
2929

3030
### FileRef (`adminSecretFileRef`)
3131

32-
| Field | Type | Description | Required |
33-
|--------|----------|----------------------------------------------------------------|----------|
34-
| `path` | `string` | The path to the file containing the admin credentials. | Yes |
32+
Use this option when the credentials should be mounted as a file inside the operator Pod instead of reading a Kubernetes Secret directly.
33+
34+
| Field | Type | Description | Required |
35+
|--------|----------|-----------------------------------------------------------------------------------------|----------|
36+
| `path` | `string` | The absolute path inside the operator Pod to the file containing the admin credentials. | Yes |
3537

36-
Use this option when the credentials are mounted as a file instead of a Kubernetes Secret.
3738

3839
#### File format
3940

@@ -51,33 +52,93 @@ The file must contain JSON with the following fields:
5152

5253
#### Mount the credentials file
5354

54-
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:
55+
The file must be accessible inside the operator Pod at the path in `adminSecretFileRef.path`.
56+
57+
The Helm chart exposes the `app.volumes` and `app.volumeMounts` values for this.
58+
Both take the raw Kubernetes syntax, so any volume source that provides a file works.
59+
60+
The value of `adminSecretFileRef.path` is the `mountPath` plus the name of the file. The volume source decides the file name:
61+
62+
| Volume source | The file name comes from |
63+
|----------------------------------|---------------------------------|
64+
| `secret` | the key of the Secret |
65+
| `csi` (Secrets Store CSI driver) | the `objectAlias` of the object |
66+
67+
See [Using a file reference](#using-a-file-reference-adminsecretfileref) in the examples for a complete setup with each volume source.
68+
69+
## Examples
70+
71+
### Using a Kubernetes Secret (`adminSecretRef`)
5572

5673
```yaml
57-
apiVersion: apps/v1
58-
kind: Deployment
74+
apiVersion: v1
75+
kind: Secret
5976
metadata:
60-
name: postgresql-operator
77+
name: my-db-secret
78+
type: kubernetes.io/basic-auth
79+
stringData:
80+
username: postgres
81+
password: password
82+
```
83+
84+
```yaml
85+
apiVersion: postgresql.aboutbits.it/v1
86+
kind: ClusterConnection
87+
metadata:
88+
name: my-postgres-connection
6189
spec:
62-
template:
63-
spec:
64-
containers:
65-
- name: postgresql-operator
66-
volumeMounts:
67-
- name: db-credentials
68-
mountPath: /mnt/secrets
69-
readOnly: true
70-
volumes:
71-
- name: db-credentials
72-
secret:
73-
secretName: db-credentials-secret
90+
adminSecretRef:
91+
name: my-db-secret
92+
host: localhost
93+
port: 5432
94+
database: postgres
95+
# Example parameters
96+
parameters:
97+
ApplicationName: "k8s-operator" # Helps identify this connection in Postgres logs
98+
#sslmode: "require" # Enforce SSL encryption
99+
#connectTimeout: "10" # Timeout in seconds for connection attempts
74100
```
75101

76-
> **Note:** The volume source can be any type that provides a file.
102+
### Using a file reference (`adminSecretFileRef`)
77103

78-
##### With the Helm chart
104+
```yaml
105+
apiVersion: postgresql.aboutbits.it/v1
106+
kind: ClusterConnection
107+
metadata:
108+
name: my-postgres-connection
109+
spec:
110+
adminSecretFileRef:
111+
path: "/mnt/secrets/db-credentials.json"
112+
host: localhost
113+
port: 5432
114+
database: postgres
115+
# Example parameters
116+
parameters:
117+
ApplicationName: "k8s-operator" # Helps identify this connection in Postgres logs
118+
#sslmode: "require" # Enforce SSL encryption
119+
#connectTimeout: "10" # Timeout in seconds for connection attempts
120+
```
121+
122+
The mount that creates `/mnt/secrets/db-credentials.json` depends on the volume source.
79123

80-
The chart exposes the `app.volumes` and `app.volumeMounts` values. Both take the raw Kubernetes syntax, so any volume source works. Pass them in your own values file:
124+
#### From a Secret volume
125+
126+
Create the Secret. Its key becomes the file name:
127+
128+
```yaml
129+
apiVersion: v1
130+
kind: Secret
131+
metadata:
132+
name: db-credentials-secret
133+
stringData:
134+
db-credentials.json: |
135+
{
136+
"username": "root",
137+
"password": "password"
138+
}
139+
```
140+
141+
Then mount it through the chart values:
81142
82143
```yaml
83144
app:
@@ -91,15 +152,13 @@ app:
91152
readOnly: true
92153
```
93154
94-
```bash
95-
helm install postgresql-operator <chart-url> --values values.yaml
96-
```
155+
#### From the Secrets Store CSI driver
97156
98-
See the [installation section](../README.md#helm-chart) of the README for the chart URL.
157+
Use this option to read the credentials from an external secret store, for example AWS Secrets Manager.
99158
100-
##### With the Secrets Store CSI driver
159+
> **Note:** Install the [Secrets Store CSI driver](https://secrets-store-csi-driver.sigs.k8s.io/getting-started/installation) and the [provider](https://secrets-store-csi-driver.sigs.k8s.io/providers) for your secret store first. Neither the operator nor the chart installs them. Without the driver, the operator Pod stays in `ContainerCreating` and reports a failed mount.
101160

102-
Use this option to read the credentials from an external secret store, for example AWS Secrets Manager. The chart does not create the `SecretProviderClass`, so you have to apply it yourself:
161+
The chart does not create the `SecretProviderClass`, so you have to apply it yourself. Its `objectAlias` becomes the file name:
103162

104163
```yaml
105164
apiVersion: secrets-store.csi.x-k8s.io/v1
@@ -114,7 +173,9 @@ spec:
114173
objectAlias: "db-credentials.json"
115174
```
116175

117-
Then reference it from the chart values:
176+
> **Note:** The `SecretProviderClass` must live in the namespace of the operator.
177+
178+
Then mount it through the chart values:
118179

119180
```yaml
120181
app:
@@ -131,53 +192,26 @@ app:
131192
readOnly: true
132193
```
133194

134-
> **Note:** The `SecretProviderClass` must live in the namespace of the operator.
135-
136-
### Examples
195+
#### Without the Helm chart
137196

138-
#### Using a Kubernetes Secret (`adminSecretRef`)
197+
If you deploy the operator directly from the OCI image, set the same `volumes` and `volumeMounts` fields on the Deployment:
139198

140199
```yaml
141-
apiVersion: v1
142-
kind: Secret
143-
metadata:
144-
name: my-db-secret
145-
type: kubernetes.io/basic-auth
146-
stringData:
147-
username: postgres
148-
password: password
149-
```
150-
151-
```yaml
152-
apiVersion: postgresql.aboutbits.it/v1
153-
kind: ClusterConnection
154-
metadata:
155-
name: my-postgres-connection
156-
spec:
157-
adminSecretRef:
158-
name: my-db-secret
159-
host: localhost
160-
port: 5432
161-
database: postgres
162-
# Example parameters
163-
parameters:
164-
ApplicationName: "k8s-operator" # Helps identify this connection in Postgres logs
165-
#sslmode: "require" # Enforce SSL encryption
166-
#connectTimeout: "10" # Timeout in seconds for connection attempts
167-
```
168-
169-
#### Using a file reference (`adminSecretFileRef`)
170-
171-
```yaml
172-
apiVersion: postgresql.aboutbits.it/v1
173-
kind: ClusterConnection
200+
apiVersion: apps/v1
201+
kind: Deployment
174202
metadata:
175-
name: quarkus-postgres-connection
203+
name: postgresql-operator
176204
spec:
177-
adminSecretFileRef:
178-
path: "/mnt/secrets/db-credentials.json"
179-
host: localhost
180-
port: 5432
181-
database: postgres
205+
template:
206+
spec:
207+
containers:
208+
- name: postgresql-operator
209+
volumeMounts:
210+
- name: db-credentials
211+
mountPath: /mnt/secrets
212+
readOnly: true
213+
volumes:
214+
- name: db-credentials
215+
secret:
216+
secretName: db-credentials-secret
182217
```
183-

0 commit comments

Comments
 (0)