alloydb-omni-kubernetes

What this skill does

# Context

You're an experienced sysadmin and database administrator. You're familiar with
containers and Kubernetes. You're also familiar with PostgreSQL and AlloyDB for
PostgreSQL. Your focus is to help users with tasks related to AlloyDB Omni in
Kubernetes such as creating, managing, and monitoring AlloyDB Omni DBClusters.

# Prerequisites

After activating, confirm with the user that you can run `kubectl` commands and
that it is connected to the right Kubernetes clusters.

**Important**: `kubectl` commands can modify existing resources and may result
in data loss. Always double-check with the user before running any `kubectl`
commands.

# Operator deep dive

By default, the operator runs under the `alloydb-omni-system` namespace. This
namespace can be changed by the user when installing the helm chart, so if
there's nothing there, ask the user where the operator is running.

# Resource Inspection

When monitoring or verifying the state of a resource, use `kubectl describe
<resource_type> <resource_name>` in addition to `kubectl get`. The `describe`
command provides a detailed view of the resource, including the **Events**
section, which often contains critical information regarding the lifecycle and
current state of the resource.

# Connecting to the Database

The most straightforward way to connect to a DBCluster from your local
environment is to use `kubectl port-forward`.

**Important**: The `kubectl port-forward` command is a persistent process that
does not terminate on its own. **The user MUST execute this command in a
separate terminal.** Running it directly within the Gemini CLI will cause the
session to hang and break the agent's functionality.

Example: `kubectl port-forward svc/<service-name> 5432:5432`

# Resource Hierarchy:

**External resources:** are resources that users will interact with directly on
a daily basis. They are equivalent to public APIs of AlloyDB Omni.

```text
backupplans.alloydbomni.dbadmin.goog
backups.alloydbomni.dbadmin.goog
dbclusters.alloydbomni.dbadmin.goog
dbinstances.alloydbomni.dbadmin.goog
failovers.alloydbomni.dbadmin.goog
pgbouncers.alloydbomni.dbadmin.goog
replications.alloydbomni.dbadmin.goog
restores.alloydbomni.dbadmin.goog
sidecars.alloydbomni.dbadmin.goog
switchovers.alloydbomni.dbadmin.goog
tdeconfigs.alloydbomni.dbadmin.goog
userdefinedauthentications.alloydbomni.dbadmin.goog
```

**Internal resources:** are resources that are managed by the AlloyDB Omni
operator and are not meant to be interacted with directly by users. They are
equivalent to private APIs of AlloyDB Omni. However, you may need to interact
with them to get more information.

```text
instances.alloydbomni.internal.dbadmin.goog
```

The central resource is `dbcluster` (full name:
`dbclusters.alloydbomni.dbadmin.goog`). A DBCluster (or database cluster) is a
collection of database instances (fullname:
`instances.alloydbomni.internal.dbadmin.goog`) and other resources that are
managed together. **Important differentiation**: Instances (full name:
`instances.alloydbomni.internal.dbadmin.goog`) are different from DBInstances
(full name: `dbinstances.alloydbomni.dbadmin.goog`). Instances (the internal
resource) represent a unit of compute and storage resource that runs the
database (similar to a Kubernetes `pod`). `DBInstance` (the external resource)
is a read-only group of internal Instances, to be used to scale read-only
workloads on that DBCluster.

The DBCluster, internal instances, and their pods all run under the same
namespace.

To take a backup of a `dbcluster`, you need to first create a `backupplan`
(fullname: `backupplans.alloydbomni.dbadmin.goog`). A `backupplan` defines the
backup schedule, retention, and other configuration. Then `backupplan` will
create individual `backup` (fullname: `backups.alloydbomni.dbadmin.goog`) each
time a backup is taken. You can check the status of each backup by looking at
the `backups` resources.

A highly available dbcluster will have one primary instance and one or more
secondary instances. The primary instance is the one that is used to serve read
and write traffic. The secondary instances can be used to serve read traffic and
can be promoted to primary instances in case of a failover. You can check the
status of each internal instance by looking at the `instances` resources. To
trigger a fail-over (faster, can have data loss), use the `failover` (fullname:
`failovers.alloydbomni.dbadmin.goog`) resource. To trigger a switch-over
(slower, no data loss), use the `switchover` (fullname:
`switchovers.alloydbomni.dbadmin.goog`) resource.

By default, a `restore` (full name: `restores.alloydbomni.dbadmin.goog`) will
restore the data onto the same DBCluster. To create a new DBCluster from a
backup, you need to specify the new DBCluster name under
`clonedDBClusterConfig`.

To deploy a PgBouncer connection pool / proxy fronting the DBCluster, create a
`pgbouncer` (fullname: `pgbouncers.alloydbomni.dbadmin.goog`) resource.

## Inspectin resources

When monitoring or verifying the state of a resource, use `kubectl describe
<resource_type> <resource_name>` in addition to `kubectl get`. The `describe`
command provides a detailed view of the resource, including the **Events**
section, which often contains critical information regarding the lifecycle and
current state of the resource.

## Connecting to the Database

The most straightforward way to connect to a DBCluster from your local
environment is to use `kubectl port-forward`.

**Important**: The `kubectl port-forward` command is a persistent process that
does not terminate on its own. **The user MUST execute this command in a
separate terminal.** Running it directly within the Gemini CLI will cause the
session to hang and break the agent's functionality.

Example: `kubectl port-forward svc/<service-name> 5432:5432`

# AlloyDB Omni on Kubernetes Configuration Samples

## DBCluster examples

### Minimal DBCluster

A basic configuration to get a DBCluster running.

```yaml
# This is a minimal DBCluster spec. See v1_dbcluster_full.yaml for more configurations.
apiVersion: v1
kind: Secret
metadata:
  name: db-pw-dbcluster-sample
type: Opaque
data:
  dbcluster-sample: "Q2hhbmdlTWUxMjM=" # Password is ChangeMe123
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: dbcluster-sample
spec:
  databaseVersion: "16.9.0"
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-dbcluster-sample
    resources:
      memory: 5Gi
      cpu: 1
      disks:
        - name: DataDisk
          size: 10Gi
```

### Full DBCluster

A comprehensive DBCluster configuration showing more options.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: db-pw-dbcluster-sample
type: Opaque
data:
  dbcluster-sample: "Q2hhbmdlTWUxMjM=" # Password is ChangeMe123
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: dbcluster-sample
spec:
  allowExternalIncomingTraffic: true
  availability:
    healthcheckPeriodSeconds: 30 # The default is 30 seconds. This is a new feature in 1.2.0. The minimum value is 1 and the maximum value is 86400
    autoFailoverTriggerThreshold: 3 # The number of failures after which failover is triggered.
    autoHealTriggerThreshold: 3
    enableAutoFailover: true
    enableAutoHeal: true
    enableStandbyAsReadReplica: true
    numberOfStandbys: 1
  controlPlaneAgentsVersion: "1.6.0"
  databaseVersion: "16.9.0"
  databaseImageOSType: UBI9
  isDeleted: false
  mode: ""
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-dbcluster-sample
    allowExternalIncomingTrafficToInstance: false
    auditLogTarget: {}
    dbLoadBalancerOptions:
      annotations:
        networking.gke.io/load-balancer-type: "internal"
        lb.company.com/enabled: "true"
      gcp: {}
    features:
      columnarSpillToDisk:
        cacheSize: 50Gi
      ultraFastCache:
        cacheSize: 100Gi
      # either generic volume or local volume
      genericVolume:
        storageClass: "local-storage"