From 6a4f0b56a18aea3a5699eec20819200152f34a47 Mon Sep 17 00:00:00 2001 From: Kevin Carter Date: Fri, 7 Jun 2019 20:48:40 -0500 Subject: [PATCH] Add basic role skeleton and doc it A basic skeleton and molecule has been added to the project which should assist folks looking to contribute roles to the effort. The basic skeleton will initialize the all new roles to test with molecule and provides access to a simple interface develoeprs can leverage to add new roles into the project. A minimal implementation of sphinx docs has been added to the project in support of the new role skeleton. Change-Id: I7a0fea87226b73b72b40e831922183a527ce901a Signed-off-by: Kevin Carter --- _skeleton_role_/README.md | 29 +++++++ _skeleton_role_/defaults/main.yml.j2 | 21 +++++ .../roles => _skeleton_role_/files}/.gitkeep | 0 _skeleton_role_/handlers/main.yml | 15 ++++ _skeleton_role_/meta/main.yml.j2 | 44 ++++++++++ .../molecule/default/Dockerfile.j2 | 37 ++++++++ _skeleton_role_/molecule/default/molecule.yml | 48 +++++++++++ .../molecule/default/playbook.yml.j2 | 21 +++++ _skeleton_role_/molecule/default/prepare.yml | 21 +++++ _skeleton_role_/molecule/default/verify.yml | 15 ++++ _skeleton_role_/tasks/main.yml | 32 +++++++ _skeleton_role_/vars/main.yml | 22 +++++ doc/source/conf.py | 85 +++++++++++++++++++ doc/source/contributing.rst | 10 +++ doc/source/index.rst | 21 +++++ doc/source/installation.rst | 16 ++++ doc/source/usage.rst | 7 ++ 17 files changed, 444 insertions(+) create mode 100644 _skeleton_role_/README.md create mode 100644 _skeleton_role_/defaults/main.yml.j2 rename {tripleo_ansible/roles => _skeleton_role_/files}/.gitkeep (100%) create mode 100644 _skeleton_role_/handlers/main.yml create mode 100644 _skeleton_role_/meta/main.yml.j2 create mode 100644 _skeleton_role_/molecule/default/Dockerfile.j2 create mode 100644 _skeleton_role_/molecule/default/molecule.yml create mode 100644 _skeleton_role_/molecule/default/playbook.yml.j2 create mode 100644 _skeleton_role_/molecule/default/prepare.yml create mode 100644 _skeleton_role_/molecule/default/verify.yml create mode 100644 _skeleton_role_/tasks/main.yml create mode 100644 _skeleton_role_/vars/main.yml create mode 100755 doc/source/conf.py create mode 100644 doc/source/contributing.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/installation.rst create mode 100644 doc/source/usage.rst diff --git a/_skeleton_role_/README.md b/_skeleton_role_/README.md new file mode 100644 index 000000000..51675fb1b --- /dev/null +++ b/_skeleton_role_/README.md @@ -0,0 +1,29 @@ +Role Name +========= + +A brief description of the role goes here. + + +Requirements +------------ + +Any pre-requisites that may not be covered by Ansible itself or the role should +be mentioned here. + + +Role Variables +-------------- + +A description of the settable variables for this role should go here, including +any variables that are in defaults/main.yml, vars/main.yml, and any variables +that can/should be set via parameters to the role. Any variables that are read +from other roles and/or the global scope (ie. hostvars, group vars, etc.) +should be mentioned here as well. + + +Dependencies +------------ + +A list of other roles hosted on Galaxy should go here, plus any details in +regards to parameters that may need to be set for other roles, or variables +that are used from other roles. diff --git a/_skeleton_role_/defaults/main.yml.j2 b/_skeleton_role_/defaults/main.yml.j2 new file mode 100644 index 000000000..686551500 --- /dev/null +++ b/_skeleton_role_/defaults/main.yml.j2 @@ -0,0 +1,21 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + + +# All variables intended for modification should place placed in this file. + +# All variables within this role should have a prefix of "{{ role_name }}" +{{ role_name }}_debug: false diff --git a/tripleo_ansible/roles/.gitkeep b/_skeleton_role_/files/.gitkeep similarity index 100% rename from tripleo_ansible/roles/.gitkeep rename to _skeleton_role_/files/.gitkeep diff --git a/_skeleton_role_/handlers/main.yml b/_skeleton_role_/handlers/main.yml new file mode 100644 index 000000000..dfd4c7352 --- /dev/null +++ b/_skeleton_role_/handlers/main.yml @@ -0,0 +1,15 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. diff --git a/_skeleton_role_/meta/main.yml.j2 b/_skeleton_role_/meta/main.yml.j2 new file mode 100644 index 000000000..5d53d3bba --- /dev/null +++ b/_skeleton_role_/meta/main.yml.j2 @@ -0,0 +1,44 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + + +galaxy_info: + author: OpenStack + description: TripleO OpenStack Role -- {{ role_name }} + company: Red Hat + license: Apache-2.0 + min_ansible_version: 2.7 + # + # Provide a list of supported platforms, and for each platform a list of versions. + # If you don't wish to enumerate all versions for a particular platform, use 'all'. + # To view available platforms and versions (or releases), visit: + # https://galaxy.ansible.com/api/v1/platforms/ + # + platforms: + - name: Fedora + versions: + - 28 + - name: CentOS + versions: + - 7 + + galaxy_tags: + - tripleo + + +# List your role dependencies here, one per line. Be sure to remove the '[]' above, +# if you add dependencies to this list. +dependencies: [] diff --git a/_skeleton_role_/molecule/default/Dockerfile.j2 b/_skeleton_role_/molecule/default/Dockerfile.j2 new file mode 100644 index 000000000..4475353b9 --- /dev/null +++ b/_skeleton_role_/molecule/default/Dockerfile.j2 @@ -0,0 +1,37 @@ +# Molecule managed +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +{% raw %} +{% if item.registry is defined %} +FROM {{ item.registry.url }}/{{ item.image }} +{% else %} +FROM {{ item.image }} +{% endif %} + +RUN if [ $(command -v apt-get) ]; then apt-get update && apt-get install -y python sudo bash ca-certificates && apt-get clean; \ + elif [ $(command -v dnf) ]; then dnf makecache && dnf --assumeyes install python sudo python-devel python*-dnf bash {{ item.pkg_extras | default('') }} && dnf clean all; \ + elif [ $(command -v yum) ]; then yum makecache fast && yum install -y python sudo yum-plugin-ovl python-setuptools bash {{ item.pkg_extras | default('') }} && sed -i 's/plugins=0/plugins=1/g' /etc/yum.conf && yum clean all; \ + elif [ $(command -v zypper) ]; then zypper refresh && zypper install -y python sudo bash python-xml {{ item.pkg_extras | default('') }} && zypper clean -a; \ + elif [ $(command -v apk) ]; then apk update && apk add --no-cache python sudo bash ca-certificates {{ item.pkg_extras | default('') }}; \ + elif [ $(command -v xbps-install) ]; then xbps-install -Syu && xbps-install -y python sudo bash ca-certificates {{ item.pkg_extras | default('') }} && xbps-remove -O; fi + +{% for pkg in item.easy_install | default([]) %} +# install pip for centos where there is no python-pip rpm in default repos +RUN easy_install {{ pkg }} +{% endfor %} +{% endraw %} + +CMD ["sh", "-c", "while true; do sleep 10000; done"] diff --git a/_skeleton_role_/molecule/default/molecule.yml b/_skeleton_role_/molecule/default/molecule.yml new file mode 100644 index 000000000..3a32890d4 --- /dev/null +++ b/_skeleton_role_/molecule/default/molecule.yml @@ -0,0 +1,48 @@ +--- +driver: + name: docker + +log: true + +platforms: + - name: centos7 + hostname: centos7 + image: centos:7 + dockerfile: Dockerfile + pkg_extras: python-setuptools + easy_install: + - pip + environment: &env + http_proxy: "{{ lookup('env', 'http_proxy') }}" + https_proxy: "{{ lookup('env', 'https_proxy') }}" + + - name: fedora28 + hostname: fedora28 + image: fedora:28 + dockerfile: Dockerfile + pkg_extras: python*-setuptools + environment: + <<: *env + +provisioner: + name: ansible + log: true + env: + ANSIBLE_STDOUT_CALLBACK: yaml + +scenario: + test_sequence: + - destroy + - create + - prepare + - converge + - verify + - destroy + +lint: + enabled: false + +verifier: + name: testinfra + lint: + name: flake8 diff --git a/_skeleton_role_/molecule/default/playbook.yml.j2 b/_skeleton_role_/molecule/default/playbook.yml.j2 new file mode 100644 index 000000000..8d823ecb6 --- /dev/null +++ b/_skeleton_role_/molecule/default/playbook.yml.j2 @@ -0,0 +1,21 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + + +- name: Converge + hosts: all + roles: + - role: "{{ role_name }}" diff --git a/_skeleton_role_/molecule/default/prepare.yml b/_skeleton_role_/molecule/default/prepare.yml new file mode 100644 index 000000000..ef85c3128 --- /dev/null +++ b/_skeleton_role_/molecule/default/prepare.yml @@ -0,0 +1,21 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + + +- name: Prepare + hosts: all + roles: + - role: test_deps diff --git a/_skeleton_role_/molecule/default/verify.yml b/_skeleton_role_/molecule/default/verify.yml new file mode 100644 index 000000000..dfd4c7352 --- /dev/null +++ b/_skeleton_role_/molecule/default/verify.yml @@ -0,0 +1,15 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. diff --git a/_skeleton_role_/tasks/main.yml b/_skeleton_role_/tasks/main.yml new file mode 100644 index 000000000..749bfdfe4 --- /dev/null +++ b/_skeleton_role_/tasks/main.yml @@ -0,0 +1,32 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + + +# "{{ role_name }}" will search for and load any operating system variable file +# found within the "vars/" path. If no OS files are found the task will skip. +- name: Gather variables for each operating system + include_vars: "{{ item }}" + with_first_found: + - skip: true + files: + - "{{ ansible_distribution | lower }}-{{ ansible_distribution_version | lower }}.yml" + - "{{ ansible_distribution | lower }}-{{ ansible_distribution_major_version | lower }}.yml" + - "{{ ansible_os_family | lower }}-{{ ansible_distribution_major_version | lower }}.yml" + - "{{ ansible_distribution | lower }}.yml" + - "{{ ansible_os_family | lower }}-{{ ansible_distribution_version.split('.')[0] }}.yml" + - "{{ ansible_os_family | lower }}.yml" + tags: + - always diff --git a/_skeleton_role_/vars/main.yml b/_skeleton_role_/vars/main.yml new file mode 100644 index 000000000..d4719abd0 --- /dev/null +++ b/_skeleton_role_/vars/main.yml @@ -0,0 +1,22 @@ +--- +# Copyright 2019 Red Hat, Inc. +# All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + + +# While options found within the vars/ path can be overridden using extra +# vars, items within this path are considered part of the role and not +# intended to be modified. + +# All variables within this role should have a prefix of "{{ role_name }}" diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 000000000..90a094cdb --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +# Add the project +sys.path.insert(0, os.path.abspath('../..')) +# Add the extensions +sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts')) + +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'openstackdocstheme', + 'sphinx.ext.autodoc', + 'workbooks' +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'tripleo-ansible' +copyright = u'2013, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project +html_theme = 'openstackdocs' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +# intersphinx_mapping = {'http://docs.python.org/': None} + +# openstackdocstheme options +repository_name = 'openstack/tripleo-ansible' +bug_project = 'tripleo' +bug_tag = 'documentation' diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 000000000..899c59208 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,10 @@ +============ +Contributing +============ + +Adding roles into this project is easy and starts with a compatible skeleton. + + +From with the project root, creating a skeleton for the new role:: + + $ ansible-galaxy init --role-skeleton=_skeleton_role_ --init-path=tripleo_ansible/roles NEWROLENAME diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..69bfff7f2 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,21 @@ +.. tripleo-ansible documentation master file, created by + sphinx-quickstart on Tue Jun 7 22:26:36 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to tripleo-ansible's documentation! +=========================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + installation + contributing + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 000000000..ffceaef0c --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,16 @@ +============ +Installation +============ + +At the command line:: + + $ pip install tripleo-ansible + +Or, if you have virtualenvwrapper installed:: + + $ python -m virtualenv tripleo-ansible + $ pip install tripleo-ansible + +Or, using the package manager:: + + $ yum install tripleo-ansible diff --git a/doc/source/usage.rst b/doc/source/usage.rst new file mode 100644 index 000000000..1e1c94022 --- /dev/null +++ b/doc/source/usage.rst @@ -0,0 +1,7 @@ +===== +Usage +===== + +Once the tripleo ansible project has been installed navigate to the share path, +usually `/usr/share/ansible` path to access the installed roles, playbooks, and +libraries.