UCS 微服务
UCS 微服务是 Helm Chart 之上的规范，用于标准化微服务的描述。它包括：
基本信息 - 可用于搜索和过滤微服务的名称、简短描述、关键字和标签
Helm Chart - Helm Chart 名称、版本、链接
参数信息 - 参数名称、类型、描述、允许的值/范围
端点信息 - 入口和出口端点名称、描述、相应的服务名称和端口（对于入口）、协议、方案、预期的数据交换格式。
其他要求 - 指定微服务需要的其他要求，例如密钥（例如密码、密钥）
合规性信息 - 关于微服务是否遵循创建安全且可用于生产的微服务的一组指南的详细信息
文档 - 功能、用法、KPI、已知问题、参考、更新日志等。
许可信息 - 使用的第三方软件的许可证
此信息对于创建将使用此微服务的应用程序非常有用，例如如何配置其参数、将其连接到其他微服务以及指定使用此微服务所需的任何其他详细信息。
UCS 应用程序构建工具（例如 UCS Studio 和 UCS 应用程序构建器 CLI）也使用此信息来验证应用程序。验证包括参数值验证、连接验证（例如连接的端点是否兼容）、其他要求是否满足（例如是否指定了密钥）。
创建微服务
UCS 微服务是使用 UCS 微服务构建器 CLI 创建和构建的。有关更多信息，请参阅创建微服务。
微服务位置
当 UCS 微服务被创建和构建时，它首先被添加到 local 存储库，这是一个位于用户主机文件系统上的 SQLite 数据库。此外，NVIDIA 提供的一些 UCS 微服务也上传到 NGC 存储库。
查看微服务信息
可以使用图形格式的 UCS Studio 或文本格式的 UCS 应用程序构建器 CLI 或 UCS 微服务构建器 CLI 查看微服务的完整信息。
以下是使用 MsBuilder 工具创建和构建的模板微服务的 CLI 输出
$ 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>
基本信息
下表列出了微服务信息中包含的基本信息。
字段 |
描述 |
|---|---|
specVersion |
清单/MS 遵循的 UCS MS 规范版本。当前 specVersion 为 |
name |
微服务的唯一字符串标识符。 |
namespace |
服务预期部署到的命名空间 |
nSpectId |
NVIDIA 的 nSpect 分配的唯一 ID |
chartName |
微服务 Helm Chart 名称 |
chart |
微服务 Helm Chart 的链接 |
description |
微服务的简短描述 |
displayName |
微服务的用户友好名称 |
category.functional |
微服务的功能类别，例如数据库、视觉 AI 等 |
category.industry |
微服务的行业类别，例如通用、零售、智能空间等 |
version |
微服务版本。支持遵循 语义版本控制，包括预发布标签。 |
tags |
用于分类微服务的字符串列表 |
keywords |
搜索此微服务时可能有所帮助的字符串列表 |
buildToolVersion |
用于构建微服务的 UCS 工具的版本 |
metadata |
保留供将来使用 |
入口端点
入口端点是由当前微服务实现的端点（服务器），其他微服务/服务连接到该端点（客户端）。入口端点的属性包括：
字段 |
描述 |
|---|---|
name |
入口端点的字符串标识符 |
description |
端点的简短描述 |
scheme |
端点遵循的方案。可以是 |
data-flow |
通过出口端点的数据流。可以是 |
service |
端点的 Kubernetes 服务抽象名称。 |
port |
入口端点的端口号。 |
protocol |
端点必须使用的网络协议。可以是 |
出口端点
出口端点是由其他微服务/服务实现的端点（服务器），当前微服务发起与该端点的连接（客户端）。出口端点的属性包括：
字段 |
描述 |
|---|---|
name |
出口端点的字符串标识符 |
description |
端点的简短描述 |
protocol |
端点必须使用的网络协议。可以是 |
scheme |
端点遵循的方案。可以是 |
mandatory |
布尔值，指示连接出口端点对于微服务正常工作是否是强制性的 |
data-flow |
通过出口端点的数据流。可以是 |
multi |
布尔值，指示出口端点是否可以连接到多个入口端点。如果未指定，则假定为 false。 |
参数
如以上部分所示，该命令打印微服务的参数。
每个参数都将有一个描述。
参数类型可以是
number、string、boolean、array或object。使用
array和object类型，可以指定嵌套参数。某些参数可能是强制指定的，而另一些则不是
某些参数可能接受一组固定的允许值
密钥
微服务的密钥要求在 secrets 字段下描述。微服务假定密钥作为文件挂载在微服务容器内部。支持的属性包括：
字段 |
描述 |
|---|---|
name |
密钥的字符串标识符 |
description |
密钥要求的简短描述 |
mountPath |
微服务容器内用于挂载密钥文件的路径 |
fileName |
挂载密钥文件时使用的文件名。文件将挂载在 |
mandatory |
布尔值，指示使用微服务的应用程序是否必须设置密钥 |
外部文件
微服务的外部文件要求在 externalFiles 字段下描述。微服务假定文件挂载在微服务容器内，前缀为 /opt/ext-files。支持的属性包括：
字段 |
描述 |
|---|---|
name |
文件的名称。文件预计挂载在 |
description |
预期文件及其内容的简短描述 |
mandatory |
布尔值，指示使用微服务的应用程序是否必须设置文件 |
isDirectory |
布尔值，指示微服务是否期望提供目录而不是文件 |
指标
微服务指标端点和微服务导出的自定义指标的信息在 metrics 字段下描述。
合规性
本节报告微服务的合规性结果。它报告一个总体结果 - 遵循的规则百分比，以及一个详细的表格，其中包含每个单独规则的结果。
文档
每个微服务包含 3 部分信息
详细文档
更新日志
许可证 - 用于第三方软件