Create a cluster

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

For information about access to this release, see the access request page.

Select a documentation version: 18.1.0

• Current (18.1.0)
• 18.1.0

Create a database cluster to start using AlloyDB Omni.

Limitations

The following limitations apply:

• AlloyDB Omni runs on port 5432. Configuring a custom port is not supported.

• Ensure that all database parameter configurations are correct before creating your cluster. Once your cluster is created, you cannot modify any database parameters.

Before you begin

Before you create your cluster, complete the following:

• Install the AlloyDB Omni orchestrator

• Install AlloyDB Omni components

• Configure TLS certificates

• Mount an external volume (DataDisk) to PG_DATA_DIR on all database nodes provisioned within the orchestrator.

• If you plan to use alloydbctl instead of Ansible, ensure that the required policycoreutils-python-utils package is installed on all of your VMs. To install this package, run the following command:

  sudo dnf install policycoreutils-python-utils

Prepare cluster specifications

To create your cluster, AlloyDB Omni must know how to configure it. To create the necessary specifications, create a YAML file using the DBCluster format:

Secret:
  metadata:
    name: db-pw-DBCLUSTER_NAME
  spec:
    type: Opaque
    data:
      DBCLUSTER_NAME: BASE64_PASSWORD
---
DBCluster:
  metadata: DBCLUSTER_NAME
    name:
  spec:
    databaseVersion: 18.1.0
    mode: ""
    availability:
      numberOfStandbys: NUM_STANDBY_NODES
      enableAutoFailover: true
      enableAutoHeal: true
      autoFailoverTriggerThreshold: AUTOFAILOVER_TRIGGER_THRESHOLD
      autoHealTriggerThreshold: AUTOHEAL_TRIGGER_THRESHOLD
      healthcheckPeriodSeconds: HEALTHCHECK_PERIOD
      replayReplicationSlotsOnStandbys: false
    primarySpec:
      adminUser:
        passwordRef:
          name: db-pw-DBCLUSTER_NAME
      resources:
        cpu: CPU_LIMIT
        memory: MEMORY_LIMIT
        disks:
        - name: DataDisk
          path: PG_DATA_DIR
      parameters:
        max_connections: "MAX_CONNECTIONS"
        max_wal_size: "MAX_WAL_SIZE"
        max_worker_processes: "MAX_WORKER_PROCESSES"
        log_connections: "LOG_CONNECTIONS"
        log_disconnections: "LOG_DISCONNECTS"
        log_hostname: "LOG_HOSTNAME"
        log_statement: "LOG_STATEMENT"
        huge_pages: "HUGE_PAGES"
        tcp_keepalives_idle: "TCP_KEEPALIVES_IDLE"
        tcp_keepalives_interval: "TCP_KEEPALIVES_INTERVAL"
        tcp_keepalives_count: "TCP_KEEPALIVES_COUNT"
      dbLoadBalancerOptions:
        DB_LOAD_BALANCER_TYPE:
          loadBalancerIP: "VIRTUAL_IP"
          loadBalancerType: "internal"
          loadBalancerInterface: "VIRTUAL_IP_INTERFACE"

Replace the following variables:

• DBCLUSTER_NAME: name of your database cluster. For example, my-dbcluster.

• BASE64_PASSWORD: base64-encoded password used for the postgres administrator user.

• NUM_STANDBY_NODES: number of standby nodes in your cluster. For example, 2.

• (Optional) AUTOFAILOVER_TRIGGER_THRESHOLD: number of times the health check can fail before a failover occurs. The default value is 3. The minimum value is 0, but if the value is set to 0, AlloyDB Omni uses the default value.

  An automatic failover occurs if the health check fails AUTOFAILOVER_TRIGGER_THRESHOLD times or if the cumulative duration of the health check reaches HEALTHCHECK_PERIOD * AUTOFAILOVER_TRIGGER_THRESHOLD seconds.

• (Optional) AUTOHEAL_TRIGGER_THRESHOLD: number of times the health check can fail before auto-heal begins. The default value is 3. The minimum value is 0, but if the value is set to 0, AlloyDB Omni uses the default value.

  An automatic recovery occurs if the health check fails AUTOHEAL_TRIGGER_THRESHOLD times or if the cumulative duration of the health check reaches HEALTHCHECK_PERIOD * AUTOHEAL_TRIGGER_THRESHOLD seconds.

• (Optional) HEALTHCHECK_PERIOD: number of seconds to wait between each health check. The default value is 30. The minimum value is 1. The maximum value is 86400 (one day).

• CPU_LIMIT: number of CPUs to allocate to the database container. For example, 4.

• MEMORY_LIMIT: amount of memory to allocate to the database container. For example, 32Gi, 500Mi.

• PG_DATA_DIR: host path to the directory where the database data will be stored.

• (Optional) MAX_CONNECTIONS: maximum number of concurrent connections to the PostgreSQL database. The default value is 100. For more information, see the PostgreSQL max_connections reference.

• (Optional) MAX_WAL_SIZE: maximum size to let the Write-Ahead-Log (WAL) grow during automatic checkpoints. The default value is 2GB. For more information, see the PostgreSQL max_wal_size reference.

• (Optional) MAX_WORKER_PROCESSES: maximum number of workers that can be started by a single Gather or Gather Merge. The default value is 32. For more information, see the PostgreSQL max_worker_processes reference.

• (Optional) LOG_CONNECTIONS: determines whether or not connections to your PostgreSQL server are logged. The default value is on. For more information, see the PostgreSQL log_connections reference.

• (Optional) LOG_DISCONNECTS: determines if PostgreSQL session terminations are logged. The default value is on. For more information, see the PostgreSQL log_disconnections reference.

• (Optional) LOG_HOSTNAME: determines whether or not the hostname is logged in addition to the IP for the connecting host. The default value is on. For more information, see the PostgreSQL log_hostname reference.

• (Optional) LOG_STATEMENT: determines which SQL statements are logged. The default value is none. For more information, see the PostgreSQL log_statement reference.

• (Optional) HUGE_PAGES: determines if huge pages are requested for the main shared memory area. The default value is off. For more information, see the PostgreSQL huge_pages reference.

• (Optional) TCP_KEEPALIVES_IDLE: amount of time, in seconds, with no network activity before the OS attempts to send a TCP keepalive message to the client. The default value is 10. For more information, see the PostgreSQL tcp_keepalives_idle reference.

• (Optional) TCP_KEEPALIVES_INTERVAL: amount of time, in seconds, before a TCP keepalive message that hasn't been acknowledged by the client should be retransmitted. The default value is 10. For more information, see the PostgreSQL tcp_keepalives_interval reference.

• (Optional) TCP_KEEPALIVES_COUNT: number of TCP keepalive messages that can be lost before the server's connection to the client is considered inactive. The default value is 10. For more information, see the PostgreSQL tcp_keepalives_count reference.

• (Optional) DB_LOAD_BALANCER_TYPE: determines the type of load balancer: onprem or gcp.

• (Optional) VIRTUAL_IP: virtual IP address used by the load balancer. If you define dbLoadBalancerOptions, this is required. For more information, see Manage high availability.

• (Optional) VIRTUAL_IP_INTERFACE: network interface where VIRTUAL_IP is configured. The default value is eth0.

Create your cluster

To create your cluster, select the tab that matches your environment and follow the instructions.

Ansible

To create your cluster, complete the following instructions:

1. Create a playbook for your database cluster specifications.

   - name: Create DBCluster
     hosts: localhost
     vars:
       ansible_become: true
       ansible_user: ANSIBLE_USER
       ansible_ssh_private_key_file: ANSIBLE_SSH_PRIVATE_KEY_FILE
     roles:
     - role: google.alloydbomni_orchestrator.bootstrap
   
   

   Replace the following variables:

   • ANSIBLE_USER: OS user that Ansible uses to log into your AlloyDB Omni nodes.

   • ANSIBLE_SSH_PRIVATE_KEY_FILE: private key Ansible uses to connect to your AlloyDB Omni nodes using SSH.

2. Run your playbook.

   ansible-playbook DBCLUSTER_PLAYBOOK -i "DEPLOYMENT_SPEC" \
         -e resource_spec="DBCLUSTER_SPECIFICATIONS"

   Replace the following variables:

   • DBCLUSTER_PLAYBOOK: path to the playbook that you created for your database cluster.

   • DEPLOYMENT_SPEC: path to the deployment specification you created in Install AlloyDB Omni components.

   • DBCLUSTER_SPECIFICATIONS: path to your cluster specifications.

alloydbctl

To create your cluster, run the following command:

alloydbctl apply -d "DEPLOYMENT_SPEC" -r "DBCLUSTER_SPECIFICATIONS"

Replace the following variables:

• DEPLOYMENT_SPEC: path to the deployment specification you created in Install AlloyDB Omni components.

• DBCLUSTER_SPECIFICATIONS: path to your cluster specifications.

Delete your cluster

To delete your cluster, select the tab that matches your environment and follow the instructions.

Ansible

To delete your cluster using Ansible, complete the following:

1. Create a playbook named teardown.yaml:

   - name: Tear down AlloyDB Omni cluster
     hosts: localhost
     vars:
       ansible_become: true
       ansible_user: ANSIBLE_USER
       ansible_ssh_private_key_file: ANSIBLE_SSH_PRIVATE_KEY_FILE
     roles:
     - role: google.alloydbomni_orchestrator.delete
   

2. Execute the playbook using ansible-playbook. You must specify DBCluster as the resource_type and the name of the cluster to be deleted as resource_name.

   ansible-playbook -i "DEPLOYMENT_SPEC" teardown.yaml \
     -e `resource_type`=`DBCluster` -e `resource_name`="DBCLUSTER_NAME"

If the teardown process fails due to inconsistencies in the cluster state (for example, if a node is unreachable), you can attempt to force delete your cluster by adding -e force=true to the command. This instructs the orchestrator to ignore errors during the teardown process and attempt to remove as many resources as possible.

  ansible-playbook -i "DEPLOYMENT_SPEC" teardown.yaml \
    -e resource_type=DBCluster -e resource_name="DBCLUSTER_NAME" -e force=true

alloydbctl

To delete your cluster using alloydbctl, run the following command:

alloydbctl delete -d "DEPLOYMENT_SPEC" \
      --resource_type DBCluster --resource_name "DBCLUSTER_NAME"

Replace the following variables:

• DEPLOYMENT_SPEC: path to the deployment specification you created in Install AlloyDB Omni components.

• DBCLUSTER_NAME: name of your database cluster. For example, my-dbcluster.