First commit, Melanie's guide for ref and SAF docs

Author: JoanneOFlynn2018

guides/.gitignore

@@ -0,0 +1,3 @@
+/build/
+/common/build.adoc
+/upstreamize_report.md

guides/LICENSE

@@ -0,0 +1,9 @@
+Copyright © 2019 Red Hat, Inc.
+
+The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
+
+Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
+
+Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
+
+All other trademarks are the property of their respective owners.

guides/Makefile

@@ -0,0 +1,16 @@
+all: html
+
+html: all-html
+
+pdf: all-pdf
+
+clean: all-clean
+
+all-html:
+	cd doc-Provisioning_Guide && $(MAKE) html
+
+all-pdf:
+	cd doc-Provisioning_Guide && $(MAKE) pdf
+
+all-clean:
+	cd doc-Provisioning_Guide && $(MAKE) clean

guides/README.md

@@ -0,0 +1,88 @@
+# Foreman Guides
+
+This is upstream source code of [Red Hat Satellite 6](https://access.redhat.com/documentation/en-us/red_hat_satellite) documentation. All content in this repository uses [AsciiDoctor](https://asciidoctor.org/) syntax and aims to follow [Guidelines for Red Hat Documentation](https://redhat-documentation.github.io/). This is a **work in progress*, an attempt to take content written by Red Hat documentation team, modularize it, incorporate [existing documentation](https://theforeman.org/documentation.html) and eventually make this the only and official documentation for Foreman, Katello and all plugins.
+
+## Building
+
+Install required tools. In Fedora perform:
+
+    dnf -y install ruby asciidoctor asciidoctor-pdf make
+
+In MacOS required tools can be installed via brew but instead "make" call "gmake":
+
+    brew install asciidoctor make
+
+Alternatively, XCode development environment can be installed to have make utility available on PATH, however this takes about an hour to download and install and requires several gigabytes of HDD space:
+
+	xcode-select --install
+
+If AsciiDoctor is not available in repositories or under RVM/rbenv, simply install it from rubygems:
+
+  	gem install asciidoctor asciidoctor-pdf --pre
+
+Then simply run `make` or `make html` which builds HTML artifacts. Generating PDF output is slow, therefore command `make pdf` must be used separately. To make both formats in one command, use `make html pdf`. To build downstream version perform `make BUILD=satellite`.
+
+Few additional make targets are available on the guide level. To quickly build HTML version and open new tab in a browser do:
+
+    cd doc-Provisioning_Guide
+    make browser
+
+Similarly, to build and open PDF version do:
+
+    make open-pdf
+
+The final artifacts can be found in the ./build subdirectory. Note that GNU Makefile tracks changes and only builds relevant artifacts, to trigger full rebuild use `make clean` to delete build directory and start over.
+
+## Reading or Publishing
+
+We do not publish the content yet to prevent users confusion, however this section will cover steps required to publish the content. We should make sure that only the last stable version of the HTML document is indexed by search engines, old and nightly builds should not be indexed. All PDFs should be available for download tho.
+
+## Contributing
+
+Please read [Guidelines for Red Hat Documentation](https://redhat-documentation.github.io/) before opening a Pull Request. Additional rules apply:
+
+Never write "Foreman" or "Satellite" words directly but use the following variables:
+
+| Variable | Upstream value | Downstream value |
+| -------- | -------------- | ---------------- |
+| {ProjectNameXY} | Foreman 1.22 | Red Hat Satellite 6.5 |
+| {ProjectNameX} | Foreman | Red Hat Satellite 6 |
+| {ProjectName} | Foreman | Red Hat Satellite |
+| {ProjectXY} | Foreman 1.22 | Satellite 6.5 |
+| {ProjectX} | Foreman | Satellite 6 |
+| {Project} | Foreman | Satellite |
+| {SmartProxyServer} | Smart Proxy server | Capsule Server |
+| {SmartProxy} | Smart Proxy | Capsule |
+
+Variables cannot be used in shell or code examples. To use them, use "attributes" keyword:
+
+	[options="nowrap" subs="+quotes,+attributes"]
+	----
+	# ls {VariableName}
+	----
+
+Hide or show specific blocks, paragraphs, warnings or chapters via special variable called "build". Its value can be set either to "foreman" or "satellite":
+
+	ifeval::["{build}" == "foreman"]
+	NOTE: This part is only relevant for deployments with Katello plugin.
+	endif::[]
+
+When doing review, consider checking out the topic branch and putting necessary changes on top of author's work to making many comments on github.
+
+We should avoid using phases like, "Starting from version 6.5 or 1.22" because it is not possible to easily translate these strings in both the streams.
+
+## The process (TODO)
+
+This is what we are working on right now:
+
+* [x] Initial import of Provisioning Guide
+* [x] Provide Makefiles and Travis integration
+* [x] Replace Satellite 6 with Foreman term
+* [ ] Modularize content
+* [ ] Hide irrelevant chapters
+* [ ] Incorporate parts from upstream docs
+* [ ] Incorporate https://community.theforeman.org/t/discovery-ipxe-efi-workflow-in-foreman-1-20/13026
+* [ ] Write better introduction
+* [ ] Add Anaconda-image based provisioning workflow
+* [ ] Update with PXE Grub2 steps
+* [ ] Discuss with Foreman community if to continue with other guides

guides/common/Makefile

@@ -0,0 +1,48 @@
+BUILD = foreman
+BUILD_DIR = ../build
+ROOTDIR = $(realpath .)
+NAME = $(notdir $(ROOTDIR))
+DEST_DIR = $(BUILD_DIR)/$(NAME)
+DEST_HTML = $(DEST_DIR)/index-$(BUILD).html
+DEST_PDF = $(BUILD_DIR)/$(NAME)-$(BUILD).pdf
+IMAGES_DIR = $(DEST_DIR)/images
+IMAGES_TS = $(DEST_DIR)/.timestamp-images
+SOURCES = master.adoc $(shell ls topics/*.adoc)
+IMAGES = $(shell find ./images -type f)
+UNAME = $(shell uname)
+
+ifeq ($(UNAME), Linux)
+BROWSER_OPEN = xdg-open
+endif
+ifeq ($(UNAME), Darwin)
+BROWSER_OPEN = open
+endif
+
+all: html
+
+html: prepare $(IMAGES_TS) $(DEST_HTML)
+
+pdf: prepare $(DEST_PDF)
+
+prepare:
+	@mkdir -p $(BUILD_DIR)
+	@mkdir -p $(DEST_DIR) $(IMAGES_DIR)
+
+clean:
+	@rm -rf "$(DEST_DIR)" "$(DEST_PDF)"
+
+browser: html
+	${BROWSER_OPEN} "file://$(realpath $(ROOTDIR)/$(DEST_HTML))"
+
+open-pdf: pdf
+	${BROWSER_OPEN} "$(realpath $(ROOTDIR)/$(DEST_PDF))"
+
+$(IMAGES_TS): $(IMAGES)
+	cp $? $(IMAGES_DIR)
+	touch $(IMAGES_TS)
+
+$(DEST_HTML): $(SOURCES)
+	asciidoctor -a build=$(BUILD) -b xhtml5 -d book -o $@ $<
+
+$(DEST_PDF): $(SOURCES) $(IMAGES)
+	asciidoctor-pdf -a build=$(BUILD) -d book -o $@ $<

guides/common/attributes.adoc

@@ -0,0 +1,44 @@
+:TargetVersion: 6.4
+:ProductVersion: 6.4
+:ProductVersionPrevious: 6.3
+:RepoRHEL7ServerSatelliteServerProductVersion: rhel-7-server-satellite-6.4-rpms
+:RepoRHEL7ServerSatelliteServerProductVersionPrevious: rhel-7-server-satellite-6.3-rpms
+:RepoRHEL7ServerSatelliteServerPuppetVersion: rhel-7-server-satellite-6.3-puppet4-rpms
+:RepoRHEL7ServerSatelliteCapsuleProductVersion: rhel-7-server-satellite-capsule-6.4-rpms
+:RepoRHEL7ServerSatelliteCapsulePuppetVersion: rhel-7-server-satellite-capsule-6.3-puppet4-rpms
+:RepoRHEL7ServerSatelliteToolsProductVersion: rhel-7-server-satellite-tools-6.4-rpms
+:RepoRHEL7Server: rhel-7-server-rpms
+:RepoRHEL7ServerSoftwareCollections: rhel-server-rhscl-7-rpms
+:RepoRHEL7ServerOptional: rhel-7-server-optional-rpms
+:RepoRHEL7ServerSatelliteMaintenanceProductVersion: rhel-7-server-satellite-maintenance-6-rpms
+:RepoRHEL7ServerAnsible: rhel-7-server-ansible-2.6-rpms
+:context: assembly
+
+ifeval::["{build}" == "upstream"]
+:OpenShift: OpenShift
+:OpenShiftShort: OpenShift
+:OVirt: oVirt
+:OVirtShort: oVirt
+:OVirtLegacy: oVirt
+:OVirtLegacyShort: oVirt
+:ovirt-example-com: ovirt.example.com
+:OpenStack: OpenStack
+:Project: Service Assurance Framework
+:ProjectShort: SAF
+:MessageBus: QDR
+endif::[]
+
+ifeval::["{build}" == "downstream"]
+:OpenShift: Red Hat OpenShift Container Platform
+:OpenShiftShort: OCP
+:OVirt: Red{nbsp}Hat{nbsp}Virtualization
+:OVirtShort: RHV
+:OVirtLegacy: Red{nbsp}Hat{nbsp}Enterprise{nbsp}Virtualization
+:OVirtLegacyShort: RHEV
+:ovirt-example-com: rhv.example.com
+:OpenStack: Red{nbsp}Hat OpenStack Platform
+:Project: Service Assurance Framework
+:ProjectShort: SAF
+:MessageBus: AMQP 1.0
+
+endif::[]

guides/common/collectd/con_data-collecting-agent.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+
+// This module can be included from assemblies using the following include statement:
+// include::<path>/con_data-collecting-agent.adoc[leveloffset=+1]
+
+// The file name and the ID are based on the module title. For example:
+// * file name: con_my-concept-module-a.adoc
+// * ID: [id='con_my-concept-module-a_{context}']
+// * Title: = My concept module A
+//
+// The ID is used as an anchor for linking to the module. Avoid changing
+// it after the module has been published to ensure existing links are not
+// broken.
+//
+// The `context` attribute enables module reuse. Every module's ID includes
+// {context}, which ensures that the module has a unique ID even if it is
+// reused multiple times in a guide.
+//
+// In the title, include nouns that are used in the body text. This helps
+// readers and search engines find information quickly.
+// Do not start the title with a verb. See also _Wording of headings_
+// in _The IBM Style Guide_.
+[id="data-collecting-agent_{context}"]
+= Data collecting agent
+
+Performance monitoring collects system information periodically and provides a mechanism to store and monitor the values in a variety of ways using a data collecting agent. Red Hat supports the collectd daemon as a collection agent. This daemon stores the data in a time-series database. One of the Red Hat supported databases is called Prometheus. You can use this stored data to monitor systems, find performance bottlenecks, and predict future system load.
+
+[NOTE]
+Red Hat OpenStack Platform supports performance monitoring only on the client side.

guides/common/collectd/proc_installing-collectd.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// doc-Service-Assurance-Framework/assemblies/assembly_configuring-saf-components.adoc
+
+// This module can be included from assemblies using the following include statement:
+// include::<path>/proc_installing-collectd.adoc[leveloffset=+1]
+
+// The file name and the ID are based on the module title. For example:
+// * file name: proc_doing-procedure-a.adoc
+// * ID: [id='proc_doing-procedure-a_{context}']
+// * Title: = Doing procedure A
+//
+// The ID is used as an anchor for linking to the module. Avoid changing
+// it after the module has been published to ensure existing links are not
+// broken.
+//
+// The `context` attribute enables module reuse. Every module's ID includes
+// {context}, which ensures that the module has a unique ID even if it is
+// reused multiple times in a guide.
+//
+// Start the title with a verb, such as Creating or Create. See also
+// _Wording of headings_ in _The IBM Style Guide_.
+
+[id="installing-collectd"]
+= Installing collectd
+
+To install collectd on the overcloud, complete the following steps:
+
+. Copy the file ``/usr/share/openstack-tripleo-heat-templates/environments/collectd-environment.yaml` to your local directory.  Open the file, set the following parameters, and list the plugins you want under `CollectdExtraPlugins`. You can also provide parameters in the `ExtraConfig` section:
++
+----
+parameter_defaults:
+   CollectdExtraPlugins:
+     - disk
+     - df
+     - virt
+
+   ExtraConfig:
+     collectd::plugin::virt::connection: "qemu:///system"
+     collectd::plugin::virt::hostname_format: "hostname uuid"
+----
++
+By default, collectd comes with the disk, interface, load, memory, processes, and tcpconns plugins. You can add additional plugins using the `CollectdExtraPlugins` parameter. You can also provide additional configuration information for the `CollectdExtraPlugins` using the `ExtraConfig` option as shown. The example above adds the virt plugin and configures the connection string and the hostname format.
+
+. Include the modified YAML files in the `openstack overcloud deploy` command to install the collectd daemon on all overcloud nodes. For example:
++
+----
+$ openstack overcloud deploy
+--templates /home/templates/environments/collectd.yaml \
+-e /path-to-copied/collectd-environment.yaml
+----
++
+To view the collectd plugins and configurations, see
+<<appe-saf-collectd-plugins>>.