> [!WARNING]
>
> **Preview**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).
>
>
> For information about access to this release, see the [access
> request page](https://forms.gle/zxuHekMtV67Bw9Av9).

## Spec schema

DBClusterSpec defines the desired state of DBCluster.

```yaml
DBCluster:
  metadata:
    name: string
  spec:
    availability:
      autoFailoverTriggerThreshold: integer
      autoHealTriggerThreshold: integer
      enableAutoFailover: boolean
      enableAutoHeal: boolean
      healthcheckPeriodSeconds: integer
      replayReplicationSlotsOnStandbys: boolean
      numberOfStandbys: integer

    primarySpec:
      adminUser:
        passwordRef:
          name: string
      dbLoadBalancerOptions:
        gcp:
          loadBalancerIP: string
          loadBalancerType: string
          loadBalancerInterface: string
        onprem:
          loadBalancerIP: string
          loadBalancerType: string
          loadBalancerInterface: string
      parameters: object
      resources:
        cpu: integer or string
        memory: string or integer
        disks:
        - name: string
          path: string

    tls:
      certSecret:
        name: string
```

| Field Type Required or optional | Description |
|---|---|
| `availability` ||
| `object` *Optional* | Availability contains adjustable settings for DBCluster high availability (HA) features. |
| `availability.autoFailoverTriggerThreshold` ||
| `integer` *Optional* | AutoFailoverTriggerThreshold is the number of consecutive healthcheck failures on the primary instance that triggers an automatic failover. If set to 0, then it will use the system default value. Use the EnableAutoFailover flag to disable automatic failover. |
| `availability.autoHealTriggerThreshold` ||
| `integer` *Optional* | AutoHealTriggerThreshold is the number of consecutive standby instance health check failures that start automatic healing. To deactivate automatic healing, use the EnableAutoHeal flag. The default value is 5. |
| `availability.enableAutoFailover` ||
| `boolean` *Optional* | EnableAutoFailover means this DBCluster will trigger a failover if it detects the primary instance is unhealthy and the standby instance is healthy. If set to true, then automatic failover is enabled. If set to false, then autofailover isn't triggered even if the system detects that the primary instance is unhealthy. The default value is true. When it is enabled, if the system detects that the primary instance is unhealthy for the given threshold, it will trigger a failover. This feature is only applicable if this is an HA DBCluster and if the standby is healthy. |
| `availability.enableAutoHeal` ||
| `boolean` *Optional* | EnableAutoHeal means this DBCluster will trigger an autoheal if it detects the standby instance is unhealthy. If set to true, then autoheal is enabled. If set to false, then autoheal is not triggered even if the system detects that the standby instance is unhealthy. The default value is true. When it is enabled, if the system detects that the standby instance is unhealthy for the given threshold, it triggers an autoheal. This feature is only applicable if this is an HA DBCluster. |
| `availability.healthcheckPeriodSeconds` ||
| `integer` *Optional* | HealthcheckPeriodSeconds is the number of seconds the healthcheck prober waits before checking the health of the primary and standby instances again and updating the status accordingly. |
| `availability.replayReplicationSlotsOnStandbys` ||
| `boolean` *Optional* | Setting replayReplicationSlotsOnStandbys to true allows HA standbys to replay replication slots from WAL files. We recommend also enabling the LogReplicationSlot field on the upstream Replication resources so that the corresponding replication slots are logged in the WAL files. This configuration helps to confirm that in the event of an HA failover or switchover on the primary DBCluster, the new HA primary instance retains WAL files which have not yet been consumed by these replication slots. Note that modifying this field causes all HA standbys to restart. |
| `availability.numberOfStandbys` ||
| `integer` *Optional* | NumberOfStandbys is the number of standbys that should be created for this DBCluster. If set to any value greater than 0, then HA is enabled on the cluster and the system will create the indicated number of standby instances. The maximum allowed standby instances is 5. To check the current status of HA on this DBCluster, look at the HAReady condition under the DBCluster status. If HAReady is true, then setup has been complete and ready. If set to 0, then HA is disabled on the cluster, and deletes any existing standby instances. Any number between 0 and 5 inclusive is supported. The default value is 0. |
| `databaseVersion` ||
| `string` *Required* | DatabaseVersion is the desired database version for the cluster for example, "18.1.0" This field is required. This version is applied to all instances of the database cluster. |
| `primarySpec` ||
| `object` *Required* | PrimarySpec contains the specifications of the Primary instance of the database cluster. The primary instance contains the compute and storage resources serving the read-write endpoints of the database cluster. |
| `primarySpec.adminUser` ||
| `object` *Required* | AdminUser represents the admin user specification. This is the initial database user that the control plane creates. Additional database users are managed by the end-user directly. This field can also be used to reset the password of the initial user. |
| `primarySpec.adminUser.passwordRef` ||
| `object` *Required* | PasswordRef is the name of the secret containing the admin user's password. This value is used during initial provisioning or password reset to set the admin user to that password. The secret must be under the same project as the Database cluster. The name of the secret must follow this pattern: db-pw-. Additionally, the key of the password (inside the secret) must be the same as the database cluster name. |
| `primarySpec.adminUser.passwordRef.name` ||
| `string` *Required* | The name of the referent. |
| `primarySpec.dbLoadBalancerOptions` ||
| `object` *Optional* | DBLoadBalancerOptions allows users to provide details for the Load B. |
| `primarySpec.dbLoadBalancerOptions.gcp` ||
| `object` *Optional* | Contains Google Cloud-specific attributes for the LoadBalancer. |
| `primarySpec.dbLoadBalancerOptions.gcp.loadBalancerIP` ||
| `string` *Optional* | LoadBalancerIP is a static IP address. For more information, see [Configure static external IP addresses](https://docs.cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address). |
| `primarySpec.dbLoadBalancerOptions.gcp.loadBalancerType` ||
| `string` *Optional* | A LoadBalancer can be internal or external. |
| `primarySpec.dbLoadBalancerOptions.gcp.loadBalancerInterface` ||
| `string` *Optional* | LoadBalancerInterface is the network interface to be used by the LoadBalancer. |
| `primarySpec.dbLoadBalancerOptions.onprem` ||
| `object` *Optional* | Contains on-premises attributes for the LoadBalancer. |
| `primarySpec.dbLoadBalancerOptions.onprem.loadBalancerIP` ||
| `string` *Optional* | LoadBalancerIP is a static IP address. |
| `primarySpec.dbLoadBalancerOptions.onprem.loadBalancerType` ||
| `string` *Optional* | A LoadBalancer can be internal or external. |
| `primarySpec.dbLoadBalancerOptions.onprem.loadBalancerInterface` ||
| `string` *Optional* | LoadBalancerInterface is the network interface to be used by the LoadBalancer. |
| `primarySpec.parameters` ||
| `object` *Optional* | Parameters allow setting database parameters for the database cluster. Parameters take a key-value pair corresponding to the parameter name/value as defined by the database engine. |
| `primarySpec.resources` ||
| `object` *Required* | Resource specification for the database process. When any of the fields inside the resource changes, the operator restarts the database instance with the new resource specification. |
| `primarySpec.resources.cpu` ||
| `integer or string` *Required* | The amount of CPU allocated to the database process. |
| `primarySpec.resources.disks` ||
| `object` *Required* | The specifications of the disks allocated to the database process. |
| `primarySpec.resources.disks.name` ||
| `string` *Required* | Name of the disk. This field is required. The allowed values are: DataDisk and ObsDisk. |
| `primarySpec.resources.disks.path` ||
| `string` *Required* | Path where the disk will be mounted on file system |
| `primarySpec.resources.memory` ||
| `string or integer` *Required* | The amount of memory allocated to the database process. |
| `tls` ||
| `object` *Optional* | TLS is the desired server certificate configuration for the cluster.By default, this field is empty and a new self-signed CA and leaf certificate are generated for the cluster. |
| `tls.certSecret` ||
| `object` *Optional* | CertSecret references the certificate secret within the same namespace. The secret must contain entries ca.crt (CA certificate), tls.key (server private key), and tls.crt (server leaf certificate). This secret is used to set the TLS config for the database instances that are a part of the database cluster. |
| `tls.certSecret.name` ||
| `string` *Optional* | Name of the referent. |

## Status schema

DBClusterStatus defines the observed state of DBCluster.

```yaml
conditions:
- lastTransitionTime: string
  message: string
  observedGeneration: integer
  reason: string
  status: string
  type: string
criticalIncidents:
- code: string
  createTime: string
  message: string
  messageTemplateParams: object
  resource:
    component: string
    location:
      cluster: string
      group: string
      kind: string
      name: string
      namespace: string
      version: string
  stackTrace:
  - component: string
    message: string
  transientUntil: string
latestFailoverStatus:
  failoverName: string
  status:
    conditions:
    - lastTransitionTime: string
      message: string
      observedGeneration: integer
      reason: string
      status: string
      type: string
    createTime: string
    criticalIncidents:
    - code: string
      createTime: string
      message: string
      messageTemplateParams: object
      resource:
        component: string
        location:
          cluster: string
          group: string
          kind: string
          name: string
          namespace: string
          version: string
      stackTrace:
      - component: string
        message: string
      transientUntil: string
  endTime: string
  internal:
    attempt: integer
    lastPhaseChangeTime: string
    newPrimary: string
    newPrimaryZone: string
    oldPrimary: string
    phase: string
  observedGeneration: integer
  reconciled: boolean
  startTime: string
  state: string
observedGeneration: integer
phase: string
primary:
  allocatedResources:
    cpu: integer or string
    memory: integer or string
  conditions:
  - lastTransitionTime: string
    message: string
    observedGeneration: integer
    reason: string
    status: string
    type: string
  endpoint: string
  endpoints:
  - name: string
    value: string
  phase: string
  url: string
reconciled: boolean
```

| Field Type Required or optional | Description |
|---|---|
| `conditions` ||
| `list (object)` *Optional* | Conditions represent the latest available observations of the Entity's current state. |
| `conditions[]` ||
| `object` *Optional* | Conditions contain details for one aspect of the current state of this API Resource. |
| `conditions[].lastTransitionTime` ||
| `string` *Required* | lastTransitionTime is the last time the condition transitioned from one status to another, which occurs when the underlying condition changed. If the time when the underlying condition changed is unknown, use the time when the API field changed. |
| `conditions[].message` ||
| `string` *Required* | message is a human readable message indicating details about the transition. This can be an empty string. |
| `conditions[].observedGeneration` ||
| `integer` *Optional* | observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is 12 and the .status.conditions\[x\].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. |
| `conditions[].reason` ||
| `string` *Required* | reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types can define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value must be a CamelCase string. This field might not be empty. |
| `conditions[].status` ||
| `string` *Required* | The status of the condition, one of True, False, Unknown. |
| `conditions[].type` ||
| `string` *Required* | The type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regular expression that it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt). |
| `criticalIncidents` ||
| `object` *Optional* | CriticalIncidents is a flat list of all active Critical Incidents. |
| `criticalIncidents[]` ||
| `object` *Optional* | CriticalIncident contains all information about an ongoing critical incident. |
| `criticalIncidents[].code` ||
| `string` *Required* | Code is the error code of this particular error. Error codes are DBSE+numeric strings, like "DBSE1012". |
| `criticalIncidents[].createTime` ||
| `string` *Required* | CreateTime is the timestamp when this Incident was created at the origin. |
| `criticalIncidents[].message` ||
| `string` *Optional* | Message describes the incident or error that occurred. |
| `criticalIncidents[].messageTemplateParams` ||
| `object` *Optional* | MessageTemplateParams contains key-value pairs necessary for generating a user-friendly data-driven version of Message in the user interface. |
| `criticalIncidents[].resource` ||
| `object` *Required* | The resource contains information about the Database Service component that reported the incident, as well as information about the Kubernetes resource. |
| `criticalIncidents[].resource.component` ||
| `string` *Required* | Component is an internal identifier of the Database Service subsystem that reported the incident. |
| `criticalIncidents[].resource.location` ||
| `object` *Optional* | Location |
| `criticalIncidents[].resource.location.cluster` ||
| `string` *Optional* | Cluster is the name of the cluster of the affected Kubernetes resource. |
| `criticalIncidents[].resource.location.group` ||
| `string` *Optional* | Group is the Group name of the Cluster Manager resource. |
| `criticalIncidents[].resource.location.kind` ||
| `string` *Optional* | Kind is the Kind of the Kubernetes resource. |
| `criticalIncidents[].resource.location.name` ||
| `string` *Optional* | Name is the name of the affected Kubernetes resource. |
| `criticalIncidents[].resource.location.namespace` ||
| `string` *Optional* | Namespace is the namespace of the affected Kubernetes resource. |
| `criticalIncidents[].resource.location.version` ||
| `string` *Optional* | Group is the Version of the Kubernetes resource. |
| `criticalIncidents[].stackTrace` ||
| `object` *Optional* | StackTrace contains an unstructured list of messages from the stack trace. |
| `criticalIncidents[].stackTrace.component` ||
| `string` *Optional* | Component is the name of a Database Service component that logged the message. |
| `criticalIncidents[].stackTrace.message` ||
| `string` *Optional* | Logged message. |
| `criticalIncidents[].transientUntil` ||
| `string` *Optional* | TransientUntil, if present, indicates that the issue must be considered transient until the specified time. |
| `latestFailoverStatus` ||
| `object` *Optional* | LatestFailoverStatus is the status of the most recently updated failover for the database cluster This status is a copy of the status of the current or most recently updated failover operation for the database cluster. This can be used to conveniently monitor the status of a running failover operation. |
| `latestFailoverStatus.failoverName` ||
| `string` *Optional* | FailoverName is the Name of the latest failover. |
| `latestFailoverStatus.status` ||
| `object` *Optional* | Status represents the status of the latest failover for the database cluster. |
| `latestFailoverStatus.status.conditions` ||
| `object` *Optional* | Conditions represent the latest available observations of the Entity's current state. |
| `latestFailoverStatus.status.conditions.lastTransitionTime` ||
| `string` *Required* | lastTransitionTime is the last time the condition transitioned from one status to another, which occurs when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. |
| `latestFailoverStatus.status.conditions.message` ||
| `string` *Required* | message is a human readable message indicating details about the transition. This may be an empty string. |
| `latestFailoverStatus.status.conditions.observedGeneration` ||
| `integer` *Optional* | observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is 12, but the .status.conditions\[x\].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. |
| `latestFailoverStatus.status.conditions.reason` ||
| `string` *Required* | reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types can define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. |
| `latestFailoverStatus.status.conditions.status` ||
| `string` *Required* | The status of the condition, one of True, False, Unknown. |
| `latestFailoverStatus.status.conditions.type` ||
| `string` *Required* | The type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regular expression that it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt). |
| `latestFailoverStatus.status.createTime` ||
| `string` *Optional* | CreateTime is the time when the internal failover workflow mechanism was created. |
| `latestFailoverStatus.status.criticalIncidents` ||
| `object` *Optional* | CriticalIncidents is a flat list of all active Critical Incidents. |
| `latestFailoverStatus.status.criticalIncidents.code` ||
| `string` *Required* | Code is the error code of this particular error. Error codes are DBSE+numeric strings, like "DBS1012". |
| `latestFailoverStatus.status.criticalIncidents.createTime` ||
| `string` *Required* | CreateTime is the timestamp when this Incident was created at the origin. |
| `latestFailoverStatus.status.criticalIncidents.message` ||
| `string` *Optional* | Message describes the incident or error that occurred. |
| `latestFailoverStatus.status.criticalIncidents.messageTemplateParams` ||
| `object` *Optional* | MessageTemplateParams contains key-value pairs necessary for generating a user-friendly data-driven version of Message in the user interface. |
| `latestFailoverStatus.status.criticalIncidents.resource` ||
| `object` *Required* | The resource contains information about the Database Service component that reported the incident as well as information about the Cluster Manager resource. |
| `latestFailoverStatus.status.criticalIncidents.resource.component` ||
| `string` *Required* | Component is an internal identifier of the Database Service subsystem that reported the incident. |
| `latestFailoverStatus.status.criticalIncidents.resource.location` ||
| `object` *Optional* | Location |
| `latestFailoverStatus.status.criticalIncidents.resource.location.cluster` ||
| `string` *Optional* | Cluster is the name of the cluster of the affected Cluster Manager resource. |
| `latestFailoverStatus.status.criticalIncidents.resource.location.group` ||
| `string` *Optional* | Group is the Group name of the Cluster Manager resource. |
| `latestFailoverStatus.status.criticalIncidents.resource.location.kind` ||
| `string` *Optional* | Kind is the Kind of the Cluster Manager resource. |
| `latestFailoverStatus.status.criticalIncidents.resource.location.name` ||
| `string` *Optional* | Name is the name of the affected Cluster Manager resource. |
| `latestFailoverStatus.status.criticalIncidents.resource.location.namespace` ||
| `string` *Optional* | Namespace is the namespace of the affected Cluster Manager resource. |
| `latestFailoverStatus.status.criticalIncidents.resource.location.version` ||
| `string` *Optional* | Group is the Version of the Cluster Manager resource. |
| `latestFailoverStatus.status.criticalIncidents.stackTrace` ||
| `object` *Optional* | StackTrace contains an unstructured list of messages from the stack trace. |
| `latestFailoverStatus.status.criticalIncidents.stackTrace.component` ||
| `string` *Optional* | Component is the name of a Database Service component that logged the message. |
| `latestFailoverStatus.status.criticalIncidents.stackTrace.message` ||
| `string` *Optional* | Logged message. |
| `latestFailoverStatus.status.criticalIncidents.transientUntil` ||
| `string` *Optional* | TransientUntil, if present, indicates that the issue must be considered transient until the specified time. |
| `latestFailoverStatus.status.endTime` ||
| `string` *Optional* | EndTime is the time the failover reached its final state. |
| `latestFailoverStatus.status.internal` ||
| `object` *Optional* | Internal is used by the system controllers. Do not depend on the information in this section. |
| `latestFailoverStatus.status.internal.attempt` ||
| `integer` *Required* | Attempt is used for retry logic and the default value is 0. |
| `latestFailoverStatus.status.internal.lastPhaseChangeTime` ||
| `string` *Optional* | LastPhaseChangeTime is the last time the L1 failover changed to a new phase. This is used for timeout logic. |
| `latestFailoverStatus.status.internal.newPrimary` ||
| `string` *Required* | NewPrimary is the instance that you're attempting to failover to. |
| `latestFailoverStatus.status.internal.newPrimaryZone` ||
| `string` *Optional* | NewPrimaryZone is the zone that we are attempting to failover to. |
| `latestFailoverStatus.status.internal.oldPrimary` ||
| `string` *Required* | OldPrimary is the instance that was the primary at the start of the failover. |
| `latestFailoverStatus.status.internal.phase` ||
| `string` *Optional* | Phase is used to keep track of the current state of the failover. |
| `latestFailoverStatus.status.observedGeneration` ||
| `integer` *Optional* | The generation observed by the controller. |
| `latestFailoverStatus.status.reconciled` ||
| `boolean` *Optional* | Whether the resource was reconciled by the controller. |
| `latestFailoverStatus.status.startTime` ||
| `string` *Optional* | StartTime is the time that the failover operation started. |
| `latestFailoverStatus.status.state` ||
| `string` *Optional* | State is the current state of the failover operation. The values are InProgress, Success, Failed. InProgress means the failover is still in progress. Success means that the failover completed. It is complete when the new primary instance is successfully promoted. Failed means that the operator was unable to promote the new primary instance. The DBCluster might need to be manually repaired. |
| `observedGeneration` ||
| `integer` *Optional* | Internal: The generation observed by the controller. |
| `phase` ||
| `string` *Optional* | Phase is a summary of the current state of the DBCluster |
| `primary` ||
| `object` *Optional* | Primary contains the status of the primary Instance. |
| `primary.allocatedResources` ||
| `object` *Optional* | AllocatedResources represents the current configuration of memory, CPU, and disks. |
| `primary.allocatedResources.cpu` ||
| `integer or string` *Required* | The amount of CPU allocated to the database process. |
| `primary.allocatedResources.memory` ||
| `string or integer` *Required* | The amount of memory allocated to the database process. |
| `primary.conditions` ||
| `object` *Required* | Conditions represent the latest available observations of the Instance's current state. |
| `primary.conditions.lastTransitionTime` ||
| `string` *Required* | lastTransitionTime is the last time the condition transitioned from one status to another, which occurs when the underlying condition changed. If the time when the underlying condition changed is unknown, you can use the time when the API field changed. |
| `primary.conditions.message` ||
| `string` *Required* | message is a human readable message indicating details about the transition. This can be an empty string. |
| `primary.conditions.observedGeneration` ||
| `integer` *Optional* | observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is 12 but the .status.conditions\[x\].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. |
| `primary.conditions.reason` ||
| `string` *Required* | reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types can define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field might not be empty. |
| `primary.conditions.status` ||
| `string` *Required* | The status of the condition, one of True, False, Unknown. |
| `primary.conditions.type` ||
| `string` *Required* | The type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regular expression that it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt). |
| `primary.endpoint` ||
| `string` *Optional* | Endpoint is the address that you can use to establish database connections. Deprecated: use the Endpoints field instead. |
| `primary.endpoints` ||
| `object` *Optional* | Endpoints contain all the endpoints through which you can access this instance. |
| `primary.endpoints.name` ||
| `string` *Required* | Name contains the name of the endpoint. |
| `primary.endpoints.value` ||
| `string` *Optional* | Value contains the endpoint information. |
| `primary.endpoints.value` ||
| `string` *Optional* | Value contains the endpoint information. |
| `primary.phase` ||
| `string` *Optional* | Phase is a summary of the current state of the instance. |
| `reconciled` ||
| `boolean` *Optional* | Whether the resource was reconciled by the controller. |