UCS Microservice#
A UCS Microservice is a specification on top of a helm chart to standardize description of a microservice. It consists of
Basic Information - Name, short description, keywords and tags that can be used to search and filter microservices
Helm Chart - Helm chart name, version, link
Parameters Information - Parameter names, types, descriptions, allowed values/ranges
Endpoint Information - Ingress and Egress endpoint names, descriptions, corresponding service names and ports (for ingress), protocol, schemes, expected data exchange format.
Other Requirements - Specify other requirements such as secrets (e.g passwords, keys) that are required by the microservice
Compliance Information - Detailed information on whether the microservice is following a set of guidelines for creating secure and production-ready microservices
Documentation - Features, Usage, KPIs, Known Issues, References, changelog etc.
Licensing Information - Licenses of 3rdparty software used
This information is useful for creating applications that will use this microservice like how to configure its parameters, connect it to other microservices and specify any other additional details that are required to use this microservice.
This information is also used by the UCS Application building tools such as the UCS Studio and UCS Application Builder CLI to validate the application. Validations such as parameter value validation, connection validation such as whether connected endpoints are compatible, other requirements satisfaction such as secrets are specified.
Creating a Microservice#
A UCS Microservice is created and built using the UCS Microservice Builder CLI. For more information, refer to Creating a Microservice.
Microservice location#
When a UCS Microservice is created and built, it is first added to the local repository, which is a SQLite database on the user’s host file system. Additionally some UCS Microservices provided by NVIDIA are also uploaded to NGC repositories.
Viewing Microservice Information#
The complete information of a microservice can be viewed using either the UCS Studio in a graphical format or in a textual format using the UCS Application Builder CLI or UCS Microservice Builder CLI.
Following is output from the CLI for the template microservice created and built using the MsBuilder Tool:
$ ucf_ms_builder_cli service info -n ucf.svc.myservice --show-license --show-docs --show-changelog --show-compliance-details
name: ucf.svc.myservice
namespace: default
specVersion: 2.5.0
chart: file:///home/nvidia/.ucf_workspace/ucf.svc.myservice/0.0.1/helm/myservice-0.0.1.tgz
description: default description
type: msapplication
tags: []
keywords: []
publish: false
ciTrigger: false
egress:
- name: myservice-endpoint-name
description: Short description of endpoint
protocol: TCP
scheme: asyncio
mandatory: true
data-flow: in-out
multi: false
ingress:
- name: http-api
description: Short description of http-api ingress endpoint
scheme: http
data-flow: in-out
service: myservice-myservice-deployment-myservice-service
port: 0
protocol: TCP
metadata:
myservice-custom-data:
param1: value1
param2: value2
version: 0.0.1
displayName: ''
category:
functional: ''
industry: ''
secrets:
- name: some-secret-name
description: Description for the secret
mandatory: true
mountPath: /secrets
fileName: someSecretFileName
externalFiles:
- name: some-config.yaml
description: Some Configuration file
mandatory: true
isDirectory: false
metrics: {}
buildToolVersion: 2.5.0
Parameters:
-------------
stringToEcho: (string ), String to echo in init container [Mandatory:False, Allowed Values:{ someString, someOtherString }]
timeToSleep: (integer), String to echo in init container [Mandatory:True]
Compliance Info:
---------------------
Report Generated on 2022-11-08 12:56:36 (UTC) using MSBuilder v2.5.0
Development compliance (Mandatory) 65.38%
Development compliance (Optional) 33.33%
+---------+---------------------------------------------------------------------------------+-------------+--------+
| ID | Description | Mandatory | Pass |
+=========+=================================================================================+=============+========+
| DEV-001 | K8S Service resource name must follow RFC 1035 convention | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-002 | Containers shall not use root permissions | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-003 | Containers shall not use host network | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-004 | Ports shall not clash in one Pod | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-005 | No hardcoded IPs or service names | Y | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-006 | Endpoint definition files are available for each endpoint | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-007 | Endpoint definitions validation | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-008 | Parameter's format validation | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-009 | Liveness and readiness probes for containers | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-010 | Helm chart must pass Helm lint test | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-011 | MS Helm charts must not include any secrets like usernames, passwords, API keys | Y | N |
| | in plain-text format | | |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-012 | Containers must not use floating tags like latest, head | Y | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-013 | Components and manifest must pass JSON schema validation | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-014 | MS containers must not fetch and install packages at deploy time | Y | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-015 | At least one test must be implemented | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-016 | Pods shall not use local directory path or host mount | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-017 | MS version updates must follow semantic versioning | Y | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-018 | MS documentation must follow the MS documentation guidelines | Y | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-019 | MS must be able to handle situations where dependent MS restart | Y | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-020 | MS must be able to gracefully handle situations where dependent MS crash / are | Y | N |
| | unresponsive | | |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-022 | Testapp shouldn't have '.' in the name | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-023 | Microservice shouldn't have '_' in the name; instead use '-' | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-024 | Only accepted (key: value) pairs should be present in the manifest | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-025 | Microservice must have at least one ingress or egress endpoint | Y | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-101 | Log information to stdout or stderr | N | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-102 | Parameter naming should follow camelCase | N | Y |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-103 | Apply CPU and memory limits to pods | N | N |
+---------+---------------------------------------------------------------------------------+-------------+--------+
Changelog:
----------
<List of changes in the current version w.r.t previous version>
Documentation:
--------------
╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ myservice ║
╚═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
Description
default description
<Detailed description of the microservice, functionality, features>
Usage
Performance
<Performance/KPIs>
Supported Platforms
<Information on supported platforms / GPUs>
Deployment requirements
<Deployment requirements like CPU / memory / NICs / node host configuration>
License
<License to use the microservice under. Detailed license text & 3rdparty licenses can be added to LICENSE.txt>
Known Issues / Limitations
<Known issues & workarounds>
References
<This section is optional. Useful links like sample apps on github, gitlab using the microservice, link to SDKs used in the
microservice etc.>
License:
--------
<LICENSE for the microservice>
<LICENSE for any 3rdparty software used>
Basic Information#
The following table lists basic information that is part of the microservice information.
Field |
Description |
|---|---|
specVersion |
The UCS MS Specification version that the manifest / MS adheres to. Current specVersion is |
name |
Unique string identifier for the microservice. |
namespace |
Namespace to which the service is expected to be deployed |
nSpectId |
Unique ID assigned by NVIDIA’s nSpect |
chartName |
Microservice helm chart name |
chart |
Link to to the microservice 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. Follows Semantic versioning is supported, including pre-release labels. |
tags |
A list of strings for categorizing the microservice |
keywords |
A list of strings that maybe helpful when searching for this microservice |
buildToolVersion |
Version of the UCS Tools that was used to build the microservice |
metadata |
Reserved for future use |
Ingress Endpoints#
Ingress endpoints are endpoints (server) implemented by the current microservice to which other microservices / services connect to (client). 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. |
port |
Port number for the ingress endpoint. |
protocol |
The network protocol the endpoint must use. Either |
Egress Endpoints#
Egress endpoints are endpoints (server) implemented by other microservices / services and the current microservice initiates a connection (client) to the endpoint. 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. |
Parameters#
As seen in the above section, the command prints the parameters of the microservice.
Each parameter will have a description.
Parameters can be of type
number,string,boolean,arrayorobject.Using
arrayandobjecttypes, nested parameters maybe specified.Some parameters may be mandatory to specify, others not
Some parameters may accept a fixed set of allowed values
Secrets#
Secret requirements for the microservice are described under the secrets field. Microservices assume that the secrets get mounted as files inside the microservice containers. 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 to be mounted at |
mandatory |
Boolean indicating if it is mandatory for the app using the microservice to set the secret |
External Files#
External file requirements for the microservice are described under the externalFiles field.
Microservices assume that 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 custom metrics exported by the microservice are described under the metrics field.
Compliance#
This section reports the compliance results for the microservice. It reports an overall result - % of rules followed as well as a detailed table consisting of result of each individual rule.
Documentation#
Every microservice contains 3 pieces of information:
Detailed documentation
Changelog
License - for 3rdparty software used