From 939055eff0cafabce97025a65b99a5284bf21c20 Mon Sep 17 00:00:00 2001 From: Pino Toscano Date: Wed, 29 Apr 2015 18:41:30 +0200 Subject: [PATCH] Improvements to README.rst of elements Improve the formatting of README.rst of elements: - proper syntax for bash snippets - improve list formatting - use list definitions for environment variariables - remove the explicit bash usage from diskimage-create.sh invocations - wrap lines at 80 characters - various small text formattings Change-Id: I93b4c35b31dac66af22663b2cec426a08fa73bd8 --- elements/apt-mirror/README.rst | 11 ++++-- elements/centos-mirror/README.rst | 11 ++++-- elements/disable-firewall/README.rst | 9 ++--- elements/extjs/README.rst | 34 ++++++++++--------- elements/fedora-mirror/README.rst | 11 ++++-- elements/hadoop-cloudera/README.rst | 13 ++++++-- elements/hadoop-hdp/README.rst | 31 ++++++++++++----- elements/hadoop-mapr/README.rst | 32 +++++++++++++----- elements/hadoop/README.rst | 50 ++++++++++++++++------------ elements/hive/README.rst | 18 ++++++++-- elements/mysql/README.rst | 6 ++-- elements/oozie/README.rst | 2 +- elements/root-passwd/README.rst | 7 ++++ elements/spark/README.rst | 29 ++++++++++++---- elements/ssh/README.rst | 2 +- elements/swift_hadoop/README.rst | 15 ++++++++- 16 files changed, 200 insertions(+), 81 deletions(-) diff --git a/elements/apt-mirror/README.rst b/elements/apt-mirror/README.rst index cd6553fb..0454cc88 100644 --- a/elements/apt-mirror/README.rst +++ b/elements/apt-mirror/README.rst @@ -2,5 +2,12 @@ apt-mirror ========== -This element setups mirror for updating Ubuntu cloud image. Using mirror increases speed of building image. -You should specify http url for Ubuntu mirror using parameter 'UBUNTU_MIRROR'. +This element sets up the mirror for updating the Ubuntu cloud image. +Using a mirror improves the speed of the image building. + +Environment Variables +--------------------- + +UBUNTU_MIRROR + :Required: Yes + :Description: URL to the Ubuntu mirror. diff --git a/elements/centos-mirror/README.rst b/elements/centos-mirror/README.rst index 588a9139..242d00e3 100644 --- a/elements/centos-mirror/README.rst +++ b/elements/centos-mirror/README.rst @@ -2,5 +2,12 @@ centos-mirror ============= -This element setups mirror for updating CentOS cloud image. Using mirror increases speed of building image. -You should specify http url for CentOS mirror using parameter 'CENTOS_MIRROR'. +This element sets up the mirror for updating the CentOS cloud image. +Using a mirror improves the speed of the image building. + +Environment Variables +--------------------- + +CENTOS_MIRROR + :Required: Yes + :Description: URL to the CentOS mirror. diff --git a/elements/disable-firewall/README.rst b/elements/disable-firewall/README.rst index ce1af0ea..b5e2df69 100644 --- a/elements/disable-firewall/README.rst +++ b/elements/disable-firewall/README.rst @@ -4,7 +4,8 @@ disable-firewall This elements disables all firewalls on the image. -Recognized firewalls - - . iptables - . ip6tables - . firewalld +Recognized firewalls: + + - iptables + - ip6tables + - firewalld diff --git a/elements/extjs/README.rst b/elements/extjs/README.rst index 21388b84..2a4cec8c 100644 --- a/elements/extjs/README.rst +++ b/elements/extjs/README.rst @@ -5,24 +5,26 @@ extjs This element downloads extjs from its website, caching it so it is not downloaded every time, and optionally unpacking it. -Configuration -------------- +Environment Variables +--------------------- The element can be configured by exporting variables using a -`environment.d` script; variables with ``*`` are mandatory: +`environment.d` script. -* EXTJS\_DESTINATION\_DIR ``*`` +EXTJS_DESTINATION_DIR + :Required: Yes + :Description: The directory where to extract (or copy) extjs; must be + an absolute directory within the image. The directory is created if not + existing already. + :Example: ``EXTJS_DESTINATION_DIR=/usr/share/someapp`` - The directory where to extract (or copy) extjs. Mandatory, must be - an absolute directory within the image, e.g. ``/usr/share/someapp``. - The directory is created if not existing already. +EXTJS_DOWNLOAD_URL + :Required: No + :Default: ``http://dev.sencha.com/deploy/ext-2.2.zip`` + :Description: The URL from where to download extjs. -* EXTJS\_DOWNLOAD\_URL - - The URL from where to download extjs. Defaults to - ``http://dev.sencha.com/deploy/ext-2.2.zip``. - -* EXTJS\_NO\_UNPACK - - If set to 1, then the extjs tarball is simply copied to the location - specified by EXTJS\_DESTINATION\_DIR. +EXTJS_NO_UNPACK + :Required: No + :Default: *unset* + :Description: If set to 1, then the extjs tarball is simply copied to the + location specified by ``EXTJS_DESTINATION_DIR``. diff --git a/elements/fedora-mirror/README.rst b/elements/fedora-mirror/README.rst index d75ce7d7..c6dd54f0 100644 --- a/elements/fedora-mirror/README.rst +++ b/elements/fedora-mirror/README.rst @@ -2,5 +2,12 @@ fedora-mirror ============= -This element setups mirror for updating Fedora cloud image. Using mirror increases speed of building image. -You should specify http url for Fedora mirror using parameter 'FEDORA_MIRROR'. +This element sets up the mirror for updating the Fedora cloud image. +Using a mirror improves the speed of the image building. + +Environment Variables +--------------------- + +FEDORA_MIRROR + :Required: Yes + :Description: URL to the Fedora mirror. diff --git a/elements/hadoop-cloudera/README.rst b/elements/hadoop-cloudera/README.rst index 530fbf98..4cb0ab46 100644 --- a/elements/hadoop-cloudera/README.rst +++ b/elements/hadoop-cloudera/README.rst @@ -2,10 +2,17 @@ hadoop-cloudera =============== -Installs cloudera (cloudera-manager-agent cloudera-manager-daemons cloudera-manager-server cloudera-manager-server-db-2 hadoop-hdfs-namenode hadoop-hdfs-secondarynamenode hadoop-hdfs-datanode hadoop-yarn-resourcemanager hadoop-yarn-nodemanager hadoop-mapreduce hadoop-mapreduce-historyserver) and java (oracle-j2sdk1.7) packages from cloudera repositories `cdh5 `_ and `cm5 `_. +Installs cloudera (cloudera-manager-agent cloudera-manager-daemons +cloudera-manager-server cloudera-manager-server-db-2 hadoop-hdfs-namenode +hadoop-hdfs-secondarynamenode hadoop-hdfs-datanode hadoop-yarn-resourcemanager +hadoop-yarn-nodemanager hadoop-mapreduce hadoop-mapreduce-historyserver) and +Java (oracle-j2sdk1.7) packages from cloudera repositories +`cdh5 `_ and +`cm5 `_. -In order to create the Cloudera images with the diskimage-create.sh script, use the following syntax to select the "cloudera" plugin: +In order to create the Cloudera images with ``diskimage-create.sh``, use the +following syntax to select the ``cloudera`` plugin: .. sourcecode:: bash - sudo bash diskimage-create.sh -p cloudera + diskimage-create.sh -p cloudera diff --git a/elements/hadoop-hdp/README.rst b/elements/hadoop-hdp/README.rst index f9e4583f..4316b5d9 100644 --- a/elements/hadoop-hdp/README.rst +++ b/elements/hadoop-hdp/README.rst @@ -4,19 +4,34 @@ hadoop-hdp Installs the JDK, the Hortonworks Data Platform, and Apache Ambari. -Please set the DIB_HDP_VERSION environment variable to configure the install to use a given version. The default script (mentioned below) sets this variable for each supported version. +Currently, the following versions of the Hortonworks Data Platform are +supported for image building: -Currently, the following versions of the Hortonworks Data Platform are supported for image building: - -1.3 -2.0 + - 1.3 + - 2.0 The following script: -sahara-image-elements/diskimage-create/diskimage-create.sh +.. code:: bash -is the default script to use for creating CentOS images with HDP installed/configured. This script can be used without modification, or can be used as an example to describe how a more customized script may be created with the "hadoop-hdp" diskimage-builder element. + diskimage-create/diskimage-create.sh -In order to create the HDP images with the diskimage-create.sh script, use the following syntax to select the "hdp" plugin: +is the default script to use for creating CentOS images with HDP +installed/configured. This script can be used without modification, or can +be used as an example to describe how a more customized script may be created +with the ``hadoop-hdp`` element. + +In order to create the HDP images with ``diskimage-create.sh``, use the +following syntax to select the ``hdp`` plugin: + +.. code:: bash diskimage-create.sh -p hdp + +Environment Variables +--------------------- + +DIB_HDP_VERSION + :Required: Yes + :Description: Version of the Hortonworks Data Platform to install. + :Example: ``DIB_HDP_VERSION=2.0`` diff --git a/elements/hadoop-mapr/README.rst b/elements/hadoop-mapr/README.rst index 884fb362..e24d5b89 100644 --- a/elements/hadoop-mapr/README.rst +++ b/elements/hadoop-mapr/README.rst @@ -2,24 +2,38 @@ hadoop-mapr =========== -Creates images with local mirrors of MapR repositories: `core `_ and `ecosystem `_. -Installs `OpenJDK `_ and `Scala `_. +Creates images with local mirrors of MapR repositories: +`core `_ and +`ecosystem `_. +Installs `OpenJDK `_ and +`Scala `_. + +In order to create the MapR images with ``diskimage-create.sh``, use the +following syntax to select the ``MapR`` plugin: -In order to create the MapR images with the diskimage-create.sh script, use the following syntax to select the "MapR" plugin: .. sourcecode:: bash - bash diskimage-create.sh -p mapr [-i ubuntu|centos] [-r 3.1.1|4.0.1|4.0.2] + diskimage-create.sh -p mapr [-i ubuntu|centos] [-r 3.1.1|4.0.1|4.0.2] -NOTE: By default MapR 4.0.1 version will be used - -In order to speed up image creation process you can download archives with MapR repositories and specify environment variable: -``DIB_MAPR_CORE_DEB_REPO``, ``DIB_MAPR_CORE_RPM_REPO``, ``DIB_MAPR_ECO_DEB_REPO``, ``DIB_MAPR_ECO_RPM_REPO`` +In order to speed up image creation process you can download archives with MapR +repositories and specify environment variables: +``DIB_MAPR_CORE_DEB_REPO``, ``DIB_MAPR_CORE_RPM_REPO``, +``DIB_MAPR_ECO_DEB_REPO``, ``DIB_MAPR_ECO_RPM_REPO``. For example: + .. sourcecode:: bash export DIB_MAPR_CORE_DEB_REPO="file:///mapr-v4.0.1GA.deb.tgz" export DIB_MAPR_CORE_RPM_REPO="file:///mapr-v4.0.1GA.rpm.tgz" export DIB_MAPR_ECO_DEB_REPO="http:///mapr-ecosystem.deb.tgz" export DIB_MAPR_ECO_RPM_REPO="http:///mapr-ecosystem.rpm.tgz" - bash diskimage-create.sh -p mapr -r 4.0.1 + diskimage-create.sh -p mapr -r 4.0.1 + +Environment Variables +--------------------- + +DIB_MAPR_VERSION + :Required: Yes + :Description: Version of MapR to install. + :Example: ``DIB_MAPR_VERSION=4.0.1`` diff --git a/elements/hadoop/README.rst b/elements/hadoop/README.rst index 3e6da21d..561570c2 100644 --- a/elements/hadoop/README.rst +++ b/elements/hadoop/README.rst @@ -2,27 +2,35 @@ hadoop ====== -Installs Java and Hadoop, configures SSH -======================================== +Installs Java and Hadoop, configures SSH. HOWTO build Hadoop Native Libs ------------------------------ -+ Install: *jdk >= 6*, *maven*, *cmake* and *protobuf >= 2.5.0* -+ Get Hadoop source code: -```sh -$ wget http://archive.apache.org/dist/hadoop/core/hadoop-2.6.0/hadoop-2.6.0-src.tar.gz -``` -+ Unpack source -```sh -$ tar xvf hadoop-2.6.0-src.tar.gz -``` -+ Build Hadoop -```sh -$ cd hadoop-2.6.0-src -$ mvn package -Pdist,native -DskipTests -``` -+ Create tarball with Hadoop Native Libs -```sh -$ cd hadoop-dist/target/hadoop-2.6.0/lib -$ tar -czvf hadoop-native-libs-2.6.0.tar.gz native -``` + +- Install: *jdk >= 6*, *maven*, *cmake* and *protobuf >= 2.5.0* + +- Get Hadoop source code: + + .. code:: bash + + wget http://archive.apache.org/dist/hadoop/core/hadoop-2.6.0/hadoop-2.6.0-src.tar.gz + +- Unpack source: + + .. code:: bash + + tar xvf hadoop-2.6.0-src.tar.gz + +- Build Hadoop: + + .. code:: bash + + cd hadoop-2.6.0-src + mvn package -Pdist,native -DskipTests + +- Create tarball with Hadoop Native Libs: + + .. code:: bash + + cd hadoop-dist/target/hadoop-2.6.0/lib + tar -czvf hadoop-native-libs-2.6.0.tar.gz native diff --git a/elements/hive/README.rst b/elements/hive/README.rst index f0cef965..d0321910 100644 --- a/elements/hive/README.rst +++ b/elements/hive/README.rst @@ -3,5 +3,19 @@ hive ==== Installs Hive on Ubuntu and Fedora. -Hive stores metadata in MySQL databases. So, this element requires 'mysql' element. -You can specify download link for Hive using parameter 'HIVE_DOWNLOAD_URL' or choose Hive version using parameter 'HIVE_VERSION'. + +Hive stores metadata in MySQL databases. So, this element requires the +``mysql`` element. + +Environment Variables +--------------------- + +HIVE_VERSION + :Required: Yes, if ``HIVE_DOWNLOAD_URL`` is not set. + :Description: Version of Hive to fetch from apache.org. + :Example: ``HIVE_VERSION=0.11.0`` + +HIVE_DOWNLOAD_URL + :Required: Yes, if ``HIVE_VERSION`` is not set. + :Default: ``http://archive.apache.org/dist/hive/hive-$HIVE_VERSION/hive-$HIVE_VERSION-bin.tar.gz`` + :Description: Download URL of the Hive package. diff --git a/elements/mysql/README.rst b/elements/mysql/README.rst index 0bfa250f..387c3b8d 100644 --- a/elements/mysql/README.rst +++ b/elements/mysql/README.rst @@ -2,5 +2,7 @@ mysql ===== -This element setups basic components of MySQL on Ubuntu and Fedora. -It is light version of original MySQL element (https://github.com/openstack/tripleo-image-elements/tree/master/elements/mysql). +This element sets up the basic components of MySQL. + +It is light version of original MySQL element +(https://github.com/openstack/tripleo-image-elements/tree/master/elements/mysql). diff --git a/elements/oozie/README.rst b/elements/oozie/README.rst index c7c06ee0..2f028026 100644 --- a/elements/oozie/README.rst +++ b/elements/oozie/README.rst @@ -2,4 +2,4 @@ oozie ===== -Oozie deployment +Oozie deployment. diff --git a/elements/root-passwd/README.rst b/elements/root-passwd/README.rst index 112ea204..4ce6aefc 100644 --- a/elements/root-passwd/README.rst +++ b/elements/root-passwd/README.rst @@ -6,3 +6,10 @@ Assign a password to root. This is useful when booting outside of a cloud environment (e.g. manually via kvm). + +Environment Variables +--------------------- + +DIB_PASSWORD + :Required: Yes + :Description: The password for the root user. diff --git a/elements/spark/README.rst b/elements/spark/README.rst index fcf150a4..a59336a7 100644 --- a/elements/spark/README.rst +++ b/elements/spark/README.rst @@ -2,12 +2,27 @@ spark ===== -Installs Spark on Ubuntu. Requires Hadoop CDH 4 (hadoop-cdh element). +Installs Spark on Ubuntu. Requires Hadoop CDH 4 (``hadoop-cdh`` element). -It will install a version of Spark known to be compatible with CDH 4 -This behaviour can be controlled also by using 'DIB_SPARK_VERSION' or directly with -'SPARK_DOWNLOAD_URL' +It will install a version of Spark known to be compatible with CDH 4; +this behaviour can be controlled also by using ``DIB_SPARK_VERSION`` or +directly with ``SPARK_DOWNLOAD_URL``. -If you set 'SPARK_CUSTOM_DISTRO' to 1, you can point the 'SPARK_DOWNLOAD_URL' -variable to a custom Spark distribution created with the make-distribution.sh -script included in Spark. +Environment Variables +--------------------- + +DIB_HADOOP_VERSION + :Required: Yes, if ``SPARK_DOWNLOAD_URL`` is not set. + :Description: Version of the Hadoop platform. See also + http://spark.apache.org/docs/latest/hadoop-third-party-distributions.html. + :Example: ``DIB_HADOOP_VERSION=CDH4`` + +DIB_SPARK_VERSION + :Required: No + :Default: Depends on ``DIB_HADOOP_VERSION``. + :Description: Version of Spark to download from apache.org. + +SPARK_DOWNLOAD_URL + :Required: Yes, if ``DIB_HADOOP_VERSION`` is not set. + :Default: ``http://archive.apache.org/dist/spark/spark-$DIB_SPARK_VERSION/spark-$DIB_SPARK_VERSION-bin-$SPARK_HADOOP_DL.tgz`` + :Description: Download URL of the Spark package. diff --git a/elements/ssh/README.rst b/elements/ssh/README.rst index eb243fc4..4d4b451a 100644 --- a/elements/ssh/README.rst +++ b/elements/ssh/README.rst @@ -3,4 +3,4 @@ ssh === This element installs an SSH server then configures it to be suitable -for use with Sahara +for use with Sahara. diff --git a/elements/swift_hadoop/README.rst b/elements/swift_hadoop/README.rst index 5a76d2e4..161ca7b6 100644 --- a/elements/swift_hadoop/README.rst +++ b/elements/swift_hadoop/README.rst @@ -2,4 +2,17 @@ swift_hadoop ============ -You can add your own Swift into image. Use 'swift_url' to specify download link for Swift jar file. +Install a Swift jar file into the image. + +Environment Variables +--------------------- + +swift_url + :Required: No + :Default: http://sahara-files.mirantis.com/hadoop-swift/hadoop-swift-latest.jar + :Description: Location of the Swift jar file. + +HDFS_LIB_DIR + :Required: No + :Default: /usr/lib/hadoop + :Description: Directory in the guest where to save the Swift jar.