Doc updates (contiv#1404)

Doc updates

Author: rastislavs

CHANGELOG.md

@@ -83,7 +83,7 @@
 
 ### New Features & Enhancements
  - added `cipherSuites` option for etcd into helm
- - [native PCI driver support for VMware vmxnet3](docs/VMXNET3.md)
+ - [native PCI driver support for VMware vmxnet3](docs/setup/VMXNET3.md)
 
 ### Known Issues
 - load-balancing between backends of a service is limited to the first 256 PODs

README.md

@@ -6,10 +6,11 @@
 [![GoDoc](https://godoc.org/github.com/contiv/vpp?status.svg)](https://godoc.org/github.com/contiv/vpp)
 [![GitHub license](https://img.shields.io/badge/license-Apache%20license%202.0-blue.svg)](https://github.com/contiv/vpp/blob/master/LICENSE)
 
-This Kubernetes network plugin uses FD.io VPP to provide network connectivity
-between PODs. Currently, only Kubernetes 1.9.X and higher versions are supported.
+[Contiv-VPP](https://contivpp.io/) is a Kubernetes CNI plugin for Kubernetes that employs
+a programmable CNF vSwitch based on [FD.io VPP](https://fd.io/) offering feature-rich,
+high-performance cloud-native networking and services.
 
-For more details see [https://contivpp.io/](https://contivpp.io/).
+For more details see [https://contivpp.io/](https://contivpp.io/)
 
 
 ## Releases
@@ -35,7 +36,7 @@ You can get started with Contiv-VPP in one of the following ways:
   VMs. This is the easiest way to bring up a cluster for exploring the
   capabilities and features of Contiv-VPP.
 
-* Use the [Contiv-specific kubeadm install](docs/MANUAL_INSTALL.md)
+* Use the [Contiv-specific kubeadm install](docs/setup/MANUAL_INSTALL.md)
   instructions to manually install Kubernetes with Contiv-VPP networking on one
   or more bare-metal servers.
 
@@ -47,14 +48,17 @@ You can get started with Contiv-VPP in one of the following ways:
   in Calico clusters, where some of the nodes can be running plain Calico (without VPP)
   and some of the nodes can be running Calico with VPP.
 
+* Try [Contiv-VPP UI](ui/README.md) web browser user interface on top of Contiv-VPP,
+  it runs in Vagrant deployments as well as on bare-metal.
+
 
 ## Configuration & Troubleshooting
-Please refer to the [Contiv-VPP configuration and troubleshooting](docs/TOOLS.md) document.
+Please refer to the [Contiv-VPP configuration and troubleshooting](docs/operation/TOOLS.md) document.
 
 
 ## Reporting Bugs
 In order to report a bug, please file an issue in GitHub. Please provide
-the information described in [Bug Reports README](docs/BUG_REPORTS.md).
+the information described in [Bug Reports README](docs/debugging/BUG_REPORTS.md).
 
 
 ## Communication Channels

docs/ARCHITECTURE.md

@@ -85,7 +85,7 @@ network stack and data-plane NIC interface controlled by VPP:
  - data-plane NIC is controlled directly by VPP using DPDK. Note that this means that
  this interface is not visible to the host Linux network stack, and the node either needs another
  management interface for k8s control plane communication, or 
- [STN (Steal The NIC)](SINGLE_NIC_SETUP.md) deployment must be applied.
+ [STN (Steal The NIC)](setup/SINGLE_NIC_SETUP.md) deployment must be applied.
 
 **Contiv VPP Agent** is the control plane part of the vSwitch container. It is responsible
 for configuring the VPP according to the information gained from ETCD and requests
@@ -114,6 +114,6 @@ do not provide 2 network interfaces, Contiv/VPP can work in the single NIC setup
 when the interface will be "stolen" from the host network stack just before starting
 the VPP and configured with the same IP address on VPP, as well as 
 on the host-VPP interconnect TAP interface, as it had in the host before it. 
-For more information on STN setup, read the [Single NIC Setup README](SINGLE_NIC_SETUP.md).
+For more information on STN setup, read the [Single NIC Setup README](setup/SINGLE_NIC_SETUP.md).
 
-[![Contiv/VPP Architecture](img/contiv-flow.png)](img/contiv-flow.svg)
+[![Contiv/VPP Architecture](img/contiv-flow.png)](img/contiv-flow.png)

docs/README.md

@@ -0,0 +1,37 @@
+# Contiv-VPP Documentation
+
+
+## General Information:
+* [ARCHITECTURE](ARCHITECTURE.md) - high-level description of Contiv-VPP
+  components and operation
+* [NETWORKING](NETWORKING.md) - detailed description on how the network
+  is programmed with Contiv-VPP
+* [DEVELOPER GUIDE](dev-guide) -  details on how Contiv-VPP works internally
+
+
+## Setup Instructions
+* [VAGRANT INSTALLATION](../vagrant/README.md) - running Contiv-VPP in Vagrant
+* [MANUAL INSTALLATION](setup/MANUAL_INSTALL.md) - running Contiv-VPP on bare metal
+* [ARM64 SETUP](arm64) - running Contiv-VPP on ARM platform
+* [CUSTOM MGMT NETWORK](setup/CUSTOM_MGMT_NETWORK.md) - setting up a custom management 
+  network on multi-homed nodes
+* [MULTI NIC SETUP](setup/MULTI_NIC_SETUP.md) - setting up a node with multiple NICs
+* [SINGLE NIC SETUP](setup/SINGLE_NIC_SETUP.md) - setting up a node with a single NIC
+* [VMXNET3](setup/VMXNET3.md) - VMware vmxnet3 driver support
+* [VPP CONFIG](setup/VPP_CONFIG.md) - creating VPP startup configuration
+* [VMWARE FUSION HOST](setup/VMWARE_FUSION_HOST.md) - preparing a VmWare Fusion host
+* [ETCD SECURITY](setup/ETCD_SECURITY.md) - securing access to ETCD
+* [HTTP SECURITY](setup/HTTP_SECURITY.md) - securing HTTP endpoints
+
+
+## Operation
+* [TOOLS](operation/TOOLS.md) - configuration and Troubleshooting Tools
+* [PROMETHEUS](operation/PROMETHEUS.md) - Prometheus statistics
+* [CONTIV UI](../ui/README.md) - web-based Contiv VPP user interface
+
+
+## Debugging
+* [VPP PACKET TRACING](debugging/VPP_PACKET_TRACING_K8S.md) - how to do VPP packet tracing in Kubernetes
+* [VPPTRACE](debugging/VPPTRACE.md) - VPP packet tracing
+* [CORE FILES](debugging/CORE_FILES.md) - capturing VPP core dumps
+* [BUG REPORTS](debugging/BUG_REPORTS.md) - debugging and reporting bugs in Contiv-VPP

docs/arm64/MANUAL_INSTALL_ARM64.md

@@ -72,12 +72,12 @@ install Contiv-VPP on Cavium Thunderx servers.
 
 
 
-[1]: ../MANUAL_INSTALL.md
+[1]: ../setup/MANUAL_INSTALL.md
 [2]: MANUAL_INSTALL_CAVIUM.md
 [3]: MULTI_NIC_SETUP_CAVIUM.md
 [4]: VPP_CONFIG_CAVIUM.md
-[5]: ../SINGLE_NIC_SETUP.md#configuring-stn-in-contiv-vpp-k8s-deployment-files
-[6]: ../SINGLE_NIC_SETUP.md
-[7]: ../MULTI_NIC_SETUP.md
-[8]: ../MANUAL_INSTALL.md#determining-network-adapter-pci-addresses
+[5]: ../setup/SINGLE_NIC_SETUP.md#configuring-stn-in-contiv-vpp-k8s-deployment-files
+[6]: ../setup/SINGLE_NIC_SETUP.md
+[7]: ../setup/MULTI_NIC_SETUP.md
+[8]: ../setup/MANUAL_INSTALL.md#determining-network-adapter-pci-addresses
 

docs/arm64/MANUAL_INSTALL_CAVIUM.md

@@ -586,11 +586,11 @@ rm -rf /var/etcd/contiv-data
 [8]: #tearing-down-kubernetes
 [10]: #14-installing-kubeadm-on-your-hosts
 [11]: ../../vagrant/README.md
-[12]: ../CUSTOM_MGMT_NETWORK.md
-[13]: ../VMWARE_FUSION_HOST.md
-[14]: ../SINGLE_NIC_SETUP.md
-[15]: ../MULTI_NIC_SETUP.md
-[16]: ../SINGLE_NIC_SETUP.md#configuring-stn-in-contiv-vpp-k8s-deployment-files
+[12]: ../setup/CUSTOM_MGMT_NETWORK.md
+[13]: ../setup/VMWARE_FUSION_HOST.md
+[14]: ../setup/SINGLE_NIC_SETUP.md
+[15]: ../setup/MULTI_NIC_SETUP.md
+[16]: ../setup/SINGLE_NIC_SETUP.md#configuring-stn-in-contiv-vpp-k8s-deployment-files
 [17]: ../../k8s/README.md#setup-node-sh
 [18]: https://www.packet.net/bare-metal/servers/c1-large-arm/
 [19]: https://help.packet.net/technical/networking/layer-2-configurations

docs/BUG_REPORTS.md renamed to docs/debugging/BUG_REPORTS.md

@@ -332,5 +332,5 @@ following steps:
   ./contiv-vpp-bug-report.sh -u vagrant -m k8s-master -f <path-to-your-vagrant-ssh-config-file>/vagrant-ssh.conf
 ```
 
-[1]: ../scripts/contiv-vpp-bug-report.sh
-[2]: ../vagrant/README.md
+[1]: ../../scripts/contiv-vpp-bug-report.sh
+[2]: ../../vagrant/README.md

docs/CORE_FILES.md renamed to docs/debugging/CORE_FILES.md

@@ -21,7 +21,7 @@ individually, but only all at the same time. In Contiv/VPP all pods are connecte
 with VPP via the same kind of the TAP interface, meaning that it is not possible to
 capture packets incoming only from one selected pod.
 
-Contiv/VPP ships with a simple bash script [vpptrace.sh](../scripts/vpptrace.sh)
+Contiv/VPP ships with a simple bash script [vpptrace.sh](../../scripts/vpptrace.sh)
 which helps to alleviate the aforementioned VPP limitations. The script automatically
 re-initializes buffer and trace whenever it is close to getting full in order to
 avoid packet loss as much as it is possible. Next it allows to filter packets

docs/VPPTRACE.md renamed to docs/debugging/VPPTRACE.md

@@ -2,7 +2,7 @@
 
 This document describes the steps to do *manual* packet tracing (capture) using
 VPP in Kubernetes. Contiv/VPP also ships with a simple bash script
-[vpptrace.sh](../scripts/vpptrace.sh), which allows to *continuously* trace and
+[vpptrace.sh](../../scripts/vpptrace.sh), which allows to *continuously* trace and
 *filter* packets incoming through a given set of interface types.
 Documentation for vpptrace.sh is available [here](VPPTRACE.md).
 

docs/VPP_PACKET_TRACING_K8S.md renamed to docs/debugging/VPP_PACKET_TRACING_K8S.md

@@ -1,4 +1,4 @@
-## Contiv-VPP Contributions
+## Contiv-VPP Contribution Guidelines
 
 Contributions to Contiv-VPP are welcome. We use the standard pull request
 model. You can either pick an open issue and assign it to yourself or open

docs/dev-guide/CONTRIBUTING.md

@@ -48,7 +48,7 @@ source code.
 
 ### Policy Plugin skeleton
 
-The [Policy Plugin Skeleton][policy-plugin] implements the [Ligato plugin API][plugin-intf],
+The [Policy Plugin Skeleton][policy-plugin] implements the [Ligato plugin API][cn-infra],
 which makes it pluggable with the Ligato CN-Infra framework.
 
 Inside the Policy Plugin's `Init()` method all the layers are initialized and
@@ -473,14 +473,14 @@ the configuration of K8s policies.
 [ligato-vpp-agent]: http://github.com/ligato/vpp-agent
 [local-client]: https://github.com/ligato/vpp-agent/tree/dev/clientv2
 [acl-plugin-vpp]: http://github.com/vpp-dev/vpp/tree/stable-1801-contiv/src/plugins/acl
-[acl-plugin-agent]: https://github.com/ligato/vpp-agent/tree/dev/plugins/vppv2/aclplugin
+[acl-plugin-agent]: https://github.com/ligato/vpp-agent/tree/master/plugins/vpp/aclplugin
 [vpptcp]: http://github.com/vpp-dev/vpp/tree/stable-1801-contiv/src/vnet/session
 [govpp]: https://wiki.fd.io/view/GoVPP
 [policy-plugin]: http://github.com/contiv/vpp/tree/master/plugins/policy/plugin_impl_policy.go
 [controller-plugin]: https://github.com/contiv/vpp/blob/master/plugins/controller/plugin_controller.go
 [transaction-api]: https://github.com/contiv/vpp/blob/master/plugins/controller/api/txn.go
 [ipv4net-plugin]: https://github.com/contiv/vpp/tree/master/plugins/ipv4net
-[plugin-intf]: http://github.com/ligato/cn-infra/tree/master/core/plugin_spi.go
+[cn-infra]: http://github.com/ligato/cn-infra
 [policy-model]: http://github.com/contiv/vpp/blob/master/plugins/ksr/model/policy/policy.proto
 [db-resources]: https://github.com/contiv/vpp/tree/master/dbresources
 [pod-model]: http://github.com/contiv/vpp/blob/master/plugins/ksr/model/pod/pod.proto

docs/dev-guide/POLICIES.md

@@ -16,4 +16,4 @@ Kubernetes services and policies implementation:
 * [Kubernetes services in Contiv/VPP](SERVICES.md)
 
 Other:
-* [Contribution guidelines](docs/dev-guide/CONTRIBUTING.md)
+* [Contribution guidelines](CONTRIBUTING.md)

docs/dev-guide/README.md

@@ -409,7 +409,7 @@ may not be useful for future renderers.
 #### Skeleton
 
 The [Service Plugin Skeleton][service-plugin-skeleton] implements the
-[Ligato plugin API][plugin-intf], which makes it pluggable with the Ligato
+[Ligato plugin API][cn-infra], which makes it pluggable with the Ligato
 CN-Infra framework.
 
 Inside the Service Plugin's `Init()` method both Processor and NAT44 Renderer
@@ -514,13 +514,13 @@ periodically cleaning up inactive NAT sessions.
 [vpp-nat-plugin-api]: https://github.com/vpp-dev/vpp/blob/stable-1801-contiv/src/plugins/nat/nat.api
 [service-plugin]: https://github.com/contiv/vpp/tree/master/plugins/service
 [service-plugin-skeleton]: https://github.com/contiv/vpp/blob/master/plugins/service/plugin_impl_service.go
-[plugin-intf]: http://github.com/ligato/cn-infra/tree/master/core/plugin_spi.go
+[cn-infra]: http://github.com/ligato/cn-infra
 [processor-api]: http://github.com/contiv/vpp/tree/master/plugins/service/processor/processor_api.go
 [processor-data-change]: http://github.com/contiv/vpp/tree/master/plugins/service/processor/data_change.go
 [processor-data-resync]: http://github.com/contiv/vpp/tree/master/plugins/service/processor/data_resync.go
 [renderer-api]: http://github.com/contiv/vpp/blob/master/plugins/service/renderer/api.go
 [nat-model]: https://github.com/ligato/vpp-agent/blob/dev/api/models/vpp/nat/nat.proto
-[vpp-agent-nat-plugin]: https://github.com/ligato/vpp-agent/tree/dev/plugins/vppv2/natplugin
+[vpp-agent-nat-plugin]: https://github.com/ligato/vpp-agent/tree/dev/plugins/vpp/natplugin
 [controller-plugin]: https://github.com/contiv/vpp/blob/master/plugins/controller/plugin_controller.go
 [transaction-api]: https://github.com/contiv/vpp/blob/master/plugins/controller/api/txn.go
 [ligato-vpp-agent]: http://github.com/ligato/vpp-agent

docs/dev-guide/SERVICES.md

@@ -7,7 +7,7 @@ on the port `32379` on each node.
 To secure the access to ETCD, we recommend using the SSL/TLS certificates to authenticate
 both client and server side and encrypt the communication.
 
-In Contiv-VPP, this can be done using the Helm charts in [k8s/contiv-vpp folder](../k8s/contiv-vpp).
+In Contiv-VPP, this can be done using the Helm charts in [k8s/contiv-vpp folder](../../k8s/contiv-vpp).
 
 The prerequisite for that is generation of SSL certificates.
 
@@ -86,4 +86,4 @@ Then you can go ahead and just deploy Contiv-VPP using this yaml file.
 
 Please note that the path of the mount folder with certificates, as well as certificate 
 file names can be customized using the config parameters of the Contiv-VPP chart, 
-as described in [this README](../k8s/contiv-vpp/README.md).
+as described in [this README](../../k8s/contiv-vpp/README.md).

docs/PROMETHEUS.md renamed to docs/operation/PROMETHEUS.md

@@ -5,7 +5,7 @@ Contiv-ksr is open to anybody. Contiv-vswitch exposes endpoints using port `9999
 
 To secure access to the endpoints, the SSL/TLS server certificate and basic auth (username password) can be configured.
 
-In Contiv-VPP, this can be done using the Helm charts in [k8s/contiv-vpp folder](../k8s/contiv-vpp).
+In Contiv-VPP, this can be done using the Helm charts in [k8s/contiv-vpp folder](../../k8s/contiv-vpp).
 
-To generate server certificate the approach described in [ETCD security](ETCD_SECURITY) can be leveraged.
+To generate server certificate the approach described in [ETCD security](ETCD_SECURITY.md) can be leveraged.
 

docs/TOOLS.md renamed to docs/operation/TOOLS.md

@@ -99,7 +99,7 @@ To define memory limit, append the following snippet to vswitch container in dep
                 memory: 1024Mi
 
 ```
-or set `contiv.vswitch.defineMemoryLimits` to `true` in [helm values](../k8s/contiv-vpp/README.md).
+or set `contiv.vswitch.defineMemoryLimits` to `true` in [helm values](../../k8s/contiv-vpp/README.md).
 
 ### (2/4) Initializing your master
 Before initializing the master, you may want to [tear down][8] up any
@@ -120,7 +120,7 @@ kubeadm init --token-ttl 0 --pod-network-cidr=10.1.0.0/16 --apiserver-advertise-
 **Note:** The CIDR specified with the flag `--pod-network-cidr` is used by
 kube-proxy, and it **must include** the `PodSubnetCIDR` from the `IPAMConfig`
 section in the Contiv-vpp config map in Contiv-vpp's deployment file
-([contiv-vpp.yaml](../k8s/contiv-vpp.yaml)). Pods in the host network namespace
+([contiv-vpp.yaml](../../k8s/contiv-vpp.yaml)). Pods in the host network namespace
 are a special case; they share their respective interfaces and IP addresses with
 the host. For proxying to work properly it is therefore required for services
 with backends running on the host to also **include the node management IP**
@@ -455,10 +455,10 @@ rm -rf /var/bolt/bolt.db
 [6]: https://kubernetes.io/docs/setup/independent/install-kubeadm/
 [8]: #tearing-down-kubernetes
 [10]: #setting-up-custom-management-network-on-multi-homed-nodes
-[11]: ../vagrant/README.md
+[11]: ../../vagrant/README.md
 [12]: CUSTOM_MGMT_NETWORK.md
 [13]: VMWARE_FUSION_HOST.md
 [14]: SINGLE_NIC_SETUP.md
 [15]: MULTI_NIC_SETUP.md
 [16]: SINGLE_NIC_SETUP.md#configuring-stn-in-contiv-vpp-k8s-deployment-files
-[17]: ../k8s/README.md#setup-node-sh
+[17]: ../../k8s/README.md#setup-node-sh

docs/CUSTOM_MGMT_NETWORK.md renamed to docs/setup/CUSTOM_MGMT_NETWORK.md

@@ -7,7 +7,7 @@ described [here](https://github.com/contiv/vpp/blob/master/docs/VPP_CONFIG.md#mu
 ##### Global configuration:
 Global configuration is used in homogeneous environments where all nodes in
 a given cluster have the same hardware configuration. If you want use DHCP to configure
-node IPs. Put the following stanza into the [`contiv.conf`](../k8s/contiv-vpp.yaml) deployment file:
+node IPs. Put the following stanza into the [`contiv.conf`](../../k8s/contiv-vpp.yaml) deployment file:
 ```
 data:
   contiv.conf: |-

docs/ETCD_SECURITY.md renamed to docs/setup/ETCD_SECURITY.md

@@ -36,8 +36,8 @@ The expected logs would look like the following excerpt:
 2018/02/23 10:08:34 Starting the STN GRPC server at port 50051
 ```
 
-For more details, please read the Go documentation for [contiv-stn](../cmd/contiv-stn/doc.go)
-and [contiv-init](../cmd/contiv-init/doc.go).
+For more details, please read the Go documentation for [contiv-stn](../../cmd/contiv-stn/doc.go)
+and [contiv-init](../../cmd/contiv-init/doc.go).
 
 #### Creating VPP interface configuration
 Create the VPP configuration for the hardware interface as described 
@@ -142,4 +142,4 @@ docker ps -q -f name=contiv-stn
 ```
 No containers should be listed.
 
-[1]: ../k8s/contiv-vpp.yaml
+[1]: ../../k8s/contiv-vpp.yaml

docs/HTTP_SECURITY.md renamed to docs/setup/HTTP_SECURITY.md

@@ -63,7 +63,7 @@ index 8d1d270a0..4b249c349 100644
      enablePeriodicHealing: false
 ``` 
 
-Please note that this config can be specified using the [helm chart](../k8s/contiv-vpp), 
+Please note that this config can be specified using the [helm chart](../../k8s/contiv-vpp), 
 and the node config also via CRD.
 
 ## STN Usage

docs/MANUAL_INSTALL.md renamed to docs/setup/MANUAL_INSTALL.md

@@ -1,6 +1,6 @@
 # Contiv VPP UI
 
-Project page: [https://contivpp.io/](https://contivpp.io)
+Demo: [video at contivpp.io](https://contivpp.io/docs/concepts/contivpp-io-demo-ui/)
 
 This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 7.0.2.
 

docs/MULTI_NIC_SETUP.md renamed to docs/setup/MULTI_NIC_SETUP.md

@@ -31,7 +31,7 @@ Environment variable | Description | Default
 `K8S_MASTER_MEMORY` | Memory size for master node | `4096`
 `K8S_NODE_MEMORY` | Memory size for worker nodes | `4096`
 `K8S_VERSION` | Kubernetes version to be installed | `1.11.5`
-`K8S_DEPLOYMENT_SCENARIO` | Contiv deployment scenario to be used [`stn`](../docs/SINGLE_NIC_SETUP.md) or `nostn` | `nostn`
+`K8S_DEPLOYMENT_SCENARIO` | Contiv deployment scenario to be used [`stn`](../docs/setup/SINGLE_NIC_SETUP.md) or `nostn` | `nostn`
 `CONTIV_IMAGE_TAG` | Docker image tag denoting contiv/vpp version to be installed | `latest`
 `CRD_DISABLED` | If set to `true` nodeconfig must be set in contiv deployment file. Otherwise it is configure using crd. | `true`
 `HELM_EXTRA_OPTS` | Allows to pass arbitrary helm option see [available parameters](../k8s/contiv-vpp)| `""`