{"id":19249255,"url":"https://github.com/sous-chefs/percona","last_synced_at":"2025-04-05T15:07:43.473Z","repository":{"id":43825109,"uuid":"2051489","full_name":"sous-chefs/percona","owner":"sous-chefs","description":"Development repository for the percona cookbook","archived":false,"fork":false,"pushed_at":"2024-02-01T01:09:15.000Z","size":1277,"stargazers_count":118,"open_issues_count":4,"forks_count":199,"subscribers_count":26,"default_branch":"main","last_synced_at":"2024-04-14T08:47:35.496Z","etag":null,"topics":["chef","chef-cookbook","chef-resource","hacktoberfest","managed-by-terraform","percona"],"latest_commit_sha":null,"homepage":"https://supermarket.chef.io/cookbooks/percona","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sous-chefs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"open_collective":"sous-chefs"}},"created_at":"2011-07-15T05:00:42.000Z","updated_at":"2023-11-27T04:25:14.000Z","dependencies_parsed_at":"2024-01-15T05:09:37.314Z","dependency_job_id":"ea8567a4-d85d-4171-971a-235d362a96e0","html_url":"https://github.com/sous-chefs/percona","commit_stats":{"total_commits":804,"total_committers":101,"mean_commits":7.96039603960396,"dds":0.6256218905472637,"last_synced_commit":"b20af2b8086cc0b56f59a5a9cc6ccc02c3cb2c8b"},"previous_names":[],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fpercona","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fpercona/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fpercona/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fpercona/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sous-chefs","download_url":"https://codeload.github.com/sous-chefs/percona/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353745,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chef","chef-cookbook","chef-resource","hacktoberfest","managed-by-terraform","percona"],"created_at":"2024-11-09T18:13:25.783Z","updated_at":"2025-04-05T15:07:43.443Z","avatar_url":"https://github.com/sous-chefs.png","language":"Ruby","funding_links":["https://opencollective.com/sous-chefs"],"categories":[],"sub_categories":[],"readme":"# Percona Cookbook\n\n[![Cookbook Version](https://img.shields.io/cookbook/v/percona.svg)](https://supermarket.chef.io/cookbooks/percona)\n[![OpenCollective](https://opencollective.com/sous-chefs/backers/badge.svg)](#backers)\n[![OpenCollective](https://opencollective.com/sous-chefs/sponsors/badge.svg)](#sponsors)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)\n\n## Description\n\nInstalls the [Percona MySQL](http://www.percona.com/software/percona-server) client and/or\nserver components. (We are attempting to leverage the Sous-Chefs\nMySQL cookbook as much as possible.)\n\nOptionally installs:\n\n- [XtraBackup](https://www.percona.com/software/mysql-database/percona-xtrabackup) hot backup software\n- [Percona Toolkit](https://www.percona.com/software/database-tools/percona-toolkit) advanced command-line tools\n- [XtraDB Cluster](https://www.percona.com/software/mysql-database/percona-xtradb-cluster) high availability and high scalability solution for MySQL.\n\n## Maintainers\n\nThis cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit [sous-chefs.org](https://sous-chefs.org/) or come chat with us on the Chef Community Slack in [#sous-chefs](https://chefcommunity.slack.com/messages/C2V7B88SF).\n\n## Requirements\n\n### Supported Platforms\n\nWe provide an expanding set of tests against the following 64-bit platforms which match what upstream supports:\n\n- CentOS 7+\n- Debian 10+\n- Ubuntu 18.04+ LTS\n\n### Cookbooks\n\n- [yum-epel](https://supermarket.chef.io/cookbooks/yum-epel)\n- [line](https://supermarket.chef.io/cookbooks/line)\n\n### Chef\n\nThis cookbook requires Chef \u003e= 16.\n\n## Recipes\n\n- `percona` - The default which includes the client recipe.\n- `percona::package_repo` - Sets up the package repository and installs common packages.\n- `percona::client` - Installs the Percona MySQL client libraries.\n- `percona::server` - Installs and configures the Percona MySQL server daemon.\n- `percona::backup` - Installs and configures the Percona XtraBackup hot backup software.\n- `percona::toolkit` - Installs the Percona Toolkit software\n- `percona::cluster` - Installs the Percona XtraDB Cluster server components\n- `percona::configure_server` - Used internally to manage the server configuration.\n- `percona::replication` - Used internally to grant permissions for replication.\n- `percona::access_grants` - Used internally to grant permissions for recipes.\n- `percona::ssl` - Used internally to setup ssl certificates for server/client.\n\n## Resources\n\n- [`percona_mysql_user`](https://github.com/sous-chefs/percona/blob/master/documentation/resource_percona_mysql_user.md)\n- [`percona_mysql_database`](https://github.com/sous-chefs/percona/blob/master/documentation/resource_percona_mysql_database.md)\n\n## Usage\n\nThis cookbook installs the Percona MySQL components if not present, and pulls updates if they are installed on the\nsystem.\n\nThis cookbook uses inclusion terminology where applicable replacing terms such as ``master/slave`` to ``source/replica``\nwhich matches the [terminology decided upstream](https://mysqlhighavailability.com/mysql-terminology-updates/). Older\nreleases of Percona still use the terms in their configuration so those will remain, however we will be using the newer\nterms with attributes, property and variable names.  Currently both terms should work however the next major release of\nthis cookbook will only use the new terminology.\n\n### Encrypted Passwords\n\nThis cookbook requires [Encrypted Data Bags](https://docs.chef.io/secrets/#encrypt-a-data-bag-item). If you forget to use them or do not use a node attribute to overwrite them empty passwords will be used.\n\nTo use encrypted passwords, you must create an encrypted data bag. This cookbook assumes a data bag named `passwords`, but you can override the name using the `node['percona']['encrypted_data_bag']` attribute.  You can also optionally specify a data bag secret file to be loaded for the secret key using the `node['percona']['encrypted_data_bag_secret_file']` attribute.\n\nThis cookbook expects a `mysql` item  and a `system` item. Please refer to the official documentation on how to get this setup. It actually uses a MySQL example so it can be mostly copied. Ensure you cover the data bag items as described below.\n\nYou also may set expected item names via attributes `node['percona']['encrypted_data_bag_item_mysql']` and `node['percona']['encrypted_data_bag_item_system']`.\n\n### Skip passwords\n\nSet the `['percona']['skip_passwords']` attribute to skip setting up passwords. Removes the need for the encrypted data bag if using chef-solo. Is useful for setting up development and ci environments where you just want to use the root user with no password. If you are doing this you may want to set `['percona']['server']['debian_username']` to be `\"root\"` also.\n\n### Skip Configure\n\nSet the `['percona']['skip_configure']` attribute to skip having the server recipe include the configure\\_server recipe directly after install. This is mostly useful in a wrapper cookbook sort of context. Once skipped, you can then perform any pre-config actions your wrapper needs to, such as dropping a custom configuration file or init script or cleaning up incorrectly sized innodb logfiles. You can then include configure\\_server where necessary.\n\n#### mysql item\n\nThe mysql item should contain entries for root, backup, and replication. If no value is found, the cookbook will fall back to the default non-encrypted password.\n\n#### system item\n\nThe \"system\" item should contain an entry for the debian system user as specified in the `node['percona']['server']['debian_username']` attribute. If no such entry is found, the cookbook will fall back to the default non-encrypted password.\n\nExample: \"passwords\" data bag - this example assumes that `node['percona']['server']['debian_username'] = spud`\n\n```javascript\n{\n  \"mysql\" :\n  {\n    \"root\" : \"trywgFA6R70NO28PNhMpGhEvKBZuxouemnbnAUQsUyo=\\n\"\n    \"backup\" : \"eqoiudfj098389fjadfkadf=\\n\"\n    \"replication\" : \"qwo0fj0213fm9020fm2023fjsld=\\n\"\n  },\n  \"system\" :\n  {\n    \"spud\" : \"dwoifm2340f024jfadgfu243hf2=\\n\"\n  }\n}\n```\n\nAbove shows the encrypted password in the data bag. Check out the `encrypted_data_bag_secret` setting in `knife.rb` to setup your data bag secret during bootstrapping.\n\n### Install client development package\n\nTo install the package including header files needed to compile software using the client library (`percona-server-devel` on Centos and `libperconaserverclient-dev` on Debian), set `node['percona']['client']['install_devel_package']` to `true`. This will add those packages to the list to be installed when running the `percona::client` recipe. This attribute is disabled by default.\n\n### Replication over SSL\n\nTo enable SSL based replication, you will need to flip the attribute `node['percona']['server']['replication']['ssl_enabled']` to `true` and add a new data\\_bag item\nto the percona encrypted data\\_bag (see`node['percona']['encrypted_data_bag']` attribute) with the id `ssl_replication` ( see `node['percona']['encrypted_data_bag_item_ssl_replication']` attribute) that contains this data:\n\n```javascript\n{\n  \"id\": \"ssl_replication\",\n  \"ca-cert\": \"CA_CERTIFICATE_STRING\",\n  \"server\": {\n    \"server-cert\": \"SERVER_CERTIFICATE_STRING\",\n    \"server-key\": \"SERVER_KEY_STRING\"\n  },\n  \"client\": {\n    \"client-cert\": \"CLIENT_CERTIFICATE_STRING\",\n    \"client-key\": \"CLIENT_KEY_STRING\"\n  }\n}\n```\n\nAll certificates and keys have to be converted to a string (easiest way is to use ruby: `/usr/bin/env ruby -e 'p ARGF.read' \u003cfilename\u003e`) and placed\ninstead of CA_CERTIFICATE_STRING, SERVER_CERTIFICATE_STRING, SERVER_KEY_STRING, CLIENT_CERTIFICATE_STRING, CLIENT_KEY_STRING.\n\n### Percona XtraDB Cluster\n\nBelow is a minimal example setup to bootstrap a Percona XtraDB Cluster. Please see the [official documentation](https://www.percona.com/doc/percona-xtradb-cluster/8.0/index.html) for more information. This is not a perfect example. It is just a sample to get you started.\n\nWrapper recipe recipes/percona.rb:\n\n```ruby\n# Setup the Percona XtraDB Cluster\ncluster_ips = []\nunless Chef::Config[:solo]\n  search(:node, 'role:percona').each do |other_node|\n    next if other_node['private_ipaddress'] == node['private_ipaddress']\n    Chef::Log.info \"Found Percona XtraDB cluster peer: #{other_node['private_ipaddress']}\"\n    cluster_ips \u003c\u003c other_node['private_ipaddress']\n  end\nend\n\ncluster_ips.each do |ip|\n  firewall_rule \"allow Percona group communication to peer #{ip}\" do\n    source ip\n    port 4567\n    action :allow\n  end\n\n  firewall_rule \"allow Percona state transfer to peer #{ip}\" do\n    source ip\n    port 4444\n    action :allow\n  end\n\n  firewall_rule \"allow Percona incremental state transfer to peer #{ip}\" do\n    source ip\n    port 4568\n    action :allow\n  end\nend\n\ncluster_address = \"gcomm://#{cluster_ips.join(',')}\"\nChef::Log.info \"Using Percona XtraDB cluster address of: #{cluster_address}\"\nnode.override['percona']['cluster']['wsrep_cluster_address'] = cluster_address\nnode.override['percona']['cluster']['wsrep_node_name'] = node['hostname']\n\ninclude_recipe 'percona::cluster'\ninclude_recipe 'percona::backup'\ninclude_recipe 'percona::toolkit'\n```\n\nExample percona role roles/percona.rb:\n\n```ruby\nname \"percona\"\ndescription \"Percona XtraDB Cluster\"\n\nrun_list 'recipe[paydici::percona]'\n\ndefault_attributes(\n  \"percona\" =\u003e {\n    \"server\" =\u003e {\n      \"role\" =\u003e \"cluster\"\n    },\n\n    \"cluster\" =\u003e {\n      \"package\"                     =\u003e \"percona-xtradb-cluster-56\",\n      \"wsrep_cluster_name\"          =\u003e \"percona_cluster_1\",\n      \"wsrep_sst_receive_interface\" =\u003e \"eth1\" # can be eth0, public, private, etc.\n    }\n  }\n)\n```\n\nNow you need to bring three servers up one at a time with the percona role applied to them. By default the servers will sync up via rsync server state transfer (SST)\n\n## Explicit my.cnf templating\n\nIn some situations it is preferable to explicitly define the attributes needed in a `my.cnf` file. This is enabled by adding categories to the `node['percona']['conf']` attributes. All keys found in the `node['percona']['conf']` map will represent categories in the `my.cnf` file. Each category contains a map of attributes that will be written to the `my.cnf` file for that category. See the example for more details.\n\n### Example\n\n```ruby\nnode['percona']['conf']['mysqld']['slow_query_log_file'] = \"/var/lib/mysql/data/mysql-slow.log\"\n```\n\nThis configuration would write the `mysqld` category to the `my.cnf` file and have an attribute `slow_query_log_file` whose value would be `/var/lib/mysql/data/mysql-slow.log`.\n\n### Example output (my.cnf)\n\n```ini\n[mysqld]\nslow_query_log_file = /var/lib/mysql/data/mysql-slow.log\n```\n\n## Dynamically setting the bind address\n\nThere's a special attribute `node['percona']['server']['bind_to']` that allows you to dynamically set the bind address. This attribute accepts the values `\"public_ip\"`, `\"private_ip\"`, `\"loopback\"`, or and interface name like `\"eth0\"`. Based on this, the recipe will find a corresponding ipv4 address, and override the `node['percona']['server']['bind_address']` attribute.\n\n## Goals\n\nIn no particular order:\n\n- Be the most flexible way to setup a MySQL distribution through Chef\n  - Support for Chef Solo\n  - Support for Chef Server\n- Support the following common database infrastructures:\n  - Single server instance\n  - Traditional Source/Replica replication\n  - Multi-source cluster replication\n- Support the most recent Chef runtime environments\n- Be the easiest way to setup a MySQL distribution through Chef\n\n## TODO\n\n- Fully support all of the standard Chef-supported distributions\n\n## Contributing\n\n- Fork it\n- Create your feature branch (`git checkout -b my-new-feature`)\n- Commit your changes (`git commit -am 'Added some feature'`)\n- Push to the branch (`git push origin my-new-feature`)\n- Create new Pull Request\n\n## Contributors\n\nThis project exists thanks to all the people who [contribute.](https://opencollective.com/sous-chefs/contributors.svg?width=890\u0026button=false)\n\n### Backers\n\nThank you to all our backers!\n\n![https://opencollective.com/sous-chefs#backers](https://opencollective.com/sous-chefs/backers.svg?width=600\u0026avatarHeight=40)\n\n### Sponsors\n\nSupport this project by becoming a sponsor. Your logo will show up here with a link to your website.\n\n![https://opencollective.com/sous-chefs/sponsor/0/website](https://opencollective.com/sous-chefs/sponsor/0/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/1/website](https://opencollective.com/sous-chefs/sponsor/1/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/2/website](https://opencollective.com/sous-chefs/sponsor/2/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/3/website](https://opencollective.com/sous-chefs/sponsor/3/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/4/website](https://opencollective.com/sous-chefs/sponsor/4/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/5/website](https://opencollective.com/sous-chefs/sponsor/5/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/6/website](https://opencollective.com/sous-chefs/sponsor/6/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/7/website](https://opencollective.com/sous-chefs/sponsor/7/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/8/website](https://opencollective.com/sous-chefs/sponsor/8/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/9/website](https://opencollective.com/sous-chefs/sponsor/9/avatar.svg?avatarHeight=100)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Fpercona","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsous-chefs%2Fpercona","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Fpercona/lists"}