Lusheng Ji | bd11574 | 2017-10-13 19:18:52 +0000 | [diff] [blame] | 1 | PostgreSQL as a Service |
| 2 | ============ |
Tony Hansen | 30c453e | 2017-10-13 14:34:46 +0000 | [diff] [blame] | 3 | |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 4 | PostgreSQL as a Service (PGaaS) comes in two flavors: all-in-one blueprint, and |
Tony Hansen | 30c453e | 2017-10-13 14:34:46 +0000 | [diff] [blame] | 5 | separate disk/cluster/database blueprints to separate the management of |
| 6 | the lifetime of those constituent parts. Both are provided for use. |
| 7 | |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 8 | Why Three Flavors? |
Lusheng Ji | bd11574 | 2017-10-13 19:18:52 +0000 | [diff] [blame] | 9 | ------------ |
Tony Hansen | 30c453e | 2017-10-13 14:34:46 +0000 | [diff] [blame] | 10 | |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 11 | The reason there are three flavors of blueprints lays in the difference in |
| 12 | lifetime management of the constituent parts and the number of VMs created. |
Tony Hansen | 30c453e | 2017-10-13 14:34:46 +0000 | [diff] [blame] | 13 | |
| 14 | For example, a database usually needs to have persistent storage, which |
| 15 | in these blueprints comes from Cinder storage volumes. The primitives |
| 16 | used in these blueprints assume that the lifetime of the Cinder storage |
| 17 | volumes matches the lifetime of the blueprint deployment. So when the |
| 18 | blueprint goes away, any Cinder storage volume allocated in the |
| 19 | blueprint also goes away. |
| 20 | |
Tony Hansen | 8c55897 | 2017-10-17 18:14:52 +0000 | [diff] [blame] | 21 | Similarly, a database's lifetime may be the same time as an application's |
| 22 | lifetime. When the application is undeployed, the associated database should |
| 23 | be deployed too. OR, the database should have a lifetime beyond the scope |
| 24 | of the applications that are writing to it or reading from it. |
Tony Hansen | 30c453e | 2017-10-13 14:34:46 +0000 | [diff] [blame] | 25 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 26 | Blueprint Files |
Tony Hansen | 8c55897 | 2017-10-17 18:14:52 +0000 | [diff] [blame] | 27 | ------------ |
Tony Hansen | 30c453e | 2017-10-13 14:34:46 +0000 | [diff] [blame] | 28 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 29 | The Blueprints for PG Services and Cinder |
| 30 | ^^^^^^^^^^^ |
| 31 | |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 32 | The all-in-one blueprint ``pgaas.yaml`` assumes that the PG servers and Cinder volumes can be allocated and |
| 33 | deallocated together. The ``pgaas.yaml`` blueprint creates a cluster of two VMs named "``pstg``" by default. |
Tony Hansen | 8c55897 | 2017-10-17 18:14:52 +0000 | [diff] [blame] | 34 | |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 35 | The ``pgaas-onevm.yaml`` blueprint creates a single-VM instance named "``pgvm``" by default. |
| 36 | |
| 37 | Alternatively, you can split them apart into separate steps, using ``pgaas-disk.yaml`` to allocate the |
| 38 | Cinder volume, and ``pgaas-cluster.yaml`` to allocate a PG cluster. Create the Cinder volume first using |
| 39 | ``pgaas-disk.yaml``, and then use ``pgaas-cluster.yaml`` to create the cluster. The PG cluster can be |
Tony Hansen | 8c55897 | 2017-10-17 18:14:52 +0000 | [diff] [blame] | 40 | redeployed without affecting the data on the Cinder volumes. |
| 41 | |
| 42 | The Blueprints for Databases |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 43 | ^^^^^^^^^^^ |
Tony Hansen | 8c55897 | 2017-10-17 18:14:52 +0000 | [diff] [blame] | 44 | |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 45 | The ``pgaas-database.yaml`` blueprint shows how a database can be created separately from any application |
| 46 | that uses it. That database will remain present until the pgaas-database.yaml blueprint is |
| 47 | undeployed. The ``pgaas-getdbinfo.yaml`` file demonstrates how an application would access the credentials |
Tony Hansen | 8c55897 | 2017-10-17 18:14:52 +0000 | [diff] [blame] | 48 | needed to access a given database on a given PostgreSQL cluster. |
| 49 | |
| 50 | If the lifetime of your database is tied to the lifetime of your application, use a block similar to what |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 51 | is in ``pgaas-database.yaml`` to allocate the database, and use the attributes as shown in ``pgaas-getdbinfo.yaml`` |
Tony Hansen | 8c55897 | 2017-10-17 18:14:52 +0000 | [diff] [blame] | 52 | to access the credentials. |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 53 | |
Tony Hansen | ca73462 | 2017-11-01 22:02:10 +0000 | [diff] [blame] | 54 | Both of these blueprints use the ``dcae.nodes.pgaas.database`` plugin reference, but ``pgaas-getdbinfo.yaml`` |
| 55 | adds the ``use_existing: true`` property. |
| 56 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 57 | |
| 58 | What is Created by the Blueprints |
| 59 | ^^^^^^^^^^^^ |
| 60 | |
| 61 | Each PostgreSQL cluster has a name, represented below as ``${CLUSTER}`` or ``CLNAME``. Each cluster is created |
| 62 | with two VMs, one VM used for the writable master and the other as a cascaded read-only secondary. |
| 63 | |
| 64 | |
| 65 | There are two DNS A records added, ``${LOCATIONPREFIX}${CLUSTER}00.${LOCATIONDOMAIN}`` and |
| 66 | ``${LOCATIONPREFIX}${CLUSTER}01.${LOCATIONDOMAIN}``. In addition, |
| 67 | there are two CNAME entries added: |
| 68 | ``${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN} `` |
| 69 | and |
| 70 | ``${LOCATIONPREFIX}-${CLUSTER}.${LOCATIONDOMAIN}``. The CNAME |
| 71 | ``${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN}`` will be used by further |
| 72 | blueprints to create and attach to databases. |
| 73 | |
| 74 | |
| 75 | Parameters |
| 76 | ------------ |
| 77 | |
| 78 | The blueprints are designed to run using the standard inputs file used for all of the blueprints, |
| 79 | plus several additional parameters that are given reasonable defaults. |
| 80 | |
| 81 | How to Run |
| 82 | ------------ |
| 83 | |
| 84 | |
| 85 | |
| 86 | To install the PostgreSQL as a Service |
| 87 | ^^^^^^^^^^^^ |
| 88 | |
| 89 | Installing the all-in-one blueprint is straightforward: |
| 90 | |
| 91 | :: |
| 92 | |
| 93 | cfy install -p pgaas.yaml -i inputs.yaml |
| 94 | |
| 95 | By default, the all-in-one blueprint creates a cluster by the name ``pstg``. |
| 96 | |
| 97 | You can override that name using another ``-i`` option. |
| 98 | (When overriding the defaults, it is also best to explicitly |
| 99 | set the -b and -d names.) |
| 100 | |
| 101 | :: |
Tony Hansen | 09c6a76 | 2017-10-30 18:52:57 +0000 | [diff] [blame] | 102 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 103 | cfy install -p pgaas.yaml -b pgaas-CLNAME -d pgaas-CLNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME |
| 104 | |
| 105 | |
| 106 | Separating out the disk allocation from the service creation requires using two blueprints: |
| 107 | |
| 108 | :: |
Tony Hansen | 09c6a76 | 2017-10-30 18:52:57 +0000 | [diff] [blame] | 109 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 110 | cfy install -p pgaas-disk.yaml -i inputs.yaml |
| 111 | cfy install -p pgaas-cluster.yaml -i inputs.yaml |
| 112 | |
| 113 | By default, these blueprints create a cluster named ``pgcl``, which can be overridden the same |
| 114 | way as shown above: |
| 115 | |
| 116 | :: |
Tony Hansen | 09c6a76 | 2017-10-30 18:52:57 +0000 | [diff] [blame] | 117 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 118 | cfy install -p pgaas-disk.yaml -b pgaas-disk-CLNAME -d pgaas-disk-CLNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME |
| 119 | cfy install -p pgaas-cluster.yaml -b pgaas-disk-CLNAME -d pgaas-disk-CLNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME |
| 120 | |
| 121 | |
| 122 | You must use the same pgaas_cluster_name for the two blueprints to work together. |
| 123 | |
| 124 | For the disk, you can also specify a ``cinder_volume_size``, as in ``-i cinder_volume_size=1000`` |
| 125 | for 1TiB volume. (There is no need to override the ``-b`` and ``-d`` names when changing the |
| 126 | volume size.) |
| 127 | |
| 128 | |
| 129 | You can verify that the cluster is up and running by connecting to the PostgreSQL service |
Tony Hansen | b32a0b6 | 2017-10-25 11:53:09 +0000 | [diff] [blame] | 130 | on port 5432. To verify that all of the DNS names were created properly and that PostgreSQL is |
| 131 | answering on port 5432, you can use something like this: |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 132 | |
| 133 | :: |
Tony Hansen | 09c6a76 | 2017-10-30 18:52:57 +0000 | [diff] [blame] | 134 | |
Tony Hansen | b32a0b6 | 2017-10-25 11:53:09 +0000 | [diff] [blame] | 135 | sleep 1 | nc -v ${LOCATIONPREFIX}${CLUSTER}00.${LOCATIONDOMAIN} 5432 |
| 136 | sleep 1 | nc -v ${LOCATIONPREFIX}${CLUSTER}01.${LOCATIONDOMAIN} 5432 |
| 137 | sleep 1 | nc -v ${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN} 5432 |
| 138 | sleep 1 | nc -v ${LOCATIONPREFIX}-${CLUSTER}.${LOCATIONDOMAIN} 5432 |
| 139 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 140 | |
| 141 | Once you have the cluster created, you can then allocate databases. An application that |
| 142 | wants a persistent database not tied to the lifetime of the application blueprint can |
| 143 | use the ``pgaas-database.yaml`` blueprint to create the database; |
| 144 | |
| 145 | :: |
Tony Hansen | 09c6a76 | 2017-10-30 18:52:57 +0000 | [diff] [blame] | 146 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 147 | cfy install -p pgaas-database.yaml -i inputs.yaml |
| 148 | |
| 149 | By default, the ``pgaas-database.yaml`` blueprint creates a database with the name ``sample``, which |
| 150 | can be overridden using ``database_name``. |
| 151 | |
| 152 | |
| 153 | :: |
Tony Hansen | 09c6a76 | 2017-10-30 18:52:57 +0000 | [diff] [blame] | 154 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 155 | cfy install -p pgaas-database.yaml -b pgaas-database-DBNAME -d pgaas-database-DBNAME -i inputs.yaml -i database_name=DBNAME |
| 156 | cfy install -p pgaas-database.yaml -b pgaas-database-CLNAME-DBNAME -d pgaas-database-CLNAME-DBNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME -i database_name=DBNAME |
| 157 | |
| 158 | |
| 159 | The ``pgaas-getdbinfo.yaml`` blueprint shows how an application can attach to an existing |
| 160 | database and access its attributes: |
| 161 | |
| 162 | :: |
Tony Hansen | 09c6a76 | 2017-10-30 18:52:57 +0000 | [diff] [blame] | 163 | |
Tony Hansen | 1c0b82f | 2017-10-17 19:09:16 +0000 | [diff] [blame] | 164 | cfy install -p pgaas-getdbinfo.yaml -d pgaas-getdbinfo -b pgaas-getdbinfo -i inputs.yaml |
| 165 | cfy deployments outputs -d pgaas-getdbinfo |
| 166 | cfy uninstall -d pgaas-getdbinfo |