RFC: DBaaS M1 TLS Lifecycle and Certificate Management

[Yohansenanayake]

Context

This proposal suggests treating TLS as its own lifecycle for M1, separate from the tenant master password lifecycle.

The tenant master password lifecycle covers provisioning, BYO password, generated initial password, reveal, and reset. TLS is different: it controls PostgreSQL transport security and server identity.

The goal of this discussion is to agree on the M1 TLS API and lifecycle. Feedback is especially welcome on the open questions at the end.

Goals

For M1, TLS support could provide:

• TLS enable/disable toggle.
• DBaaS-managed TLS material when TLS is enabled.
• User-configurable certificate validity duration.
• Tenant-readable public CA certificate.
• A common tenant connection Secret for application/client configuration.
• Controller-private CA/server private keys.
• Clear status for connection and certificate metadata.
• Deterministic cleanup of DBaaS-owned TLS material.

Non-Goals for M1

Suggested non-goals for M1:

• cert-manager integration.
• User-provided serving certificates.
• External CA integration.
• Automatic certificate rotation.
• CA rotation / trust rollover.
• mTLS / client certificates.
• Changing TLS mode after the DB has been provisioned.

Proposed API

TLS Enabled

apiVersion: dbaas.opencloud.wso2.com/v1alpha1
kind: DBInstance
metadata:
  name: orders-db
  namespace: tenant-a
spec:
  tls:
    mode: DBaaSManaged
    certificate:
      duration: 8760h

TLS Disabled

apiVersion: dbaas.opencloud.wso2.com/v1alpha1
kind: DBInstance
metadata:
  name: orders-db
  namespace: tenant-a
spec:
  tls:
    mode: Disabled

API Fields

spec:
  tls:
    mode: DBaaSManaged | Disabled
    certificate:
      duration: 8760h

spec.tls.mode

Controls whether PostgreSQL is provisioned with TLS.

Supported M1 values:

DBaaSManaged
Disabled

Suggested default:

DBaaSManaged

The current proposal is to enable TLS by default for M1 DBInstances and let users explicitly opt out with tls.mode=Disabled.

Possible future values:

CertManager
UserProvided

spec.tls.certificate.duration

Controls the validity duration for DBaaS-managed certificates.

Example:

spec:
  tls:
    mode: DBaaSManaged
    certificate:
      duration: 8760h

Suggested M1 validation:

default: 8760h   # 1 year
minimum: 24h or 168h
maximum: 87600h # 10 years, if we want dev-friendly certs

If tls.mode=Disabled, certificate.duration has no effect because no certificate is issued. Whether this should be rejected at admission time or ignored is an open question below. The current leaning is to reject it so the spec does not contain inert configuration.

Mutability Rules

Suggested M1 behavior:

spec.tls.mode is immutable after provisioning.
spec.tls.certificate.duration is immutable after certificate issuance.

Rationale:

Changing TLS mode after provisioning requires modifying PostgreSQL config, rewriting pg_hba.conf, reloading/restarting PostgreSQL, updating endpoint URLs, and possibly creating/deleting cert material. The proposal is to defer that modify workflow until after M1.

Secret Model

When TLS is enabled, the proposed model is for DBaaS to create durable private TLS material in the controller namespace, for example dbaas-system.

Tenant-readable connection material would live in a common connection Secret in the tenant namespace. This Secret exists for both TLS-enabled and TLS-disabled configurations, but it contains ca.crt only when TLS is enabled.

dbaas-system
└── dbi-<hash(namespace/name/uid)>-tls

tenant namespace
└── pg-<dbinstance-name>-connect

The connection Secret is different from password reveal/reset Secrets:

Connection Secret:
  Stable client/application connection details.
  Exists for generated-password and BYO-password configurations.
  Does not contain password material.

Password reveal/reset Secret:
  Temporary password delivery for generated-password flows.
  Does not contain endpoint, DB name, port, or TLS private material.

Hash input:

<dbinstance-namespace>/<dbinstance-name>/<dbinstance-uid>

Including the UID helps avoid collisions when a tenant deletes and recreates a DBInstance with the same name.

Recommended Secret Shapes

Private TLS Secret

Readable by the DBaaS controller only.

apiVersion: v1
kind: Secret
metadata:
  name: dbi-7f3a91c2-tls
  namespace: dbaas-system
  labels:
    dbaas.opencloud.wso2.com/tenant-namespace: tenant-a
    dbaas.opencloud.wso2.com/dbinstance-name: orders-db
    dbaas.opencloud.wso2.com/dbinstance-uid: "<uid>"
    dbaas.opencloud.wso2.com/secret-scope: private
    dbaas.opencloud.wso2.com/secret-purpose: tls-private
type: kubernetes.io/tls
data:
  ca.crt: <base64>
  ca.key: <base64>
  tls.crt: <base64>
  tls.key: <base64>

Public Connection Secret

Readable by users or applications that need DB connection metadata.

When TLS is enabled:

apiVersion: v1
kind: Secret
metadata:
  name: pg-orders-db-connect
  namespace: tenant-a
type: Opaque
data:
  host: <base64>
  port: <base64>
  dbname: <base64>
  jdbcUrl: <base64>
  sslmode: <base64>
  ca.crt: <base64>

When TLS is disabled, the same Secret shape is used but ca.crt is omitted:

apiVersion: v1
kind: Secret
metadata:
  name: pg-orders-db-connect
  namespace: tenant-a
type: Opaque
data:
  host: <base64>
  port: <base64>
  dbname: <base64>
  jdbcUrl: <base64>
  sslmode: <base64>

The public connection Secret would not include:

password
ca.key
tls.key

Reasons to provide a common connection Secret even when endpoint details are also available in status:

• Kubernetes workloads can mount Secret keys directly as files or consume them as environment variables.
• Application deployment tooling already knows how to consume Secrets; consuming CR status usually needs custom glue.
• RBAC can grant an app or operator access to this specific Secret without granting broader DBInstance read access.
• The same application integration path works for BYO-password and generated-password configurations.
• The same application integration path works for TLS-enabled and TLS-disabled configurations.
• When TLS is enabled, keeping ca.crt in a stable Secret path avoids copying PEM blocks out of status into a separate app Secret.

The connection Secret intentionally does not include the tenant master password. In BYO mode, the user owns the password Secret. In generated-password mode, the password is delivered through a temporary reveal/reset Secret and is not stored long-term by DBaaS.

If TLS is disabled, DBaaS would still create the connection Secret, but without ca.crt. DBaaS would not create the private TLS Secret.

Status Shape

TLS Enabled

status:
  connectionSecretRef:
    name: pg-orders-db-connect
  tls:
    mode: DBaaSManaged
    lifecycleOwner: DBaaS
    # Open question: should this controller-private Secret reference be exposed
    # in tenant-facing status, or tracked only internally?
    privateSecretRef:
      namespace: dbaas-system
      name: dbi-7f3a91c2-tls
    trust:
      caCertSecretRef:
        name: pg-orders-db-connect
        key: ca.crt
      caCertPEM: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
    servingCertificate:
      status: Active
      notBefore: "2026-06-18T10:30:00Z"
      notAfter: "2027-06-18T10:30:00Z"

Whether to expose the controller-private TLS Secret reference in status is an open question below. Tracking it improves admin visibility for debugging, audits, backup checks, and recovery; it does not grant Secret data access without RBAC. Omitting it keeps status smaller and lets the controller track the Secret internally by namespace/name/UID hash and labels.

TLS Disabled

status:
  tls:
    mode: Disabled
  connectionSecretRef:
    name: pg-orders-db-connect

TLS Impaired

status:
  tls:
    mode: DBaaSManaged
    lifecycleOwner: DBaaS
    servingCertificate:
      status: Impaired
      reason: PrivateTLSSecretMissing
    message: "TLS private material is missing; database remains unavailable until DBaaS recovers or recreates serving material"

Connection URL Behavior

When TLS is enabled:

jdbc:postgresql://<host>:5432/<db>?ssl=true&sslmode=verify-ca

When TLS is disabled:

jdbc:postgresql://<host>:5432/<db>?sslmode=disable

Flow 1: Provision With TLS Enabled

sequenceDiagram
    actor User
    participant K8s as Kubernetes API
    participant DBI as DBInstance
    participant Ctrl as DBaaS Controller
    participant TLS as Private TLS Secret
    participant Conn as Connection Secret
    participant VM as PostgreSQL VM
    participant PG as PostgreSQL

    User->>K8s: Create DBInstance with tls.mode=DBaaSManaged
    K8s->>DBI: Store DBInstance

    Ctrl->>K8s: Watch DBInstance
    Ctrl->>Ctrl: Resolve certificate duration
    Ctrl->>Ctrl: Generate CA + server certificate
    Ctrl->>TLS: Store ca.crt, ca.key, tls.crt, tls.key in dbaas-system
    Ctrl->>Conn: Store connection details + public ca.crt in tenant namespace

    Ctrl->>VM: Bootstrap PostgreSQL with TLS material
    VM->>PG: Configure ssl=on and hostssl rules
    PG-->>Ctrl: PostgreSQL ready

    Ctrl->>DBI: Update status.tls and endpoint URL
    Ctrl-->>User: DB ready with public TLS trust material

    Note over Conn: Tenant mounts connection details and ca.crt.
    Note over TLS: Private TLS keys remain controller-private.

Loading

Flow 2: Provision With TLS Disabled

sequenceDiagram
    actor User
    participant K8s as Kubernetes API
    participant DBI as DBInstance
    participant Ctrl as DBaaS Controller
    participant VM as PostgreSQL VM
    participant PG as PostgreSQL

    User->>K8s: Create DBInstance with tls.mode=Disabled
    K8s->>DBI: Store DBInstance

    Ctrl->>K8s: Watch DBInstance
    Ctrl->>Ctrl: Skip TLS material generation
    Ctrl->>Connection Secret: Store connection details without ca.crt
    Ctrl->>VM: Bootstrap PostgreSQL without TLS material
    VM->>PG: Configure ssl=off and host rules
    PG-->>Ctrl: PostgreSQL ready

    Ctrl->>DBI: Update status.tls.mode=Disabled and endpoint URL
    Ctrl-->>User: DB ready without TLS

Loading

State Machine

stateDiagram-v2
    [*] --> TLSModeResolved

    TLSModeResolved --> TLSDisabled: mode=Disabled
    TLSDisabled --> DBReady: PostgreSQL ssl=off

    TLSModeResolved --> TLSPending: mode=DBaaSManaged
    TLSPending --> TLSMaterialCreated: private TLS Secret created
    TLSMaterialCreated --> TLSConfigured: PostgreSQL ssl=on
    TLSConfigured --> TLSActive: endpoint published with verify-ca

    TLSActive --> TLSImpaired: private material missing or invalid
    TLSImpaired --> TLSActive: recovered safely

    TLSActive --> TLSDeleting: DBInstance deletion
    DBReady --> TLSDeleting: DBInstance deletion
    TLSDeleting --> [*]: DBaaS-owned connection/TLS material deleted

Loading

Proposed Cleanup

If TLS is enabled:

Delete DBaaS-owned private TLS Secret.
Delete DBaaS-owned connection Secret.
Avoid relying on cross-namespace owner references.
Use DBInstance finalizer cleanup by status reference, deterministic name, or UID labels.

If TLS is disabled:

No private TLS Secret is expected.
Delete DBaaS-owned connection Secret.

Open Questions

1. Should spec.tls.certificate.duration default to 1 year or 90 days?
2. What minimum and maximum duration should we enforce?
3. If tls.mode=Disabled, should certificate.duration be rejected at admission time or ignored?
4. Should status.tls.privateSecretRef be exposed in tenant-facing status, or tracked only internally?