TMF Customized Microservices using TMF Builder

MATRIXX provides a continuous integration and continuous deployment (CI/CD) pipeline to deliver custom TM Forum (TMF) microservices using the MATRIXX TMF Integration Builder.

Use the TMF builder to customize your microservice so you can deploy the output from the builder in a production environment. The TMF builder image itself is not intended for a production environment.

This topic describes the steps necessary to set up a CI/CD pipeline for custom TMF microservices using the TMF Builder. You should be familiar with the procedures and concepts described in MATRIXX Installation and Upgrade.

The steps in the CI/CD process are:

Figure 1. TMF Builder CI/CD Pipeline Process
TMF Builder CI/CD Pipeline process flow
  1. Create — The TMF administrator creates a Git repository.
  2. Configure — The TMF administrator does a Git commit and push of the new TMF Builder customized files. Customized files include:
    • Jenkinsfile — Specifies the Jenkins job.
    • mdc_config_custom.xml — Specifies engine extensions.
    • custom-tmf-swagger.json — Extends the TMF microservice.
  3. Build — The code repository triggers a push event to Jenkins. Jenkins spawns an instance according to Jenkinsfile and Kubernetes configurations. The Jenkinsfile configuration includes the ENGINE_VERSION variable necessary to set the schema version. The following must also be set in Jenkins:
    • Registry credentials
    • Target Registry URL
    • Target Image Name
    • Target Image Tag (version)
  4. Push — The Agent executes the steps in the Jenkinsfile and pushes the resulting microservice image file to the image registry.
Before you begin, you must have:
  • A tmf-xxx-builder image, where xxx indicates the number of the microservice you are customizing. Each TMF microservice has its own TMF builder image.
  • A Jenkins environment with a customized Jenkinsfile. In the Jenkinsfile, customize the following:
    • ENGINE_VERSION — The MATRIXX Engine version.
    • TARGET_DOCKER_REPO_URL — The registry where the output image is pushed.
    • TARGET_IMAGE_NAME — The name of the target image.
    • TARGET_IMAGE_TAG— The tag of the target image.
    • The agent Docker image — The version of the TMF builder to use.

    The following is sample code for the pipeline stages:

    pipeline {
    environment {
        USER_CREDENTIALS = credentials("YOUR.CREDENTIAL")
        ENGINE_VERSION = '5261'
        TARGET_DOCKER_REPO_URL = 'YOUR_URL.COM'
        TARGET_IMAGE_NAME = 'tmf640-catalyst-tef2023'
        TARGET_IMAGE_TAG = '1.0.2'
    }    
    agent {
        docker {
            image 'a.j.m0012242008.com/mtx-docker-eng-snapshot/tmf-640-builder:1.0.1-SNAPSHOT'
            args '-v $HOME/.m2:/var/maven/.m2 --privileged --group-add docker -e DOCKER_REGISTRY="YOUR_URL.COM"'
        }
    }
    stages {
        stage('Prepare') {
            steps {
                sh 'docker login YOUR_URL.COM --username $USER_CREDENTIALS_USR --password $USER_CREDENTIALS_PSW' 
                sh 'info'
                sh 'configure-maven --empty'
                sh 'validate'
                sh 'loadDependencies'
            }
        }
        stage('Build') {
            steps {
                sh 'build'
                archiveArtifacts allowEmptyArchive: true, onlyIfSuccessful: true, artifacts: 'tmf-service-activation-management-1.0.1-SNAPSHOT.jar'
                archiveArtifacts allowEmptyArchive: true, onlyIfSuccessful: true, artifacts: 'postman/TMF640-ServiceActivationManagement.postman_collection.json'
                archiveArtifacts allowEmptyArchive: true, onlyIfSuccessful: true, artifacts: 'postman/README.md'
            }
        }
        stage('Test') {
            steps {
                sh 'verify'
            }
        }
        stage('Deploy') {
            steps {
                sh 'deploy'                         
            }                   
        }                      
    }
}
  • A Git repository.
  • A credential with privileges to configure the registry and cloud environment.
  • The registry is populated with the relevant container images.
  • A node that runs a Jenkins agent must have privileges to access the registry.
  • A Maven Java builder version 1.1.13 — Set this in the pom.xml file of the tmf-xxx-builder. For each step of build, test, and deployment, Maven Java builder includes a build_project function with build scripts build.sh, pre-build.sh, and post-build.sh to support the CI/CD pipeline process.
  • An engine extension created using create_config.info; use the engine extension to extract mdc_config_custom.xml.