decouple from CORD guide
Change-Id: I9187b72a95721b2620f65ccf4b581a11d8de8125
diff --git a/VERSION b/VERSION
index a0b09d3..5473cf8 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.1.25
+2.1.26-dev
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index d88aa17..353863f 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -5,6 +5,7 @@
* [Installing XOS](install.md)
* [Download Source Code](repo.md)
* [XOS Containers](xos_internals.md)
+ * [XOS Configuration](modules/xosconfig.md)
* [Using XOS](use.md)
* [XOS Modeling Framework](dev/xproto.md)
* [XOS Tool Chain (Internals)](dev/xosgenx.md)
diff --git a/docs/book.json b/docs/book.json
index 1312ebb..b9ce15e 100644
--- a/docs/book.json
+++ b/docs/book.json
@@ -9,7 +9,13 @@
},
"plugins": [
"anchorjs",
+ "custom-favicon",
"smart-nav-collapse",
"versions-select"
- ]
+ ],
+ "pluginsConfig": {
+ "favicon": "static/xos.ico"
+ }
}
+
+
diff --git a/docs/dev/workflow_pod.md b/docs/dev/workflow_pod.md
index 6b659b8..51cdf91 100644
--- a/docs/dev/workflow_pod.md
+++ b/docs/dev/workflow_pod.md
@@ -24,29 +24,29 @@
2. Teardown the existing XOS installation and clean up OpenStack to
remove any leftover instances or networks:
- ```
- cd ~/cord/build
- make xos-teardown
- make clean-openstack
- ```
+```shell
+cd ~/cord/build
+make xos-teardown
+make clean-openstack
+```
3. Optional: Teardown ONOS. Sometimes we find it helpful to reinstall the
onos-cord and onos-fabric containers, to ensure that all state is wiped
clean from ONOS.
- ```
- cd ~/cord/build
- make clean-onos
- ```
+```shell
+cd ~/cord/build
+make clean-onos
+```
4. Build the new XOS container images and deploy to the pod.
- ```
- cd ~/cord/build
- make -j4 build
- make compute-node-refresh
- make pod-test
- ```
+```shell
+cd ~/cord/build
+make -j4 build
+make compute-node-refresh
+make pod-test
+```
5. Test and verify your changes.
diff --git a/docs/install.md b/docs/install.md
index 85b77c3..bc3bc24 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -10,8 +10,8 @@
Helm client-side tool. If you are new to Kubernetes, we recommend this [tutorial](https://kubernetes.io/docs/tutorials/) as a good place to start.
Although you are free to set up Kubernetes and Helm in whatever way
-makes sense to you, the following walks you through an
-example installation sequence on MacOS. It was tested on version 10.12.6.
+makes sense to you, the following walks through an example
+installation sequence on MacOS. It was tested on version 10.12.6.
## Prerequisites
@@ -101,84 +101,124 @@
[XOS tutorial](tutorials/basic_synchronizer.md). The easiest way to do
this uses the `repo` tool, as described [here](repo.md).
-## Bring Up XOS
+## Bring Up XOS
-To deploy `xos-core` (plus affiliated micro-services) into your
+To deploy `xos-core` (plus affiliated micro-services) into your
Kubernetes cluster, execute the following from the `$SRC_DIR/helm-charts`
directory:
-```shell
-helm dep update xos-core
-helm install xos-core -n xos-core
+```shell
+helm dep update xos-core
+helm install xos-core -n xos-core
```
-Use `kubectl get pods` to verify that all containers that implement XOS
-are successfully running. You should see output that looks something
-like this:
+You also need to start the Kafka message bus to catch event
+notifications send by the various components:
-```shell
-NAME READY STATUS RESTARTS AGE
-xos-chameleon-6f49b67f68-pdf6n 1/1 Running 0 2m
-xos-core-57fd788db-8b97d 1/1 Running 0 2m
-xos-db-f9ddc6589-rtrml 1/1 Running 0 2m
-xos-gui-7fcfcd4474-prhfb 1/1 Running 0 2m
-xos-redis-74c5cdc969-ppd7z 1/1 Running 0 2m
-xos-tosca-7c665f97b6-krp5k 1/1 Running 0 2m
-xos-ws-55d676c696-pxsqk 1/1 Running 0 2m
+```shell
+helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator
+helm install -f examples/kafka-single.yaml --version 0.8.8 -n cord-kafka incubator/kafka
```
-## Bring Up a Service
+Use `kubectl get pods` to verify that all containers that implement XOS
+(and Kafka) are successfully running. You should see output that looks
+something like this:
-Optionally, you can bring up a simple service to be managed by XOS.
+```shell
+NAME READY STATUS RESTARTS AGE
+cord-kafka-0 1/1 Running 0 3m
+cord-kafka-zookeeper-0 1/1 Running 0 3m
+xos-chameleon-58c5b847d6-48jvf 1/1 Running 0 11m
+xos-core-7dc45f677b-pzhm6 1/1 Running 0 11m
+xos-db-c49549b7f-mzs4n 1/1 Running 0 11m
+xos-gui-7c96669d8c-8zkhq 1/1 Running 0 11m
+xos-tosca-7f6cf85657-gzddq 1/1 Running 0 11m
+xos-ws-5f47ff7d94-xg9f5 1/1 Running 0 11m
+```
+
+## Bring Up Monitoring and Logging
+
+Although not required, we recommend that you also bring up two
+auxilary services to capture and display monitoring and logging
+information. This is done by executing the following Helm charts.
+
+Monitoring (once running, access [Grafana](http://docs.grafana.org/)
+Dashboard at port 31300):
+
+
+```shell
+helm dep update nem-monitoring
+helm install -n nem-monitoring nem-monitoring
+```
+
+Logging (once running, access
+[Kabana](https://www.elastic.co/guide/en/kibana/current/index.html)
+Dashboard at port 30601):
+
+```shell
+helm dep up logging
+helm install -f examples/logging-single.yaml -n logging logging
+```
+
+> **Note:** The `-f examples/logging-single.yaml` option says to
+> not use persistent storage, which is fine for development or demo
+> purposes, but not for operational deployments.
+
+## Bring Up a Service
+
+Optionally, you can bring up a simple service to be managed by XOS.
This involves deploying two additional helm charts: `base-kubernetes`
and `demo-simpleexampleservice`. Again from the `$SRC_DIR/helm-charts`
directory, execute the following:
-```shell
-helm dep update xos-profiles/base-kubernetes
-helm install xos-profiles/base-kubernetes -n base-kubernetes
-helm dep update xos-profiles/demo-simpleexampleservice
-helm install xos-profiles/demo-simpleexampleservice -n demo-simpleexampleservice
+```shell
+helm dep update xos-profiles/base-kubernetes
+helm install xos-profiles/base-kubernetes -n base-kubernetes
+helm dep update xos-profiles/demo-simpleexampleservice
+helm install xos-profiles/demo-simpleexampleservice -n demo-simpleexampleservice
```
-> **Note:** It will take some time for the various helm charts to
-> deploy and the containers to come online. The `tosca-loader`
-> container may error and retry several times as it waits for
-> services to be dynamically loaded. This is normal, and eventually
-> the `tosca-loader` will enter the completed state.
+When all the containers are successfully up and running, `kubectl get
+pod` will return output that looks something like this:
-As before, when all the containers are successfully up and running,
-`kubectl get pod` will return output that looks something like this:
-```shell
-NAME READY STATUS RESTARTS AGE
-base-kubernetes-kubernetes-55c55bd897-rn9ln 1/1 Running 0 2m
-base-kubernetes-tosca-loader-vs6pv 1/1 Running 1 2m
-demo-simpleexampleservice-787454b84b-ckpn2 1/1 Running 0 1m
-demo-simpleexampleservice-tosca-loader-4q7zg 1/1 Running 0 1m
-xos-chameleon-6f49b67f68-pdf6n 1/1 Running 0 12m
-xos-core-57fd788db-8b97d 1/1 Running 0 12m
-xos-db-f9ddc6589-rtrml 1/1 Running 0 12m
-xos-gui-7fcfcd4474-prhfb 1/1 Running 0 12m
-xos-redis-74c5cdc969-ppd7z 1/1 Running 0 12m
-xos-tosca-7c665f97b6-krp5k 1/1 Running 0 12m
-xos-ws-55d676c696-pxsqk 1/1 Running 0 12m
+```shell
+NAME READY STATUS RESTARTS AGE
+base-kubernetes-kubernetes-75d68b65bc-h594m 1/1 Running 0 6m
+base-kubernetes-tosca-loader-ltdzg 0/1 Completed 4 6m
+cord-kafka-0 1/1 Running 1 15m
+cord-kafka-zookeeper-0 1/1 Running 0 15m
+demo-simpleexampleservice-cc8fbfb7-s4r68 1/1 Running 0 5m
+demo-simpleexampleservice-tosca-loader-46qtg 0/1 Completed 4 5m
+xos-chameleon-58c5b847d6-rcqff 1/1 Running 0 16m
+xos-core-7dc45f677b-27vc9 1/1 Running 0 16m
+xos-db-c49549b7f-589n6 1/1 Running 0 16m
+xos-gui-7c96669d8c-gcwsv 1/1 Running 0 16m
+xos-tosca-7f6cf85657-bf276 1/1 Running 0 16m
+xos-ws-5f47ff7d94-mpn7g 1/1 Running 0 16m
```
-## Visit XOS Dashboard
+The two `tosca-loader` items with `Completed` status are jobs, as
+opposed to pods. Their job is to load TOSCA-based provisioning and
+configuration information into XOS, and so they run to complettion and
+then terminate. It is not uncommon to see them in an `Error` state as
+they retry while waiting for the corresponding services to come
+on-line.
+
+## Visit XOS Dashboard
Finally, to view the XOS dashboard, run the following:
-```shell
-minikube service xos-gui
+```shell
+minikube service xos-gui
```
-This will launch a window in your default browser. Administrator login
-and password are defined in `$SRC_DIR/helm-charts/xos-core/values.yaml`.
+This will launch a window in your default browser. Administrator login
+and password are defined in `$SRC_DIR/helm-charts/xos-core/values.yaml`.
-## Next Steps
+## Next Steps
-This completes the installation process. At this point, you can either
-drill down on the internals of
+This completes the installation process. At this point, you can either
+drill down on the internals of
[Simple Example Service](simpleexampleservice/simple-example-service.md),
or you can work through the [XOS tutorial](tutorials/basic_synchronizer.md).
diff --git a/docs/static/xos.ico b/docs/static/xos.ico
new file mode 100644
index 0000000..2a05b6b
--- /dev/null
+++ b/docs/static/xos.ico
Binary files differ
diff --git a/docs/static/xos_components.jpg b/docs/static/xos_components.jpg
index 81464a3..3c7f2c1 100644
--- a/docs/static/xos_components.jpg
+++ b/docs/static/xos_components.jpg
Binary files differ
diff --git a/docs/tutorials/basic_synchronizer.md b/docs/tutorials/basic_synchronizer.md
index 3e38d39..c8bc6f5 100644
--- a/docs/tutorials/basic_synchronizer.md
+++ b/docs/tutorials/basic_synchronizer.md
@@ -314,6 +314,7 @@
You can use that (and the `HelloWorldServiceInstance` model definition
too) to create an instance of both models. For your convenience, save
the following content to a file called `hello-world-tosca.yaml`
+
```yaml
tosca_definitions_version: tosca_simple_yaml_1_0
imports:
diff --git a/docs/xos_internals.md b/docs/xos_internals.md
index 8293ace..2541eb8 100644
--- a/docs/xos_internals.md
+++ b/docs/xos_internals.md
@@ -8,19 +8,15 @@
| ---- | ----------- | ----- |
| xos-core | The core of the platform; responsible for maintaining the data model | 50051, 500515 |
| xos-db | A Postgres instance; used to persist the data model | 5432 |
-| xos-redis | A Redis instance; used as pub/sub channel for internal notifications | 5432 |
| xos-tosca | Northbound TOSCA interface; accessible via REST | 9102|
| xos-gui | Northbound GUI dashboard| 4000|
-| xos-ws | Listens to `redis` events and propagates them over web-sockets | 3000|
+| xos-ws | Listens to `kafka` events and propagates them over web-sockets | 3000|
| xos-chameleon | Northbound REST interface; accessible at `/xosapi/v1/..` (`swagger` is published at `/apidocs/`| 3000|
-| kafka | A Kafka bus; used by some backend components to send event notifications | 9092|
+| kafka | A Kafka bus; used to send event notifications | 9092|
All the communication between containers happen over `gRPC` except for
`xos-gui`, which uses a combination of REST and web-socket.
-> **Note:** The dotted lines identify optional components that are
-> required only in certain configurations.
-
