Skip to content

PTP Status Reporting via Custom Resource Conditions #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

PTP Status Reporting via Custom Resource Conditions #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 141 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
- [PTP Operator](#ptp-operator)
- [PtpOperatorConfig](#ptpoperatorconfig)
- [PtpConfig](#ptpconfig)
- [PtpConfig Status](#ptpconfig-status)
- [Quick Start](#quick-start)

## PTP Operator
Expand Down Expand Up @@ -314,6 +315,146 @@ Two ptp4l configurations must exist with the phc2sysOPts field set to an empty s
The names of these ptp4l configurations will be used and listed under the ptpSettings/haProfiles key in the phc2sys-only enabled ptpConfig.


## PtpConfig Status
PtpConfig includes a status subresource with `ptpStatus.conditions[]` that operands (linuxptp-daemon, cloud-event-proxy) can update. Each condition includes `type`, `profile` (logical profile), `filename` (active config file), `status`, `reason`, `message`, and `lastUpdateTime`.

Example populated status (GM):
```yaml
status:
matchList:
- nodeName: worker-0
profile: GM-Profile-A
ptpStatus:
conditions:
- type: PTP4lRunning
profile: GM-Profile-A
filename: ptp4l.0.config
status: "True"
reason: Started
message: "ptp4l is running (pid 3124)"
lastUpdateTime: "2025-06-27T10:13:10Z"
- type: LockState
profile: GM-Profile-A
filename: ptp4l.0.config
status: "True"
reason: LOCKED
message: "clock state is LOCKED"
lastUpdateTime: "2025-06-27T10:15:00Z"
- type: ClockClass
profile: GM-Profile-A
filename: ptp4l.0.config
status: "True"
reason: Class6
message: "clock class is 6"
lastUpdateTime: "2025-06-27T10:15:00Z"
- type: PortState
profile: GM-Profile-A
filename: ptp4l.0.config
status: "True"
reason: MASTER
message: "interface ens5f0 state MASTER"
lastUpdateTime: "2025-06-27T10:13:50Z"
- type: ClockType
profile: GM-Profile-A
filename: ptp4l.0.config
status: "True"
reason: T-GM
message: "profile reports T-GM Clock"
lastUpdateTime: "2025-06-27T10:13:00Z"

Example populated status (OC):
```yaml
status:
ptpStatus:
conditions:
- type: PTP4lRunning
profile: OC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: Started
message: "ptp4l is running"
lastUpdateTime: "2025-06-27T11:05:00Z"
- type: LockState
profile: OC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: LOCKED
message: "OC locked to GM"
lastUpdateTime: "2025-06-27T11:06:10Z"
- type: ClockClass
profile: OC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: Class6
message: "clock class is 6"
lastUpdateTime: "2025-06-27T11:06:10Z"
- type: PortState
profile: OC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: SLAVE
message: "interface ens5f1 state SLAVE (receiving time)"
lastUpdateTime: "2025-06-27T11:05:20Z"
- type: ClockType
profile: OC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: OC
message: "profile reports Ordinary Clock"
lastUpdateTime: "2025-06-27T11:05:00Z"
```

Example populated status (BC):
```yaml
status:
ptpStatus:
conditions:
- type: PTP4lRunning
profile: BC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: Started
message: "ptp4l is running"
lastUpdateTime: "2025-06-27T12:00:00Z"
- type: LockState
profile: BC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: HOLDOVER
message: "BC in holdover"
lastUpdateTime: "2025-06-27T12:01:00Z"
- type: ClockClass
profile: BC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: Class7
message: "clock class is 7"
lastUpdateTime: "2025-06-27T12:01:00Z"
- type: PortState
profile: BC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: SLAVE
message: "ingress port ens5f1 state SLAVE (receiving time)"
lastUpdateTime: "2025-06-27T12:00:20Z"
- type: PortState
profile: BC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: MASTER
message: "egress port ens5f0 state MASTER (transmitting time)"
lastUpdateTime: "2025-06-27T12:00:25Z"
- type: ClockType
profile: BC-Profile-A
filename: ptp4l.0.config
status: "True"
reason: BC
message: "profile reports Boundary Clock"
lastUpdateTime: "2025-06-27T12:00:00Z"
```

RBAC for linuxptp-daemon to update `ptpconfigs/status` is included in `bindata/linuxptp/ptp-daemon.yaml`.

## Quick Start

To install PTP Operator:
Expand Down
56 changes: 56 additions & 0 deletions api/v1/ptpconfig_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ limitations under the License.
package v1

import (
corev1 "k8s.io/api/core/v1"
apiextensions "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
Expand All @@ -38,6 +39,7 @@ type PtpConfigStatus struct {
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
// Important: Run "make" to regenerate code after modifying this file
MatchList []NodeMatchList `json:"matchList,omitempty"`
PtpStatus PtpStatus `json:"ptpStatus,omitempty"`
}

//+kubebuilder:object:root=true
Expand Down Expand Up @@ -112,6 +114,60 @@ type NodeMatchList struct {
Profile *string `json:"profile"`
}

// PtpConditionType represents categories of PTP conditions reported by operands
type PtpConditionType string

const (
// Process lifecycle
ConditionPodRestarted PtpConditionType = "PodRestarted"
ConditionPTP4lRunning PtpConditionType = "PTP4lRunning"
ConditionPhc2sysRunning PtpConditionType = "Phc2sysRunning"
ConditionTs2phcRunning PtpConditionType = "Ts2phcRunning"
ConditionSynce4lRunning PtpConditionType = "Synce4lRunning"
ConditionChronydRunning PtpConditionType = "ChronydRunning"
ConditionGPSPipeRunning PtpConditionType = "GPSPipeRunning"
ConditionGPSDRunning PtpConditionType = "GPSDRunning"

// Profile/apply
ConditionProfileApplied PtpConditionType = "ProfileApplied"

// NIC/PHC capabilities
ConditionNICCapabilities PtpConditionType = "NICCapabilities"

// State and class (values reflected in Reason/Message)
ConditionLockState PtpConditionType = "LockState" // LOCKED/HOLDOVER/FREERUN
ConditionClockClass PtpConditionType = "ClockClass" // 6/7/248
ConditionPortState PtpConditionType = "PortState" // INITIALIZING/LISTENING/SLAVE/MASTER/FAULTY
ConditionClockType PtpConditionType = "ClockType" // OC/BC

// Event/CEP
ConditionEventFramework PtpConditionType = "EventFramework"

// GNSS/DPLL (when applicable)
ConditionGNSSState PtpConditionType = "GNSSState"
ConditionDPLLStatus PtpConditionType = "DPLLStatus"

// Overall service readiness
ConditionPTPServiceReady PtpConditionType = "PTPServiceReady"
)

// PtpCondition mirrors standard Kubernetes condition patterns
type PtpCondition struct {
Type PtpConditionType `json:"type"`
Profile string `json:"profile,omitempty"`
Filename string `json:"filename,omitempty"`
Process string `json:"process,omitempty"`
Status corev1.ConditionStatus `json:"status"`
Reason string `json:"reason,omitempty"`
Message string `json:"message,omitempty"`
LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"`
}

// PtpStatus aggregates conditions emitted by operands for this PtpConfig
type PtpStatus struct {
Conditions []PtpCondition `json:"conditions,omitempty"`
}

func init() {
SchemeBuilder.Register(&PtpConfig{}, &PtpConfigList{})
}
39 changes: 39 additions & 0 deletions api/v1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

29 changes: 29 additions & 0 deletions bindata/linuxptp/ptp-daemon.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,35 @@ subjects:
name: prometheus-k8s
namespace: openshift-monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: ptpconfig-status-writer
namespace: openshift-ptp
rules:
- apiGroups:
- ptp.openshift.io
resources:
- ptpconfigs/status
verbs:
- get
- update
- patch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: ptpconfig-status-writer-linuxptp
namespace: openshift-ptp
subjects:
- kind: ServiceAccount
name: linuxptp-daemon
namespace: openshift-ptp
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: ptpconfig-status-writer
---
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
Expand Down
2 changes: 1 addition & 1 deletion bundle/manifests/ptp-operator.clusterserviceversion.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ metadata:
categories: Networking
certified: "false"
containerImage: quay.io/openshift/origin-ptp-operator:4.21
createdAt: "2025-09-25T09:20:14Z"
createdAt: "2025-10-03T17:05:44Z"
description: This software enables configuration of Precision Time Protocol(PTP)
on Kubernetes. It detects hardware capable PTP devices on each node, and configures
linuxptp processes such as ptp4l, phc2sys and timemaster.
Expand Down
34 changes: 34 additions & 0 deletions bundle/manifests/ptp.openshift.io_ptpconfigs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,40 @@ spec:
- profile
type: object
type: array
ptpStatus:
description: PtpStatus aggregates conditions emitted by operands for
this PtpConfig
properties:
conditions:
items:
description: PtpCondition mirrors standard Kubernetes condition
patterns
properties:
filename:
type: string
lastUpdateTime:
format: date-time
type: string
message:
type: string
process:
type: string
profile:
type: string
reason:
type: string
status:
type: string
type:
description: PtpConditionType represents categories of PTP
conditions reported by operands
type: string
required:
- status
- type
type: object
type: array
type: object
type: object
type: object
served: true
Expand Down
Loading
Loading