diff --git a/Makefile b/Makefile index 702c20a38..bcd703d51 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,7 @@ # Copyright (C) 2018-2021 Ruohang Feng #==============================================================# +# the latest version of pigsty is 0.9 VERSION=0.9 # make default will pull up vm nodes @@ -31,7 +32,7 @@ install: # BUT if your meta node DOES NOT HAVE INTERNET ACCESS # You may have to copy/ftp/scp pkg.tgz & pigsty.tgz into meta node manually pkg: - bin/get_pkg + bin/get_pkg ${VERSION} # install ansible and init infrastructure meta: boot infra @@ -77,10 +78,11 @@ deps: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" brew install vagrant virtualbox ansible -# download pigsty resources (and copy to files/pkg.tgz ) +# download pigsty resources (to files/release/v*.*/{pkg,pigsty}.tgz) download: pkg - cp -f /tmp/pkg.tgz files/pkg.tgz - curl -fsSL https://pigsty.cc/pigsty.tgz -o files/pigsty.tgz + mkdir files/release/v${VERSION}/ + cp -f /tmp/pkg.tgz files/release/v${VERSION}/pkg.tgz + curl -fsSL https://pigsty.cc/pigsty.tgz -o files/release/v${VERSION}/pigsty.tgz # start will pull-up node and write ssh-config start: up ssh sync diff --git a/README.md b/README.md index 277ecb198..03a620bbd 100644 --- a/README.md +++ b/README.md @@ -2,44 +2,61 @@ > [PIGSTY](http://pigsty.cc): Postgres in Graphic STYle -[Pigsty](https://pigsty.cc/en/) is a **monitoring** system that is specially designed for large scale PostgreSQL clusters. Along with a production-grade HA PostgreSQL cluster **provisioning** solution. +[Pigsty](https://pigsty.cc/zh/) delivers the **BEST** open source **monitoring** solution for PostgreSQL. Along with the **easiest provisioning** solution for large scale proudction-grade database clusters. + +It can be used both for large-scale pg clusters management in real-world prod-env, and for launching battery-included single pg instance for dev & demo purpose in a simple and fast way. ![](img/logo.svg) -Check [official site](https://pigsty.cc/en/ ) for more information：https://pigsty.cc/en/ | 中文站点：[https://pigsty.cc/zh/](](https://pigsty.cc/zh/)) +Check [**OFFICIAL SITE**](https://pigsty.cc/en/ ) for more information：[**https://pigsty.cc/en/**](https://pigsty.cc/en/) | 中文站点：[**https://pigsty.cc/zh/**](](https://pigsty.cc/zh/)) -> The latest version of pigsty is [v0.8](https://github.com/Vonng/pigsty/releases/tag/v0.8.0). Under RC status with guaranteed API stability. +> The latest version of pigsty is [v0.9](https://github.com/Vonng/pigsty/releases/tag/v0.9.0). > -> The final 1.0 GA version will be released on 2021-06-01. +> The final 1.0 GA version will be released near June~July 2021 + + ## Highlights -* [Monitoring](#monitoring) System based on prometheus & grafana & [`pg_exporter`](https://github.com/Vonng/pg_exporter) +* [Monitoring]() System based on prometheus & grafana & [`pg_exporter`](https://github.com/Vonng/pg_exporter) * [Provisioning](#provisioning) Solution based on ansible. Kubernetes style, scale at ease. * [HA Deployment](#ha-deployment) based on patroni. Self-healing and failover in seconds * [Service Discovery](#service-discovery) based on DCS (consul / etcd), maintenance made easy. * [Offline Installation](#offline-installation) without Internet access. Fast and reliable. * Infrastructure as Code. Fully configurable and customizable. -* Based on PostgreSQL 13 and Patroni 2. Tested under CentOS 7 +* Based on PostgreSQL 13 and Patroni 2. Verified in proudction environment (CentOS 7, 200+nodes) ## Quick Start -If you already have [vagrant](https://www.vagrantup.com/), [virtualbox](https://www.virtualbox.org/) and [ansible](https://docs.ansible.com/) installed. Try local sandbox with one command. -Clone this repo. And run following commands under project directory, pigsty will setup everything for you. +Prepare a CentOS 7.x meta node with **ssh** & **root** access. ```bash -cd /tmp && git clone git@github.com:Vonng/pigsty.git && cd pigsty -make up # pull up all vagrant nodes -make ssh # setup vagrant ssh access -make init # init infrastructure and databaes clusters -sudo make dns # write static DNS record to your host (sudo required) -make mon-view # monitoring system home page (default: admin:admin) +curl -fsSL https://pigsty.cc/pigsty.tgz | gzip -d | tar -xC ~ && cd ~/pigsty # src code +bin/ipconfig # ipconfig +make pkg # download +make meta # launch ``` -> Verified Environment:: MacOS 11, Vagrant 2.2.14, Virtualbox 6.1.16 -Check [Quick Start](http://pigsty.cc/en/docs/sandbox/) for detailed steps and more information. +Check documentation for more information. + + + +> ## Get Node +> +> The easiest way to get a node is using cloud-services. But if you wish to run pigsty on your laptop. You can either create CentOS 7.8 vm nodes with software such as vmware, parallel desktop, virtualbox manually. Or just leave it to [vagrant](https://github.com/Vonng/pigsty/blob/master/vagrant/Vagrantfile). For MacOS users, these makefile shortcuts will setup a vm node (ip: 10.10.10.10) on your Mac host using [virtualbox](https://www.virtualbox.org/wiki/Downloads). After that everything is same as [Quick Start](#quick-start). +> +> ```bash +> cd /tmp && git clone git@github.com:Vonng/pigsty.git && cd pigsty +> make deps # Install MacOS deps with homebrew: vagrant virtualbox ansible +> make download # Download packages to files/release/v*.*/{pkg,pigsty}.tgz +> make start # launch vagrant vm nodes based on vagrant/Vagrantfile +> make dns # write static DNS record to your host (sudo required) +> make copy # copy pigsty resource to vagrant meta vm node +> ``` +> +> Verified Environment:: MacOS 11, Vagrant 2.2.14, Virtualbox 6.1.16 @@ -53,6 +70,8 @@ Pigsty provides a battery-included [Monitoring System](https://pigsty.cc/en/docs ![](img/overview2.jpg) + + ### Provisioning PostgreSQL cluster comes before monitoring system. That's why pigsty is shipping with a [Provisioning Solution](https://pigsty.cc/en/docs/concept/provision/). @@ -63,16 +82,24 @@ It allows you to create, update, scale, and manage your postgres cluster in kube vi pigsty.yml # edit configuration to define new clusters ./infra.yml # provision infrastructure on meta node ./pgsql.yml -l # provision new clusters/instasnces -./pgsql-remove.yml -l # remove clusters/instances ``` Here is an example base on vagrant 4-node demo. The default configuration file is [`pigsty.yml`](pigsty.yml) -This [Vagrantfile](vagrant/Vagrantfile) defines four nodes: `meta` , `node-1` , `node-2`, `node-3`. - -Check [Architecture Overview](https://pigsty.cc/en/docs/concepts/architecture/) for more information. +This [Vagrantfile](vagrant/Vagrantfile) defines four nodes: `meta` , `node-1` , `node-2`, `node-3`. Check [Architecture Overview](https://pigsty.cc/en/docs/concepts/architecture/) for more information. ![](img/infra.jpg) +And you can also mange cluster with pigsty [CLI](https://github.com/Vonng/pigsty-cli) & GUI (beta) + +
+Pigsty GUI (beta) + +![](img/gui.jpg) + +
+ + + ### High Availability Pigsty has HA Deployment powered by [Patroni 2.0](https://github.com/zalando/patroni). @@ -90,6 +117,9 @@ Each instance is **idempotent**, Pigsty uses a 'NodePort' approach to expose dif | default | 5436 | read-write/interactive | direct to primary 5432 | | offline | 5438 | read-only/interactive | direct to offline 5432 | + + + ### Infrastructure as Code Define infrastructure and new database clusters with declarative configurations. @@ -100,20 +130,14 @@ Creating a new database cluster `pg-test` with three nodes only require 6 lines pg-test: # - cluster members - # hosts: - 10.10.10.11: {pg_seq: 1, pg_role: primary, ansible_host: node-1} - 10.10.10.12: {pg_seq: 2, pg_role: replica, ansible_host: node-2} - 10.10.10.13: {pg_seq: 3, pg_role: offline, ansible_host: node-3} + 10.10.10.11: {pg_seq: 1, pg_role: primary} + 10.10.10.12: {pg_seq: 2, pg_role: replica} + 10.10.10.13: {pg_seq: 3, pg_role: offline} # - cluster config - # vars: { pg_cluster: pg-test } # cluster name ``` -And run [playbooks](https://pigsty.cc/en/docs/deploy/playbook/) to *instanlize* that cluster: - -```bash -./pgsql.yml -l pg-test -``` -
Complex One @@ -121,25 +145,41 @@ And run [playbooks](https://pigsty.cc/en/docs/deploy/playbook/) to *instanlize* #----------------------------- # cluster: pg-meta #----------------------------- +# pg-meta is a single-node pgsql cluster deployed on meta node (10.10.10.10) pg-meta: # - cluster members - # hosts: - 10.10.10.10: {pg_seq: 1, pg_role: primary, ansible_host: meta} + 10.10.10.10: {pg_seq: 1, pg_role: primary, pg_offline_query: true} # - cluster configs - # vars: pg_cluster: pg-meta # define actual cluster name pg_version: 13 # define installed pgsql version node_tune: tiny # tune node into oltp|olap|crit|tiny mode - pg_conf: tiny.yml # tune pgsql into oltp/olap/crit/tiny mode + pg_conf: tiny.yml # tune pgsql into oltp|olap|crit|tiny mode patroni_mode: pause # enter maintenance mode, {default|pause|remove} patroni_watchdog_mode: off # disable watchdog (require|automatic|off) pg_lc_ctype: en_US.UTF8 # enabled pg_trgm i18n char support + # - defining business users - # pg_users: - # complete example of user/role definition for production user - - name: dbuser_meta # example production user have read-write access - password: DBUser.Meta # example user's password, can be encrypted + # default production read-write user dbuser_meta + - name: dbuser_meta # user's name is required + password: md5d3d10d8cad606308bdb180148bf663e1 # md5 password is acceptable + pgbouncer: true # add user to pgbouncer userlist + roles: [dbrole_readwrite] # grant roles to user + comment: default production read-write user for meta database + + # default production read-only user for grafana direct access + - name: dbuser_grafana + password: DBUser.Grafana + pgbouncer: true + roles: [dbrole_readonly] + comment: default readonly access for grafana datasource + + # complete example of user/role definition + - name: dbuser_pigsty # pigsty user have admin access (DDL|DML) + password: DBUser.Pigsty # example user's password, can be md5 encrypted login: true # can login, true by default (should be false for role) superuser: false # is superuser? false by default createdb: false # can create database? false by default @@ -147,79 +187,97 @@ pg-meta: inherit: true # can this role use inherited privileges? replication: false # can this role do replication? false by default bypassrls: false # can this role bypass row level security? false by default - connlimit: -1 # connection limit, -1 disable limit - expire_at: '2030-12-31' # 'timestamp' when this role is expired - expire_in: 365 # now + n days when this role is expired (OVERWRITE expire_at) - roles: [dbrole_readwrite] # dborole_admin|dbrole_readwrite|dbrole_readonly pgbouncer: true # add this user to pgbouncer? false by default (true for production user) - parameters: # user's default search path - search_path: public - comment: test user - - # simple example for personal user definition - - name: dbuser_vonng # personal user example which only have limited access to offline instance - password: DBUser.Vonng # or instance with explict mark `pg_offline_query = true` - roles: [dbrole_offline] # personal/stats/ETL user should be grant with dbrole_offline - expire_in: 365 # expire in 365 days since creation - pgbouncer: false # personal user should NOT be allowed to login with pgbouncer - comment: example personal user for interactive queries - + connlimit: -1 # connection limit, -1 disable limit + expire_in: 3650 # now + n days when this role is expired (OVERWRITE expire_at) + expire_at: '2030-12-31' # 'timestamp' when this role is expired (OVERWRITTEN by expire_in) + comment: pigsty admin user # comment on user/role + roles: [dbrole_admin] # dbrole_{admin,readonly,readwrite,offline} + parameters: # additional role level parameters with ALTER ROLE SET + search_path: pigsty,public # add pigsty schema into search_path + + # - defining business databases - # pg_databases: - name: meta # name is the only required field for a database + baseline: metadb/schema.sql # pigsty meta database baseline owner: postgres # optional, database owner template: template1 # optional, template1 by default - encoding: UTF8 # optional, UTF8 by default , must same as template database, leave blank to set to db default - locale: C # optional, C by default , must same as template database, leave blank to set to db default - lc_collate: C # optional, C by default , must same as template database, leave blank to set to db default - lc_ctype: C # optional, C by default , must same as template database, leave blank to set to db default + encoding: UTF8 # optional, UTF8 by default , must same as template database, leave blank to set to db default + locale: C # optional, C by default , must same as template database, leave blank to set to db default + lc_collate: C # optional, C by default , must same as template database, leave blank to set to db default + lc_ctype: C # optional, C by default , must same as template database, leave blank to set to db default + tablespace: pg_default # optional, 'pg_default' is the default tablespace allowconn: true # optional, true by default, false disable connect at all revokeconn: false # optional, false by default, true revoke connect from public # (only default user and owner have connect privilege on database) - # tablespace: pg_default # optional, 'pg_default' is the default tablespace - connlimit: -1 # optional, connection limit, -1 or none disable limit (default) - extensions: # optional, extension name and where to create - - {name: postgis, schema: public} - parameters: # optional, extra parameters with ALTER DATABASE - enable_partitionwise_join: true pgbouncer: true # optional, add this database to pgbouncer list? true by default comment: pigsty meta database # optional, comment string for database + connlimit: -1 # optional, connection limit, -1 or none disable limit (default) + schemas: [pigsty] # optional, create additional schema + extensions: # optional, extension name and which schema to create + - {name: adminpack, schema: pg_catalog} + parameters: # optional, extra parameters with ALTER DATABASE + search_path: 'pigsty,public' # add pigsty to search_path + log_min_duration_statement: 10 # log all action on meta database pg_default_database: meta # default database will be used as primary monitor target - - # proxy settings - vip_mode: l2 # enable/disable vip (require members in same LAN) + vip_mode: l2 # none|l2|l4, l2 vip are used in sandbox demo vip_address: 10.10.10.2 # virtual ip address vip_cidrmask: 8 # cidr network mask length vip_interface: eth1 # interface to add virtual ip ``` + +And run [playbooks](https://pigsty.cc/en/docs/deploy/playbook/) to *instanlize* that cluster: + +```bash +./pgsql.yml -l pg-test +``` +
-There are 156 [parameters](http://pigsty.cc/en/docs/config/entry/) that controls every aspect of Pigsty. Check [configuration guide](https://pigsty.cc/en/docs/config/) for more detail. -| No | Category | Args | Function | -| :--: | :----------------------------------------------------------: | :--: | ------------------------------------------------------------ | -| 1 | [connect](http://pigsty.cc/en/docs/config/1-connect) | 1 | Connection parameters and proxy setting | -| 2 | [repo](http://pigsty.cc/en/docs/config/2-repo) | 10 | local yum and offline installation | -| 3 | [node](http://pigsty.cc/en/docs/config/3-node) | 29 | common setup for all nodes | -| 4 | [meta](http://pigsty.cc/en/docs/config/4-meta) | 21 | infrastructure on meta nodes | -| 5 | [dcs](http://pigsty.cc/en/docs/config/5-dcs) | 8 | dcs service (consul/etcd) | -| 6 | [pg-install](http://pigsty.cc/en/docs/config/6-pg-install) | 11 | install postgres, extensions, users, directories, scripts, utils | -| 7 | [pg-provision](http://pigsty.cc/en/docs/config/7-pg-provision) | 25 | bootstrap postgres cluster and identity assignment | -| 8 | [pg-template](http://pigsty.cc/en/docs/config/8-pg-template) | 19 | customize postgres cluster template | -| 9 | [monitor](http://pigsty.cc/en/docs/config/9-monitor) | 13 | install monitoring components | -| 10 | [service](http://pigsty.cc/en/docs/config/10-service) | 17 | expose database service | + +There are 160+ [parameters](http://pigsty.cc/en/docs/config/entry/) that controls every aspect of Pigsty. Check [configuration guide](https://pigsty.cc/en/docs/config/) for more information. + + +
+Configuration Entries + +| No | Category | Function | +| :--: | :----------------------------------------------------------: | ------------------------------------------------------------ | +| 1 | [connect](http://pigsty.cc/en/docs/config/1-connect) | Connection parameters and proxy setting | +| 2 | [repo](http://pigsty.cc/en/docs/config/2-repo) | local yum and offline installation | +| 3 | [node](http://pigsty.cc/en/docs/config/3-node) | common setup for all nodes | +| 4 | [meta](http://pigsty.cc/en/docs/config/4-meta) | infrastructure on meta nodes | +| 5 | [dcs](http://pigsty.cc/en/docs/config/5-dcs) | dcs service (consul/etcd) | +| 6 | [pg-install](http://pigsty.cc/en/docs/config/6-pg-install) | install postgres, extensions, users, directories, scripts, utils | +| 7 | [pg-provision](http://pigsty.cc/en/docs/config/7-pg-provision) | bootstrap postgres cluster and identity assignment | +| 8 | [pg-template](http://pigsty.cc/en/docs/config/8-pg-template) | customize postgres cluster template | +| 9 | [monitor](http://pigsty.cc/en/docs/config/9-monitor) | install monitoring components | +| 10 | [service](http://pigsty.cc/en/docs/config/10-service) | expose database service | + + +
### Service Discovery -Pigsty is integrated with [Service Discovery](https://pigsty.cc/en/docs/concept/monitor/identity/) based on DCS (consul/etcd). All service are automatically register to DCS. Which eliminate lots of manual maintenance work. And you can check health status about all nodes and service in an intuitive way. +Pigsty is integrated with [Service Discovery](https://pigsty.cc/en/docs/concept/monitor/identity/) based on DCS (consul/etcd). All service are automatically register to DCS. Which eliminate lots of manual maintenance work. And you can check health status about all nodes and service in an intuitive way. -Consul is the only DCS that is supported (etcd will be added further). You can use consul as DNS service provider to achieve DNS based traffic routing. +
+Consul SD Implementation + +Consul is the only DCS that is currently supported. You can use consul as DNS service provider to achieve DNS based traffic routing. ![](img/service-discovery.jpg) +Pigsty can also use static file discovery for prometheus, which would eliminate the need of consul for monitoring. + +
+ + ### Offline Installation @@ -241,13 +299,13 @@ Pigsty comes with a local Yum repo that includes all required packages and its d **Minimal setup** -* Self-contained single node, singleton database `pg-meta` +* Self-contained, single meta node, singleton pgsql cluster `pg-meta` * Minimal requirement: 1 CPU Core & 2 GB RAM -**Standard setup ( TINY mode, vagrant demo)** +**Demo setup ( TINY mode, vagrant demo)** -* 4 Node, including single meta node, singleton database cluster `pg-meta` and 3-instances database cluster `pg-test` -* Recommend Spec: 2Core/4GB for meta controller node, 1Core/1GB for database node +* 4 Node, including single meta node, singleton database cluster `pg-meta` and 3-instances pgsql cluster `pg-test` +* Spec: 2Core/4GB for meta controller node, 1Core/1GB for database node (x3) **Production setup (OLTP/OLAP/CRIT mode)** @@ -257,6 +315,7 @@ Pigsty comes with a local Yum repo that includes all required packages and its d + ## Support [Business Support](https://pigsty.cc/en/docs/business/) for pigsty is available. diff --git a/img/gui.jpg b/img/gui.jpg new file mode 100644 index 000000000..27e46758e Binary files /dev/null and b/img/gui.jpg differ