[CORD-2585]
Additional documentation and lint fixes
Change-Id: I47c0683a71697acd31c55c2f9e34689cdc670dea
diff --git a/docs/Makefile b/docs/Makefile
index 0edad84..e222f47 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -22,7 +22,7 @@
gitbook init
gitbook install
-test: linkcheck
+test: linkcheck lint
linkcheck: build
linkchecker --check-extern -a _book/
@@ -38,7 +38,6 @@
ln -s ../../../orchestration/profiles/rcord/docs profiles/rcord
ln -s ../../../orchestration/profiles/ecord/docs profiles/ecord
ln -s ../../../orchestration/profiles/mcord/docs profiles/mcord
- ln -s ../../../orchestration/profiles/opencloud/docs profiles/opencloud
lint:
@echo "markdownlint(mdl) version: `mdl --version`"
@@ -47,7 +46,7 @@
@echo "---"
@cat mdlstyle.rb
@echo "---"
- mdl -s mdlstyle.rb `find . ! -path "./_book/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
+ mdl -s mdlstyle.rb `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
xos:
ln -s ../../orchestration/xos/docs xos
diff --git a/docs/cord_in_china.md b/docs/cord_in_china.md
index 7ae302e..5f73fb6 100644
--- a/docs/cord_in_china.md
+++ b/docs/cord_in_china.md
@@ -206,5 +206,5 @@
to see emails from the rest of the community, send a blank email to
`NAME_OF_THE_ML+subscribe@opencord.org`, for example
-[cord-dev+subscribe@opencord.org](cord-dev+subscribe@opencord.org).
+[cord-dev+subscribe@opencord.org](mailto:cord-dev+subscribe@opencord.org).
diff --git a/docs/getting_the_code.md b/docs/getting_the_code.md
index 70c68cd..e391f40 100644
--- a/docs/getting_the_code.md
+++ b/docs/getting_the_code.md
@@ -28,12 +28,7 @@
The `cord` repositories are usually checked out to `~/cord` in most of our
examples and deployments:
-```shell
-mkdir ~/cord && \
-cd ~/cord && \
-repo init -u https://gerrit.opencord.org/manifest -b {{ book.branch }} && \
-repo sync
-```
+{% include "/partials/repo-download.md" %}
> NOTE: `-b` specifies the branch name. Development work goes on in `master,
> and there are also specific stable branches such as `cord-4.0` that can be
diff --git a/docs/install.md b/docs/install.md
index 00844f6..6f11468 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -46,10 +46,7 @@
`cord-bootstrap.sh` script to install these tools and check out the CORD source
tree to `~/cord`.
-```shell
-curl -o ~/cord-bootstrap.sh https://raw.githubusercontent.com/opencord/cord/{{ book.branch }}/scripts/cord-bootstrap.sh
-chmod +x cord-bootstrap.sh
-```
+{% include "/partials/cord-bootstrap.md" %}
> NOTE: Change the `master` path component in the URL to your desired version
> branch (ex: `cord-5.0`) if required.
diff --git a/docs/install_physical.md b/docs/install_physical.md
index 590463d..a724a24 100644
--- a/docs/install_physical.md
+++ b/docs/install_physical.md
@@ -95,9 +95,9 @@
* 3x Physical Servers: one to be used as head node, two to be used as compute
nodes.
- * Suggested Model: OCP Inspired™ QuantaGrid D51B-1U server. Each server is
- configured with 2x Intel E5-2630 v4 10C 2.2GHz 85W, 64GB of RAM 2133MHz
- DDR4, 2x 500GB HDD, and a 40 Gig adapter.
+ * Suggested Model: OCP Inspired™ QuantaGrid D51B-1U server. Each
+ server is configured with 2x Intel E5-2630 v4 10C 2.2GHz 85W, 64GB of RAM
+ 2133MHz DDR4, 2x 500GB HDD, and a 40 Gig adapter.
* Strongly Suggested NIC:
* Intel Ethernet Converged Network Adapters XL710 10/40 GbE PCIe 3.0, x8
@@ -261,7 +261,7 @@
#### Give "sudoer" permissions (no password)
-```
+```bash
sudo adduser YOUR_USER_NAME sudo && \
echo 'YOUR_USER_NAME ALL=(ALL) NOPASSWD:ALL' | sudo tee --append /etc/sudoers.d/90-cloud-init-users
```
diff --git a/docs/install_virtual.md b/docs/install_virtual.md
index 9ad4110..69e6994 100644
--- a/docs/install_virtual.md
+++ b/docs/install_virtual.md
@@ -374,9 +374,9 @@
### test-exampleservice
This test builds on `test-vsg` by loading the *exampleservice* described in the
-[Developing for Cord:ExampleService](xos/example_service.md). The purpose of
-the *exampleservice* is to demonstrate how new subscriber-facing services can
-be easily deployed to a CORD POD. This test performs the following steps:
+[ExampleService](xos/tutorials/example_service.md). The purpose of the
+*exampleservice* is to demonstrate how new subscriber-facing services can be
+easily deployed to a CORD POD. This test performs the following steps:
* On-boards *exampleservice* into the CORD POD
* Creates an *exampleservice* tenant, which causes a VM to be created and
diff --git a/docs/kubernetes.md b/docs/kubernetes.md
index 4d88322..a6daa93 100644
--- a/docs/kubernetes.md
+++ b/docs/kubernetes.md
@@ -1,11 +1,25 @@
# Using CORD on Kubernetes (Exeperimental)
-
## Podconfigs & Scenarios
-There are kubernetes specific scenarios, `controlkube` and `preppedkube`.
+There are currently two kubernetes specific scenarios, `controlkube` and `preppedkube`.
-## Commands
+### controlkube
+
+This is the "small" installation, and brings up 3 nodes with 2GB of ram each.
+It's designed for laptop or testing use.
+
+### preppedkube
+
+This is the "small" installation, and brings up 3 nodes with 16GB of ram each.
+It's designed for testing and use on physical hardware.
+
+## Building a Kubernetes enabled CORD pod
+
+Currently, virtual deployment with Vagrant is only supported on linux, with
+libvirt as a backend.
+
+## `make` targets
Remove all kubespray related targets: `make clean-kubespray`
diff --git a/docs/mdlstyle.rb b/docs/mdlstyle.rb
index ce1c0a6..f738818 100644
--- a/docs/mdlstyle.rb
+++ b/docs/mdlstyle.rb
@@ -1,12 +1,15 @@
# use all rules
all
-# Intent lists with 4 spaces
+# Indent lists with 4 spaces
rule 'MD007', :indent => 4
# Don't enforce line length limitations within code blocks and tables
rule 'MD013', :code_blocks => false, :tables => false
-# numbered lists should have the correct order
+# Numbered lists should have the correct order
rule 'MD029', :style => "ordered"
+# Allow ! and ? as trailing punctuation in headers
+rule 'MD026', :punctuation => '.,;:'
+
diff --git a/docs/operate/power_up.md b/docs/operate/power_up.md
index 7afd590..58b1b05 100644
--- a/docs/operate/power_up.md
+++ b/docs/operate/power_up.md
@@ -16,22 +16,24 @@
## Check the Head Node Services
1. Verify that `mgmtbr` and `fabric` interfaces are up and have IP addresses
+
2. Verify that MAAS UI is running and accessible:
+
* **Physical POD:** `http://<head-node>/MAAS`
* **CiaB:** `http://<ciab-server>:8080/MAAS`
-> **Troubleshooting: MAAS UI not available on CiaB.** If you are running a CiaB
-> and there is no webserver on port 8080, it might be necessary to refresh port
-> forwarding to the prod VM. Run `ps ax|grep 8080` and look for an SSH command
-> (will look something like this):
+ > **Troubleshooting: MAAS UI not available on CiaB.** If you are running a CiaB
+ > and there is no webserver on port 8080, it might be necessary to refresh port
+ > forwarding to the prod VM. Run `ps ax|grep 8080` and look for an SSH command
+ > (will look something like this):
-```shell
-31353 pts/5 S 0:00 ssh -o User=vagrant -o Port=22 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o PasswordAuthentication=no -o ForwardX11=no -o IdentityFile="/users/acb/cord/build/scenarios/cord/.vagrant/machines/head1/libvirt/private_key" -L *:8080:192.168.121.14:80 -N 192.168.121.14
-```
+ ```shell
+ 31353 pts/5 S 0:00 ssh -o User=vagrant -o Port=22 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o PasswordAuthentication=no -o ForwardX11=no -o IdentityFile="/users/acb/cord/build/scenarios/cord/.vagrant/machines/head1/libvirt/private_key" -L *:8080:192.168.121.14:80 -N 192.168.121.14
+ ```
-> A workaround is to kill this process, and then copy and paste the command
-> above into another window on the CiaB server to set up a new SSH port
-> forwarding connection.
+ > A workaround is to kill this process, and then copy and paste the command
+ > above into another window on the CiaB server to set up a new SSH port
+ > forwarding connection.
3. Verify that the following Docker containers are running: mavenrepo, switchq,
automation, provisioner, generator, harvester, storage, allocator, registry
@@ -42,14 +44,15 @@
5. Run: `source /opt/cord_profile/admin-openrc.sh`
6. Verify that the following OpenStack commands work:
+
* `$ keystone user-list`
* `$ nova list --all-tenants`
* `$ neutron net-list`
-> **Troubleshooting: OpenStack commands give SSL error.** Sometimes Keystone
-> starts up in a strange state and OpenStack commands will fail with various
-> SSL errors. To fix this, it is often sufficient to run: `ssh ubuntu@keystone
-> sudo service apache2 restart`
+ > **Troubleshooting: OpenStack commands give SSL error.** Sometimes Keystone
+ > starts up in a strange state and OpenStack commands will fail with various
+ > SSL errors. To fix this, it is often sufficient to run: `ssh ubuntu@keystone
+ > sudo service apache2 restart`
## Power on Leaf and Spine Switches
@@ -78,7 +81,7 @@
2. Run: `source /opt/cord_profile/admin-openrc.sh`
3. Verify that nova service-list shows the compute node as “up”.
-> It may take a few minutes until the node's status is updated in Nova.
+ > It may take a few minutes until the node's status is updated in Nova.
4. Verify that you can log into the compute nodes from the head node as the
ubuntu user
diff --git a/docs/partials/cord-bootstrap.md b/docs/partials/cord-bootstrap.md
new file mode 100644
index 0000000..f0a95e2
--- /dev/null
+++ b/docs/partials/cord-bootstrap.md
@@ -0,0 +1,2 @@
+<pre><code class="lang-sh">curl -o ~/cord-bootstrap.sh https://raw.githubusercontent.com/opencord/cord/{{ book.branch }}/scripts/cord-bootstrap.sh
+chmod +x cord-bootstrap.sh</code></pre>
diff --git a/docs/partials/repo-download.md b/docs/partials/repo-download.md
new file mode 100644
index 0000000..3b5c124
--- /dev/null
+++ b/docs/partials/repo-download.md
@@ -0,0 +1,4 @@
+<pre><code class="lang-sh">mkdir ~/cord && \
+cd ~/cord && \
+repo init -u https://gerrit.opencord.org/manifest -b {{ book.branch }} && \
+repo sync</code></pre>
diff --git a/docs/quickstarts.md b/docs/quickstarts.md
index bc3bdae..3122dcb 100644
--- a/docs/quickstarts.md
+++ b/docs/quickstarts.md
@@ -11,11 +11,7 @@
Virtual pod, you can use the
[cord-bootstrap.sh](install.html#cord-bootstrapsh-script) script:
-```shell
-curl -o ~/cord-bootstrap.sh https://raw.githubusercontent.com/opencord/cord/master/scripts/cord-bootstrap.sh
-chmod +x cord-bootstrap.sh
-./cord-bootstrap.sh -v
-```
+{% include "/partials/cord-bootstrap.md" %}
> NOTE: Change the `master` path component in the URL to your desired version
> branch (ex: `cord-5.0`) if required.
@@ -29,6 +25,7 @@
system, run the following commands:
```shell
+./cord-bootstrap.sh -v
cd ~/cord/build && \
make PODCONFIG=rcord-virtual.yml config && \
make -j4 build |& tee ~/build.out && \