blob: 080e57573094edfdd9254ab850bdc4de6e8c8cbc [file] [log] [blame]
Lusheng Jibd115742017-10-13 19:18:52 +00001PostgreSQL as a Service
2============
Tony Hansen30c453e2017-10-13 14:34:46 +00003
Tony Hansenca734622017-11-01 22:02:10 +00004PostgreSQL as a Service (PGaaS) comes in two flavors: all-in-one blueprint, and
Tony Hansen30c453e2017-10-13 14:34:46 +00005separate disk/cluster/database blueprints to separate the management of
6the lifetime of those constituent parts. Both are provided for use.
7
Tony Hansenca734622017-11-01 22:02:10 +00008Why Three Flavors?
Lusheng Jibd115742017-10-13 19:18:52 +00009------------
Tony Hansen30c453e2017-10-13 14:34:46 +000010
Tony Hansenca734622017-11-01 22:02:10 +000011The reason there are three flavors of blueprints lays in the difference in
12lifetime management of the constituent parts and the number of VMs created.
Tony Hansen30c453e2017-10-13 14:34:46 +000013
14For example, a database usually needs to have persistent storage, which
15in these blueprints comes from Cinder storage volumes. The primitives
16used in these blueprints assume that the lifetime of the Cinder storage
17volumes matches the lifetime of the blueprint deployment. So when the
18blueprint goes away, any Cinder storage volume allocated in the
19blueprint also goes away.
20
Tony Hansen8c558972017-10-17 18:14:52 +000021Similarly, a database's lifetime may be the same time as an application's
22lifetime. When the application is undeployed, the associated database should
23be deployed too. OR, the database should have a lifetime beyond the scope
24of the applications that are writing to it or reading from it.
Tony Hansen30c453e2017-10-13 14:34:46 +000025
Tony Hansen1c0b82f2017-10-17 19:09:16 +000026Blueprint Files
Tony Hansen8c558972017-10-17 18:14:52 +000027------------
Tony Hansen30c453e2017-10-13 14:34:46 +000028
Tony Hansen1c0b82f2017-10-17 19:09:16 +000029The Blueprints for PG Services and Cinder
30^^^^^^^^^^^
31
Tony Hansenca734622017-11-01 22:02:10 +000032The all-in-one blueprint ``pgaas.yaml`` assumes that the PG servers and Cinder volumes can be allocated and
33deallocated together. The ``pgaas.yaml`` blueprint creates a cluster of two VMs named "``pstg``" by default.
Tony Hansen8c558972017-10-17 18:14:52 +000034
Tony Hansenca734622017-11-01 22:02:10 +000035The ``pgaas-onevm.yaml`` blueprint creates a single-VM instance named "``pgvm``" by default.
36
37Alternatively, you can split them apart into separate steps, using ``pgaas-disk.yaml`` to allocate the
38Cinder 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 Hansen8c558972017-10-17 18:14:52 +000040redeployed without affecting the data on the Cinder volumes.
41
42The Blueprints for Databases
Tony Hansen1c0b82f2017-10-17 19:09:16 +000043^^^^^^^^^^^
Tony Hansen8c558972017-10-17 18:14:52 +000044
Tony Hansenca734622017-11-01 22:02:10 +000045The ``pgaas-database.yaml`` blueprint shows how a database can be created separately from any application
46that uses it. That database will remain present until the pgaas-database.yaml blueprint is
47undeployed. The ``pgaas-getdbinfo.yaml`` file demonstrates how an application would access the credentials
Tony Hansen8c558972017-10-17 18:14:52 +000048needed to access a given database on a given PostgreSQL cluster.
49
50If the lifetime of your database is tied to the lifetime of your application, use a block similar to what
Tony Hansenca734622017-11-01 22:02:10 +000051is in ``pgaas-database.yaml`` to allocate the database, and use the attributes as shown in ``pgaas-getdbinfo.yaml``
Tony Hansen8c558972017-10-17 18:14:52 +000052to access the credentials.
Tony Hansen1c0b82f2017-10-17 19:09:16 +000053
Tony Hansenca734622017-11-01 22:02:10 +000054Both of these blueprints use the ``dcae.nodes.pgaas.database`` plugin reference, but ``pgaas-getdbinfo.yaml``
55adds the ``use_existing: true`` property.
56
Tony Hansen1c0b82f2017-10-17 19:09:16 +000057
58What is Created by the Blueprints
59^^^^^^^^^^^^
60
61Each PostgreSQL cluster has a name, represented below as ``${CLUSTER}`` or ``CLNAME``. Each cluster is created
62with two VMs, one VM used for the writable master and the other as a cascaded read-only secondary.
63
64
65There are two DNS A records added, ``${LOCATIONPREFIX}${CLUSTER}00.${LOCATIONDOMAIN}`` and
66``${LOCATIONPREFIX}${CLUSTER}01.${LOCATIONDOMAIN}``. In addition,
67there are two CNAME entries added:
68``${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN} ``
69and
70``${LOCATIONPREFIX}-${CLUSTER}.${LOCATIONDOMAIN}``. The CNAME
71``${LOCATIONPREFIX}-${CLUSTER}-write.${LOCATIONDOMAIN}`` will be used by further
72blueprints to create and attach to databases.
73
74
75Parameters
76------------
77
78The blueprints are designed to run using the standard inputs file used for all of the blueprints,
79plus several additional parameters that are given reasonable defaults.
80
81How to Run
82------------
83
84
85
86To install the PostgreSQL as a Service
87^^^^^^^^^^^^
88
89Installing the all-in-one blueprint is straightforward:
90
91::
92
93 cfy install -p pgaas.yaml -i inputs.yaml
94
95By default, the all-in-one blueprint creates a cluster by the name ``pstg``.
96
97You can override that name using another ``-i`` option.
98(When overriding the defaults, it is also best to explicitly
99set the -b and -d names.)
100
101::
Tony Hansen09c6a762017-10-30 18:52:57 +0000102
Tony Hansen1c0b82f2017-10-17 19:09:16 +0000103 cfy install -p pgaas.yaml -b pgaas-CLNAME -d pgaas-CLNAME -i inputs.yaml -i pgaas_cluster_name=CLNAME
104
105
106Separating out the disk allocation from the service creation requires using two blueprints:
107
108::
Tony Hansen09c6a762017-10-30 18:52:57 +0000109
Tony Hansen1c0b82f2017-10-17 19:09:16 +0000110 cfy install -p pgaas-disk.yaml -i inputs.yaml
111 cfy install -p pgaas-cluster.yaml -i inputs.yaml
112
113By default, these blueprints create a cluster named ``pgcl``, which can be overridden the same
114way as shown above:
115
116::
Tony Hansen09c6a762017-10-30 18:52:57 +0000117
Tony Hansen1c0b82f2017-10-17 19:09:16 +0000118 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
122You must use the same pgaas_cluster_name for the two blueprints to work together.
123
124For the disk, you can also specify a ``cinder_volume_size``, as in ``-i cinder_volume_size=1000``
125for 1TiB volume. (There is no need to override the ``-b`` and ``-d`` names when changing the
126volume size.)
127
128
129You can verify that the cluster is up and running by connecting to the PostgreSQL service
Tony Hansenb32a0b62017-10-25 11:53:09 +0000130on port 5432. To verify that all of the DNS names were created properly and that PostgreSQL is
131answering on port 5432, you can use something like this:
Tony Hansen1c0b82f2017-10-17 19:09:16 +0000132
133::
Tony Hansen09c6a762017-10-30 18:52:57 +0000134
Tony Hansenb32a0b62017-10-25 11:53:09 +0000135 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 Hansen1c0b82f2017-10-17 19:09:16 +0000140
141Once you have the cluster created, you can then allocate databases. An application that
142wants a persistent database not tied to the lifetime of the application blueprint can
143use the ``pgaas-database.yaml`` blueprint to create the database;
144
145::
Tony Hansen09c6a762017-10-30 18:52:57 +0000146
Tony Hansen1c0b82f2017-10-17 19:09:16 +0000147 cfy install -p pgaas-database.yaml -i inputs.yaml
148
149By default, the ``pgaas-database.yaml`` blueprint creates a database with the name ``sample``, which
150can be overridden using ``database_name``.
151
152
153::
Tony Hansen09c6a762017-10-30 18:52:57 +0000154
Tony Hansen1c0b82f2017-10-17 19:09:16 +0000155 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
159The ``pgaas-getdbinfo.yaml`` blueprint shows how an application can attach to an existing
160database and access its attributes:
161
162::
Tony Hansen09c6a762017-10-30 18:52:57 +0000163
Tony Hansen1c0b82f2017-10-17 19:09:16 +0000164 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