diff --git a/docs/index.rst b/docs/index.rst index 18a4350..b9e9031 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,6 +9,7 @@ Salt Extension for interacting with Apache Zookeeper :hidden: topics/installation + topics/configuration .. toctree:: :maxdepth: 2 diff --git a/docs/topics/configuration.md b/docs/topics/configuration.md new file mode 100644 index 0000000..dc6760a --- /dev/null +++ b/docs/topics/configuration.md @@ -0,0 +1,54 @@ +(zookeeper-setup)= +# Configuration +This Salt extension requires configuration, either in the minion's config file or via the Pillar. + +## Basic +```yaml +zookeeper: + hosts: zoo1,zoo2,zoo3 + default_acl: + - username: daniel + password: test + read: true + write: true + create: true + delete: true + admin: true + username: daniel + password: test +``` + +## Multiple environments +If configuration for multiple zookeeper environments is required, they can +be set up as different configuration profiles. For example: + +```yaml +zookeeper: + prod: + hosts: zoo1,zoo2,zoo3 + default_acl: + - username: daniel + password: test + read: true + write: true + create: true + delete: true + admin: true + username: daniel + password: test + dev: + hosts: + - dev1 + - dev2 + - dev3 + default_acl: + - username: daniel + password: test + read: true + write: true + create: true + delete: true + admin: true + username: daniel + password: test +``` diff --git a/src/saltext/zookeeper/modules/zk_concurrency.py b/src/saltext/zookeeper/modules/zk_concurrency.py index 7f11e7c..217d754 100644 --- a/src/saltext/zookeeper/modules/zk_concurrency.py +++ b/src/saltext/zookeeper/modules/zk_concurrency.py @@ -1,12 +1,12 @@ """ Concurrency controls in zookeeper -========================================================================= +================================= -:depends: kazoo -:configuration: See :py:mod:`salt.modules.zookeeper` for setup instructions. +.. important:: + This module requires the general :ref:`Zookeeper setup `. This module allows you to acquire and release a slot. This is primarily useful -for ensureing that no more than N hosts take a specific action at once. This can +for ensuring that no more than N hosts take a specific action at once. This can also be used to coordinate between masters. """ diff --git a/src/saltext/zookeeper/modules/zookeeper.py b/src/saltext/zookeeper/modules/zookeeper.py index f1d8dfb..187c6f6 100644 --- a/src/saltext/zookeeper/modules/zookeeper.py +++ b/src/saltext/zookeeper/modules/zookeeper.py @@ -1,73 +1,12 @@ """ -Zookeeper Module -~~~~~~~~~~~~~~~~ -:maintainer: SaltStack -:maturity: new -:platform: all -:depends: kazoo - -.. versionadded:: 2018.3.0 - -Configuration -============= - -:configuration: This module is not usable until the following are specified - either in a pillar or in the minion's config file: - - .. code-block:: yaml - - zookeeper: - hosts: zoo1,zoo2,zoo3 - default_acl: - - username: daniel - password: test - read: true - write: true - create: true - delete: true - admin: true - username: daniel - password: test - - If configuration for multiple zookeeper environments is required, they can - be set up as different configuration profiles. For example: - - .. code-block:: yaml - - zookeeper: - prod: - hosts: zoo1,zoo2,zoo3 - default_acl: - - username: daniel - password: test - read: true - write: true - create: true - delete: true - admin: true - username: daniel - password: test - dev: - hosts: - - dev1 - - dev2 - - dev3 - default_acl: - - username: daniel - password: test - read: true - write: true - create: true - delete: true - admin: true - username: daniel - password: test +Interface with a Zookeeper service. + +.. important:: + This module requires the general :ref:`Zookeeper setup `. """ -# Import Salt libraries import salt.utils.stringutils -# Import python libraries try: import kazoo.client import kazoo.security diff --git a/src/saltext/zookeeper/states/zk_concurrency.py b/src/saltext/zookeeper/states/zk_concurrency.py index 9ed3c82..ac2c68c 100644 --- a/src/saltext/zookeeper/states/zk_concurrency.py +++ b/src/saltext/zookeeper/states/zk_concurrency.py @@ -2,9 +2,8 @@ Control concurrency of steps within state execution using zookeeper =================================================================== -:depends: kazoo -:configuration: See :py:mod:`salt.modules.zookeeper` for setup instructions. - +.. important:: + This module requires the general :ref:`Zookeeper setup `. This module allows you to "wrap" a state's execution with concurrency control. This is useful to protect against all hosts executing highstate simultaneously @@ -16,6 +15,11 @@ called it will coordinate with zookeeper to ensure that no more than max_concurrency steps are executing with a single path. +Example +------- +This example would allow the file state to change, but would limit the +concurrency of the trafficserver service restart to 4. + .. code-block:: yaml acquire_lock: @@ -40,9 +44,6 @@ - name: /trafficserver - require: - service: trafficserver - -This example would allow the file state to change, but would limit the -concurrency of the trafficserver service restart to 4. """ # TODO: use depends decorator to make these per function deps, instead of all or nothing diff --git a/src/saltext/zookeeper/states/zookeeper.py b/src/saltext/zookeeper/states/zookeeper.py index 46bdc10..670ccaf 100644 --- a/src/saltext/zookeeper/states/zookeeper.py +++ b/src/saltext/zookeeper/states/zookeeper.py @@ -1,30 +1,42 @@ """ -Zookeeper State +Manage Zookeeper znodes and ACLs statefully. -:depends: kazoo -:configuration: See :py:mod:`salt.modules.zookeeper` for setup instructions. +.. important:: + This module requires the general :ref:`Zookeeper setup `. -ACLS -~~~~ +ACLs +---- -For more information about acls, please checkout the kazoo documentation. +For more information about ACLs, please checkout the kazoo documentation. -http://kazoo.readthedocs.io/en/latest/api/security.html#kazoo.security.make_digest_acl +https://kazoo.readthedocs.io/en/latest/api/security.html#kazoo.security.make_digest_acl +.. _acl-dicts: + +ACL dictionaries +~~~~~~~~~~~~~~~~ The following options can be included in the acl dictionary: - :param username: Username to use for the ACL. - :param password: A plain-text password to hash. - :param write: Write permission. - :type write: bool - :param create: Create permission. - :type create: bool - :param delete: Delete permission. - :type delete: bool - :param admin: Admin permission. - :type admin: bool - :param all: All permissions. - :type all: bool +username + Username to use for the ACL. + +password + A plain-text password to hash. + +write [bool] + Write permission. + +create [bool] + Create permission. + +delete [bool] + Delete permission. + +admin [bool] + Admin permission. + +all [bool] + All permissions. """ __virtualname__ = "zookeeper"