Roles¶

A Role resource represents a PostgreSQL role (user) within a cluster.

Overview¶

The Role controller:

Connects to the referenced PostgreSQL cluster
Creates or updates the role with specified permissions
Auto-generates a password and creates a credentials Secret
Manages role membership (GRANT role TO role)
Cleans up the role on deletion

Example¶

apiVersion: pgop.ruck.io/v1alpha1
kind: Role
metadata:
  name: app-user
  namespace: default
spec:
  clusterRef:
    name: my-cluster
  login: true
  createDB: false
  connectionLimit: 100
  memberOf:
    - app_read_role

Spec Reference¶

Field	Type	Default	Description
`clusterRef.name`	string	required	Name of the Cluster resource (same namespace)
`login`	bool	`false`	Can role log in?
`superuser`	bool	`false`	Grant superuser privileges
`createDB`	bool	`false`	Can role create databases?
`createRole`	bool	`false`	Can role create other roles?
`inherit`	bool	`true`	Inherit privileges from member roles
`replication`	bool	`false`	Can role initiate replication?
`bypassRLS`	bool	`false`	Bypass row-level security?
`connectionLimit`	int	`-1`	Max concurrent connections (-1 = unlimited)
`memberOf`	[]string	-	Roles this role is a member of
`passwordSecretRef`	SecretKeySelector	-	Use existing password (optional)

Status¶

Field	Description
`ready`	Whether the role exists in PostgreSQL
`secretName`	Name of the auto-generated credentials secret (`<cluster>-<role>-credentials`)
`conditions`	Detailed status conditions

Credentials Secret¶

The operator creates a Secret named <cluster-name>-<role-name>-credentials (e.g. my-cluster-app-user-credentials). The name is deterministic — it is derived from clusterRef.name and the Role's own name — so you can reference it from other manifests (including a Helm chart at template time) before status.secretName is populated.

data:
  username: app-user                          # = the Role name
  password: <auto-generated>
  host: my-cluster.default.svc.cluster.local
  port: "5432"

Note

This Secret does not contain a database key or a ready-made uri. Apps assemble their DSN from these keys plus the target database name (see the Database per-database Secret, which does include database).

Role Types¶

Application User¶

spec:
  clusterRef:
    name: my-cluster
  login: true
  connectionLimit: 50

Read-Only Role¶

spec:
  clusterRef:
    name: my-cluster
  login: false  # Group role, not a login
  inherit: true

Admin Role¶

spec:
  clusterRef:
    name: my-cluster
  login: true
  createDB: true
  createRole: true

Password Source¶

A password is always auto-generated by the operator and written to the credentials Secret above. Apps should read the password from that Secret.

Warning

spec.passwordSecretRef is present in the API schema but is not yet honored by the controller — a supplied value is ignored and the auto-generated password is used instead. Do not rely on it to inject a custom password today. (Tracked for a future release.)