summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/conf.py40
-rw-r--r--docs/create_vl.pngbin0 -> 36106 bytes
-rw-r--r--docs/create_vnf.pngbin0 -> 47090 bytes
-rw-r--r--docs/img/default_pdf.pngbin0 -> 347636 bytes
-rw-r--r--docs/img/diagram.pngbin0 -> 128882 bytes
-rw-r--r--docs/krd_architecture.rst162
-rw-r--r--docs/sampleCommands.rst84
-rw-r--r--docs/swagger.yaml184
8 files changed, 470 insertions, 0 deletions
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 00000000..2e30879a
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
+
+sys.path.insert(0, ROOT)
+sys.path.insert(0, BASE_DIR)
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+ 'sphinx.ext.autodoc',
+ #'sphinx.ext.intersphinx'
+]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'MultiCloud Kubernetes Plugin'
diff --git a/docs/create_vl.png b/docs/create_vl.png
new file mode 100644
index 00000000..803b6da8
--- /dev/null
+++ b/docs/create_vl.png
Binary files differ
diff --git a/docs/create_vnf.png b/docs/create_vnf.png
new file mode 100644
index 00000000..27b50d79
--- /dev/null
+++ b/docs/create_vnf.png
Binary files differ
diff --git a/docs/img/default_pdf.png b/docs/img/default_pdf.png
new file mode 100644
index 00000000..a783cb3b
--- /dev/null
+++ b/docs/img/default_pdf.png
Binary files differ
diff --git a/docs/img/diagram.png b/docs/img/diagram.png
new file mode 100644
index 00000000..897801da
--- /dev/null
+++ b/docs/img/diagram.png
Binary files differ
diff --git a/docs/krd_architecture.rst b/docs/krd_architecture.rst
new file mode 100644
index 00000000..f188135e
--- /dev/null
+++ b/docs/krd_architecture.rst
@@ -0,0 +1,162 @@
+.. Copyright 2018 Intel Corporation.
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+****************
+KRD Architecture
+****************
+
+This document explains the different components of the Kubernetes
+Reference Deployment project and how they can be configured to modify
+its default behaviour.
+
+Vagranfile
+##########
+
+This file describes how the Virtual Machines are going to be
+configured and the scripts and arguments used during their
+provisioning process. This file uses *elastic/ubuntu-16.04-x86_64*
+vagrant box for VirtualBox and Libvirt providers.
+
+config/
+#######
+
+This folder contains the POD Descriptor File (PDF) which is used
+by Vagrant during the provisioning process. The *samples* folder
+contains examples for some setups (All-in-One, Mini, NoHA, HA, etc.)
+that can be used.
+
+This list contains the valid entries used by Vagrant to define the virtual
+resources used by Vagrant during the creation of the Virtual Machines:
+
+ * ip - The static IP address assigned to the VM. (String value)
+ * memory - The amount of memory RAM. (KB - Integer value)
+ * cpus - Number of CPUs. (Integer value)
+ * volumes - List of volumes to be formatted and mounted to the VM.
+
+config/default.yml
+******************
+
+If there is no *pdf.yml* file present in *config* folder, Vagrant will
+use the information specified in the **config/default.yml**. The following
+diagram displays how the services are installed in the nodes using the
+default configuration.
+
+.. image:: ./img/default_pdf.png
+
+docs/
+#####
+
+This folder contains documentation files using reStructuredText
+(RST) syntax. It's possible to generate documentation in *html*
+format using `python tox module <https://tox.readthedocs.io/en/latest/>`_
+. Once this is installed, it's possible to build html files using
+this following command:
+
+.. code-block:: bash
+
+ tox -e docs
+
+After its execution, the **docs/build** subfolder will contain
+subfolders and html files that can be opened from any web browser.
+
+galaxy-requirements.yml
+#######################
+
+This file contains third party Ansible roles. Only those tasks which
+are not related with the main installation process have been placed in
+this file.
+
+installer.sh
+############
+
+Main bash script that installs dependencies and executes ansible
+playbooks for provisioning KRD components on external nodes. This
+script uses some arguments for the additional installation of
+components. For more information about its usage:
+
+.. code-block:: bash
+
+ ./installer.sh -h
+
+inventory/
+##########
+
+This folder contains the Ansible host inventory file. The
+**inventory/host.ini** file, which is used during the execution of
+Ansible playbooks, is created by Vagrant using the values specified
+in the *config/pdf.yml* file (or *config/default.yml*).
+
+inventory/group_vars/k8s-cluster.yml
+************************************
+
+A preferred practice in Ansible is to not store variables in the
+main inventory file. The configuration variables required for
+`Kubespray <https://github.com/kubernetes-incubator/kubespray>`_ are
+stored in this file.
+
+node.sh
+#######
+
+This bash script is executed in every node after this has been
+provisioned. The script provides the possibility to partition and
+mount external volumes.
+
+playbooks/
+##########
+
+This folder contains a set of Ansible playbooks which perform the
+tasks required for configuring services like Multus, Virtlet and/or
+OVN.
+
+playbooks/configure-krd.yml
+***************************
+
+This ansible playbook collects the common actions among all the
+Kubernetes AddOns offered by the KRD.
+
+playbooks/krd-vars.yml
+************************
+
+This file centralizes the version numbers and source URLs used for
+different components offered by the KRD. Bumping a version requires
+extensive testing to ensure compatibility.
+
+setup.sh
+########
+
+This bash script is used for the installation and configuration of
+dependencies required for the usage of the KRD via Virtual Machines.
+Some of this dependencies are:
+
+ - `Vagrant <https://www.vagrantup.com/>`_,
+ - `Libvirt <https://libvirt.org/>`_ or `VirtualBox <https://www.virtualbox.org/>`_
+
+The *-p* argument determines the Virtualization provider to be used
+and installed in the host machine.
+
+.. code-block:: bash
+
+ ./setup.sh -p libvirt
+
+Vagrant uses VirtualBox as default Virtualization provider. It's
+possible to modify this behavior using the global enviroment variable
+named **VAGRANT_DEFAULT_PROVIDER**.
+
+.. note:: The execution of this script is recommended only during the initial setup.
+
+tests/
+######
+
+This folder contains the health check scripts that guarantee the
+proper installation/configuration of Kubernetes AddOns. Its
+execution is disabled by default. In order to enable it, it's
+necessary to pass the *-t* argument to the **installer.sh** bash
+script, usually through changing the arguments in the *Vagrantfile*.
diff --git a/docs/sampleCommands.rst b/docs/sampleCommands.rst
new file mode 100644
index 00000000..2407b260
--- /dev/null
+++ b/docs/sampleCommands.rst
@@ -0,0 +1,84 @@
+.. Copyright 2018 Intel Corporation.
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+====================
+Sample cURL commands
+====================
+
+****
+POST
+****
+
+URL: `localhost:8081/v1/vnf_instances/cloudregion1/namespacetest`
+
+Request Body
+------------
+
+.. code-block:: json
+
+ {
+ "cloud_region_id": "region1",
+ "csar_id": "uuid",
+ "namespace": "test",
+ "oof_parameters": [{
+ "key1": "value1",
+ "key2": "value2",
+ "key3": {}
+ }],
+ "network_parameters": {
+ "oam_ip_address": {
+ "connection_point": "string",
+ "ip_address": "string",
+ "workload_name": "string"
+ }
+ }
+ }
+
+Expected Response
+-----------------
+
+.. code-block:: json
+
+ {
+ "response": "Created Deployment:nginx-deployment"
+ }
+
+The above POST request will download the following YAML file and run it on the Kubernetes cluster.
+
+.. code-block:: yaml
+
+ apiVersion: apps/v1
+ kind: Deployment
+ metadata:
+ name: nginx-deployment
+ labels:
+ app: nginx
+ spec:
+ replicas: 3
+ selector:
+ matchLabels:
+ app: nginx
+ template:
+ metadata:
+ labels:
+ app: nginx
+ spec:
+ containers:
+ - name: nginx
+ image: nginx:1.7.9
+ ports:
+ - containerPort: 80
+
+***
+GET
+***
+
+URL: `localhost:8081/v1/vnf_instances`
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
new file mode 100644
index 00000000..3b7e36ba
--- /dev/null
+++ b/docs/swagger.yaml
@@ -0,0 +1,184 @@
+# Copyright 2018 Intel Corporation.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: "2.0"
+info:
+ description: "API reference for MultiCloud Kubernetes Plugin."
+ version: "1.0.0"
+ title: "API reference for MultiCloud Kubernetes Plugin."
+ contact:
+ url: "https://wiki.onap.org/display/DW/Support+for+K8S+%28Kubernetes%29+based+Cloud+regions"
+ license:
+ name: "Apache 2.0"
+ url: "http://www.apache.org/licenses/LICENSE-2.0.html"
+basePath: "/v1.0"
+schemes:
+- "http"
+paths:
+ /vnf_instances:
+ post:
+ tags:
+ - "Deployment of VNF Containers"
+ summary: "Create Kubernetes based VNFs."
+ description: "Endpoint to create Kubernetes based VNFs."
+ consumes:
+ - "application/json"
+ produces:
+ - "application/json"
+ parameters:
+ - in: "body"
+ name: "body"
+ description: "Create new VNF containers"
+ required: true
+ schema:
+ $ref: "#/definitions/POSTRequest"
+ responses:
+ 200:
+ description: "successful operation"
+ schema:
+ $ref: "#/definitions/POSTResponse"
+ /vnf_instances/:
+ get:
+ tags:
+ - "Deployment of VNF Containers"
+ summary: "List all Kubernetes based VNFs."
+ description: "Endpoint to list all Kubernetes based VNF."
+ produces:
+ - "application/json"
+ responses:
+ 200:
+ description: "successful operation"
+ schema:
+ $ref: "#/definitions/GETSResponse"
+ /vnf_instances/{name}:
+ get:
+ tags:
+ - "Deployment of VNF Containers"
+ summary: "Get details of a Kubernetes based VNFs."
+ description: "Endpoint to get details of a Kubernetes based VNFs."
+ produces:
+ - "application/json"
+ parameters:
+ - name: "name"
+ in: "path"
+ description: "Name used to query"
+ required: true
+ type: "string"
+ responses:
+ 200:
+ description: "successful operation"
+ schema:
+ $ref: "#/definitions/GETResponse"
+ patch:
+ tags:
+ - "Deployment of VNF Containers"
+ summary: "Update a Kubernetes based VNFs."
+ description: "Endp to update a Kubernetes based VNFs."
+ produces:
+ - "application/json"
+ parameters:
+ - name: "name"
+ in: "path"
+ description: "Name used to patch"
+ required: true
+ type: "string"
+ - name: "body"
+ in: "body"
+ description: "Patch an existing Kubernetes based VNFs."
+ required: true
+ schema:
+ $ref: "#/definitions/PATCHRequest"
+ responses:
+ 200:
+ description: "successful operation"
+ schema:
+ $ref: "#/definitions/PATCHResponse"
+ delete:
+ tags:
+ - "Deployment of VNF Containers"
+ summary: "Delete a Kubernetes based VNFs."
+ description: "Endpoint to delete a Kubernetes based VNFs."
+ produces:
+ - "application/json"
+ parameters:
+ - name: "name"
+ in: "path"
+ description: "Name used to delete"
+ required: true
+ type: "string"
+ responses:
+ 200:
+ description: "successful operation"
+ schema:
+ $ref: "#/definitions/DELETEResponse"
+definitions:
+ POSTRequest:
+ type: "object"
+ properties:
+ cloud_region_id:
+ type: "string"
+ csar_id:
+ type: "string"
+ namespace:
+ type: "string"
+ oof_parameters:
+ items:
+ type: "object"
+ additionalProperties: true
+ example:
+ key1: value1
+ key2: value2
+ key3: {}
+ network_parameters:
+ type: "object"
+ properties:
+ oam_ip_address:
+ type: "object"
+ properties:
+ connection_point:
+ type: "string"
+ ip_address:
+ type: "string"
+ workload_name:
+ type: "string"
+ POSTResponse:
+ type: "object"
+ properties:
+ vnf_id:
+ type: "string"
+ name:
+ type: "string"
+ GETSResponse:
+ type: "object"
+ properties:
+ vnf_list:
+ items:
+ type: "string"
+ GETResponse:
+ type: "object"
+ properties:
+ response:
+ type: "string"
+ PATCHRequest:
+ type: "object"
+ properties:
+ name:
+ type: "string"
+ PATCHResponse:
+ type: "object"
+ properties:
+ response:
+ type: "string"
+ DELETEResponse:
+ type: "object"
+ properties:
+ response:
+ type: "string" \ No newline at end of file