Microservice Builder Input Specification
In this section, we will go through the specification of the input to the UCS Microservice Builder (msbuider) tool used for creating and building UCS Microservices.
For more information, on what a UCS Microservice is refer to - UCS Microservice.
Note
A template input directory for the msbuilder can be generated using - Generate scaffolding.
Input Directory Structure
A typical input directory structure for msbuilder would contain:
<msbuilder-input-directory>
├── changelog.txt
├── configs
├── containers
│ └── cb_config.yaml
├── endpoints
│ ├── http-api.yaml
│ └── myservice-endpoint-name.yaml
├── LICENSE.txt
├── manifest.yaml
├── manual_compliance_test_results.yaml
├── README.md
├── scripts
├── tests
│ └── dev
│ ├── app.yaml
│ └── params1.yaml
└── values.yaml
Some of the files / directories are not used when using a particular type of msbuilder input. Individual sections below will clarify if the file / directory is not used.
Manifest file - manifest.yaml
The manifest file manifest.yaml
contains information for describing the microservice, the helm chart implementation and container build config details.
The template manifests generated for each of the three use cases differ slightly.
Following is an example of the template manifest.yaml
file:
type: msapplication
specVersion: 2.5.0
name: ucf.svc.myservice
chartName: myservice
description: default description
version: 0.0.1
tags: []
keywords: []
publish: false
egress-endpoints:
- name: myservice-endpoint-name
description: Short description of endpoint
protocol: TCP # Or UDP
scheme: asyncio # Or grpc / rtsp / asyncio / none
mandatory: True # Or False
data-flow: in-out # Or in or out
ingress-endpoints:
- name: http-api
description: Short description of http-api ingress endpoint
scheme: http
data-flow: in-out # Or in or out
secrets:
- name: some-secret-name
description: Description for the secret
mandatory: True
mountPath: /secrets
fileName: someSecretFileName
params:
stringToEcho: someString
#> type: string
#> enum_values: someString, someOtherString
#> description: String to echo in init container
timeToSleep: 1000000
#> type: integer
#> maximum: 2000000
#> minimum: 1000000
#> description: String to echo in init container
#> flags: mandatory
# Files and directories will be mounted with prefix /opt/ext-files/
externalFiles:
- name: some-config.yaml # File will be available in containers at /opt/ext-files/some-config.yaml
description: Some Configuration file
mandatory: True
isDirectory: False
tests:
- name: dev-params1
app: tests/dev/app.yaml
params: tests/dev/params1.yaml
ciTrigger: false
timeout: 10
duration: 10
installPreReqs: true # Wether to install foundational services
namespace: default # Kubernetes namespace
gpuNodeLabels: ""
watchAllPods: true # OR set to false and set list of pods to watch below
watchPods:
- <pod-name-regex>
testerPods: # At least one tester pod is required
- name: testpod1 # Name of the test pod
startSignature: <START> # Signature to look for in the logs indicating start of tests. Regex is accepted
endSignature: <END> # Signature to look for in the logs indicating end of tests. Regex is accepted
errorSignatures: # Signatures that indicate test failures. Regex is accepted
- <REGEX1>
- <REGEX2>
---
spec:
- name: myservice-deployment
type: ucf.k8s.app.deployment
parameters:
apptype: stateless
- name: myservice-init-container
type: ucf.k8s.initcontainer
parameters:
image: ubuntu
imagePullPolicy: IfNotPresent
args: [echo, $params.stringToEcho]
- name: "myservice-container"
type: ucf.k8s.container
parameters:
image:
repository: ubuntu
tag: "latest"
command: ["sleep", "$params.timeToSleep"]
ports:
- containerPort: 0 # <PORT>
name: http
startupProbe:
httpGet:
path: /healthz
port: http
failureThreshold: 30
periodSeconds: 10
livenessProbe:
httpGet:
path: /healthz
port: http
readinessProbe:
exec:
command:
- cat
- /tmp/healthy
initialDelaySeconds: 5
periodSeconds: 5
- name: myservice-service
type: ucf.k8s.service
parameters:
annotations:
test-svc-annotation: annotation-value
labels:
test-svc-label: label-value
ports:
- port: 0 # <OUT_PORT>
name: http-api
#externalTrafficPolicy: # Cluster / Local. Allowed when service type is NodePort or LoadBalancer
Basic Information
The following table lists basic information that must be specified in the manifest file.
Field |
Description |
---|---|
specVersion |
The UCS MS Specification version that the manifest / MS adheres to. Current specVersion is |
name |
Unique string identifier for the microservice. Must start with |
chartName |
A unique name for the microservice helm chart. Must follow convention at https://helm.sh/docs/chart_best_practices/conventions/#chart-names. Ignored if using a prebuilt helm chart |
chart |
Link to a prebuilt helm chart |
description |
A short description of the microservice |
displayName |
User friendly name for the microservice |
category.functional |
Functional category for the microservice e.g. Database, Vision AI etc |
category.industry |
Industry category for the microservice e.g. General, Retail, Smart Space etc |
version |
Microservice version. Must follow semantic versioning https://semver.org/ |
tags |
A list of strings for categorizing the microservice |
keywords |
A list of strings that maybe helpful when searching for this microservice |
Ingress Endpoints
Ingress endpoints are specified as a list under the ingress-endpoints
field. The attributes for an Ingress endpoint are:
Field |
Description |
---|---|
name |
A string identifier for the ingress endpoint |
description |
A short description of the endpoint |
scheme |
Scheme the endpoint follows. One of |
data-flow |
Flow of data through the egress endpoint. One of |
service |
Kubernetes service abstraction name for the endpoint. Can be skipped if it should be inferred from a |
port |
Port number for the ingress endpoint. Can be skipped if it should be inferred from a |
protocol |
The network protocol the endpoint must use. Either |
For more information on endpoints refer to Endpoints.
Egress Endpoints
Egress endpoints are specified as a list under the egress-endpoints
field. The attributes for an Egress endpoint are:
Field |
Description |
---|---|
name |
A string identifier for the egress endpoint |
description |
A short description of the endpoint |
protocol |
The network protocol the endpoint must use. Either |
scheme |
Scheme the endpoint follows. One of |
mandatory |
Boolean indicating if connecting the egress endpoint is mandatory for the microservice to work correctly |
data-flow |
Flow of data through the egress endpoint. One of |
multi |
Boolean indicating if the egress endpoint can be connected to multiple ingress endpoints. Assumed to be false if not specified. |
Placeholders $egress.<egress-endpoint-name>.address
and $egress.<egress-endpoint-name>.port
can be used where these egress connection parameters are needed.
These placeholders can be used anywhere in spec
section of manifest.yaml
or in the files inside configs
directory.
These placeholders will get overridden by actual address and port during application build.
For example, microserviceServer
implements an HTTP API server, creates a kubernetes service resource for it with name server-http-api-svc
and port 8000
and creates a corresponding ingress endpoint named http-api
.
Another microserviceClient
contains a client for the HTTP API and creates a corresponding egress endpoint named http-api
.
It specifies an environment variable SERVER_ENDPOINT
in the container section with placeholders in the value http://$egress.http-api.address:$egress.http-api.port/
e.g:
# microserviceClient manifest.yaml
...
egress-endpoints:
- name: myservice-endpoint-name
description: Short description of endpoint
protocol: TCP # Or UDP
scheme: asyncio # Or grpc / rtsp / asyncio / none
mandatory: True # Or False
data-flow: in-out # Or in or out
...
spec:
- name: "client-container"
type: ucf.k8s.container
parameters:
image:
repository: client-container-repo
tag: client-container-tag
env:
- name: SERVER_ENDPOINT
value: http://$egress.http-api.address:$egress.http-api.port/
In the UCS Application, http-api egress endpoint of microserviceClient is connected to http-api egress endpoint of microserviceServer, then during app build all occurrences of $egress.http-api.address and $egress.http-api.port will be overridden with server-http-api-svc and 8000 respectively. Thus environment variable SERVER_ENDPOINT in the container of microserviceClient will be set to http://server-http-api-svc:8000/.
For more information on endpoints refer to Endpoints.
Parameters
Parameters for microservice can be described under params
field. Supported parameter types are primitives like Boolean, numbers and string as well as lists and objects. Nested structures are supported.
Default values can provided for the parameters. Parameters maybe annotated using comments beginning at the next line after the parameter. The lines must start with the prefix #>
followed by a keyword and a value for the keyword. Example:
params:
someParam: 100
#> type: number
#> description: Description for someParam
#> minimum: 10
#> maximum: 1000
#> flags: mandatory
someStringParam: someDefaultValue
#> type: string
#> description: Description for someStringParam
#> enum_values: someDefaultValue, someOtherValue
someObjectParam:
#> type: object
#> description: Description for someObjectParam
someSubParamInSomeObjectParam: false
#> type: boolean
#> description: Description for someSubParamInSomeObjectParam
Supported annotations for annotation keywords are:
Keyword |
Description |
---|---|
type |
Type of parameter. One of |
description |
A short description of the parameter |
minimum |
Minimum allowed value if the parameter type is |
maximum |
Maximum allowed value if the parameter type is |
enum_values |
Comma separated list of allowed values |
flags |
Comma separated list of flags for the parameter. Currently supported flags are |
Parameters can be referenced in the manifest.yaml
or in the files inside the configs
directory using the $params
placeholders. These placeholder get overridden by the user set value or the default value during app build time. Example:
spec:
...
- name: app-container
type: ucf.k8s.container
parameters:
...
env:
- name: SOME_ENV_VAR
value: $params.someObjectParam.someSubParamInSomeObjectParam
Parameter values are also set in the values of the microservice helm chart. And hence they can be referenced using helm templates as well. Example:
{{- if .Values.someObjectParam.someSubParamInSomeObjectParam }}
...
{{- end }}
Secrets
Secret requirements for the microservice can be described under the secrets
field. The secrets get mounted as files inside the microservice containers.
A list of secret requirements can be added under secrets
field. Supported attributes are:
Field |
Description |
---|---|
name |
A string identifier for the secret |
description |
A short description of the secret requirement |
mountPath |
Path inside the microservice containers to mount the secret file under |
fileName |
Name of the file to use when mounting the secret file. Files are mounted at |
mandatory |
Boolean indicating if it is mandatory for the app using the microservice to set the secret |
For details on how secrets works in UCS and requirements from microservice and application developers refer to Secrets Management.
External Files
External file requirements for the microservice can be described under the externalFiles
field.
With this application builder can pass entire files/directories from the local system to microservice when building
the application.
The files get mounted inside the microservice containers with prefix /opt/ext-files
.
Supported attributes are:
Field |
Description |
---|---|
name |
Name for the file. File is expected to be mounted at |
description |
A short description of the expected file and contents |
mandatory |
Boolean indicating if it is mandatory for the app using the microservice to set the file |
isDirectory |
Boolean indicating if microservice expects a directory to be provided instead of a file |
Metrics
Information on the microservice metrics endpoint and metrics exported by the microservice are described under the metrics
field as an array.
Tests
Tests for the microservice can be specified under tests
section. Tests are basically UCS Applications tailored to test the microservice being developed. When the building the microservice, it’s test applications get built as well.
The tests can be executed locally by deploying the test application helm charts.
The tests are specified as a list under tests
section. Supported attributes for a test are:
Field |
Description |
---|---|
name |
A string identifier for the test app |
app |
Path to a UCS Application graph file. Can be specified as an absolute path or relative to the |
params |
Path to a UCS Application params file to override parameters in the application graph file. Can be specified as an absolute path or relative to the |
ciTrigger |
Boolean to indicate if the test should be executed as part of UCS MS Validation |
timeout |
CI pipeline will stop the test after this time and mark it as fail if it does not complete after this time. Value is in minutes. This parameter is applicable to services which returns result and stop when finished. |
duration |
CI pipeline will stop the test after this time and mark test as pass. Value is in minutes. This is parameter is applicable to services which does not return result and does not stop. It can be used to test if a particular service is deployable and running for a particular time. |
installPreReqs |
Boolean to indicate if foundational services must be installed before the test application |
namespace |
Kubernetes namespace to install the test app helm chart under. Currently unused |
gpuNodeLabels |
Reserved for future use |
watchAllPods |
Boolean indicating if CI should watch all pods for failures |
watchPods |
List of regex for pod names that the CI should watch for failures |
testerPods |
Reserved for future use |
For more details on creating UCS Applications refer to Creating an Application.
Spec
Implementation of the microservice (i.e. it’s helm chart) can be specified under the spec
field.
As part of the UCS Microservice Builder Tool, the microservice implementation must be done using composable components.
When using Pre-built Helm Chart, this section must be omitted. msbuilder ignores this field since it does not build the microservice helm chart.
Components
Components define a small part of the microservice implementation such as a container, a service, a volume.
Adding components to the spec
The components must be added under spec
as a list along with their parameters. The parameter values must follow the parameter schema for the component
which can be viewed using the component info
command as shown above. Placeholders $params
, $egress
and $secrets
can be used in
parameter values to refer to the parameters, egress endpoint and secret respectively. These placeholders remain in the built microservice helm chart
but are substituted during application build.
An example of adding components with placeholders is:
spec:
- name: myservice-deployment
type: ucf.k8s.app.deployment
parameters:
apptype: stateless
- name: "myservice-container"
type: ucf.k8s.container
parameters:
image:
repository: ubuntu
tag: "latest"
env:
- name: HTTP_API_CA_CERT_PATH
value: $secrets.ca-cert.path
command: ["curl", "$egress.http-api.address:$egress.http-api.port",
"--connect-timeout", $params.connectTimeout, "--cacert", $(HTTP_API_CA_CERT_PATH)]
startupProbe:
httpGet:
path: /healthz
port: http
failureThreshold: 30
periodSeconds: 10
livenessProbe:
httpGet:
path: /healthz
port: http
readinessProbe:
exec:
command:
- cat
- /tmp/healthy
initialDelaySeconds: 5
periodSeconds: 5
Note
For the components defined in spec, parameters must adhere to the component schema specific to each type as shown above.
Only one workload type (e.g stateless
, stateful
, job
, cronjob
, daemonset
, static-pod
) can be specified in one yamldoc. To add multiple workload types (e.g. two stateless
(i.e. Deployment
) ) to the microservice:
---
spec:
- name: app-deployment-1
type: ucf.k8s.app.deployment
parameters:
apptype: stateless
...
---
spec:
- name: app-deployment-2
type: ucf.k8s.app.deployment
parameters:
apptype: stateless
...
Configs Directory - configs
This directory can be used for adding any configuration files for the microservice. Files added to this directory get automatically added to a configmap
and mounted under /opt/configs
directory in the containers that are part of the microservice.
Files used in this directory can contain the $params
, $egress
and $secrets
placeholders. These placeholders and thus the mounted files
under /opt/configs
directory will have the placeholders substituted with the actual values when the application is built and deployed.
For example a file named app_cfg.yaml
in the configs
directory will get mounted at /opt/configs/app_cfg.yaml
in containers that are part of the microservice with
placeholders updated with actual values.
The files in this directory are NOT used when using a Pre-built Helm Chart.
Scripts Directory - scripts
This directory can be used for adding any script files used by applications running inside the microservice. Files added to this directory get automatically added to a configmap
and mounted under /opt/scripts
directory in the containers that are part of the microservice.
Placeholders $params
, $egress
and $secrets
added to the files inside this directory will NOT get substituted.
For example a file named run.sh
in the scripts
directory will get mounted at /opt/scripts/run.sh
in containers that are part of the microservice with
exactly the same contents.
The files in this directory are NOT used when using a Pre-built Helm Chart.
Container Configs Directory - containers
This directory contains Container Build configuration files for containers used by the microservice. Containers are built using these configuration files during microservice build.
These configuration files follow the Container Build configuration specification. A separate file must be created for each container to be built. There is no restriction on the filenames.
The files in this directory are NOT used when using a Pre-built Helm Chart or when using Pre-built Container Images.
Endpoint Definition Files Directory - endpoints
This directory contains endpoint definition files for each endpoint Ingress or Egress that is
part of the microservice. The expected file name is <endpoint-name>.<ext>
. The file extension
depends on the scheme of the endpoint.
Endpoint definition files are not mandatory for building the microservice, but required for a fully UCS-compliant microservice.
For more information on endpoints and endpoint definition files refer to Endpoints.
Customized Helm Template Directory - templates
User can put customized Helm template yaml files here and they’ll be copied to the final Helm templates folder verbatim。
Manual Compliance Test Results - manual_compliance_test_results.yaml
UCS Microservice compliance requires that microservice developers run some tests manually. The
test results can be provided using the manual_compliance_test_results.yaml
input file.
The expected format of the file is a map of <compliance-id>: <result-as-boolean>
. Example contents of
the file:
DEV-005: false
DEV-011: false
DEV-014: false
DEV-017: false
DEV-018: false
DEV-019: false
DEV-020: false
DEV-101: false
For more information on UCS Microservice Compliance and manual compliance checks refer to UCS Microservice Compliance.
Documentation - README.md
Detailed documentation for the microservice must be added to README.md
. It must be in a specific format and
list of sections is required to be included. The sections include:
Description - Detailed description of the microservice, functionality, features
Usage - Details on using the microservice in an application like any parameter / endpoint details that cannot be added to the manifest, examples on adding the microservice to an app and its connections.
Performance/KPIs - Details on expected performance / KPIs
Supported Platforms - Information on supported platforms / GPUs
Deployment requirements - Deployment requirements like CPU / memory / NICs / node host configuration
License - License the microservice uses
Known Issues / Limitations - List of known issues, limitations & workarounds
References - References / useful links like sample apps on GitHub, SDKs used, further reading.
Note
A template README.md
can be created using the service create
command. Refer to Generate scaffolding.
License - LICENSE.txt
Licenses of 3rdparty software used in the microservice
Changelog - changelog.txt
This file must contain the changelog for the current version of the microservice.
Tests Directory - tests
This directory contains the test applications for the microservice. The applications must be in UCS Application specification. These test applications get built along with the microservice.
Values file values.yaml
This file is used ONLY when using a Pre-built Helm Chart.
It is in the form of a standard Helm values.yaml
and contains values of the pre-built helm chart that must be overridden. The file can contain the
$params
, $egress
and $secrets
placeholders which will get substituted with the actual values when the application is built and deployed.