diff --git a/docs/enterprise/externalsecrets/generators/postgresql.mdx b/docs/enterprise/externalsecrets/generators/postgresql.mdx new file mode 100644 index 0000000..7ec1982 --- /dev/null +++ b/docs/enterprise/externalsecrets/generators/postgresql.mdx @@ -0,0 +1,142 @@ +--- +title: 'PostgreSQL User Generator' +description: 'Easily manage and rotate PostgreSQL Users in your setup' +--- + + + The External Secrets Enterprise product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + + + In order to use the PostgreSQL User Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](../../esi-agent/quickstart.mdx). + + +## Introduction + +The PostgreSQL User Generator for ESO allows you to dynamically create and rotate database users with native integration. + +This is useful when providing applications with scoped credentials to PostgreSQL, reducing the operational overhead of manual user management and improving security posture. + +## Output Keys and Values + +| Key | Description | +| ---------- | --------------------------------- | +| `username` | The generated PostgreSQL username | +| `password` | The generated PostgreSQL password | + +## Parameters + +| Key | Default | Description | +| ------------------------- | ------------ | ----------- | +| `database` | `postgres` | The name of the PostgreSQL database to connect to. | +| `host` | **Required** | The hostname or IP of the PostgreSQL server. | +| `port` | `5432` | The port used to connect to the PostgreSQL server. | +| `auth.username` | `postgres` | Admin username for authentication. | +| `auth.password.name` | **Required** | Kubernetes secret name containing the admin password. | +| `auth.password.key` | **Required** | Key in the secret that holds the admin password. | +| `user.username` | **Required** | The username to create. A random suffix will be appended. | +| `user.suffixSize` | `8` | Length of the random suffix appended to the username. If set to 0, no suffix is appended. | +| `user.attributes` | `[]` | List of PostgreSQL attributes to assign. Each item must be an object with a name field (e.g., `CREATEDBT`) and an optional value field for attributes that require a parameter (e.g.,`CONNECTION LIMIT`). | +| `user.roles` | `[]` | List of existing roles to grant to the user. Non-existent roles are created with no attributes. | +| `user.destructiveCleanup` | `false` | If `true`, all owned objects are dropped during cleanup. Otherwise, ownership is reassigned to the `reassignTo` user. | +| `user.reassignTo` | - | The name of the role to which all owned objects should be reassigned during cleanup. `auth.username` is used if not set. | + +## Set up + +### PostgreSQL Permissions + +The admin user provided in the spec must have sufficient permissions to create and delete users in PostgreSQL. Typically, the built-in `postgres` admin account has the required permissions. + +### Generator Config + + +```yaml +apiVersion: generators.external-secrets.io/v1alpha1 +kind: PostgreSql +metadata: + name: postgres-generator + namespace: default +spec: + host: postgres.default.svc.cluster.local + port: "5432" + database: postgres + auth: + username: postgres + password: + name: pg-admin-secret + key: password + user: + username: appuser + suffixSize: 6 + attributes: + - name: CREATEDB + - name: "CONNECTION LIMIT" + value: "10" + roles: + - pg_read_all_data + - custom_role + destructiveCleanup: false +``` + + +### ExternalSecret Config + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: postgres-credentials + namespace: default +spec: + refreshInterval: 1h # Rotates every 1 hour + dataFrom: + - sourceRef: + generatorRef: + apiVersion: generators.external-secrets.io/v1alpha1 + kind: PostgreSql + name: postgres-generator +``` + +### Using the Generated Secret + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: my-app + template: + metadata: + labels: + app: my-app + spec: + containers: + - name: my-container + image: my-image:latest + env: + - name: POSTGRES_USER + valueFrom: + secretKeyRef: + name: postgres-credentials + key: username + - name: POSTGRES_PASSWORD + valueFrom: + secretKeyRef: + name: postgres-credentials + key: password +``` + +### Notes and Considerations + +* If destructiveCleanup is true, owned objects are dropped before dropping the user. +* If destructiveCleanup is false, ownership is reassigned to the user defined in user.reassignTo. +* If user.reassignTo is not set, the admin user defined in auth.username is used for reassignment. +* If user.reassignTo does not exists, it will be created with no attributes or roles. +* Roles listed in user.roles are created if missing and assigned to the generated user. +* Only the standard PostgreSQL attributes (SUPERUSER, CREATEDB, CREATEROLE, REPLICATION) are supported. \ No newline at end of file diff --git a/mint.json b/mint.json index f8e8721..0faeb27 100644 --- a/mint.json +++ b/mint.json @@ -136,7 +136,8 @@ "group": "Generators", "pages": [ "docs/enterprise/externalsecrets/generators/iam-keys", - "docs/enterprise/externalsecrets/generators/neo4j" + "docs/enterprise/externalsecrets/generators/neo4j", + "docs/enterprise/externalsecrets/generators/postgresql" ] }, {