Go to gopaddle
All Collections
User Guide
Extensions
Initializing a microservice from scratch

Initializing a microservice from scratch

Generate Dockerfile, build the docker image, create Kubernetes artifacts and deploy to Kubernetes - all in a single gpctl command
Vinothini Raju avatar
Written by Vinothini Raju. Updated over a week ago

Initializing a microservice from scratch transforms a microservice source code project into a Kubernetes deployment using gopaddle command-line utility 'gpctl'. gopaddle builds the necessary Dockerfile and the Kubernetes artifacts based on the microservice profile.

Support Matrix

Project Type

gpctl Support

Long-running services

✅

Terminal based services

❌

Utilities, libraries, and short-lived binaries

❌

Supported Languages

Java, NodeJS

Source Control Repositories

GitHub

Pre-requisites

From the gopaddle UI, perform these steps:

1. Register a Cloud Account which can be used to provision a Kubernetes Cluster and to register a Docker registry.

2. Create or Register a Kubernetes Cluster. This cluster will be used to build the Docker container and to deploy the microservice. Follow these steps to create an EKS, GKE, or AKS cluster or register an external cluster.

3. Register a Docker Registry. This registry will be used for both pulling the base image used to build the microservice and also to push the final docker image generated after the build process.

4. Create an allocation policy to build and run the project.

5. Register a Source Control Repository.

Pre-requisites on the local environment:


1. Currently, Ubuntu 18.04 is the Linux distribution supported. Make sure that your system is installed with this Linux distribution.

2. Download and configure gopaddle command-line utility by following the steps here.

3. Install the 'git' package, if it is not already installed on the system (skip this step If 'git' package is already installed):

If you are running on the host/VM:

$ sudo apt-get install -y git

If you are running inside a container:

# apt-get install -y git

Important Note: There are a few other pre-requisites to run the gpctl tool. Please refer to the steps here first, before proceeding.

Login to the gopaddle account


Login to the gopaddle account using the email, password for root user / sub-user, and the account Id in case of sub-user:

$ gpctl login --emailID=<user email address> --password=<user password> --endPoint=<gopaddle endpoint>

*endPoint - gopaddle endpoint to connect to. If you are connecting to the gopaddle SaaS portal, then the endPoint is https://portal.gopaddle.io

Initialize the microservice

1. Clone the project from the source control repository and change it to the project root folder.

$ git clone <cloneURL>
$ cd <project-root-folder>

2. Make sure the .git file exists in the project root folder.

$ ls -la
drwxr-xr-x    15 demo  staff     480 Mar  3 19:02 .git

Prepare the User Scripts

📌 Expose Environment Variables

Export ENVs that are to be used during the build or deployment process.
Say, if an environment variable named PORT is required by the application, then you can export the PORT variable in the local environment before running the gpctl init command.

📌 Self-sufficient - install required libs & packages


If each of these scripts is dependent on any libraries, packages or utilities, those dependencies must either be available in the base image or be installed or configured as a part of these scripts.
For example, if the build script uses npm command say npm run build, then the base image must have npm installed or the build script must install the npm command, before running npm run build.

📌 StartScript must start the application on the intended port

For instance, if a node-JS application is expected to bind on port 3000, but if the port is not available in the local environment, node-JS may automatically pick the next available port. This may break the discovery process. To overcome this scenario, assign a static port to the application while starting the application.

Build Script

Start Script

HealthCheck Script

Stop Script

Purpose

Builds the app

Starts the app

Checks if the app is running

Stops the app

Used during

Discovery & Build

Discovery & Deploy

Discovery & Deploy

Discovery

Success criteria

Exit 0

Runs forever

Exit 0

NA

timeout

Applicable

NA

Applicable

Applicable

startAwait

NA

Applicable

NA

NA

3. Create a build script to build the project. Say if it is a nodeJS application, you can create a buildScript.sh as below. 

#!/bin/bash
npm install
npm run build

4. Create a run script to run the project. Say, if it is a nodeJS application that has a dependency on an external Mongodb database, you can create a runScript.sh as below:

#!/bin/bash
cd dist
MONGODB_URI=mongodb://35.232.13.226:30000 npm start

🔔 Since the buildScript.sh and startScript.sh will be run on two different environments, environment variables required to build the container and to run the container should be defined in these scripts appropriately.
 
🔔 Service started through startScript.sh must bind to 0.0.0.0 instead of localhost.

5. Create a healthCheck script that checks for the running status of the microservice. A sample healthCheck.sh would look like this:

#!/bin/bash
curl http://localhost:3000

6. Create a stopScript that stops the microsevice. A sample stopScript.sh would look like this:

#!/bin/sh 
procs=`ps -ae -o comm,pid | grep "^node" | tr -s ' ' | cut -f2 -d' '` 
if [ -n "$procs" ] 
then 
    kill -1 $procs 
fi

7. Change the mode of the buildScript.sh, startScript.sh, healthCheck.sh and stopScript.sh scripts so that they have execute permissions:

$ chmod +x buildScript.sh
$ chmod +x startScript.sh
$ chmod +x healthCheck.sh
$ chmod +x stopScript.sh

8. Now, run each of the scripts, and make sure that the 'build', 'start', 'health check' and 'stop' scripts execute successfully, in that order, for the application:

$ ./buildScript.sh 
$ ./startScript.sh 
$ ./healthCheck.sh [ This may have to be issued on different terminal, based on the application ] 
$ ./stopScript.sh

9. Initialize the project by executing the gpctl init command

$ gpctl [-v] init --buildScript=<file_pathname> --startScript=<file_pathname> --healthCheck=<file_pathname> --stopScript=<file_pathname> [--baseImage=<docker_repo>/<image_name>[:tag]] [[--configMap=<config_file_path>:<mount_path>] ...] [--startAwait=<time_in_seconds>] [--timeout=<time_in_seconds>] [--svcTimeout=<time_in_seconds> ] [--projectID=<project ID>] [--releaseID=<release ID>] [--distributionID=<distribution ID>] [--desc=<description>] [--outputType=<output type>] [--outputDir=<Directory for helm>] [--fsGroup=<Filesystem Group>] [--enableVulScan] [--enableCI] [--buildOutputDir=<directory name>] [--clusterID=<cluster ID>] [--allocationPolicyID=<allocation Policy ID>] [--registryID=<registry ID>] [--templateID=<template ID>] [--overrideENV] [--discover] [--privileged] [--imagePullPolicy=<image Pull Policy>] [--appName=<Application Name>]

Mandatory options:

  • buildScript - Pathname of the file that contains the script/program that builds the service

  • startScript - Pathname of the file that contains the script/program that starts the service

  • healthCheck - Pathname of the file that contains the script/program that checks for the health of the service

  • stopScript - Pathname of the file that contains the script/program that stops the service

Non-mandatory (Optional) options:

  • baseImage - This specifies the name of image to be used to bring up a container that acts as the build environment to build the service. Build script will be executed within this container to build the service.

  • configMap - A folder in the current project (folder1) that needs to be added as configMap (folder2) in Kubernetes. All regular files within this folder (folder1) in the current project will be added to a configMap (folder2) and used for service deployment. To specify multiple such mappings, use configMap option multiple times.

  • startAwait - Initial wait time before the initialization process starts. Defaults to 30 seconds if not provided.

  • timeout - Seconds to wait before stopping command/script previously started (if still running). Default: 360 seconds.

  • svcTimeout - Seconds to await completion before exiting gopaddle-internal svcs previously initiated. Default: 540 seconds.

  • projectID - The 'project' identifier for this service. When this option is omitted, resources are added under 'default' project.

  • releaseID - The 'release' identifier for this service. When this option is omitted, resources are added under 'default' release.

  • distributionID - The 'distribution' identifier for this service. When this option is omitted, resources are added under 'default' distribution.

  • desc - Description for all gopaddle resources created. When not provided, defaults to contents of project 'description' file.

  • outputType - can either be appLaunch, helm, or template. When not specified, or if this option is omitted, defaults to appLaunch.

  • outputDir - Output directory to store helm charts. Applicable only when --outputType is used and specfied to be: helm.

  • fsGroup - set the filesystem mount group in Kubernetes for this service (a group to which the permission of all files in volumes will be changed when mounted by Kubernetes). If this option is omitted, fsGroup in Kubernetes is set to the GID (group id) of the current user.

  • enableVulScan - Enable Vulnerability scanning during 'image build' on Kubernetes

  • enableCI - Enable triggering build on commit to the git repository involved.

  • buildOutputDir - The output directory to place the artifacts generated during 'image build' on Kubernetes. This is applicable only when the root directory of the git source repository for this project does not contain a Dockerfile.

  • clusterID - 'cluster' to perform a build and deploy. When not provided, it asks for user input.

  • allocationPolicyID - 'allocationPolicy' to assign cpu and memory to build and deploy. When not provided, it asks for user input.

  • registryID - 'registry' to pull and push the images.

  • templateID - To add the service into pre-existing template.

  • overrideENV - OverrideEnv helps to change the ENV.

  • discover - discover the ENV and OS and Language of the given baseImage.

  • privileged - To set the security policy to run a container in privileged mode.

  • imagePullPolicy - To set imagePullPolicy for the container. It can either be 'ifNotPresent', 'always', or 'never'.

  • appName - To set appName for the application name.

  • purge - remove/purge all gopaddle resources associated with this project.

  • insecureSkipVerify - ignore TLS verification when a self-signed certificate is used for gopaddle endpoint.

  • help - Help for init process.

10. On executing 'gpctl init', you will be asked to choose the cluster where the build needs to be executed, the docker registry where the docker image has to be pushed, the allocation policy to use for building and deploying the container. When 'gpctl init' completes, you will get the application URL to access the microservice running in the Kubernetes environment.

Open up the firewall for the nodeports, to access the application URL from the browser.

Did this answer your question?