README.rst

cookiecutter-salt-formula
=========================

A cookiecutter template for Salt Formula.

Installation
============

.. code-block:: bash

    pip install cookiecutter

    cd cookiecutter

    cookiecutter salt-formula

Procedure of Data model and Schemas validation.
===============================

run_tests.sh script is able to validate data model by schemas and test pillars.
It supports versioned and unversioned schemas and pillars. Schemas and pillars must contains yaml format.

Unversioned items must be avaible in:

.. code-block:: text

    {FORMULA_NAME}/{FORMULA_NAME}/schemas/
    {FORMULA_NAME}/tests/pillar/

Versioned items must be avaible in:

.. code-block:: text

    {FORMULA_NAME}/{FORMULA_NAME}/schemas/{version}/
    {FORMULA_NAME}/tests/pillar/{version}/

You can run run_tests.sh  by following command:

.. code-block:: shell

    # cd <formula repository>
    ./tests/run_tests.sh

You can run run_tests.sh which inlude schema validation if schemas present by following command:

.. code-block:: shell

    # cd <formula repository>
    ./tests/run_tests.sh model-validate

Example schemas:

.. code-block:: yaml

    %YAML 1.1
    ---
    "$schema": "http://json-schema.org/draft-06/schema#"
    title: {{cookiecutter.service_name}} daemon role
    description: |
      {{cookiecutter.service_name|capitalize}} daemon, server role
    type: object
    additionalProperties: false

    required:
      - enabled

    properties:
      enabled:
        description: |
          Enables {{cookiecutter.service_name}} daemon service
        type: boolean

Example pillar:

.. code-block:: yaml
    {{cookiecutter.service_name}}:
      {{cookiecutter.role_name}}:
        enabled: true

You can read more about it here:
    http://json-schema.org/implementations.html
    http://github.com/Julian/jsonschema

Init Test Kitchen configuration
===============================

Follow the `salt formula testing <https://salt-formulas.readthedocs.io/en/latest/develop/testing-formulas.html>`_ guidelines and
automated CI in the main `documentation <https://salt-formulas.readthedocs.io/en/latest/develop/testing.html>`_.

To generate ``.kitchen.yml`` for new or existing project:

- install `envtpl`, renders jinja2 templates with shell environment variables
- install required gems, it depends on drivers configured to be used (docker by default)

.. code-block:: shell

    pip install envtpl
    gem install kitchen-docker kitchen-salt [kitchen-openstack kitchen-vagrant kitchen-inspec busser-serverspec]

Once you create your `tests/pillar` structure (required if you want to auto-populate kitchen yaml with test suites)

.. code-block:: shell

    # cd <formula repository>
    ../kitchen-init.sh

Instantly, to add kitchen configuration into existing repository:

.. code-block:: shell

    # cd <formula repository>
    curl -skL "https://raw.githubusercontent.com/salt-formulas/cookiecutter-salt-formula/master/kitchen-init.sh" | bash -s --


Docker way
===============================

.. code-block:: bash

    MY_NEW_SALT_FORMULA_DIR="watchdog"
    mkdir $MY_NEW_SALT_FORMULA_DIR
    git clone https://github.com/salt-formulas/cookiecutter-salt-formula.git
    docker run --rm -it -u $(id -u):$(id -g) --env HOME=/$MY_NEW_SALT_FORMULA_DIR -v $PWD/$MY_NEW_SALT_FORMULA_DIR:/$MY_NEW_SALT_FORMULA_DIR -v $PWD/cookiecutter-salt-formula:/cookiecutter-salt-formula:ro cookiecutter/cookiecutter /cookiecutter-salt-formula --output-dir /$MY_NEW_SALT_FORMULA_DIR
    service_name [some_service]: watchdog
    role_name [server]:
    initial_version [2018.1]:
    copyright_year [2018]:
    copyright_holder [Your Name et al.]: Mirantis, Inc.
    author_name [John Doe]: Petr Ruzicka
    author_contact [jdoe@domain.com]: pruzicka@mirantis.com
    homepage [https://github.com/salt-formulas]:
    debian_version [xenial]:
    kitchen_driver [docker]:
    kitchen_verifier [inspec]:
    kitchen_formula [watchdog]:
    kitchen_suites []: server