New to KubeVault? Please start here.

PostgresRole

What is PostgresRole

A PostgresRole is a Kubernetes CustomResourceDefinition (CRD) which allows a user to create a database secret engine role in a Kubernetes native way.

When a PostgresRole is created, the KubeVault operator creates a role according to specification. If the user deletes the PostgresRole CRD, then the respective role will also be deleted from Vault.

PostgresRole CRD Specification

Like any official Kubernetes resource, a PostgresRole object has TypeMeta, ObjectMeta, Spec and Status sections.

A sample PostgresRole object is shown below:

apiVersion: engine.kubevault.com/v1alpha1
kind: PostgresRole
metadata:
  name: pg-role
  namespace: demo
spec:
  vaultRef:
    name: vault-app
  databaseRef:
    name: postgres-app
    namespace: demo
  creationStatements:
    - "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';"
    - "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"
status:
  observedGeneration: 1
  phase: Success

Note: To resolve the naming conflict, name of the role in Vault will follow this format: k8s.{clusterName}.{metadata.namespace}.{metadata.name}

Here, we are going to describe the various sections of the PostgresRole crd.

PostgresRole Spec

PostgresRole spec contains information that necessary for creating a database role.

spec:
  vaultRef:
    name: <vault-appbinding-name>
  databaseRef:
    name: <database-appbinding-name>
    namespace: <database-appbinding-namespace>
  databaseName: <database-name>
  path: <database-secret-engine-path>
  defaultTTL: <default-ttl>
  maxTTL: <max-ttl>
  creationStatements:
    - "statement-0"
    - "statement-1"
  revocationStatements:
    - "statement-0"
  rollbackStatements:
    - "statement-0"
  renewStatements:
    - "statement-0"

PostgresRole spec has the following fields:

spec.vaultRef

spec.vaultRef is a required field that specifies the name of an AppBinding reference which is used to connect with a Vault server. AppBinding must be on the same namespace with the PostgresRole object.

spec:
  vaultRef:
    name: vault-app

spec.databaseRef

spec.databaseRef is an optional field that specifies the reference to an AppBinding that contains PostgreSQL database connection information. It is used to generate the db_name. The naming format for db_name is: k8s.{clusterName}.{metadata.namespace}.{metadata.name}.

spec:
  databaseRef:
    name: postgres-app
    namespace: demo

spec.databaseName

spec.databaseName is an optional field that specifies the db_name. It is used when spec.databaseRef is empty otherwise ignored. Both spec.databaseRef and spec.databaseName cannot be empty at the same time.

spec:
  databaseName: k8s.-.demo.postgres-app

spec.path

spec.path is an optional field that specifies the path where the secret engine is enabled. The default value is database.

spec:
  path: my-postgres-path

spec.creationStatements

spec.creationStatements is a required field that specifies a list of database statements executed to create and configure a user. The {{name}}, {{password}} and {{expiration}} values will be substituted by Vault.

spec:
  creationStatements:
    - "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';"
    - "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"

spec.defaultTTL

spec.defaultTTL is an optional field that specifies the TTL for the leases associated with this role. Accepts time suffixed strings (“1h”) or an integer number of seconds. Defaults to system/engine default TTL time.

spec:
  defaultTTL: "1h"

spec.maxTTL

spec.maxTTL is an optional field that specifies the maximum TTL for the leases associated with this role. Accepts time suffixed strings (“1h”) or an integer number of seconds. Defaults to system/engine default TTL time.

spec:
  maxTTL: "1h"

spec.revocationStatements

spec.revocationStatements is an optional field that specifies a list of database statements to be executed to revoke a user. The {{name}} value will be substituted. If not provided defaults to a generic drop user statement.

spec.rollbackStatements

spec.rollbackStatements is an optional field that specifies a list of database statements to be executed rollback a create operation in the event of an error. Not every plugin type will support this functionality.

spec.renewStatements

spec.renewStatements is an optional field that specifies a list of database statements to be executed to renew a user. Not every plugin type will support this functionality.

PostgresRole Status

status shows the status of the PostgresRole. It is managed by the KubeVault operator. It contains the following fields:

• observedGeneration: Specifies the most recent generation observed for this resource. It corresponds to the resource’s generation, which is updated on mutation by the API Server.

• phase: Indicates whether the role successfully applied to Vault or not.

• conditions : Represent observations of a PostgresRole.