mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
443 lines
12 KiB
Plaintext
443 lines
12 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
// * networking/ptp/ptp-events-rest-api-reference.adoc
|
|
|
|
:_mod-docs-content-type: PROCEDURE
|
|
[id="cnf-fast-event-notifications-api-refererence_{context}"]
|
|
= PTP events REST API v1 endpoints
|
|
|
|
[id="api-ocloud-notifications-v1-subscriptions_{context}"]
|
|
== api/ocloudNotifications/v1/subscriptions
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`GET api/ocloudNotifications/v1/subscriptions`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Returns a list of subscriptions. If subscriptions exist, a `200 OK` status code is returned along with the list of subscriptions.
|
|
|
|
.Example API response
|
|
[source,json]
|
|
----
|
|
[
|
|
{
|
|
"id": "75b1ad8f-c807-4c23-acf5-56f4b7ee3826",
|
|
"endpointUri": "http://localhost:9089/event",
|
|
"uriLocation": "http://localhost:8089/api/ocloudNotifications/v1/subscriptions/75b1ad8f-c807-4c23-acf5-56f4b7ee3826",
|
|
"resource": "/cluster/node/compute-1.example.com/ptp"
|
|
}
|
|
]
|
|
----
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`POST api/ocloudNotifications/v1/subscriptions`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Creates a new subscription for the required event by passing the appropriate payload.
|
|
If a subscription is successfully created, or if it already exists, a `201 Created` status code is returned.
|
|
You can subscribe to the following PTP events:
|
|
|
|
* `lock-state` events
|
|
* `os-clock-sync-state` events
|
|
* `clock-class` events
|
|
* `gnss-sync-status` events
|
|
* `sync-state` events
|
|
|
|
.Query parameters
|
|
[cols=2*, width="60%", options="header"]
|
|
|====
|
|
|Parameter
|
|
|Type
|
|
|
|
|subscription
|
|
|data
|
|
|====
|
|
|
|
.Example PTP events subscription payload
|
|
[source,json]
|
|
----
|
|
{
|
|
"uriLocation": "http://localhost:8089/api/ocloudNotifications/v1/subscriptions",
|
|
"resource": "/cluster/node/compute-1.example.com/ptp"
|
|
}
|
|
----
|
|
|
|
.Example PTP lock-state events subscription payload
|
|
[source,json]
|
|
----
|
|
{
|
|
"endpointUri": "http://localhost:8989/event",
|
|
"resource": "/cluster/node/{node_name}/sync/ptp-status/lock-state"
|
|
}
|
|
----
|
|
|
|
.Example PTP os-clock-sync-state events subscription payload
|
|
[source,json]
|
|
----
|
|
{
|
|
"endpointUri": "http://localhost:8989/event",
|
|
"resource": "/cluster/node/{node_name}/sync/sync-status/os-clock-sync-state"
|
|
}
|
|
----
|
|
|
|
.Example PTP clock-class events subscription payload
|
|
[source,json]
|
|
----
|
|
{
|
|
"endpointUri": "http://localhost:8989/event",
|
|
"resource": "/cluster/node/{node_name}/sync/ptp-status/clock-class"
|
|
}
|
|
----
|
|
|
|
.Example PTP gnss-sync-status events subscription payload
|
|
[source,json]
|
|
----
|
|
{
|
|
"endpointUri": "http://localhost:8989/event",
|
|
"resource": "/cluster/node/{node_name}/sync/gnss-status/gnss-sync-status"
|
|
}
|
|
----
|
|
|
|
.Example sync-state subscription payload
|
|
[source,json]
|
|
----
|
|
{
|
|
"endpointUri": "http://localhost:8989/event",
|
|
"resource": "/cluster/node/{node_name}/sync/sync-status/sync-state"
|
|
}
|
|
----
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`DELETE api/ocloudNotifications/v1/subscriptions`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Deletes all subscriptions.
|
|
|
|
.Example API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"status": "deleted all subscriptions"
|
|
}
|
|
----
|
|
|
|
[id="api-ocloud-notifications-v1-subscriptions-subscription_id_{context}"]
|
|
== api/ocloudNotifications/v1/subscriptions/{subscription_id}
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`GET api/ocloudNotifications/v1/subscriptions/{subscription_id}`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Returns details for the subscription with ID `subscription_id`.
|
|
|
|
.Global path parameters
|
|
[cols=2*, width="60%", options="header"]
|
|
|====
|
|
|Parameter
|
|
|Type
|
|
|
|
|`subscription_id`
|
|
|string
|
|
|====
|
|
|
|
.Example API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"id":"48210fb3-45be-4ce0-aa9b-41a0e58730ab",
|
|
"endpointUri": "http://localhost:9089/event",
|
|
"uriLocation":"http://localhost:8089/api/ocloudNotifications/v1/subscriptions/48210fb3-45be-4ce0-aa9b-41a0e58730ab",
|
|
"resource":"/cluster/node/compute-1.example.com/ptp"
|
|
}
|
|
----
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`DELETE api/ocloudNotifications/v1/subscriptions/{subscription_id}`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Deletes the subscription with ID `subscription_id`.
|
|
|
|
.Global path parameters
|
|
[cols=2*, width="60%", options="header"]
|
|
|====
|
|
|Parameter
|
|
|Type
|
|
|
|
|`subscription_id`
|
|
|string
|
|
|====
|
|
|
|
.Example API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"status": "OK"
|
|
}
|
|
----
|
|
|
|
[id="api-ocloudnotifications-v1-health_{context}"]
|
|
== api/ocloudNotifications/v1/health
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`GET api/ocloudNotifications/v1/health/`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Returns the health status for the `ocloudNotifications` REST API.
|
|
|
|
.Example API response
|
|
[source,terminal]
|
|
----
|
|
OK
|
|
----
|
|
|
|
[id="api-ocloudnotifications-v1-publishers_{context}"]
|
|
== api/ocloudNotifications/v1/publishers
|
|
|
|
[IMPORTANT]
|
|
====
|
|
The `api/ocloudNotifications/v1/publishers` endpoint is only available from the cloud-event-proxy container in the PTP Operator managed pod.
|
|
It is not available for consumer applications in the application pod.
|
|
====
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`GET api/ocloudNotifications/v1/publishers`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Returns a list of publisher details for the cluster node.
|
|
The system generates notifications when the relevant equipment state changes.
|
|
|
|
You can use equipment synchronization status subscriptions together to deliver a detailed view of the overall synchronization health of the system.
|
|
|
|
.Example API response
|
|
[source,json]
|
|
----
|
|
[
|
|
{
|
|
"id": "0fa415ae-a3cf-4299-876a-589438bacf75",
|
|
"endpointUri": "http://localhost:9085/api/ocloudNotifications/v1/dummy",
|
|
"uriLocation": "http://localhost:9085/api/ocloudNotifications/v1/publishers/0fa415ae-a3cf-4299-876a-589438bacf75",
|
|
"resource": "/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state"
|
|
},
|
|
{
|
|
"id": "28cd82df-8436-4f50-bbd9-7a9742828a71",
|
|
"endpointUri": "http://localhost:9085/api/ocloudNotifications/v1/dummy",
|
|
"uriLocation": "http://localhost:9085/api/ocloudNotifications/v1/publishers/28cd82df-8436-4f50-bbd9-7a9742828a71",
|
|
"resource": "/cluster/node/compute-1.example.com/sync/ptp-status/clock-class"
|
|
},
|
|
{
|
|
"id": "44aa480d-7347-48b0-a5b0-e0af01fa9677",
|
|
"endpointUri": "http://localhost:9085/api/ocloudNotifications/v1/dummy",
|
|
"uriLocation": "http://localhost:9085/api/ocloudNotifications/v1/publishers/44aa480d-7347-48b0-a5b0-e0af01fa9677",
|
|
"resource": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state"
|
|
},
|
|
{
|
|
"id": "778da345d-4567-67b0-a43f0-rty885a456",
|
|
"endpointUri": "http://localhost:9085/api/ocloudNotifications/v1/dummy",
|
|
"uriLocation": "http://localhost:9085/api/ocloudNotifications/v1/publishers/778da345d-4567-67b0-a43f0-rty885a456",
|
|
"resource": "/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status"
|
|
}
|
|
]
|
|
----
|
|
|
|
[id="resource-address-current-state_{context}"]
|
|
== api/ocloudNotifications/v1/{resource_address}/CurrentState
|
|
|
|
[discrete]
|
|
=== HTTP method
|
|
|
|
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/ptp-status/lock-state/CurrentState`
|
|
|
|
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/sync-status/os-clock-sync-state/CurrentState`
|
|
|
|
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/ptp-status/clock-class/CurrentState`
|
|
|
|
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/sync-status/sync-state/CurrentState`
|
|
|
|
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/gnss-status/gnss-sync-state/CurrentState`
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
Returns the current state of the `os-clock-sync-state`, `clock-class`, `lock-state`, `gnss-sync-status`, or `sync-state` events for the cluster node.
|
|
|
|
* `os-clock-sync-state` notifications describe the host operating system clock synchronization state. Can be in `LOCKED` or `FREERUN` state.
|
|
* `clock-class` notifications describe the current state of the PTP clock class.
|
|
* `lock-state` notifications describe the current status of the PTP equipment lock state. Can be in `LOCKED`, `HOLDOVER` or `FREERUN` state.
|
|
* `sync-state` notifications describe the current status of the least synchronized of the `ptp-status/lock-state` and
|
|
`sync-status/os-clock-sync-state` endpoints.
|
|
* `gnss-sync-status` notifications describe the GNSS clock synchronization state.
|
|
|
|
.Global path parameters
|
|
[cols=2*, width="60%", options="header"]
|
|
|====
|
|
|Parameter
|
|
|Type
|
|
|
|
|`resource_address`
|
|
|string
|
|
|====
|
|
|
|
.Example lock-state API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"id": "c1ac3aa5-1195-4786-84f8-da0ea4462921",
|
|
"type": "event.sync.ptp-status.ptp-state-change",
|
|
"source": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",
|
|
"dataContentType": "application/json",
|
|
"time": "2023-01-10T02:41:57.094981478Z",
|
|
"data": {
|
|
"version": "1.0",
|
|
"values": [
|
|
{
|
|
"resource": "/cluster/node/compute-1.example.com/ens5fx/master",
|
|
"dataType": "notification",
|
|
"valueType": "enumeration",
|
|
"value": "LOCKED"
|
|
},
|
|
{
|
|
"resource": "/cluster/node/compute-1.example.com/ens5fx/master",
|
|
"dataType": "metric",
|
|
"valueType": "decimal64.3",
|
|
"value": "29"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
----
|
|
|
|
.Example os-clock-sync-state API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"specversion": "0.3",
|
|
"id": "4f51fe99-feaa-4e66-9112-66c5c9b9afcb",
|
|
"source": "/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state",
|
|
"type": "event.sync.sync-status.os-clock-sync-state-change",
|
|
"subject": "/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state",
|
|
"datacontenttype": "application/json",
|
|
"time": "2022-11-29T17:44:22.202Z",
|
|
"data": {
|
|
"version": "1.0",
|
|
"values": [
|
|
{
|
|
"resource": "/cluster/node/compute-1.example.com/CLOCK_REALTIME",
|
|
"dataType": "notification",
|
|
"valueType": "enumeration",
|
|
"value": "LOCKED"
|
|
},
|
|
{
|
|
"resource": "/cluster/node/compute-1.example.com/CLOCK_REALTIME",
|
|
"dataType": "metric",
|
|
"valueType": "decimal64.3",
|
|
"value": "27"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
----
|
|
|
|
.Example clock-class API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"id": "064c9e67-5ad4-4afb-98ff-189c6aa9c205",
|
|
"type": "event.sync.ptp-status.ptp-clock-class-change",
|
|
"source": "/cluster/node/compute-1.example.com/sync/ptp-status/clock-class",
|
|
"dataContentType": "application/json",
|
|
"time": "2023-01-10T02:41:56.785673989Z",
|
|
"data": {
|
|
"version": "1.0",
|
|
"values": [
|
|
{
|
|
"resource": "/cluster/node/compute-1.example.com/ens5fx/master",
|
|
"dataType": "metric",
|
|
"valueType": "decimal64.3",
|
|
"value": "165"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
----
|
|
|
|
.Example sync-state API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"specversion": "0.3",
|
|
"id": "8c9d6ecb-ae9f-4106-82c4-0a778a79838d",
|
|
"source": "/sync/sync-status/sync-state",
|
|
"type": "event.sync.sync-status.synchronization-state-change",
|
|
"subject": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
|
|
"datacontenttype": "application/json",
|
|
"time": "2024-08-28T14:50:57.327585316Z",
|
|
"data":
|
|
{
|
|
"version": "1.0",
|
|
"values": [
|
|
{
|
|
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
|
|
"data_type": "notification",
|
|
"value_type": "enumeration",
|
|
"value": "LOCKED"
|
|
}]
|
|
}
|
|
}
|
|
----
|
|
|
|
.Example gnss-sync-status API response
|
|
[source,json]
|
|
----
|
|
{
|
|
"id": "435e1f2a-6854-4555-8520-767325c087d7",
|
|
"type": "event.sync.gnss-status.gnss-state-change",
|
|
"source": "/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status",
|
|
"dataContentType": "application/json",
|
|
"time": "2023-09-27T19:35:33.42347206Z",
|
|
"data": {
|
|
"version": "1.0",
|
|
"values": [
|
|
{
|
|
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
|
|
"dataType": "notification",
|
|
"valueType": "enumeration",
|
|
"value": "LOCKED"
|
|
},
|
|
{
|
|
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
|
|
"dataType": "metric",
|
|
"valueType": "decimal64.3",
|
|
"value": "5"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
----
|