Microservice Overview

Overview

The Microservice SDK provides the steps and detailed understanding needed to start creating microservices for Unified Assurance. The SDK is comprised of an Unified Assurance package called sdk-lib that must be installed manually. Most of the steps in this guide assume you are building on a single-server, development instance of Unified Assurance. While this guide is helpful for starting your development, it is recommended you attend the Oracle Communications Microservice Development training course to gain a firm grasp of all the details necessary.

Architecture

The architecture for Unified Assurance Hyperscale Clusters can be found in the Understanding Microservices document. You should have a firm understanding of each component in the solution.

Docker Image

Docker multi-stage builds should use a build pattern to first build microservice images by requiring all the build dependencies in the first stage, and secondly save only the necessary applications and files in a minimal second stage.

See the discussion of multi-stage builds in the Docker documentation for more information.

Helm Chart

In addition to the standard configuration of Helm Charts, Unified Assurance has an opinionated set of additions.

The first addition is a global imageRegistry variable must exist and be set during the installation of a Helm release. This variable needs to point to the primary presentation server WebFQDN. All references to images in the yaml templates must be prefixed with the imageRegistry variable.

The second addition is a set of configData key/value pairs used to provide configuration to your microservice. The keys should be all upper-case with words separated by underscores as is the convention for environment variables.

More information can be found in the Helm documentation.

Development

Languages

The benefit of microservices being language agnostic means there is no limitation on which programing language is used. That being said, there are 3 programming languages we recommend for various purposes. The primary recommendation is Go (GoLang) for its ability handle concurrency and compile down to small application binaries. The second recommendation is Node.js for its vast module library and familiarity by a wide range of developers. The final recommendation is Python when the need is for machine learning and analytic libraries.

Application Requirements

Every microservice must be written to handle the following requirements in order to fit seamlessly into the Unified Assurance Hyperscale Architecture. Oracle recommends following the twelve-factor app methodology. See 12factor.net for information.

Configuration

Microservices need to both gather configurations about the location of Unified Assurance API and database servers, as well as support configurations specific to the microservice itself. All Kubernetes Pods will automatically bind a ConfigMap for the Unified Assurance configuration located at /config/assure1.yaml. Microservice configurations should support sane defaults that can be overridden with environment variables.

Certificates

Microservices need to use certificates and keys, located in /cert/a1, for both validating the Unified Assurance services being connected to as well as authenticating to those services. Additionally, each Kubernetes namespace will have a wildcard certificate and key, located in /cert/ns, available for serving content if needed.

Logging

Microservices need to log to stderr (stdout alternatively) in Newline Delimited JSON (http://ndjson.org/) format. Required fields include: - @timestamp in RFC3339 format - level string in set (FATAL, ERROR, WARN, INFO, DEBUG, TRACE) - message - app

Instrumentation

Microservices need to gather internal metrics about the health, processing, and state of themselves by exposing Prometheus metrics. The default recommended port is 8080 at the endpoint /metrics.

Examples

goexample

The goexample microservice provides examples of several different capabilities including connecting to the Pulsar message bus, connecting to the database and making queries, and making a request to the Unified Assurance REST API. It is not a fully functional microservice, but an introduction to those capabilities.

gotemplate

The gotemplate microservice is an example template that can be used to kickstart the development of a microservice. The build examples below will use this template.

Build

Preparation

Set the exported variables to the values that are appropriate for your project. The APPVERSION and CHARTVERSION have slightly different formats but should match semantic versions. Some variables below are automatically available if running on the CLI as the assure1 user. If you are running as another user, you should source them from .bashrc or .assure1_bashrc in the Unified Assurance installation directory.

export APPNAME=mygomicroservice
export APPVERSION=v5.0.0-1
export CHARTVERSION=5.0.0
export DEVELDIR=/tmp/$APPNAME
export PRESWEBFQDN=pres.example.com

cp -a $A1BASEDIR/sdk/microservice/gotemplate $DEVELDIR

cd $DEVELDIR
find . -type file -exec sed -i -e "s/gotemplate/$APPNAME/g" {} \;

Once the stub for your new microservice is ready, code the application, add configurations, and adjust Helm chart as needed.

Update the list of dependencies.

go get -u ./...

Once ready, build the Docker image and Helm chart.

Docker Image

a1docker build -t assure1/$APPNAME:$APPVERSION .

Helm Chart

a1helm package helm --app-version $APPVERSION --version $CHARTVERSION

Distribution

Manual Local Distribution

Follow these steps if you are building and testing on your local development instance of Unified Assurance.

a1docker tag assure1/$APPNAME:$APPVERSION $PRESWEBFQDN/assure1/$APPNAME:$APPVERSION
a1docker push $PRESWEBFQDN/assure1/$APPNAME:$APPVERSION
a1docker rmi assure1/$APPNAME:$APPVERSION

cp $APPNAME-$CHARTVERSION.tgz $A1BASEDIR/var/chartmuseum
a1helm repo update

Manual Remote Distribution

Follow these steps if you are building on your local development instance but will distribute and deploy on a separate instance.

a1docker save assure1/$APPNAME:$APPVERSION | gzip --stdout > $APPNAME-$APPVERSION.tgz

Manually copy $APPNAME-$APPVERSION.tgz and $APPNAME-$CHARTVERSION.tgz to your presentation server and run these commands as the assure1 user.

a1docker load --input $APPNAME-$APPVERSION.tgz
a1docker tag assure1/$APPNAME:$APPVERSION $PRESWEBFQDN/assure1/$APPNAME:$APPVERSION
a1docker push $PRESWEBFQDN/assure1/$APPNAME:$APPVERSION
a1docker rmi assure1/$APPNAME:$APPVERSION

cp $APPNAME-$CHARTVERSION.tgz $A1BASEDIR/var/chartmuseum
a1helm repo update

Unified Assurance Package

A Unified Assurance package can be created to distribute 1 or more microservice images and Helm charts. See the Package Manager documentation.

export PACKAGENAME=customFooBarMicroservice-img
bin/Package add $DEVELDIR/$PACKAGENAME
mkdir $DEVELDIR/$PACKAGENAME/img
mkdir $DEVELDIR/$PACKAGENAME/helm
a1docker save assure1/$APPNAME:$APPVERSION | gzip --stdout > $DEVELDIR/PACKAGENAME/img/IMAGES.tgz
echo assure1/$APPNAME-$APPVERSION >> $DEVELDIR/PACKAGENAME/img/IMAGES.txt
cp $APPNAME-$CHARTVERSION.tgz $DEVELDIR/PACKAGENAME/helm

In addition to the steps above, you need to configure the Package.def to support installing correctly.

"Directory": [
    {
        "Type":      "img",
        "Directory": "distrib/images/customFooBarMicroservice"
    },
    {
        "Type":      "helm",
        "Directory": "var/chartmuseum"
    }
],

"PostInstall": [
    "dockerLoadImages('$PACKAGEDIR_img/IMAGES.tgz')",
    "registryLoadImages('$PACKAGEDIR_img/IMAGES.txt')",
    "remove('$PACKAGEDIR_img/IMAGES.tgz')"
],

Finally, create the package.

bin/Package create $DEVELDIR/$PACKAGENAME

Deployment

a1helm repo update
a1helm install $APPNAME assure1/$APPNAME -n a1-zone1-pri --set global.imageRegistry=$PRESWEBFQDN