Skip to content

Commit 142043d

Browse files
pcallewaertpcallewaert
committed
Update README for 2.0 release
1 parent 2302925 commit 142043d

File tree

2 files changed

+83
-59
lines changed

2 files changed

+83
-59
lines changed

‎CONTRIBUTING.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# CONTRIBUTING
2+
3+
You can contribute to this project by opening a PR to merge to `master`, or one of the `vX.X.X` branches.
4+
5+
## Branching
6+
7+
`master` branch contains the latest source code with all the features. `vX.X.X` contains code for the specific major versions.
8+
i.e. `v0.4.x` contains the latest code for 0.4 version of the operator. See compatibility matrix below.
9+
10+
## Tests
11+
12+
Please write tests and fix any broken tests before you open a PR. Tests should cover at least 80% of your code.
13+
14+
## e2e-tests
15+
16+
End-to-end tests are implemented using [kuttl](https://kuttl.dev/), a Kubernetes test framework. To execute these tests locally, first install kuttl on your system, then run the command `make e2e` from the project root directory.

‎README.md

Lines changed: 67 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,81 @@
1-
# External PostgreSQL server operator for Kubernetes
1+
# External PostgreSQL Server Operator for Kubernetes
2+
3+
Manage external PostgreSQL databases in Kubernetes with ease—supporting AWS RDS, Azure Database for PostgreSQL, GCP Cloud SQL, and more.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
- [Sponsors](#sponsors)
10+
- [Features](#features)
11+
- [Supported Cloud Providers](#supported-cloud-providers)
12+
- [Configuration](#configuration)
13+
- [Installation](#installation)
14+
- [Custom Resources (CRs)](#custom-resources-crs)
15+
- [Multiple Operator Support](#multiple-operator-support)
16+
- [Secret Templating](#secret-templating)
17+
- [Compatibility](#compatibility)
18+
- [Contributing](#contributing)
19+
- [License](#license)
20+
21+
---
222

323
## Sponsors
424

5-
Please consider sponsoring my work
25+
Please consider supporting this project!
626

7-
<a class="github-button" href="https://github.com/sponsors/hitman99" data-icon="octicon-heart" data-size="large" aria-label="Sponsor @hitman99 on GitHub">Sponsor</a>
27+
[![Sponsor](https://img.shields.io/badge/Sponsor_on_GitHub-ff69b4?style=for-the-badge&logo=github)](https://github.com/sponsors/hitman99)
828

9-
### Current Sponsors
10-
None
29+
**Current Sponsors:**
30+
_None yet. [Become a sponsor!](https://github.com/sponsors/hitman99)_
1131

1232
## Features
1333

14-
* Creates a database from a CR
15-
* Creates a role with random username and password from a CR
16-
* If the database exist, it will only create a role
17-
* Multiple user roles can own one database
18-
* Creates Kubernetes secret with postgres_uri in the same namespace as CR
19-
* Support for AWS RDS and Azure Database for PostgresSQL
20-
* Support for managing CRs in dynamically created namespaces
21-
* Template secret values
34+
- Create databases and roles using Kubernetes CRs
35+
- Automatic creation of randomized usernames and passwords
36+
- Supports multiple user roles per database
37+
- Auto-generates Kubernetes secrets with PostgreSQL connection URIs
38+
- Supports AWS RDS, Azure Database for PostgreSQL, and GCP Cloud SQL
39+
- Handles CRs in dynamically created namespaces
40+
- Customizable secret values using templates
41+
42+
---
2243

23-
## Cloud specific configuration
44+
## Supported Cloud Providers
2445

2546
### AWS
2647

27-
In order for this operator to work correctly with AWS RDS, you need to set `POSTGRES_CLOUD_PROVIDER` to `AWS` either in
28-
the ext-postgres-operator kubernetes secret or directly in the deployment manifest (`operator.yaml`).
48+
Set `POSTGRES_CLOUD_PROVIDER` to `AWS` via environment variable, Kubernetes Secret, or deployment manifest (`operator.yaml`).
2949

30-
### Azure Database for PostgreSQL (both Single Server and Flexible Server)
50+
### Azure Database for PostgreSQL – Flexible Server
3151

32-
In order for this operator to work correctly with Azure managed PostgreSQL database, two env variables needs to be provided for the operator:
52+
> **Note:** Azure Single Server is deprecated as of v2.x. Only Flexible Server is supported.
3353
34-
* `POSTGRES_CLOUD_PROVIDER` set to `Azure`
35-
* `POSTGRES_DEFAULT_DATABASE` set to your default database, i.e. `postgres`
54+
- `POSTGRES_CLOUD_PROVIDER=Azure`
55+
- `POSTGRES_DEFAULT_DATABASE=postgres`
3656

3757
### GCP
3858

39-
In order for this operator to work correctly with GCP, you need to set `POSTGRES_CLOUD_PROVIDER` to `GCP`
40-
41-
To have operator work with GCP properly you have to:
42-
* use postgresql connection in secret
43-
* manually create a Master role e.g. "devops-operators"
44-
* use such role in database CR e.g. spec.masterRole: devops-operator
45-
46-
DropRole method will check for db owner and will skip master role dropping
59+
- `POSTGRES_CLOUD_PROVIDER=GCP`
60+
- Configure a PostgreSQL connection secret
61+
- Manually create a Master role and reference it in your CRs
62+
- Master roles are never dropped by the operator
4763

4864
## General Configuration
4965
These environment variables are embedded in [deploy/operator.yaml](deploy/operator.yaml), `env` section.
5066

5167
* `WATCH_NAMESPACE` - which namespace to watch. Defaults to empty string for all namespaces
52-
* `OPERATOR_NAME` - name of the operator, defaults to `ext-postgres-operator`
68+
* `OPERATOR_NAME` - name of the operator, defaults to `ext-postgres-operator`
5369
* `POSTGRES_INSTANCE` - identity of operator, this matched with `postgres.db.movetokube.com/instance` in CRs. Default is empty
5470
* `KEEP_SECRET_NAME` - use secret name as provided by user (disabled by default)
5571

5672
`POSTGRES_INSTANCE` is only available since version 1.2.0
5773

58-
> While using `KEEP_SECRET_NAME` could be a convenient way to define secrets with predictable and explicit names,
59-
> the default logic reduces risk of operator from entering the endless reconcile loop as secret is very unlikely to exist.
74+
> While using `KEEP_SECRET_NAME` could be a convenient way to define secrets with predictable and explicit names,
75+
> the default logic reduces risk of operator from entering the endless reconcile loop as secret is very unlikely to exist.
6076
>
61-
> The administrator should ensure that the `SecretName` does not collide with other secrets in the same namespace.
62-
> If the secret already exists, the operator will never stop reconciling the CR until either offending secret is deleted
77+
> The administrator should ensure that the `SecretName` does not collide with other secrets in the same namespace.
78+
> If the secret already exists, the operator will never stop reconciling the CR until either offending secret is deleted
6379
> or CR is deleted or updated with another SecretName
6480
6581
## Installation
@@ -96,7 +112,7 @@ To install the operator using kustomize, follow the steps below.
96112
or by using [kustomize](https://github.com/kubernetes-sigs/kustomize) directly\
97113
`kustomize build deploy/ | apply -f -`
98114

99-
Alternatively you can install operator using Helm Chart located in the
115+
Alternatively you can install operator using Helm Chart located in the
100116
`charts/ext-postgres-operator` subdirectory. Sample installation commands provided below:
101117

102118
```
@@ -105,7 +121,7 @@ helm install -n operators ext-postgres-operator ext-postgres-operator/ext-postg
105121
```
106122
See [values.yaml](charts/ext-postgres-operator/values.yaml) for the possible values to define.
107123

108-
## CRs
124+
## Custom Resources (CRs)
109125

110126
### Postgres
111127

@@ -117,7 +133,7 @@ metadata:
117133
namespace: app
118134
annotations:
119135
# OPTIONAL
120-
# use this to target which instance of operator should process this CR. See General config
136+
# use this to target which instance of operator should process this CR. See General config
121137
postgres.db.movetokube.com/instance: POSTGRES_INSTANCE
122138
spec:
123139
database: test-db # Name of database created in PostgreSQL
@@ -177,19 +193,18 @@ Every PostgresUser has a generated Kubernetes secret attached to it, which conta
177193
| `POSTGRES_JDBC_URL` | JDBC compatible Postgres URI, formatter as `jdbc:postgresql://{POSTGRES_HOST}/{DATABASE_NAME}` |
178194

179195
### Multiple operator support
180-
Since version 1.2 it is possible to use many instances of postgres-operator to control different databases based on annotations in CRs.
181-
Follow the steps below to enable multi-operator support.
182-
1. Add POSTGRES_INSTANCE
196+
197+
Run multiple operator instances by setting unique POSTGRES_INSTANCE values and using annotations in your CRs to assign them.
183198

184199
#### Annotations Use Case
185200

186201
With the help of annotations it is possible to create annotation-based copies of secrets in other namespaces.
187202

188203
For more information and an example, see [kubernetes-replicator#pull-based-replication](https://github.com/mittwald/kubernetes-replicator#pull-based-replication)
189204

190-
#### Template Use Case
205+
### Secret Templating
191206

192-
Users can specify the structure and content of secrets based on their unique requirements using standard
207+
Users can specify the structure and content of secrets based on their unique requirements using standard
193208
[Go templates](https://pkg.go.dev/text/template#hdr-Actions). This flexibility allows for a more tailored approach to
194209
meeting the specific needs of different applications.
195210

@@ -202,23 +217,6 @@ Available context:
202217
| `.Database` | Referenced database name |
203218
| `.Password` | Generated role password |
204219

205-
### Contribution
206-
207-
You can contribute to this project by opening a PR to merge to `master`, or one of the `vX.X.X` branches.
208-
209-
#### Branching
210-
211-
`master` branch contains the latest source code with all the features. `vX.X.X` contains code for the specific major versions.
212-
i.e. `v0.4.x` contains the latest code for 0.4 version of the operator. See compatibility matrix below.
213-
214-
#### Tests
215-
216-
Please write tests and fix any broken tests before you open a PR. Tests should cover at least 80% of your code.
217-
218-
#### e2e-tests
219-
220-
End-to-end tests are implemented using [kuttl](https://kuttl.dev/), a Kubernetes test framework. To execute these tests locally, first install kuttl on your system, then run the command `make e2e` from the project root directory.
221-
222220
### Compatibility
223221

224222
Postgres operator uses Operator SDK, which uses kubernetes client. Kubernetes client compatibility with Kubernetes cluster
@@ -230,4 +228,14 @@ Postgres operator compatibility with Operator SDK version is in the table below
230228
|---------------------------|----------------------|----------------------|
231229
| `postgres-operator 0.4.x` | v0.17 | v1beta1 |
232230
| `postgres-operator 1.x.x` | v0.18 | v1 |
233-
| `HEAD` | v0.18 | v1 |
231+
| `postgres-operator 2.x.x` | v1.39 | v1 |
232+
| `HEAD` | v1.39 | v1 |
233+
234+
235+
## Contributing
236+
237+
See [CONTRIBUTING.md](CONTRIBUTING.md)
238+
239+
## License
240+
241+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)