1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. SPDX-License-Identifier CC-BY-4.0
.. (c) Authors of Clover
.. _controller_services_config_guide:
==============================================
Clover Controller Services Configuration Guide
==============================================
This document provides a guide to use the Clover controller services, which are introduced in
the Clover Gambia release.
Overview
=========
Clover controller services allow users to control and access information about Clover
microservices. Two new components are added to Clover to facilitate an ephemeral, cloud native
workflow. A CLI interface with the name **cloverctl** interfaces to the Kubernetes (k8s)
API and also to **clover-controller**, a microservice deployed within the k8s cluster to
instrument other Clover k8s services including sample network services, visibility/validation
services and supporting datastores (redis, cassandra). The **clover-controller** service
provides message routing communicating REST with cloverctl or other API/UI interfaces and
gRPC to internal k8s cluster microservices. It acts as an internal agent and reduces the need
to expose multiple Clover services outside of a k8s cluster.
The **clover-controller** is packaged as a docker container with manifests to deploy
in a Kubernetes (k8s) cluster. The **cloverctl** CLI is packaged as a binary (Golang) within a
tarball with associated yaml files that can be used to configure and control other Clover
microservices within the k8s cluster via **clover-controller**. The **cloverctl** CLI can also
deploy/delete other Clover services within the k8s cluster for convenience.
The **clover-controller** service provides the following functions:
* **REST API:** interface allows CI scripts/automation to control sample network sample services,
visibility and validation services. Analyzed visibility data can be consumed by other
services with REST messaging.
* **CLI Endpoint:** acts as an endpoint for many **cloverctl** CLI commands using the
**clover-controller** REST API and relays messages to other services via gRPC.
* **UI Dashboard:** provides a web interface exposing visibility views to interact with
Clover visibility services. It presents analyzed visibility data and provides basic controls
such as selecting which user services visibility will track.
.. image:: imgs/controller_services.png
:align: center
:scale: 100%
The **cloverctl** CLI command syntax is similar to k8s kubectl or istio istioctl CLI tools, using
a <verb> <noun> convention.
Help can be accessed using the ``--help`` option, as shown below::
$ cloverctl --help
Deploying Clover system services
================================
Prerequisites
-------------
The following assumptions must be met before continuing on to deployment:
* Installation of Docker has already been performed. It's preferable to install Docker CE.
* Installation of k8s in a single-node or multi-node cluster.
.. _controller_services_cli:
Download Clover CLI
-------------------
Download the cloverctl binary from the location below::
$ curl -L https://github.com/opnfv/clover/raw/stable/gambia/download/cloverctl.tar.gz | tar xz
$ cd cloverctl
$ export PATH=$PWD:$PATH
To begin deploying Clover services, ensure the correct k8s context is enabled. Validate that
the CLI can interact with the k8s API with the command::
$ cloverctl get services
The command above must return a listing of the current k8s services similar to the output of
'kubectl get svc --all-namespaces'.
.. _controller_services_controller:
Deploying clover-controller
---------------------------
To deploy the **clover-controller** service, use the command below:
.. code-block:: bash
$ cloverctl create system controller
The k8s pod listing below must include the **clover-controller** pod in the **clover-system**
namespace:
.. code-block:: bash
$ kubectl get pods --all-namespaces | grep clover-controller
NAMESPACE NAME READY STATUS
clover-system clover-controller-74d8596bb5-jczqz 1/1 Running
Exposing clover-controller
==========================
To expose the **clover-controller** deployment outside of the k8s cluster, a k8s NodePort
or LoadBalancer service must be employed.
Using NodePort
--------------
To use a NodePort for the **clover-controller** service, use the following command::
$ cloverctl create system controller nodeport
The NodePort default is to use port 32044. To modify this, edit the yaml relative
to the **cloverctl** path at ``yaml/controller/service_nodeport.yaml`` before invoking
the command above. Delete the ``nodePort:`` key in the yaml to let k8s select an
available port within the the range 30000-32767.
Using LoadBalancer
------------------
For k8s clusters that support a LoadBalancer service, such as GKE, one can be created for
**clover-controller** with the following command::
$ cloverctl create system controller lb
Setup with cloverctl CLI
------------------------
The **cloverctl** CLI will communicate with **clover-controller** on the service exposed above
and requires the IP address of either the load balancer or a cluster node IP address, if a
NodePort service is used. For a LoadBalancer service, **cloverctl** will automatically find
the IP address to use and no further action is required.
However, if a NodePort service is used, an additional step is required to configure the IP
address for **cloverctl** to target. This may be the CNI (ex. flannel/weave) IP address or the IP
address of an k8s node interface. The **cloverctl** CLI will automatically determine the
NodePort port number configured. To configure the IP address, create a file named
``.cloverctl.yaml`` and add a single line to the yaml file with the following::
ControllerIP: <IP addresss>
This file must be located in your ``HOME`` directory or in the same directory as the **cloverctl**
binary.
Uninstall from Kubernetes environment
=====================================
Delete with Clover CLI
-----------------------
When you're finished working with Clover system services, you can uninstall it with the
following command:
.. code-block:: bash
$ cloverctl delete system controller
$ cloverctl delete system controller nodeport # for NodePort
$ cloverctl delete system controller lb # for LoadBalancer
The commands above will remove the clover-controller deployment and service resources
created from the current k8s context.
Uninstall from Docker environment
=================================
The OPNFV docker image for the **clover-controller** can be removed with the following commands
from nodes in the k8s cluster.
.. code-block:: bash
$ docker rmi opnfv/clover-controller
|
