Skip to content

Commit e1f7fc9

Browse files
ThoSapThoSap
authored
Merge pull request #6 from aboutbits/ab-449-polish-readme-and-docs
AB-449 Polish the `README.md` and add new docs
2 parents 0d6bc52 + a7bd463 commit e1f7fc9

14 files changed

+686
-131
lines changed

‎.editorconfig‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ indent_size = 2
1515

1616
[*.md]
1717
max_line_length = off
18+
indent_size = 2
1819

1920
[Makefile*]
2021
indent_style = tab

‎.github/workflows/main.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
name: Test
22

33
on:
4+
push:
5+
branches:
6+
- main
47
pull_request:
58
types: [ opened, reopened, synchronize ]
69

‎README.md‎

Lines changed: 188 additions & 131 deletions
Large diffs are not rendered by default.

‎docs/cluster-connection.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# ClusterConnection
2+
3+
The `ClusterConnection` Custom Resource Definition (CRD) defines the connection details for a PostgreSQL cluster.
4+
It specifies the host, port, database, and the credentials to use for administrative operations.
5+
6+
Other Custom Resources (like `Database`, `Role`, `Schema`, `Grant`, `DefaultPrivilege`) reference a specific target PostgreSQL cluster using `clusterRef` on which to execute the operations.
7+
8+
## Spec
9+
10+
| Field | Type | Description | Required |
11+
|------------------|---------------------|-----------------------------------------------------------------------|----------|
12+
| `host` | `string` | The hostname of the PostgreSQL instance. | Yes |
13+
| `port` | `integer` | The port of the PostgreSQL instance (1-65535). | Yes |
14+
| `database` | `string` | The database to connect to (usually `postgres` for admin operations). | Yes |
15+
| `adminSecretRef` | `SecretRef` | Reference to the secret containing admin credentials. | Yes |
16+
| `parameters` | `map[string]string` | Additional connection parameters. | No |
17+
18+
### SecretRef
19+
20+
| Field | Type | Description | Required |
21+
|-------------|----------|---------------------------------------------------------------------|----------|
22+
| `name` | `string` | Name of the secret. | Yes |
23+
| `namespace` | `string` | Namespace of the secret. If not specified, uses the CR's namespace. | No |
24+
25+
The referenced secret must be of type `kubernetes.io/basic-auth` and contain the keys `username` and `password`.
26+
27+
### Example
28+
29+
```yaml
30+
apiVersion: v1
31+
kind: Secret
32+
metadata:
33+
name: my-db-secret
34+
type: kubernetes.io/basic-auth
35+
stringData:
36+
username: postgres
37+
password: password
38+
```
39+
40+
```yaml
41+
apiVersion: postgresql.aboutbits.it/v1
42+
kind: ClusterConnection
43+
metadata:
44+
name: my-postgres-connection
45+
spec:
46+
adminSecretRef:
47+
name: my-db-secret
48+
host: localhost
49+
port: 5432
50+
database: postgres
51+
# Example parameters
52+
parameters:
53+
ApplicationName: "k8s-operator" # Helps identify this connection in Postgres logs
54+
#sslmode: "require" # Enforce SSL encryption
55+
#connectTimeout: "10" # Timeout in seconds for connection attempts
56+
```

‎docs/database.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Database
2+
3+
The `Database` Custom Resource Definition (CRD) is responsible for managing PostgreSQL databases.
4+
5+
## Spec
6+
7+
| Field | Type | Description | Required | Immutable |
8+
|-----------------|--------------------|------------------------------------------------------------------------------------------------------|----------|-----------|
9+
| `clusterRef` | `ClusterReference` | Reference to the `ClusterConnection` to use. | Yes | No |
10+
| `name` | `string` | The name of the database to create. | Yes | Yes |
11+
| `owner` | `string` | The owner of the database. | No | No |
12+
| `reclaimPolicy` | `string` | The policy for reclaiming the database when the CR is deleted. Values: `Retain` (Default), `Delete`. | No | No |
13+
14+
### ClusterReference
15+
16+
| Field | Type | Description | Required |
17+
|-------------|----------|----------------------------------------------------------------------------------|----------|
18+
| `name` | `string` | Name of the `ClusterConnection`. | Yes |
19+
| `namespace` | `string` | Namespace of the `ClusterConnection`. If not specified, uses the CR's namespace. | No |
20+
21+
### Reclaim Policy
22+
23+
The `reclaimPolicy` controls what happens to the PostgreSQL database when the Custom Resource is deleted from Kubernetes.
24+
25+
- `Retain` (Default): The database remains in the PostgreSQL cluster. Only the Kubernetes Custom Resource is deleted. This prevents accidental data loss.
26+
- `Delete`: The database is dropped from the PostgreSQL cluster. **Warning:** This will permanently delete the database and all its data.
27+
28+
## Example
29+
30+
```yaml
31+
apiVersion: postgresql.aboutbits.it/v1
32+
kind: Database
33+
metadata:
34+
name: my-database
35+
spec:
36+
clusterRef:
37+
name: my-postgres-connection
38+
name: my_database
39+
owner: my_role
40+
reclaimPolicy: Retain
41+
```
42+
43+
## Official Documentation
44+
45+
- [CREATE DATABASE](https://www.postgresql.org/docs/current/sql-createdatabase.html)
46+
- [ALTER DATABASE](https://www.postgresql.org/docs/current/sql-alterdatabase.html)

‎docs/default-privilege.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# DefaultPrivilege
2+
3+
The `DefaultPrivilege` Custom Resource Definition (CRD) manages default privileges (ALTER DEFAULT PRIVILEGES) for objects created in the future.
4+
5+
## Spec
6+
7+
| Field | Type | Description | Required | Immutable |
8+
|--------------|--------------------|---------------------------------------------------------------------------------------------------------|-------------|-----------|
9+
| `clusterRef` | `ClusterReference` | Reference to the `ClusterConnection` to use. | Yes | No |
10+
| `database` | `string` | The database where default privileges apply. | Yes | Yes |
11+
| `role` | `string` | The role to which default privileges are granted. | Yes | Yes |
12+
| `owner` | `string` | The role that owns the objects (the creator). Default privileges apply to objects created by this role. | Yes | Yes |
13+
| `schema` | `string` | The schema where default privileges apply. Required, unless `objectType` is `schema`. | Conditional | Yes |
14+
| `objectType` | `string` | The type of object. | Yes | Yes |
15+
| `privileges` | `array[string]` | List of privileges to grant. | Yes | No |
16+
17+
### Object Types
18+
19+
Supported object types:
20+
21+
- `schema`
22+
- `sequence`
23+
- `table`
24+
25+
### Privileges
26+
27+
Supported privileges depend on the `objectType`:
28+
29+
- `connect`
30+
- `create`
31+
- `delete`
32+
- `insert`
33+
- `maintain`
34+
- `references`
35+
- `select`
36+
- `temporary`
37+
- `trigger`
38+
- `truncate`
39+
- `update`
40+
- `usage`
41+
42+
### ClusterReference
43+
44+
| Field | Type | Description | Required |
45+
|-------------|----------|----------------------------------------------------------------------------------|----------|
46+
| `name` | `string` | Name of the `ClusterConnection`. | Yes |
47+
| `namespace` | `string` | Namespace of the `ClusterConnection`. If not specified, uses the CR's namespace. | No |
48+
49+
## Example
50+
51+
```yaml
52+
apiVersion: postgresql.aboutbits.it/v1
53+
kind: DefaultPrivilege
54+
metadata:
55+
name: default-privileges-tables
56+
spec:
57+
clusterRef:
58+
name: my-postgres-connection
59+
database: my_database
60+
role: read_only_role
61+
owner: app_user
62+
objectType: table
63+
schema: public
64+
privileges:
65+
- select
66+
```
67+
68+
## Official Documentation
69+
70+
- [ALTER DEFAULT PRIVILEGES](https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html)

‎docs/docker-environment.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Docker Environment
2+
3+
This example demonstrates how to set up a local development environment using Quarkus Dev Services to test the Operator manually.
4+
As the K3s cluster port and the secrets change on every `./gradlew :operator:quarkusDev` run, you will have to manually update the port and secrets in the `~/.kube/config` every time.
5+
6+
## 1. Configure Kubeconfig from Dev Services
7+
8+
When running in dev mode (`make run` or via IntelliJ), Quarkus starts the pre-configured K3s and PostgreSQL Dev Services.
9+
10+
1. Access the Quarkus Dev UI at [http://localhost:8080/q/dev-ui/dev-services](http://localhost:8080/q/dev-ui/dev-services).
11+
2. Locate the properties for the `kubernetes-client` Dev Service.
12+
3. Convert these properties into a **Kubeconfig YAML** format, see the example below.
13+
4. Merge this configuration into your local `~/.kube/config`. This allows your local environment to communicate with the ephemeral Kubernetes cluster provided by Dev Services.
14+
15+
```yml
16+
apiVersion: v1
17+
kind: Config
18+
current-context: quarkus-cluster
19+
clusters:
20+
- cluster:
21+
certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJkekNDQVIyZ0F3SUJBZ0lCQURBS0JnZ3Foa2pPUFFRREFqQWpNU0V3SHdZRFZRUUREQmhyTTNNdGMyVnkKZG1WeUxXTmhRREUzTmpjNU56UTFNREF3SGhjTk1qWXdNVEE1TVRZd01UUXdXaGNOTXpZd01UQTNNVFl3TVRRdwpXakFqTVNFd0h3WURWUVFEREJock0zTXRjMlZ5ZG1WeUxXTmhRREUzTmpjNU56UTFNREF3V1RBVEJnY3Foa2pPClBRSUJCZ2dxaGtqT1BRTUJCd05DQUFRYlpRQmgzdlNXMVExd1pST0tBQ1NlY3dreXhQUXVjVm9FN0tVM1MrQnYKZ1hJYzdCREQrb2JqTXFETXZuRkpNUlBCYUw0R2RDVVNsRDM3QzJUV01DNjlvMEl3UURBT0JnTlZIUThCQWY4RQpCQU1DQXFRd0R3WURWUjBUQVFIL0JBVXdBd0VCL3pBZEJnTlZIUTRFRmdRVURPdkI4eWt1VFJBTDRjRjhNOUo4Cit3STh5U2t3Q2dZSUtvWkl6ajBFQXdJRFNBQXdSUUlnQWlZb0RsR2txUXd6WXVzcno5V3RMcUdEMXE2SmR6TVYKdW1nTFFPeFdNTEFDSVFDenQyMmxVTXJMNm1zMnBSRTBpQmZ3azNLbGdKSmJzZkp0YlI0bW9mRE16UT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
22+
server: https://localhost:53658
23+
name: quarkus-cluster
24+
# ... more clusters
25+
contexts:
26+
- context:
27+
cluster: quarkus-cluster
28+
namespace: default
29+
user: quarkus-user
30+
name: quarkus-context
31+
# ... more contexts
32+
users:
33+
- name: quarkus-user
34+
user:
35+
client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJrakNDQVRlZ0F3SUJBZ0lJTlpCUDhySWZaTlV3Q2dZSUtvWkl6ajBFQXdJd0l6RWhNQjhHQTFVRUF3d1kKYXpOekxXTnNhV1Z1ZEMxallVQXhOelkzT1RjME5UQXdNQjRYRFRJMk1ERXdPVEUyTURFME1Gb1hEVEkzTURFdwpPVEUyTURFME1Gb3dNREVYTUJVR0ExVUVDaE1PYzNsemRHVnRPbTFoYzNSbGNuTXhGVEFUQmdOVkJBTVRESE41CmMzUmxiVHBoWkcxcGJqQlpNQk1HQnlxR1NNNDlBZ0VHQ0NxR1NNNDlBd0VIQTBJQUJIdnE1UWxVWVBFRldvYXEKRTJNRXI1cUM4TjBFMVkyRTJBTDcrYUl0a1YzYWZHRkkyMGtBODl1eEorc1phQ0ZzblJzYmE1ZmtuVEhPaGJtOApYZGpSeERxalNEQkdNQTRHQTFVZER3RUIvd1FFQXdJRm9EQVRCZ05WSFNVRUREQUtCZ2dyQmdFRkJRY0RBakFmCkJnTlZIU01FR0RBV2dCUWJ3RktrRXhOaitCZjl2YVVNSGxtUi9oeC9PekFLQmdncWhrak9QUVFEQWdOSkFEQkcKQWlFQXlncll6eFIrZWoxWk5CdGdsZW5WT01HWWYrRWlPbkR6L1dzK1dQc1hnd0VDSVFEcEZhMlJ2RkRIVXhLMwpEODkzcGNLUkt1eU5MdXp6ZVZGODNlMURpckF1ZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tQkVHSU4gQ0VSVElGSUNBVEUtLS0tLQpNSUlCZGpDQ0FSMmdBd0lCQWdJQkFEQUtCZ2dxaGtqT1BRUURBakFqTVNFd0h3WURWUVFEREJock0zTXRZMnhwClpXNTBMV05oUURFM05qYzVOelExTURBd0hoY05Nall3TVRBNU1UWXdNVFF3V2hjTk16WXdNVEEzTVRZd01UUXcKV2pBak1TRXdId1lEVlFRRERCaHJNM010WTJ4cFpXNTBMV05oUURFM05qYzVOelExTURBd1dUQVRCZ2NxaGtqTwpQUUlCQmdncWhrak9QUU1CQndOQ0FBVGNWU1NCOHdNakJIbHVOekVZb2krUUU1di9iUWl3cS81d2Jtb2hKU0FGCmZ2aE95eUhCcDBweDRRR0l6YU5BVm9kdkFIazRFV0ViMy9sMWpZVXNCSGlTbzBJd1FEQU9CZ05WSFE4QkFmOEUKQkFNQ0FxUXdEd1lEVlIwVEFRSC9CQVV3QXdFQi96QWRCZ05WSFE0RUZnUVVHOEJTcEJNVFkvZ1gvYjJsREI1WgprZjRjZnpzd0NnWUlLb1pJemowRUF3SURSd0F3UkFJZ2FJemlrUzN6THNSakZTdit1Ny9BbmRNQzdDWTZaREF4Ckp4T1pKbzJVTmVRQ0lFaVlLQlpEVjhVZDZHN3BGU2doSVU5UVZYQ3FYSmx6MHNRbWpnRTJUeUZHCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
36+
client-key-data: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUFuN1dTOWJGZUhlaUpKMmJHcHFFTjBJc28vQzR3VEVNRFBSdENRNzNYMmhvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFZStybENWUmc4UVZhaHFvVFl3U3Ztb0x3M1FUVmpZVFlBdnY1b2kyUlhkcDhZVWpiU1FEegoyN0VuNnhsb0lXeWRHeHRybCtTZE1jNkZ1YnhkMk5IRU9nPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
37+
# ... more users
38+
```
39+
40+
## 2. Create PostgreSQL Connection and Secret
41+
42+
For the `postgresql` Dev Service, you can generate the necessary Custom Resources to test the Operator:
43+
44+
1. From the Dev UI, get the `postgresql` Dev Service properties (username, password, host, port).
45+
2. Convert the `postgresql` Dev Service properties to a **Basic Auth Secret** and a **ClusterConnection** CR instance.
46+
For more details see the [ClusterConnection](cluster-connection.md) CRD definition.
47+
3. Apply the generated files using IntelliJ or `kubectl`.
48+
![Apply Cluster Connection](images/apply-cluster-connection.png)
49+
50+
**Example Secret (`secret.yml`):**
51+
52+
```yaml
53+
apiVersion: v1
54+
kind: Secret
55+
metadata:
56+
name: quarkus-db-secret
57+
labels:
58+
app.kubernetes.io/name: quarkus-postgres
59+
type: kubernetes.io/basic-auth
60+
stringData:
61+
# extracted from quarkus.datasource.username
62+
username: root
63+
# extracted from quarkus.datasource.password
64+
password: password
65+
```
66+
67+
**Example ClusterConnection (`cluster-connection.yml`):**
68+
69+
```yaml
70+
apiVersion: postgresql.aboutbits.it/v1
71+
kind: ClusterConnection
72+
metadata:
73+
name: quarkus-postgres-connection
74+
spec:
75+
adminSecretRef:
76+
name: quarkus-db-secret
77+
host: localhost
78+
port: 5432
79+
database: postgres
80+
```
81+
82+
![Established Cluster Connection](images/established-cluster-connection.png)
83+
84+
## 3. Create a Role
85+
86+
Similarly, you can create a `Role` resource:
87+
88+
1. Manually create a **Role** CR instance.
89+
For more details see the [Role](role.md) CRD definition.
90+
2. Apply the file using IntelliJ or `kubectl`.
91+
92+
**Example Role (`role.yml`):**
93+
94+
```yaml
95+
apiVersion: postgresql.aboutbits.it/v1
96+
kind: Role
97+
metadata:
98+
name: test-role-from-crd
99+
spec:
100+
# The actual name of the role to be created in the PostgreSQL database
101+
name: test-role-from-crd
102+
comment: It simply works
103+
# Connects this role definition to the specific Postgres ClusterConnection CR instance
104+
clusterRef:
105+
name: quarkus-postgres-connection
106+
flags:
107+
createdb: true
108+
validUntil: "2026-12-31T23:59:59Z"
109+
```
110+
111+
![Created Role](images/created-role.png)
112+
![Role in pg_authid](images/role-in-table-pg-authid.png)
113+
114+
The same principle applies to other CRDs.

‎docs/grant.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Grant
2+
3+
The `Grant` Custom Resource Definition (CRD) is responsible for managing privileges (GRANT/REVOKE) on PostgreSQL objects.
4+
5+
## Spec
6+
7+
| Field | Type | Description | Required | Immutable |
8+
|--------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------|-------------|-----------|
9+
| `clusterRef` | `ClusterReference` | Reference to the `ClusterConnection` to use. | Yes | No |
10+
| `database` | `string` | The database containing the objects. | Yes | Yes |
11+
| `role` | `string` | The role to which privileges are granted. | Yes | Yes |
12+
| `schema` | `string` | The schema containing the objects. Required, unless `objectType` is `database`. | Conditional | Yes |
13+
| `objectType` | `string` | The type of object. | Yes | Yes |
14+
| `objects` | `array[string]` | List of object names. If empty, all objects of this `objectType` will be granted. Required, unless `objectType` is `database` or `schema`. | Conditional | No |
15+
| `privileges` | `array[string]` | List of privileges to grant. | Yes | No |
16+
17+
### Object Types
18+
19+
Supported object types:
20+
21+
- `database`
22+
- `schema`
23+
- `sequence`
24+
- `table`
25+
26+
### Privileges
27+
28+
Supported privileges depend on the `objectType`:
29+
30+
- `connect`
31+
- `create`
32+
- `delete`
33+
- `insert`
34+
- `maintain`
35+
- `references`
36+
- `select`
37+
- `temporary`
38+
- `trigger`
39+
- `truncate`
40+
- `update`
41+
- `usage`
42+
43+
### ClusterReference
44+
45+
| Field | Type | Description | Required |
46+
|-------------|----------|----------------------------------------------------------------------------------|----------|
47+
| `name` | `string` | Name of the `ClusterConnection`. | Yes |
48+
| `namespace` | `string` | Namespace of the `ClusterConnection`. If not specified, uses the CR's namespace. | No |
49+
50+
## Example
51+
52+
```yaml
53+
apiVersion: postgresql.aboutbits.it/v1
54+
kind: Grant
55+
metadata:
56+
name: grant-select-tables
57+
spec:
58+
clusterRef:
59+
name: my-postgres-connection
60+
database: my_database
61+
role: my_role
62+
objectType: table
63+
schema: public
64+
objects:
65+
- my_table
66+
- another_table
67+
privileges:
68+
- select
69+
- insert
70+
```
71+
72+
## Official Documentation
73+
74+
- [GRANT](https://www.postgresql.org/docs/current/sql-grant.html)
75+
- [REVOKE](https://www.postgresql.org/docs/current/sql-revoke.html)

docs/apply-cluster-connection.png renamed to docs/images/apply-cluster-connection.png

File renamed without changes.

docs/created-role.png renamed to docs/images/created-role.png

File renamed without changes.

0 commit comments

Comments
 (0)