Microservice SDK Overview

The Microservice SDK provides the steps and detailed understanding needed to start creating microservices for Oracle Communications Unified Assurance.

The SDK consists of a Unified Assurance package called sdk-lib that you install manually as described in Installing the SDK. Most of the steps in this document assume you are building on a single-server development instance of Unified Assurance. While this document is helpful for starting your development, Oracle recommends attending training courses for microservices to gain a firm grasp of all the details necessary.

The sdk-lib package includes the following examples:

Architecture

For information about the microservice cluster architecture, see Understanding Microservices in Unified Assurance Concepts. You should have a firm understanding of each component in the solution.

Container Image Recommendations

Build the container image with a multi-stage build:

  1. In the first stage, build microservice images by requiring all the build dependencies

  2. In the second stage, save only the necessary applications and files.

Helm Chart Additions

Unified Assurance has an opinionated set of additions to the standard configuration of Helm charts:

See the Helm documentation for more information about Helm charts.

Microservice Requirements

Before building your microservice, you must understand the requirements and recommendations described in this section.

Programming Language Recommendations

Because microservices are language-agnostic, you can use any programing language. Oracle recommends the following options, depending on your needs:

Note:

You can alternatively use the Java Microservices SDK to create microservices in Java. See Java Microservice SDK.

Application Requirements

When developing microservice, you must meet the requirements described in this section in order to fit seamlessly into the Unified Assurance Hyperscale Architecture. Oracle also recommends following the twelve-factor app methodology. See 12factor.net for information.

Developing a Microservice

To develop your microservice:

  1. Build the microservice. This involves preparing the template based on the SDK sample, coding the microservice, and building the image and Helm chart.

  2. Distribute the microservice. This involves adding the microservice image and Helm chart to the Helm repository, and creating a Unified Assurance package to distribute the microservice to other servers in your environment.

  3. Deploy the microservice. This involves installing the microservice on the cluster in your Unified Assurance environment.

Building the Microservice

  1. Prepare the template:

    1. Set standard environment variables:

      source <UA_home>/.bashrc

      By default, <UA_home> is /opt/assure1/. If you used a custom home directory, this will be different.

    2. Set the following variables to values that are appropriate for your project: 

      export APPNAME=<microservice_name>
export APPVERSION=<application_version>
export CHARTVERSION=<chart_version>
export DEVELDIR=$A1BASEDIR/tmp/$APPNAME
export PRESWEBFQDN=<presentation_server_web_FQDN>

      APPVERSION and CHARTVERSION should match semantic versions.

    3. Copy the template to your development directory and replace the template name with your microservice name:

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

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

  2. Code the microservice, add configurations, and adjust the Helm chart as needed.

  3. Update the list of dependencies:

    go get -u ./...

  4. Build the container image by running the following command as the assure1 user:

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

  5. Package the Helm chart:

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

  6. Proceed to Distributing the Microservice.

Distributing the Microservice

You can distribute the image locally or remotely.

Manual Local Distribution

If you are building and testing on your local development instance of Unified Assurance, run the following commands as the assure1 user:

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

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

This tags the image with the appropriate repository, pushes it to the repository, removes the local image, copies the chart to the chartmuseum, and updates the repository with the chart.

Proceed to Creating the Unified Assurance Package

Manual Remote Distribution

If you are building on your local development instance but will distribute and deploy on a separate instance, run the following commands to push the image to the presentation server repository:

  1. Locally, zip up the image by running the following command as the assure1 user:

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

  2. Copy the archived image ($APPNAME-$APPVERSION.tgz) and chart ($APPNAME-$CHARTVERSION.tgz) to your presentation server.

  3. On the presentation server, run the following commands as the assure1 user:

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

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

    This loads the image into container storage, tags the image with the appropriate repository, pushes it to the repository, and removes the local image, copies the chart to the chartmuseum, and updates the repository with the chart.

  4. Proceed to Creating the Unified Assurance Package

Creating the Unified Assurance Package

You can create a Unified Assurance package to distribute microservice images and Helm charts. See Package in Unified Assurance Implementation Guide for complete information about the Package application.

To create the Unified Assurance package:

  1. Prepare the package directory by running the following commands as the assure1 user:

    export PACKAGENAME=<microservice_package_name>-img
mkdir $DEVELDIR/$PACKAGENAME/img
mkdir $DEVELDIR/$PACKAGENAME/helm
a1podman 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

    This creates the required directories and saves the image and helm chart to them.

  2. Create a custom Package.def file. See About Package.def Files in the Core Interface SDK documentation for information about the required schema for Package.def files, and use the following values in your microservice package:

    • For the Version value, make sure to use the correct semantic version.

    • For the Directory key, use the following array, replacing <microservice_package_name> as appropriate for your new microservice package:

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

    • For the PostInstall key, use the following array:

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

      Note:

      $PACKAGEDIR is a token supported by the Unified Assurance Package application. It is replaced dynamically when creating the package with the values from the Directory key.

  3. Create the package:

    $A1BASEDIR/bin/Package create $DEVELDIR/$PACKAGENAME

You can distribute the package to other servers and use the Package install command to install it.

Deploying the Microservice

To deploy the new microservice to an existing Unified Assurance microservice cluster, run the following commands:

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

You can also use the Unified Assurance UI to deploy microservices. See Microservice Cluster Setup and Deploying a Microservice by Using the UI in Unified Assurance Implementation Guide for more information about setting up the microservice cluster and deploying microservices.