Title: UCS Microservice — UCS Tools Documentation

URL Source: https://docs.nvidia.com/ucf/2.10.0/text/UCS_microservice.html

Published Time: Thu, 30 Oct 2025 07:23:04 GMT

Markdown Content: 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 3rd-party software used

This information helps create applications that will use this microservice. It shows how to configure its parameters, connect it to other microservices, and specify any other additional details required to use this microservice.

UCS Application building tools such as UCS Studio and UCS Application Builder CLI also use this information to validate the application. They perform validations such as parameter value validation, connection validation to check if connected endpoints are compatible. Other requirements satisfaction such as secrets are specified.

Creating a Microservice#

Create and build a UCS Microservice using the UCS Microservice Builder CLI. For more information, see Creating a Microservice.

Microservice Location#

When you create and build a UCS Microservice, it gets added first 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#

View the complete information of a microservice 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.

The 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 & 3rd-party 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 3rd-party software used>

Basic Information#

The following table lists basic information that is part of the microservice information.

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:

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:

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, array or object.

• Using array and object types, nested parameters may be 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:

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:

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 3rd-party software used

Links/Buttons:

• #
• UCS Studio
• UCS Application Builder CLI
• UCS Microservice Builder CLI
• Creating a Microservice
• nSpect
• Semantic versioning

Related Articles

• UCS Tools Application — UCS Tools Documentation
• Creating a Microservice — UCS Tools Documentation
• Unified Cloud Services Tools (UCS Tools) — UCS Tools Documentation