diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 40 | ||||
| -rw-r--r-- | docs/create_vl.png | bin | 0 -> 36106 bytes | |||
| -rw-r--r-- | docs/create_vnf.png | bin | 0 -> 47090 bytes | |||
| -rw-r--r-- | docs/img/default_pdf.png | bin | 0 -> 347636 bytes | |||
| -rw-r--r-- | docs/img/diagram.png | bin | 0 -> 128882 bytes | |||
| -rw-r--r-- | docs/krd_architecture.rst | 162 | ||||
| -rw-r--r-- | docs/sampleCommands.rst | 84 | ||||
| -rw-r--r-- | docs/swagger.yaml | 184 |
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 Binary files differnew file mode 100644 index 00000000..803b6da8 --- /dev/null +++ b/docs/create_vl.png diff --git a/docs/create_vnf.png b/docs/create_vnf.png Binary files differnew file mode 100644 index 00000000..27b50d79 --- /dev/null +++ b/docs/create_vnf.png diff --git a/docs/img/default_pdf.png b/docs/img/default_pdf.png Binary files differnew file mode 100644 index 00000000..a783cb3b --- /dev/null +++ b/docs/img/default_pdf.png diff --git a/docs/img/diagram.png b/docs/img/diagram.png Binary files differnew file mode 100644 index 00000000..897801da --- /dev/null +++ b/docs/img/diagram.png 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 |
