Microservice SDK Overview¶

Overview¶

The Microservice SDK provides the steps and detailed understanding needed to start creating microservices for Assure1. The SDK is comprised of an Assure1 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 Assure1. While this guide is helpful for starting your development, it is recommended you attend the Federos Microservice Development training course to gain a firm grasp of all the details necessary.

Architecture¶

The architecture for Assure1 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.

More information can be found in the Docker Use multi-stage builds (https://docs.docker.com/develop/develop-images/multistage-build/) documentation.

Helm Chart¶

In addition to the standard configuration of Helm Charts, Assure1 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 (https://helm.sh/docs/) 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 Assure1 Hyperscale Architecture. Additionally, it is recommended that you are familiar with The Twelve-Factor App (https://12factor.net/) methodology.

Configuration¶

Microservices need to both gather configurations about the location of Assure1 API and database servers, as well as support configurations specific to the microservice itself. All Kubernetes Pods will automatically bind a ConfigMap for the Assure1 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 Assure1 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 Assure1 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 assure1 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 Assure1.

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

Assure1 Package¶

An Assure1 package can be created to distribute 1 or more microservice images and Helm charts. See the Package 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