[vishnukothakapu]

Description

This PR adds the comprehensive UI Design Document for the LFX Term-3 Headlamp Plugin project (docs/headlamp-plugin-design.md).

It covers:

• Core goals and non-goals of the plugin UI
• Required integrations with NodeReadinessRule and NodeReadinessEvaluation CRDs
• View architecture (Dashboards, List Views, Node Extension)

Related Issue

Related to #327

Type of Change

/kind design
/kind documentation

Testing

Not applicable (documentation only).

Checklist

• make test passes
• make lint passes

Does this PR introduce a user-facing change?

NONE

Generative AI Usage Disclosure

• No AI tools were used
• AI tools were used (complete below)

How they were used: Antigravity was used to help format and organize the Markdown structure of this design document.

[kubernetes-prow]

@vishnukothakapu: The label(s) kind/design cannot be applied, because the repository doesn't have them.

Details

In response to this:

Description

This PR adds the comprehensive UI Design Document for the LFX Term-3 Headlamp Plugin project (docs/headlamp-plugin-design.md).

It covers:

• Core goals and non-goals of the plugin UI
• Required integrations with NodeReadinessRule and NodeReadinessEvaluation CRDs
• View architecture (Dashboards, List Views, Node Extension)
• Scale limitations and proposed UX enhancements

Related Issue

Related to #327

Type of Change

/kind design
/kind documentation

Testing

Not applicable (documentation only).

Checklist

• make test passes
• make lint passes

Does this PR introduce a user-facing change?

NONE

Generative AI Usage Disclosure

• No AI tools were used
• AI tools were used (complete below)

How they were used: Antigravity was used to help format and organize the Markdown structure of this design document.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[netlify]

✅ Deploy Preview for node-readiness-controller canceled.

Name	Link
🔨 Latest commit	1978a39
🔍 Latest deploy log	https://app.netlify.com/projects/node-readiness-controller/deploys/6ae8b8359143ae4a8cdab47e

[kubernetes-prow]

Hi @vishnukothakapu. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[vishnukothakapu]

cc @ajaysundark @AnuragThePathak

[AnuragThePathak]

I will look into part 6 onwards in upcoming days. In the meantime these are some points for you to look into in case they skipped proper human iteration.

[AnuragThePathak]

My thoughts after checking the full document -

1. Great job extending beyond the spec I wrote down.
2. This is already very long for a random passer-by to read. However we can still add more details like more concrete details of the UI, for example how a field value in a details page will actually look like.
3. I would also encourage you to fine tune the document yourself by undergoing one or two revision with the points I mentioned.
4. What I wrote in SPEC was mainly from the technical point of view. I didn't dive deep into the UI/UX aspect. Hence on top of what I added I would request you to do analysis on existing patterns in headlamp and its plugins and finalize the UI for every column and field and other part properly. If we use simple text mention that too. That's the level of sharpness and precision is what we need.

All of these points I mentioned will add another 10-20 hours of work or may slightly more in worst case. But it will help avoid much back-and-forth during implementation phase + will significantly cut down effort in implementation stage for you as well, while using LLM.

[AnuragThePathak]

Thanks for updating the design doc to reflect client-side aggregation over status.nodeEvaluations as discussed!

A few technical adjustments needed to get this fully polished:

1. Client-side aggregation logic (Sections 7.1, 7.2, and 11):

   • In Sections 7.1 and 7.2, please replace references like status.nodeEvaluations.targetedNodes with the actual array logic:
     • Targeted: nodeEvaluations.length
     • Satisfied: count where taintStatus === 'Absent'
     • Unsatisfied: count where taintStatus === 'Present'
     • Failed: failedNodes.length
   • In Section 11 (Line 418), please update the note that still says the plugin "avoids client-side iteration over large arrays" so it aligns with this client-side aggregation strategy for Phase 1.

2. NRE Schema Alignment (Section 3.2):

   • In api/v1alpha1/nodereadinessevaluation_types.go, an NRE is 1:1 per Node (spec.nodeName: string). There is no spec.ruleRef.
   • The status field is status.rules: []RuleEvaluation (not ruleEvaluations).
   • The evaluation state is an enum ruleStatus: "Satisfied" | "Unsatisfied" (not a boolean satisfied).

3. Conditions Table Styling (Section 7.3):

   • In the Conditions table under Rule Details, let's avoid rendering requiredStatus: "False" with a red status="error" badge. In Kubernetes condition specs, False is often the healthy/desired target (e.g. NetworkUnavailable == False). Since it is just a spec requirement rather than a runtime failure, using standard neutral text or a default chip fits much better.

[AnuragThePathak]

The direction looks good to me, but many details being far from ideal in my view. Didn't validate CRD field level details either. Though I think the doc is in a state to actually start pushing actual code, and we can review a lot of details in that review.

But anyways I think @vishnukothakapu we should sit down together for a hour and rectify a few points to get a good shape rather than going through infinite feedback and correction loop.

With that being said @ajaysundark and @rawadhossain, would you two like to take a look before the final polish? I would appreciate if you two pay more attention to persona part and landing screen choice if not the rest.

[vishnukothakapu]

cc @ajaysundark @AnuragThePathak

[vishnukothakapu]

@illume Would love your review specifically from a headlamp point of view to make sure the component choices and UI integration align with Headlamp best practices!

[AnuragThePathak]

Work on the suggestions as discussed over the call.

[illume]

Thanks for updating this. The direction fits Headlamp well: native Kubernetes watches, shared components, cluster-aware navigation, and no separate backend. The distinction between taint presence and logical readiness is particularly important.

Disclosure: "assisted by copilot", but I did read this design document. Initial thoughts...

---

**Overall, I think we should try and start releasing more often rather than try and strictly adhere to a design document. To simplify, I think one alpha release before demo day, and then at least two more alpha releases in the remaining term will let us gather good feedback and react to it. **

---

some things to consider, and initial thoughts...

1. Consider the original project outcome

The LFX proposal includes node-level investigation: applicable rules, per-condition results, failure reasons, managed taints, Events, and lifecycle conditions.

An NRR-only first alpha is reasonable. We could distinguish first-alpha scope from end-of-project scope, and track NRE-dependent work, Events, and bootstrap-completion reporting as deliverables or explicitly agreed deferrals.

For NRE, it would be good to add a dependency owner and decision date. “After upstream merges” is not sufficient planning for the remaining mentorship period.

2. Complete the evaluation contract and align the implementation

Sections 5.4–5.6 need a concrete per-condition evaluation table, not only rule-level status and reason/message. Against the currently proposed NRE schema, include status.conditions, status.rules[].readinessConditions, and the actual timestamp fields (firstEvaluatedAt, lastEvaluatedAt). Use NotAvailable as the API value; “Not Available” can remain display text.

Also synchronize the implementation PR with this design before releasing: its legacy statistics fallback still labels absent taints as “satisfied,” and dry-run failures become N/A. Those conflict with the revised semantics here.

Please test missing data versus zero, unknown states, and bootstrap-only behavior. An absent taint must not imply logical satisfaction or completed bootstrap.

3. Correct the Headlamp RBAC assumption

Section 5.6 says Headlamp cannot perform authorization checks for plugin CRDs. Headlamp provides AuthVisible and KubeObject.getAuthorization for custom resource classes; Kueue demonstrates this. That does not mean every plugin read is automatically preflighted.

Use the existing mechanisms where appropriate and still handle API errors. Update the permission table to include Node reads from NRE details, while avoiding additional Node fetches in the extension when Headlamp already supplies the resource. Test NRE access without Node access.

4. Make validation measurable and incremental

Section 3 correctly acknowledges payload costs; Section 7 implies pagination solves them, but does it? Test representative node/rule counts, overlapping rules, large responses, and watch-update bursts. Record payload size, render time, browser memory, and tested limits.

There's some load-tests/ in the headlamp repo which uses KWOK for load testing and stress testing, maybe that could be useful here.

Tests should accompany each feature, including permission errors, pending/stale status, watch updates, and cluster switching. Consider keyboard access, light/dark themes, and translatable strings rather than leaving these until final polish.

5. Replace beta/stable milestones with three alpha checkpoints

We are almost halfway through the project. Please use calendar dates and plan for two interim alphas plus a final alpha:

Release	Timing	Purpose
First alpha	Soon, ideally before the October 19 demo	Installable rule list/details, correct semantics, basic tests, sample manifests, and installation instructions.
Second alpha	Midway through the remaining project time	Incorporate feedback and deliver the agreed next functionality, especially node investigation.
Final alpha	Near project end, allowing verification time	Agreed deliverables, validation results, documented limitations, and maintenance handover.

IMHO: Do not block the first alpha on a separate landing dashboard. A useful, installable list/detail workflow is enough to begin gathering feedback. A "Getting Started" guide in the README.md is more important for feedback, and to ease testing by other developers reviewing.

For Demo day Monday, October 19, aim to demonstrate packaged installation and live updates without reloads, clearly identifying any NRE-dependent gaps. For Tuesday, October 20, bring the release/demo links, completed/remaining/blocked deliverables, dependency decisions, and dated remaining milestones.

Follow the getting-started guide and plugin tutorials for shared views and release packaging. Each alpha should have an archive/checksum, compatibility information, release notes, and a reproducible installation walkthrough.

Overall: ship a small, correct alpha soon, while keeping the original node-debugging outcome visible and achievable. Maps and forms can remain outside this initial read-only scope.

[AnuragThePathak]

Seems like with some polish we can get this in a mergable state. Let's sync up over a call to surgically make the adjustments needed and close this.

[AnuragThePathak]

Have you reached any agreement regarding this with @Karthik-K-N or @ajaysundark ?

[AnuragThePathak]

This looks very much right to me. Just minor changes and we would be sorted.

[AnuragThePathak]

LGTM

@ajaysundark PTAL at your convenience.

Some things will be updated in actual implementation incrementally and then this design doc will also require updates. For now it reflects the current implementation plan than the ideal plan or final idea of implementation.

[kubernetes-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: AnuragThePathak, vishnukothakapu
Once this PR has been reviewed and has the lgtm label, please assign dchen1107 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[AnuragThePathak]

Following up on my comment in headlamp-k8s/plugins#1405, I am bringing this into to notice here too, once we plan to make update to the strategy for determining if the controller is active or not, let's update the same thing here too.

Relying on lease is a much better choice, because first of all, it's the administrators or such people with higher privileges is the primary target to show controller is active or not, and they are likely to have enough access to view leases.

On top of that, deployment name and namespace based search to find, NRC controller is not a good idea because first of all namespace where it is installed is highly volatile and name of the deployment can also fluctuate depending on various reasons including how it's configured in helm/kustomize etc.

However, often labels in the deployments has been consistent across various manifests. Hence, leveraging that sounds like a better strategy accompanied by check for image name as same label can be used by other deployments too, and our NRC image is overall consistent to apply regex or prefix match.

Hence this would be my proposed strategy going forward.

flowchart TD
    Start(["Start: Check Controller Status"]) --> CRDCheck{"1. Check CRD Presence<br>nodereadinessrules.readiness.node.x-k8s.io"}
    CRDCheck -- "404 Not Found" --> NotInstalled["🔴 Not Installed<br>(CRD not present in cluster)"]
    
    CRDCheck -- "200 Found" --> LeaseCheck{"2. Primary Check: Query Lease<br>ba65f13e.readiness.node.x-k8s.io"}
    
    LeaseCheck -- "Lease Found" --> TimeCheck{"renewTime < 45s?"}
    TimeCheck -- "Yes" --> ActiveLeader["🟢 Active (Leader)<br>Pod: holderIdentity"]
    TimeCheck -- "No" --> InactiveLease["🔴 Inactive<br>Leader lease expired"]
    
    LeaseCheck -- "0 items / Not Found<br>(--leader-elect=false)" --> DeployCheck{"3. Fallback: Query Deployments<br>app.kubernetes.io/name in (...) "}
    
    DeployCheck -- "Matches Found" --> VerifyImage{"Client-side Check:<br>Image contains NRC?"}
    VerifyImage -- "Yes" --> ReplicaCheck{"readyReplicas > 0?"}
    ReplicaCheck -- "Yes" --> ActiveDeploy["🟢 Active (Non-HA)<br>Deployment ready"]
    ReplicaCheck -- "No" --> InactiveDeploy["🔴 Inactive<br>0 ready replicas"]
    
    VerifyImage -- "No" --> UnknownState["⚪ Unknown State<br>Custom setup / Ambiguous"]
    DeployCheck -- "0 matches" --> UnknownState

Loading