From 1dca54c838b759eab1ae7c49871e2bba85dae06c Mon Sep 17 00:00:00 2001 From: Alex Schultz Date: Tue, 29 May 2018 11:26:41 -0600 Subject: [PATCH] Fix readme for package The previous readme contained formatting issues for pypi which prevents publishing. This change moves the old readme to the docs page and simplifies the main README. Change-Id: I0bee3951c8c5d7a8d5650c8cfdbf40e9ba6734fc Related-Bug: #1774001 --- README.md | 84 ------------------------------------------ doc/source/readme.rst | 86 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 85 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index cacb294..02f6bbb 100644 --- a/README.md +++ b/README.md @@ -21,87 +21,3 @@ knowledge of the elements within diskimage-builder and tripleo-image-elements. An example of higher level tooling that uses instack to install a TripleO style undercloud is at: https://github.com/rdo-management/instack-undercloud - -Usage ------ - -Use the command line arguments for fine grained control over which elements to -apply, or drive instack via a declarative style json file (see -https://github.com/openstack/instack-undercloud/blob/master/json-files/centos-7-undercloud-packages.json -for an example). - -Be aware that most elements are not idempotent. Subsequent runs of instack with the same set of elements -will often fail due to things files and directories already existing. One way around this is to write a clean up -element for your environment that cleans up before a run early in pre-install.d, and then always -include that element when you run instack. - -

-usage: instack [-h] [-e [ELEMENT [ELEMENT ...]]]
-               [-p ELEMENT_PATH [ELEMENT_PATH ...]] [-k [HOOK [HOOK ...]]]
-               [-b [BLACKLIST [BLACKLIST ...]]]
-               [-x [EXCLUDE_ELEMENT [EXCLUDE_ELEMENT ...]]] [-j JSON_FILE]
-               [-d] [-i] [--dry-run] [--no-cleanup]
-
-Execute diskimage-builder elements on the current system.
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -e [ELEMENT [ELEMENT ...]], --element [ELEMENT [ELEMENT ...]]
-                        element(s) to execute
-  -p ELEMENT_PATH [ELEMENT_PATH ...], --element-path ELEMENT_PATH [ELEMENT_PATH ...]
-                        element path(s) to search for elements (ELEMENTS_PATH
-                        environment variable will take precedence if defined)
-  -k [HOOK [HOOK ...]], --hook [HOOK [HOOK ...]]
-                        hook(s) to execute for each element
-  -b [BLACKLIST [BLACKLIST ...]], --blacklist [BLACKLIST [BLACKLIST ...]]
-                        script names, that if found, will be blacklisted and
-                        not run
-  -x [EXCLUDE_ELEMENT [EXCLUDE_ELEMENT ...]], --exclude-element [EXCLUDE_ELEMENT [EXCLUDE_ELEMENT ...]]
-                        element names that will be excluded from running even
-                        if they are listed as dependencies
-  -j JSON_FILE, --json-file JSON_FILE
-                        read runtime configuration from json file
-  -d, --debug           Debugging output
-  -i, --interactive     If set, prompt to continue running after a failed
-                        script.
-  --dry-run             Dry run only, don't actually modify system, prints out
-                        what would have been run.
-  --no-cleanup          Do not cleanup tmp directories
-
- -Setup ------ - -1. Make sure you have pip and git installed. If using your distro's pip, make you have at least pip version 1.5. There's a bug in older versions that causes some files to not be installed +x, which is a requirement for element hook scripts. To use upstream pip, see: http://www.pip-installer.org/en/latest/installing.html - -1. git clone this repository - - git clone https://github.com/rdo-management/instack - -1. pip install the cloned instack - - pushd instack && sudo pip install -e . && popd - -1. pip install diskimage-builder and tripleo-image-elements - - sudo pip install diskimage-builder tripleo-image-elements -If you so choose, you can use these from their git repositories instead: - - git clone https://git.openstack.org/openstack/diskimage-builder - git clone https://git.openstack.org/openstack/tripleo-image-elements - pushd diskimage-builder && sudo pip install . && popd - pushd tripleo-image-elements && sudo pip install . && popd - -Example Uses ------------- - -On Fedora, apply the keystone and mariadb element: - -

-sudo -E instack \
-    -p /usr/share/tripleo-image-elements /usr/share/diskimage-builder/elements \
-    -e fedora base keystone mariadb \
-    -k extra-data pre-install install post-install \
-    -b 15-remove-grub 10-cloud-init 05-fstab-rootfs-label
-
- diff --git a/doc/source/readme.rst b/doc/source/readme.rst index 6b2b3ec..8416370 100644 --- a/doc/source/readme.rst +++ b/doc/source/readme.rst @@ -1 +1,85 @@ -.. include:: ../README.rst \ No newline at end of file +.. include:: ../../README.md + +Usage +----- + +Use the command line arguments for fine grained control over which elements to +apply, or drive instack via a declarative style json file (see +https://github.com/openstack/instack-undercloud/blob/master/json-files/centos-7-undercloud-packages.json +for an example). + +Be aware that most elements are not idempotent. Subsequent runs of instack with the same set of elements +will often fail due to things files and directories already existing. One way around this is to write a clean up +element for your environment that cleans up before a run early in pre-install.d, and then always +include that element when you run instack. + +

+usage: instack [-h] [-e [ELEMENT [ELEMENT ...]]]
+               [-p ELEMENT_PATH [ELEMENT_PATH ...]] [-k [HOOK [HOOK ...]]]
+               [-b [BLACKLIST [BLACKLIST ...]]]
+               [-x [EXCLUDE_ELEMENT [EXCLUDE_ELEMENT ...]]] [-j JSON_FILE]
+               [-d] [-i] [--dry-run] [--no-cleanup]
+
+Execute diskimage-builder elements on the current system.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -e [ELEMENT [ELEMENT ...]], --element [ELEMENT [ELEMENT ...]]
+                        element(s) to execute
+  -p ELEMENT_PATH [ELEMENT_PATH ...], --element-path ELEMENT_PATH [ELEMENT_PATH ...]
+                        element path(s) to search for elements (ELEMENTS_PATH
+                        environment variable will take precedence if defined)
+  -k [HOOK [HOOK ...]], --hook [HOOK [HOOK ...]]
+                        hook(s) to execute for each element
+  -b [BLACKLIST [BLACKLIST ...]], --blacklist [BLACKLIST [BLACKLIST ...]]
+                        script names, that if found, will be blacklisted and
+                        not run
+  -x [EXCLUDE_ELEMENT [EXCLUDE_ELEMENT ...]], --exclude-element [EXCLUDE_ELEMENT [EXCLUDE_ELEMENT ...]]
+                        element names that will be excluded from running even
+                        if they are listed as dependencies
+  -j JSON_FILE, --json-file JSON_FILE
+                        read runtime configuration from json file
+  -d, --debug           Debugging output
+  -i, --interactive     If set, prompt to continue running after a failed
+                        script.
+  --dry-run             Dry run only, don't actually modify system, prints out
+                        what would have been run.
+  --no-cleanup          Do not cleanup tmp directories
+
+ +Setup +----- + +1. Make sure you have pip and git installed. If using your distro's pip, make you have at least pip version 1.5. There's a bug in older versions that causes some files to not be installed +x, which is a requirement for element hook scripts. To use upstream pip, see: http://www.pip-installer.org/en/latest/installing.html + +1. git clone this repository + + git clone https://github.com/rdo-management/instack + +1. pip install the cloned instack + + pushd instack && sudo pip install -e . && popd + +1. pip install diskimage-builder and tripleo-image-elements + + sudo pip install diskimage-builder tripleo-image-elements +If you so choose, you can use these from their git repositories instead: + + git clone https://git.openstack.org/openstack/diskimage-builder + git clone https://git.openstack.org/openstack/tripleo-image-elements + pushd diskimage-builder && sudo pip install . && popd + pushd tripleo-image-elements && sudo pip install . && popd + +Example Uses +------------ + +On Fedora, apply the keystone and mariadb element: + +

+sudo -E instack \
+    -p /usr/share/tripleo-image-elements /usr/share/diskimage-builder/elements \
+    -e fedora base keystone mariadb \
+    -k extra-data pre-install install post-install \
+    -b 15-remove-grub 10-cloud-init 05-fstab-rootfs-label
+
+