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.

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.

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’.

Deploying clover-controller

To deploy the clover-controller service, use the command below:

$ cloverctl create system controller

The k8s pod listing below must include the clover-controller pod in the clover-system namespace:

$ 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:

$ 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.

$ docker rmi opnfv/clover-controller