summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorVictor Morales <victor.morales@intel.com>2018-08-28 15:09:02 -0700
committerVictor Morales <victor.morales@intel.com>2018-08-30 10:11:00 -0700
commit574785c07010a494fbd1456d11e7c0449ad43c38 (patch)
treed0b8bc992752d5344a9de281e01558bd32b6071b /docs
parent88579fa6f563a3bea8c39aa98159eb54d13d44a5 (diff)
Add KRD source code
This changes includes the source code created for the Kubernetes Reference Deployment(KRD) which helps to provide an automated mechanism to install and configure Kubernetes services required for the MultiCloud/K8s plugin. Change-Id: Ica49566fcd531e25846ed3e5062de2f92ec56f6c Signed-off-by: Victor Morales <victor.morales@intel.com> Issue-ID: MULTICLOUD-301
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