UCF Microservice¶
A UCF 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 UCF Application building tools such as the UCF Studio and UCF 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 UCF Microservice is created and built using the UCF Microservice Builder CLI. For more information, refer to Creating a Microservice.
Microservice location¶
When a UCF Microservice is created and built, it is first added to the local repository i.e. on the host’s local file system. when it is locally built. Additionally some UCF 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 UCF Studio in a graphical format or in a textual format using the UCF Application Builder CLI or UCF 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
specVersion: 1.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:
- portName: metrics
path: /metrics
details:
- name: latency
description: Average latency of handling HTTP requests in milliseconds
labels: [ request-type ]
recommendedMin: 5 # Optional
recommendedMax: 50 # Optional
buildToolVersion: 1.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 v1.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 UCF MS Specification version that the manifest / MS adheres to. Current specVersion is |
name |
Unique string identifier for the microservice. |
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 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 |
buildToolVersion |
Version of the UCF 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.
Field |
Description |
|---|---|
[*].portName |
Name of the container port in the microservice pods that exposes the metrics |
[*].path |
HTTP path where the metrics API is implemented |
[*].podSelectorLabels |
An object (key-value pairs) of labels to be used for selecting pods for scraping metrics |
[*].details |
A list of metrics exported by the microservice and their details |
[*].details.[*].name |
Name of the metric |
[*].details.[*].description |
Description of the metric |
[*].details.[*].labels |
A list of string labels for the metric. Optional, may not be specified |
[*].details.[*].recommendedMin |
Recommended minimum value of the metric. Optional, may not be specified |
[*].details.[*].recommendedMax |
Recommended maximum value of the metric. Optional, may not be specified |
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