From a3c42d29f8e42d4dd200f1504b6bad5c3357e3c1 Mon Sep 17 00:00:00 2001 From: Cong Phuoc Hoang Date: Mon, 22 Jan 2018 01:17:40 +0900 Subject: [PATCH] Add document and release note for containerised vnf feature 1. Add user usage guide doc/source/user/containerized_vnf_usage_guide.rst 2. Add release note Change-Id: Ic762ff2c6025fa122071395289fc576dbb0532eb --- .../install/kubernetes_vim_installation.rst | 28 +- .../user/containerized_vnf_usage_guide.rst | 318 ++++++++++++++++++ ...t-containerised-vnfs-4885e45017a79a20.yaml | 3 + 3 files changed, 341 insertions(+), 8 deletions(-) create mode 100644 doc/source/user/containerized_vnf_usage_guide.rst create mode 100644 releasenotes/notes/add-support-containerised-vnfs-4885e45017a79a20.yaml diff --git a/doc/source/install/kubernetes_vim_installation.rst b/doc/source/install/kubernetes_vim_installation.rst index 56e47e36f..b80b1c704 100644 --- a/doc/source/install/kubernetes_vim_installation.rst +++ b/doc/source/install/kubernetes_vim_installation.rst @@ -43,7 +43,7 @@ You can also see the same examples in [#first]_ and [#second]_. .. code-block:: console - ./stack.sh + $ ./stack.sh 3. Get Kubernetes VIM configuration @@ -51,7 +51,7 @@ You can also see the same examples in [#first]_ and [#second]_. .. code-block:: console - TOKEN=$(kubectl describe secret $(kubectl get secrets | grep default | cut -f1 -d ' ') | grep -E '^token' | cut -f2 -d':' | tr -d '\t') + $ TOKEN=$(kubectl describe secret $(kubectl get secrets | grep default | cut -f1 -d ' ') | grep -E '^token' | cut -f2 -d':' | tr -d '\t') In the Hyperkube folder /yourdirectory/data/hyperkube/, user can get more information for authenticating to Kubernetes cluster. @@ -97,6 +97,8 @@ example: password,user,uid,"group1,group2,group3" +In this example, the user belongs to group1, group2 and group3. + * Get Kubernetes server url By default Kubernetes server listens on https://127.0.0.1:6443 and @@ -104,7 +106,7 @@ https://{HOST_IP}:6443 .. code-block:: console - curl http://localhost:8080/api/ + $ curl http://localhost:8080/api/ { "kind": "APIVersions", "versions": [ @@ -126,7 +128,7 @@ the project k8s: .. code-block:: console - openstack network list --project admin + $ openstack network list --project admin +--------------------------------------+-----------------+--------------------------------------+ | ID | Name | Subnets | +--------------------------------------+-----------------+--------------------------------------+ @@ -223,7 +225,17 @@ authentication. .. code-block:: console - tacker vim-register --config-file vim_config.yaml vim-kubernetes + $ tacker vim-register --config-file vim_config.yaml vim-kubernetes + + $ tacker vim-list + +--------------------------------------+----------------------------------+----------------+------------+------------+------------------------------------------------------------+-----------+ + | id | tenant_id | name | type | is_default | placement_attr | status | + +--------------------------------------+----------------------------------+----------------+------------+------------+------------------------------------------------------------+-----------+ + | 45456bde-6179-409c-86a1-d8cd93bd0c6d | a6f9b4bc9a4d439faa91518416ec0999 | vim-kubernetes | kubernetes | False | {u'regions': [u'default', u'kube-public', u'kube-system']} | REACHABLE | + +--------------------------------------+----------------------------------+----------------+------------+------------+------------------------------------------------------------+-----------+ + +In ``placement_attr``, there are three regions: 'default', 'kube-public', +'kube-system', that map to ``namespace`` in Kubernetes environment. * Other related commands to Kubernetes VIM @@ -237,9 +249,9 @@ authentication. type: "kubernetes" - tacker vim-update vim-kubernetes --config-file kubernetes-VIM-update.yaml - tacker vim-show vim-kubernetes - tacker vim-delete vim-kubernetes + $ tacker vim-update vim-kubernetes --config-file kubernetes-VIM-update.yaml + $ tacker vim-show vim-kubernetes + $ tacker vim-delete vim-kubernetes When update Kubernetes VIM, user can update VIM information (such as username, password, bearer_token and ssl_ca_cert) except auth_url and type of VIM. diff --git a/doc/source/user/containerized_vnf_usage_guide.rst b/doc/source/user/containerized_vnf_usage_guide.rst new file mode 100644 index 000000000..a768ffbfb --- /dev/null +++ b/doc/source/user/containerized_vnf_usage_guide.rst @@ -0,0 +1,318 @@ +==================================================== +Experimenting containerized VNFs with Kubernetes VIM +==================================================== + +In the past, Tacker only supports creating virtual machine based VNF using +Heat. This section covers how to deploy `containerized VNF` using Kubernetes +VIM in Tacker. + +Prepare Kubernetes VIM +====================== + +To use Kubernetes type of VNF, firstly user must register Kubernetes VIM. +Tacker supports Kubernetes authentication with two types: basic authentication +(username and password) or Bearer token. User can secure the connection to +Kubernetes cluster by providing SSL certificate. The following +``vim-config.yaml`` file provides necessary information to register a +Kubernetes VIM. + +.. code-block:: console + + auth_url: "https://192.168.11.110:6443" + username: "admin" + password: "admin" + project_name: "default" + ssl_ca_cert: None + type: "kubernetes" + +More details about registering Kubernetes VIM, please refer [#first]_ + +Sample container TOSCA templates +================================ + +1. One container per VDU example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Currently, because Kubernetes does not support multiple networks such as +choosing networks, connection points for applications, therefore users only +deploys their applications with default networks (Pod and Service networks). +In this case, user need to provide only information about VDU to create a VNF +in Tacker. + +The following example shows TOSCA template of containerized VNF for pure +Kubernetes environment with one container per VDU. + +**tosca-vnfd-containerized-two-containers.yaml** + +.. code-block:: yaml + + tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0 + description: A sample containerized VNF with two containers per VDU + + metadata: + template_name: sample-tosca-vnfd + + topology_template: + node_templates: + VDU1: + type: tosca.nodes.nfv.VDU.Tacker + properties: + namespace: default + mapping_ports: + - "80:80" + - "88:88" + service_type: NodePort + vnfcs: + front_end: + num_cpus: 0.5 + mem_size: 512 MB + image: nginx + ports: + - "80" + rss_reader: + num_cpus: 0.5 + mem_size: 512 MB + image: nickchase/rss-php-nginx:v1 + ports: + - "88" + policies: + - SP1: + type: tosca.policies.tacker.Scaling + targets: [VDU1] + properties: + min_instances: 1 + max_instances: 3 + target_cpu_utilization_percentage: 40 + +In "vnfcs", there are 2 components: front_end and rss_reader. +We model them as Containers [#second]_ inside a Pod [#third]_. To provide +recover ability of these containers, we put all of containers inside a +Deployment [#fourth]_ object, that can warrant the number of replica with +auto-healing automatically. + +The following table shows details about parameter of a Container. Config is +translated to ConfigMap [#fifth]_, when user want to update the VNF (config), +equivalent ConfigMap will be updated. + +.. code-block:: console + + +-----------------------------------------------------------------------------------------------+ + | vnfcs | Example | Description | + +-----------------------------------------------------------------------------------------------+ + | name | front_end | Name of container | + +-----------------------------------------------------------------------------------------------+ + | num_cpus | 0.5 | Number of CPUs | + +-----------------------------------------------------------------------------------------------+ + | mem_size | 512 MB | Memory size | + +-----------------------------------------------------------------------------------------------+ + | image | nginx | Image to launch container | + +-----------------------------------------------------------------------------------------------+ + | ports | - "80" | Exposed ports in container | + +-----------------------------------------------------------------------------------------------+ + | command | ['/bin/sh','echo'] | Command when container was started | + +-----------------------------------------------------------------------------------------------+ + | args | ['hello'] | Args of command | + +-----------------------------------------------------------------------------------------------+ + | config | param0: key1 | Set variables | + | | param1: key2 | | + +-----------------------------------------------------------------------------------------------+ + +In Tacker, VDU is modeled as a Service [#sixth]_ in Kubernetes. Because Pods +can be easily replaced by others, when the number of replica increased, +workload should be shared between Pods. To do this task, we model VDU as +Service, it acts as a Load balancer for Pods. Currently, we support some +parameters as the following table. + +.. code-block:: console + + +--------------------------------------------------------------------------------------------------------------------------------+ + | VDU properties | Example | Description | + +--------------------------------------------------------------------------------------------------------------------------------+ + | namespace | default | Namespace in Kubernetes where all objects are deployed | + +--------------------------------------------------------------------------------------------------------------------------------+ + | mapping_ports | - "443:443" | Published ports and target ports (container ports) of Service Kubernetes | + | | - "80:8080" | | + +--------------------------------------------------------------------------------------------------------------------------------+ + | labels | "app: webserver" | Labels which is set for Kubernetes objects, it is used as Selector to | + | | | Service can send requests to Pods | + +--------------------------------------------------------------------------------------------------------------------------------+ + | service_type | ClusterIP | Set service type for Service object. | + | | | | + +--------------------------------------------------------------------------------------------------------------------------------+ + | vnfcs | | Vnfcs are modeled by Containers and Deployment object. User can limit | + | | | resource, set image, publish container ports, set commands and variables | + +--------------------------------------------------------------------------------------------------------------------------------+ + +User can also set scaling policy for VDU by adding the following policy. These +information is translated to Horizontal Pod Autoscaler in Kubernetes. In the +current scope, we just support auto-scaling with CPU utilization, more metrics +will be added in the future. + +.. code-block:: yaml + + policies: + - SP1: + type: tosca.policies.tacker.Scaling + targets: [VDU1] + properties: + min_instances: 1 + max_instances: 3 + target_cpu_utilization_percentage: 40 + +2. Two containers per VDU example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Similar to the above example, in this scenario, we define 2 containers in VDU1. + +**tosca-vnfd-containerized.yaml** + +.. code-block:: yaml + + tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0 + description: A sample containerized VNF with two containers per VDU + + metadata: + template_name: sample-tosca-vnfd + + topology_template: + node_templates: + VDU1: + type: tosca.nodes.nfv.VDU.Tacker + properties: + namespace: default + mapping_ports: + - "80:8080" + labels: + - "app: webserver" + service_type: ClusterIP + vnfcs: + web_server: + properties: + num_cpus: 0.5 + mem_size: 512 MB + image: celebdor/kuryr-demo + ports: + - 8080 + config: | + param0: key1 + param1: key2 + + policies: + - SP1: + type: tosca.policies.tacker.Scaling + targets: [VDU1] + properties: + min_instances: 1 + max_instances: 3 + target_cpu_utilization_percentage: 40 + +Viewing a containerized VNF +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create sample containerized VNF + +.. code-block:: console + + $ tacker vnfd-create --vnfd-file tosca-vnfd-containerized.yaml VNFD1 + Created a new vnfd: + +-----------------+-------------------------------------------------------------------------------------------------------+ + | Field | Value | + +-----------------+-------------------------------------------------------------------------------------------------------+ + | created_at | 2018-01-21 14:36:51.757044 | + | description | A sample containerized VNF with one container per VDU | + | id | fb4a0aa8-e410-4e73-abdc-d2808de155ef | + | name | VNFD1 | + | service_types | vnfd | + | template_source | onboarded | + | tenant_id | 2d22508be9694091bb2f03ce27911416 | + | updated_at | | + +-----------------+-------------------------------------------------------------------------------------------------------+ + + $ tacker vnf-create --vnfd-name VNFD1 --vim-name vim-kubernetes VNF1 + Created a new vnf: + +----------------+-------------------------------------------------------------------------------------------------------+ + | Field | Value | + +----------------+-------------------------------------------------------------------------------------------------------+ + | created_at | 2018-01-21 14:37:23.318018 | + | description | A sample containerized VNF with one container per VDU | + | error_reason | | + | id | 1faf776b-8d2b-4ee6-889d-e3b7c7310411 | + | instance_id | default,svc-vdu1-05db44 | + | mgmt_url | | + | name | VNF1 | + | placement_attr | {"vim_name": "vim-kubernetes"} | + | status | PENDING_CREATE | + | tenant_id | 2d22508be9694091bb2f03ce27911416 | + | updated_at | | + | vim_id | 791830a6-45fd-468a-bd85-e07fe24e5ce3 | + | vnfd_id | fb4a0aa8-e410-4e73-abdc-d2808de155ef | + +----------------+-------------------------------------------------------------------------------------------------------+ + + $ tacker vnf-list + +--------------------------------------+------+----------------------------+--------+--------------------------------------+--------------------------------------+ + | id | name | mgmt_url | status | vim_id | vnfd_id | + +--------------------------------------+------+----------------------------+--------+--------------------------------------+--------------------------------------+ + | 1faf776b-8d2b-4ee6-889d-e3b7c7310411 | VNF1 | | ACTIVE | 791830a6-45fd-468a-bd85-e07fe24e5ce3 | fb4a0aa8-e410-4e73-abdc-d2808de155ef | + +--------------------------------------+------+----------------------------+--------+--------------------------------------+--------------------------------------+ + +To test VNF is running in Kubernetes environment, we can check by running +following commands + +.. code-block:: console + + $ kubectl get svc + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + kubernetes ClusterIP 192.168.28.129 443/TCP 5h + svc-vdu1-05db44 ClusterIP 192.168.28.187 80/TCP 12m + + $ kubectl get deployment + NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE + svc-vdu1-05db44 1 1 1 1 16m + + $ kubectl get pod + NAME READY STATUS RESTARTS AGE + svc-vdu1-05db44-7dcb6b955d-wkh7d 1/1 Running 0 18m + + $ kubectl get hpa + NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE + svc-vdu1-05db44 Deployment/svc-vdu1-05db44 / 40% 1 3 1 17m + + $ kubectl get configmap + NAME DATA AGE + svc-vdu1-05db44 2 17m + +User also can scale VNF manually, by running the following commands: + +.. code-block:: console + + $ tacker vnf-scale --vnf-name VNF1 --scaling-policy-name SP1 --scaling-type out + + $ kubectl get deployment + NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE + svc-vdu1-651815 2 2 2 1 3h + + $ kubectl get pods + NAME READY STATUS RESTARTS AGE + svc-vdu1-651815-5b894b8bfb-b6mzq 2/2 Running 0 3h + svc-vdu1-651815-5b894b8bfb-b7f2c 2/2 Running 0 40s + +In the same way, user also scale in VNF with scaling-type is 'in'. The range +of scaling manually is limited by 'min_instances' and 'max_instances' user +provide in VNF template. + +Known Issues and Limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Does not support Volumes in Kubernetes +- Horizontal Pod AutoScaler only support CPU utilization +- Add support Kuryr-Kubernetes for making hybrid network in the future + +References +========== +.. [#first] https://github.com/openstack/tacker/blob/master/doc/source/install/kubernetes_vim_installation.rst +.. [#second] https://kubernetes.io/docs/concepts/workloads/pods/init-containers +.. [#third] https://kubernetes.io/docs/concepts/workloads/pods/pod-overview +.. [#fourth] https://kubernetes.io/docs/concepts/workloads/controllers/deployment +.. [#fifth] https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap +.. [#sixth] https://kubernetes.io/docs/concepts/services-networking/service + diff --git a/releasenotes/notes/add-support-containerised-vnfs-4885e45017a79a20.yaml b/releasenotes/notes/add-support-containerised-vnfs-4885e45017a79a20.yaml new file mode 100644 index 000000000..c283f140c --- /dev/null +++ b/releasenotes/notes/add-support-containerised-vnfs-4885e45017a79a20.yaml @@ -0,0 +1,3 @@ +--- +features: + - Add containerised vnf support to Kubernetes VIM