nebari-dev / nebari-dev/llm-serving-pack

Document internal endpoint authorization and admission rules in design.md

Open Beginner friendly
#54 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: documentation 📖 needs: documentation 📖 needs: follow-up 📥 priority: medium ⚡ type: maintenance 🛠
Dominant language
Go
Stars
3
Forks
3
Avg merge
16h 31m
Merged PRs (30d)
11

Description

Follow-up from #47. Surfaced by the architecture review alongside the pieces tracked in #48 #49 #50 #51 #52 #53.

docs/design.md promised "validates group membership against the model's access.groups" for the internal endpoint, which is now true, but the doc doesn't describe how - specifically, which Envoy Gateway field the operator uses and what its semantics are. A couple of the follow-ups in the sibling issues would have been easier to spot with the rule written down.

Two sections to add

Internal endpoint authorization

The internal SecurityPolicy enforces group membership at the gateway via the authorization block on Envoy Gateway SecurityPolicy (v1alpha1). When a model is not public, the operator emits defaultAction: Deny plus one Allow rule whose principal.jwt.claims matches the configured groupsClaim against spec.access.groups as a StringArray. When spec.access.public is true, the authorization block is omitted and any valid JWT is allowed. This enforcement is symmetric with the external path's group gating (UI mint-time check plus periodic audit) but runs on every request rather than on key issuance.

Envoy Gateway JWT claim matchers in v1.3 treat the claim name as a top-level claim key; nested claims (e.g., realm_access.roles) are supported by claimToHeaders but not by the authorization block (tracked in #50).

Validating webhook rules (consolidated)

The validating webhook rejects LLMModels when:

  • The namespace lacks the nebari.dev/managed=true label.
  • The effective subdomain exceeds 63 characters.
  • The effective subdomain collides with another LLMModel across all namespaces.
  • spec.access.public is not true and spec.access.groups is empty (tracked in #51).
Also

Consider lifting the "BuildXResources is pure, boolOrDefault is the canonical *bool reader, unstructured objects go through labelsToInterface(StandardLabels(model))" pattern into an operator/ARCHITECTURE.md. Several of the sibling follow-ups would be one-line fixes if this were documented.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read docs/design.md first, then review the linked sibling issues for the authorization and webhook context. Add the two specified sections describing Envoy Gateway authorization and consolidated validation rules; consider the optional operator/ARCHITECTURE.md addition only if its scope is confirmed. Done means the documented behavior matches the rules stated in this issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.