Title: Endpoints — UCS Tools Documentation URL Source: https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html Published Time: Thu, 30 Oct 2025 07:23:03 GMT Markdown Content: Endpoints[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#endpoints "Link to this heading") --------------------------------------------------------------------------------------------------------- Endpoints in UCS are communication interfaces to the microservices. UCS classifies endpoints into two types: * **Ingress** endpoints - Server side of the communication interface, i.e., a server in a microservice listening for connections. * **Egress** endpoints - Client side of the communication interface, i.e., a client in a microservice initiating a connection to a server. UCS endpoints relate to `server` and `client` roles and **NOT** to the data flow direction. It follows that an **Egress** endpoint connects to an **Ingress** endpoint. **Egress** endpoints are only virtual in nature. However, they serve an important job of representing external endpoints / APIs that a microservice depends on and connects to. They also abstract the connection details (`address` and `port`) in the client microservice as explained in [Creating a Microservice](https://docs.nvidia.com/ucf/2.10.0/text/UCS_MsDevelopment.html#ms-development). In a UCS Application, when an **Egress** endpoint of a client microservice connects to an **Ingress** endpoint, the connection details (`address` and `port`) of the **Ingress** endpoint get set on the client microservice during application build. Because of the abstraction explained above: * Client microservice does not need to know the connection details of the **Ingress** endpoint beforehand during microservice development. So microservices can be developed independently. * A microservice that implements the **Ingress** endpoint can be easily replaced by another microservice that implements a similar compatible **Ingress** endpoint. | Endpoint Type | Description | | --- | --- | | [HTTP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#http-endpoint) | [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) | | [gRPC](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#grpc-endpoint) | [https://developers.google.com/protocol-buffers/docs/proto3](https://developers.google.com/protocol-buffers/docs/proto3.md) | | [RTSP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#rtsp-endpoint) | [https://www.rfc-editor.org/rfc/rfc2326.html](https://www.rfc-editor.org/rfc/rfc2326.html) | | [AsyncIO](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#asyncio-endpoint) | [asyncapi/spec](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md) | | [UCX](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#ucx-endpoint) | | | [RESP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#resp-endpoint) | [asyncapi/spec](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md) | | [MongoDB Wire](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#mongodb-wire-endpoint) | | | [Raw UDP / TCP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#raw-endpoint) | Raw UDP / TCP | For UCS **compliant** microservices, each **Ingress** or **Egress** endpoint is accompanied by an endpoint definition file which describes the data exchange format expected by the endpoint. The format of endpoint definition file depends on the scheme the endpoint follows. The endpoint schemes are described in detail in the below section. Ingress Endpoints[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#ingress-endpoints "Link to this heading") ------------------------------------------------------------------------------------------------------------------------- Ingress endpoints in UCS are described using the following attributes: | Field | Description | | --- | --- | | name | A string identifier for the ingress endpoint | | description | A short description of the endpoint | | scheme | Scheme the endpoint follows | | data-flow | Flow of data through the egress endpoint. One of `in`, `out` or `in-out` | | service | Server address or Kubernetes service abstraction name for the endpoint. | | port | Port number for the ingress endpoint. | | protocol | The network protocol the endpoint must use. Either `TCP` or `UDP`. | Egress Endpoints[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#egress-endpoints "Link to this heading") ----------------------------------------------------------------------------------------------------------------------- Egress endpoints in UCS are described using the following attributes: | 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 `TCP` or `UDP` | | scheme | Scheme the endpoint follows | | 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 `in`, `out` or `in-out` | UCS Endpoint Schemes[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#ucs-endpoint-schemes "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------- ### HTTP[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#http "Link to this heading") Represented by string enum `http`. Use it for endpoints that communicate using the **HTTP** protocol. The endpoint definition file for **HTTP** endpoint scheme must follow the **OpenAPI v3.0.3** specification - [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md). The file can be in YAML or JSON format and must have the filename `.yaml` or `.json` respectively. A sample endpoint definition file: openapi: 3.0.0 info: title: MyService API spec description: MyService HTTP API version: 0.0.1 paths: /hello: get: responses: '200': description: Success response to the /hello API description: Check if the API is up ### gRPC[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#grpc "Link to this heading") Represented by string enum `grpc`. Use it for endpoints that communicate using the **gRPC** protocol. The endpoint definition file for **gRPC** endpoint scheme must follow the Protocol Buffer Language specification - [https://developers.google.com/protocol-buffers/docs/proto3](https://developers.google.com/protocol-buffers/docs/proto3.md). It is basically the `.proto` file used in the gRPC client / server implementation and must have the filename `.proto`. A sample endpoint definition file: syntax = "proto3"; service PingTest { rpc Ping (PingRequest) returns (PingReply) {} } message PingRequest { string test_message = 1; } message PingReply { string status = 1; } ### AsyncIO[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#asyncio "Link to this heading") Represented by string enum `asyncio`. Use it for endpoints that communicate using Asynchronous events such as using Kafka or MQTT message brokers. The endpoint definition file for **AsyncIO** endpoint scheme must follow the **AsyncAPI v2.2.0** specification - [asyncapi/spec](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md). The file can be in YAML or JSON format and must have the filename `.yaml` or `.json` respectively. A sample endpoint definition file: asyncapi: 2.2.0 info: title: AsyncIO API schema for myservice-ping endpoint version: 0.0.1 channels: ping: publish: message: payload: type: string pattern: PING ### RTSP[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#rtsp "Link to this heading") Represented by string enum `rtsp`. Use it for endpoints that use RTSP for streaming data. The endpoint definition file for **RTSP** endpoint scheme must follow the JSON schema: { "$schema": "http://json-schema.org/draft-07/schema", "$id": "ucf-rtsp-ep-1.0.0", "title": " UCS RTSP Endpoint", "description": "The object defines UCS RTSP Endpoint Specification", "type": "object", "required": [ "mediaPath" ], "properties": { "mediaPath": { "description": "Streaming Media Path", "type": "string" }, "user": { "description": "Username for accessing the RTSP server", "type": "string" }, "password": { "description": " Password for accessing the RTSP server", "type": "string" } } } The file can be in YAML or JSON format and must have the filename `.yaml` or `.json` respectively. A sample endpoint definition file: { "mediaPath": "/test" } ### RESP[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#resp "Link to this heading") Represented by string enum `resp`. Use it for endpoints that communicate using Asynchronous events via Redis over RESP (REdis Serialization Protocol). The endpoint definition file for **RESP** endpoint scheme must follow the **AsyncAPI v2.2.0** specification - [asyncapi/spec](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md). The file can be in YAML or JSON format and must have the filename `.yaml` or `.json` respectively. A sample endpoint definition file: asyncapi: 2.2.0 info: title: AsyncIO API schema for myservice-ping endpoint version: 0.0.1 channels: ping: publish: message: payload: type: string pattern: PING ### UCX[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#ucx "Link to this heading") Represented by string enum `ucx`. Use it for endpoints that communicate over UCX. Endpoint definition file for the **UCX** endpoints are not required. ### MongoDB Wire[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#mongodb-wire "Link to this heading") Represented by string enum `mongodb-wire`. Use it for endpoints that communicate using MongoDB Wire Protocol. Endpoint definition file for the **MongoDB Wire** endpoints are not required. ### Raw UDP / TCP[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#raw-udp-tcp "Link to this heading") Represented by string enum `none`. Use it for endpoints that implement some other scheme on top of TCP/UDP, e.g., MongoDB Wire Protocol or using raw UDP packets / TCP sockets. It is **NOT** mandatory to specify an endpoint definition file for this scheme for the microservice to be UCS compliant. If specified, the endpoint definition file for this endpoint scheme must follow the JSON schema: { "$schema": "http://json-schema.org/draft-07/schema", "$id": "ucf-tcp-udp-ep-1.0.0", "title": " UCS TCP/UDP Endpoint", "description": "The object defines UCS TCP/UDP Endpoint Specification", "type": "object", "required": [ "transportProtocol" ], "properties": { "transportProtocol": { "description": "Protocol for data transport. e.g. RTP / RAW etc", "type": "string" }, "mediaType": { "description": "Type of media audio/video", "type": "string" }, "mediaFormat": { "description": "Media Format e.g. h264/aac/raw", "type": "string" }, "multicast": { "description": "Unicast or Multicast mode", "type": "string" } } } The file can be in YAML or JSON format and must have the filename `.yaml` or `.json` respectively. A sample endpoint definition file: { "transportProtocol": "RTP" } Endpoint Connections & Validation[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#endpoint-connections-validation "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------- As mentioned initially, a connection in a UCS Application represents a connection between an **Egress** endpoint of a client microservice and **Ingress** of a server microservice. In the textual representation, connections are specified under the `connections` field of the application in the format `/: /`. The following is an example of a connection in an application: connections: hello-client/http-api: hello-server/http-api In the visual representation (UCS Studio), connections are represented as lines connecting two ports (endpoints). The connections (lines) are color-coded. Different colors are used based on the scheme of the endpoints it connects. UCS Application building tools `UCS Application Builder CLI` and `UCS Studio` perform basic endpoint connection validation. They validate if the `scheme` and `protocol` is the same for the **Ingress** and **Egress** endpoints of a connection. Egress Endpoint with Multiple Connections[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#egress-endpoint-with-multiple-connections "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Some **Egress** endpoints might allow connecting to multiple **Ingress** endpoints. This is indicated if the egress endpoint has `multi` field set to `true`. In textual representation, multiple connections can be specified in the format: /: [ /, / ] The following is an example: connections: hello-client/http-api: [ hello-server/http-api, some-other-server/http-api ] External Endpoints[#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#external-endpoints "Link to this heading") --------------------------------------------------------------------------------------------------------------------------- In some applications, some client microservices might want to connect to a service / endpoint that is not part of the application. For instance, the service might be hosted externally. For this purpose, UCS provides a pseudo microservice `ucf.svc.external-endpoint` that can be added to applications. It has an **Ingress** endpoint named `endpoint` to which **Egress** endpoints of client microservices can be connected. An example of usage of the pseudo microservice `ucf.svc.external-endpoint` in a UCS Application is shown below: components: - name: hello-client type: ucf.svc.hello-client - name: hello-server type: ucf.svc.external-endpoint parameters: service: 10.123.2.123 port: 8080 connections: hello-client/http-api: hello-server/endpoint No connection validation is performed when `ucf.svc.external-endpoint` is part of the connection. The only job of `hello-server` component is to set the service address `10.123.2.123` and port `8080` on the client microservice `hello-client`. Links/Buttons: - [#](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#external-endpoints) - [Creating a Microservice](https://docs.nvidia.com/ucf/2.10.0/text/UCS_MsDevelopment.html#ms-development) - [HTTP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#http-endpoint) - [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) - [gRPC](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#grpc-endpoint) - [https://developers.google.com/protocol-buffers/docs/proto3](https://developers.google.com/protocol-buffers/docs/proto3.md) - [RTSP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#rtsp-endpoint) - [https://www.rfc-editor.org/rfc/rfc2326.html](https://www.rfc-editor.org/rfc/rfc2326.html) - [AsyncIO](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#asyncio-endpoint) - [asyncapi/spec](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md) - [UCX](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#ucx-endpoint) - [RESP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#resp-endpoint) - [MongoDB Wire](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#mongodb-wire-endpoint) - [Raw UDP / TCP](https://docs.nvidia.com/ucf/2.10.0/text/UCS_endpoints.html#raw-endpoint)