Skip to content

Commit da44625

Browse files
ThoSapThoSap
committed
polish the README.md and add new docs
1 parent c2a28cf commit da44625

13 files changed

Lines changed: 643 additions & 129 deletions

‎.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

‎README.md‎

Lines changed: 153 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,133 @@
11
# AboutBits PostgreSQL Operator
22

3-
## Getting started
3+
AboutBits PostgreSQL Operator is a Kubernetes operator that helps you manage PostgreSQL databases, roles (users), and privileges in a declarative way using Custom Resource Definitions (CRDs).
4+
5+
## Usage
6+
7+
This operator allows you to manage PostgreSQL resources using Kubernetes manifests.
8+
Further documentation of each Custom Resource can be found here:
9+
10+
- [ClusterConnection](docs/cluster-connection.md) – Define a connection to a PostgreSQL cluster.
11+
- [Database](docs/database.md) - Manage databases.
12+
- [Role](docs/role.md) - Manage roles (users).
13+
- [Schema](docs/schema.md) - Manage schemas.
14+
- [Grant](docs/grant.md) - Manage privileges.
15+
- [DefaultPrivilege](docs/default-privilege.md) - Manage default privileges.
16+
17+
### Showcase
18+
19+
The following example shows how to set up a connection to a PostgreSQL cluster, create a database and schema, a login role (user), and configure permissions.
20+
21+
```yaml
22+
# Define a ClusterConnection resource to connect to a PostgreSQL cluster.
23+
---
24+
apiVersion: v1
25+
kind: Secret
26+
metadata:
27+
name: my-postgres-secret
28+
type: kubernetes.io/basic-auth
29+
stringData:
30+
username: postgres
31+
password: password
32+
---
33+
apiVersion: postgresql.aboutbits.it/v1
34+
kind: ClusterConnection
35+
metadata:
36+
name: my-postgres-connection
37+
spec:
38+
host: postgres-host
39+
port: 5432
40+
database: postgres
41+
adminSecretRef:
42+
name: my-postgres-secret
43+
44+
# Create a Database
45+
---
46+
apiVersion: postgresql.aboutbits.it/v1
47+
kind: Database
48+
metadata:
49+
name: my-database
50+
spec:
51+
clusterRef:
52+
name: my-postgres-connection
53+
name: my_app_db
54+
reclaimPolicy: Retain
55+
owner: dba_user
56+
57+
# Create a Schema
58+
---
59+
apiVersion: postgresql.aboutbits.it/v1
60+
kind: Schema
61+
metadata:
62+
name: my-schema
63+
spec:
64+
clusterRef:
65+
name: my-postgres-connection
66+
name: my_app_schema
67+
reclaimPolicy: Retain
68+
owner: dba_user
69+
70+
# Create a Login Role (User)
71+
---
72+
apiVersion: v1
73+
kind: Secret
74+
metadata:
75+
name: my-app-user-secret
76+
type: kubernetes.io/basic-auth
77+
stringData:
78+
password: secret_password
79+
---
80+
apiVersion: postgresql.aboutbits.it/v1
81+
kind: Role
82+
metadata:
83+
name: my-role
84+
spec:
85+
clusterRef:
86+
name: my-postgres-connection
87+
name: my_app_user
88+
passwordSecretRef:
89+
name: my-app-user-secret
90+
flags:
91+
createdb: false
92+
93+
# Configure Permissions
94+
---
95+
apiVersion: postgresql.aboutbits.it/v1
96+
kind: Grant
97+
metadata:
98+
name: my-grant
99+
spec:
100+
clusterRef:
101+
name: my-postgres-connection
102+
database: my_app_db
103+
role: my_app_user
104+
objectType: schema
105+
schema: my_app_schema
106+
privileges:
107+
- usage
108+
109+
# Configure Default Privileges
110+
---
111+
apiVersion: postgresql.aboutbits.it/v1
112+
kind: DefaultPrivilege
113+
metadata:
114+
name: my-default-privilege
115+
spec:
116+
clusterRef:
117+
name: my-postgres-connection
118+
database: my_app_db
119+
role: my_app_user
120+
owner: shared_developer_user
121+
objectType: table
122+
schema: my_app_schema
123+
privileges:
124+
- select
125+
- insert
126+
- update
127+
- delete
128+
```
129+
130+
## Contribute
4131
5132
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
6133
@@ -12,19 +139,19 @@ To build the project, the following prerequisites must be met:
12139
- [Gradle](https://gradle.org/) (Optional)
13140
- [Docker](https://www.docker.com/)
14141
15-
### Setup configuration
142+
### Setup
16143
17144
To get started, call:
18145
19146
```bash
20147
make init
21148
```
22149

23-
### Running the project in the console
150+
### Development
24151

25152
You can run your application in dev mode that enables live coding and continuous testing using:
26153

27-
```shell script
154+
```bash
28155
make run
29156

30157
# or
@@ -45,131 +172,22 @@ make test
45172
./gradlew :operator:test
46173
```
47174

48-
### Run the project as a service in IntelliJ
175+
#### Run the project as a service in IntelliJ
49176

50177
1. Open the `Services` tool on the left side of the IDE
51178
2. Click on "+" and select "Quarkus"
52179

53180
Afterward, the project can be started in IntelliJ by navigating to `Run` -> `Run '...'`.
54181

55-
## Test the CRD on the ephemeral Dev Services cluster
182+
### Docker Environment
56183

57-
This example demonstrates how to set up a local development environment using Quarkus Dev Services to test the Operator manually.
58-
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.
184+
See [Docker Environment](docs/docker-environment.md) for setting up a local development environment using Quarkus Dev Services.
59185

60-
### 1. Configure Kubeconfig from Dev Services
61-
62-
When running in dev mode (`make run` or via IntelliJ), Quarkus starts the pre-configured K3s and PostgreSQL Dev Services.
63-
64-
1. Access the Quarkus Dev UI at [http://localhost:8080/q/dev-ui/dev-services](http://localhost:8080/q/dev-ui/dev-services).
65-
2. Locate the properties for the `kubernetes-client` Dev Service.
66-
3. Convert these properties into a **Kubeconfig YAML** format, see the example below.
67-
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.
68-
69-
```yml
70-
apiVersion: v1
71-
kind: Config
72-
current-context: quarkus-cluster
73-
clusters:
74-
- cluster:
75-
certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJkekNDQVIyZ0F3SUJBZ0lCQURBS0JnZ3Foa2pPUFFRREFqQWpNU0V3SHdZRFZRUUREQmhyTTNNdGMyVnkKZG1WeUxXTmhRREUzTmpjNU56UTFNREF3SGhjTk1qWXdNVEE1TVRZd01UUXdXaGNOTXpZd01UQTNNVFl3TVRRdwpXakFqTVNFd0h3WURWUVFEREJock0zTXRjMlZ5ZG1WeUxXTmhRREUzTmpjNU56UTFNREF3V1RBVEJnY3Foa2pPClBRSUJCZ2dxaGtqT1BRTUJCd05DQUFRYlpRQmgzdlNXMVExd1pST0tBQ1NlY3dreXhQUXVjVm9FN0tVM1MrQnYKZ1hJYzdCREQrb2JqTXFETXZuRkpNUlBCYUw0R2RDVVNsRDM3QzJUV01DNjlvMEl3UURBT0JnTlZIUThCQWY4RQpCQU1DQXFRd0R3WURWUjBUQVFIL0JBVXdBd0VCL3pBZEJnTlZIUTRFRmdRVURPdkI4eWt1VFJBTDRjRjhNOUo4Cit3STh5U2t3Q2dZSUtvWkl6ajBFQXdJRFNBQXdSUUlnQWlZb0RsR2txUXd6WXVzcno5V3RMcUdEMXE2SmR6TVYKdW1nTFFPeFdNTEFDSVFDenQyMmxVTXJMNm1zMnBSRTBpQmZ3azNLbGdKSmJzZkp0YlI0bW9mRE16UT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
76-
server: https://localhost:53658
77-
name: quarkus-cluster
78-
# ... more clusters
79-
contexts:
80-
- context:
81-
cluster: quarkus-cluster
82-
namespace: default
83-
user: quarkus-user
84-
name: quarkus-context
85-
# ... more contexts
86-
users:
87-
- name: quarkus-user
88-
user:
89-
client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJrakNDQVRlZ0F3SUJBZ0lJTlpCUDhySWZaTlV3Q2dZSUtvWkl6ajBFQXdJd0l6RWhNQjhHQTFVRUF3d1kKYXpOekxXTnNhV1Z1ZEMxallVQXhOelkzT1RjME5UQXdNQjRYRFRJMk1ERXdPVEUyTURFME1Gb1hEVEkzTURFdwpPVEUyTURFME1Gb3dNREVYTUJVR0ExVUVDaE1PYzNsemRHVnRPbTFoYzNSbGNuTXhGVEFUQmdOVkJBTVRESE41CmMzUmxiVHBoWkcxcGJqQlpNQk1HQnlxR1NNNDlBZ0VHQ0NxR1NNNDlBd0VIQTBJQUJIdnE1UWxVWVBFRldvYXEKRTJNRXI1cUM4TjBFMVkyRTJBTDcrYUl0a1YzYWZHRkkyMGtBODl1eEorc1phQ0ZzblJzYmE1ZmtuVEhPaGJtOApYZGpSeERxalNEQkdNQTRHQTFVZER3RUIvd1FFQXdJRm9EQVRCZ05WSFNVRUREQUtCZ2dyQmdFRkJRY0RBakFmCkJnTlZIU01FR0RBV2dCUWJ3RktrRXhOaitCZjl2YVVNSGxtUi9oeC9PekFLQmdncWhrak9QUVFEQWdOSkFEQkcKQWlFQXlncll6eFIrZWoxWk5CdGdsZW5WT01HWWYrRWlPbkR6L1dzK1dQc1hnd0VDSVFEcEZhMlJ2RkRIVXhLMwpEODkzcGNLUkt1eU5MdXp6ZVZGODNlMURpckF1ZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tQkVHSU4gQ0VSVElGSUNBVEUtLS0tLQpNSUlCZGpDQ0FSMmdBd0lCQWdJQkFEQUtCZ2dxaGtqT1BRUURBakFqTVNFd0h3WURWUVFEREJock0zTXRZMnhwClpXNTBMV05oUURFM05qYzVOelExTURBd0hoY05Nall3TVRBNU1UWXdNVFF3V2hjTk16WXdNVEEzTVRZd01UUXcKV2pBak1TRXdId1lEVlFRRERCaHJNM010WTJ4cFpXNTBMV05oUURFM05qYzVOelExTURBd1dUQVRCZ2NxaGtqTwpQUUlCQmdncWhrak9QUU1CQndOQ0FBVGNWU1NCOHdNakJIbHVOekVZb2krUUU1di9iUWl3cS81d2Jtb2hKU0FGCmZ2aE95eUhCcDBweDRRR0l6YU5BVm9kdkFIazRFV0ViMy9sMWpZVXNCSGlTbzBJd1FEQU9CZ05WSFE4QkFmOEUKQkFNQ0FxUXdEd1lEVlIwVEFRSC9CQVV3QXdFQi96QWRCZ05WSFE0RUZnUVVHOEJTcEJNVFkvZ1gvYjJsREI1WgprZjRjZnpzd0NnWUlLb1pJemowRUF3SURSd0F3UkFJZ2FJemlrUzN6THNSakZTdit1Ny9BbmRNQzdDWTZaREF4Ckp4T1pKbzJVTmVRQ0lFaVlLQlpEVjhVZDZHN3BGU2doSVU5UVZYQ3FYSmx6MHNRbWpnRTJUeUZHCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
90-
client-key-data: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUFuN1dTOWJGZUhlaUpKMmJHcHFFTjBJc28vQzR3VEVNRFBSdENRNzNYMmhvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFZStybENWUmc4UVZhaHFvVFl3U3Ztb0x3M1FUVmpZVFlBdnY1b2kyUlhkcDhZVWpiU1FEegoyN0VuNnhsb0lXeWRHeHRybCtTZE1jNkZ1YnhkMk5IRU9nPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
91-
# ... more users
92-
```
93-
94-
### 2. Create PostgreSQL Connection and Secret
95-
96-
For the `postgresql` Dev Service, you can generate the necessary Custom Resources to test the Operator:
97-
98-
1. From the Dev UI, get the `postgresql` Dev Service properties (username, password, host, port).
99-
2. Convert the `postgresql` Dev Service properties to a **Basic Auth Secret** and a **ClusterConnection** CR instance.
100-
For more details see class `ClusterConnectionSpec` or the `ClusterConnection` CRD definition from `build/kubernetes/clusterconnections.postgresql.aboutbits.it-v1.yml` as a reference.
101-
3. Apply the generated files using IntelliJ or `kubectl`.
102-
![Apply Cluster Connection](docs/apply-cluster-connection.png)
103-
104-
**Example Secret (`secret.yml`):**
105-
106-
```yaml
107-
apiVersion: v1
108-
kind: Secret
109-
metadata:
110-
name: quarkus-db-secret
111-
labels:
112-
app.kubernetes.io/name: quarkus-postgres
113-
type: kubernetes.io/basic-auth
114-
stringData:
115-
# extracted from quarkus.datasource.username
116-
username: root
117-
# extracted from quarkus.datasource.password
118-
password: password
119-
```
120-
121-
**Example ClusterConnection (`cluster-connection.yml`):**
122-
123-
```yaml
124-
apiVersion: postgresql.aboutbits.it/v1
125-
kind: ClusterConnection
126-
metadata:
127-
name: quarkus-postgres-connection
128-
spec:
129-
adminSecretRef:
130-
name: quarkus-db-secret
131-
host: localhost
132-
port: 5432
133-
database: postgres
134-
```
135-
136-
![Established Cluster Connection](docs/established-cluster-connection.png)
137-
138-
### 3. Create a Role
139-
140-
Similarly, you can create a `Role` resource:
141-
142-
1. Manually create a **Role** CR instance.
143-
For more details see class `RoleSpec` or the `Role` CRD definition from `build/kubernetes/roles.postgresql.aboutbits.it-v1.yml` as a reference.
144-
2. Apply the file using IntelliJ or `kubectl`.
145-
146-
**Example Role (`role.yml`):**
147-
148-
```yaml
149-
apiVersion: postgresql.aboutbits.it/v1
150-
kind: Role
151-
metadata:
152-
name: test-role-from-crd
153-
spec:
154-
# The actual name of the role to be created in the PostgreSQL database
155-
name: test-role-from-crd
156-
comment: It simply works
157-
# Connects this role definition to the specific Postgres ClusterConnection CR instance
158-
clusterRef:
159-
name: quarkus-postgres-connection
160-
flags:
161-
createdb: true
162-
validUntil: "2026-12-31T23:59:59Z"
163-
```
164-
165-
![Created Role](docs/created-role.png)
166-
![Role in pg_authid](docs/role-in-table-pg-authid.png)
167-
168-
## Packaging and running the application
186+
## Build
169187

170188
The application can be packaged using:
171189

172-
```shell script
190+
```bash
173191
./gradlew :operator:build
174192
```
175193

@@ -180,34 +198,40 @@ The application is now runnable using `java -jar build/quarkus-app/quarkus-run.j
180198

181199
If you want to build an _über-jar_, execute the following command:
182200

183-
```shell script
201+
```bash
184202
./gradlew :operator:build -Dquarkus.package.jar.type=uber-jar
185203
```
186204

187205
The application, packaged as an _über-jar_, is now runnable using `java -jar build/*-runner.jar`.
188206

189-
## Creating a native executable
207+
### Creating a native executable
190208

191209
You can create a native executable using:
192210

193-
```shell script
211+
```bash
194212
./gradlew :operator:build -Dquarkus.native.enabled=true
195213
```
196214

197215
Or, if you don't have GraalVM installed, you can run the native executable build in a container using:
198216

199-
```shell script
217+
```bash
200218
./gradlew :operator:build -Dquarkus.native.enabled=true -Dquarkus.native.container-build=true
201219
```
202220

203221
You can then execute your native executable with: `./build/postgresql-operator-1.0.0-SNAPSHOT-runner`
204222

205-
If you want to learn more about building native executables, please consult <https://quarkus.io/guides/gradle-tooling>.
223+
## Information
224+
225+
About Bits is a company based in South Tyrol, Italy. You can find more information about us on [our website](https://aboutbits.it).
226+
227+
### Support
228+
229+
For support, please contact [info@aboutbits.it](mailto:info@aboutbits.it).
230+
231+
### Credits
232+
233+
- [All Contributors](https://github.com/aboutbits/postgresql-operator/graphs/contributors)
206234

207-
## Related Guides
235+
### License
208236

209-
- Operator SDK ([guide](https://docs.quarkiverse.io/quarkus-operator-sdk/dev/index.html)): Quarkus extension for the Java Operator SDK (https://javaoperatorsdk.io)
210-
- Helm ([guide](https://docs.quarkiverse.io/quarkus-helm/dev/index.html)): Quarkus extension for Kubernetes Helm charts
211-
- SmallRye Health ([guide](https://quarkus.io/guides/smallrye-health)): Monitor service health
212-
- Micrometer metrics ([guide](https://quarkus.io/guides/micrometer)): Instrument the runtime and your application with dimensional metrics using Micrometer.
213-
- YAML Configuration ([guide](https://quarkus.io/guides/config-yaml)): Use YAML to configure your Quarkus application
237+
The MIT License (MIT). Please see the [license file](LICENSE) for more information.

0 commit comments

Comments
 (0)