[codyhartsook]

Description

v1alpha3 model and MCP server references can't name another kind:

Reference	Type today	Issue
MCP server	corev1.TypedObjectReference	An omitted apiGroup means the core group, so CEL rules pin it to RemoteMCPServer. The CRD docs describe ReferenceGrant and a feature gate kagent doesn't use.
Model	v1alpha3.ObjectReference	No kind

This PR gives both one kagent-owned shape, like v1alpha2's TypedReference: optional group and kind next to name. Omitted values keep today's meaning, and a group other than api.kagent.dev must name its own kind. Any other kind fails with reason InvalidKind on ResolvedRefs, as in Gateway API. Egress policy references keep LocalObjectReference until a second policy kind exists.

A second kind must ship at least one release after this one. A v1.0.x controller ignores group and kind on a model reference and quietly resolves the same-named ModelConfig, which may call the model with a different credential. Before rolling back to v1.0.x, point model references back to ModelConfig.

Compatibility with v1.0.x

• Stored objects and manifests need no changes, and their revision digests stay the same.
• MCP kind defaults to RemoteMCPServer in the schema, so v1.0.x controllers and clients can still update the object.
• apiGroup stays as a deprecated MCP field that must be omitted. v1.0.x Go clients, including the kagent CLI, send it as null, and the gRPC API rejects unknown fields.
• Go: ObjectReference is renamed ModelConfigReference, and MCPToolBinding.Server changes type.
• Rolling the CRDs back to v1.0.x drops group and kind from model references at the next write.

docs/kubernetes-api.md and STYLE.md now say to own reference types instead of reusing corev1 ones. The name must not be empty CEL rules on model references are gone, since the schema already requires a non-empty name.

Stacked on this: #3607 keeps group and kind on references the UI saves.

Change Type

/kind feature

Changelog

Model and MCP server references accept optional `group` and `kind` fields. Omitted values keep their current meaning; other kinds report `InvalidKind`.

Validation

• make lint, including kube-api-linter, and make manifests.
• Unit and envtest suites for api/v1alpha3, translator, controller, grpcserver, substrate and cli.
• CRD admission: v1.0.x client JSON is accepted under default and strict validation, and a foreign group without its own kind is rejected on both references.
• Swapped the CRDs between this branch and v1.0.x in envtest. Objects stay updatable after rollback, and a v1.0.x client round trip succeeds.
• Compiled the same v1.0.x-shaped Agents on main and this branch for the kagent, Codex and Claude harnesses. The revision digests match.

[shashankram]

Reviewed the updated head a1b1e84. The egress reference changes are fully removed, and the remaining model and MCP reference changes look correct. No blocking findings.

[timflannagan]

Same thing as below. I might be missing something. I don't think we care about breaking Go clients right now, so I think we can remove this field. Rollbacks aren't currently supported afaik

[codyhartsook]

Decided to keep the field and reworded its comment to give the reason. The kagent CLI sends apiGroup: null, and the gRPC API rejects unknown fields (structuredobject.go:75), so a v1.0.x CLI would break against a new server. The kind default stays because the upgrade suite rolls back to the previous release.

[timflannagan]

Also something that I forgot to mention. I think we should update STYLE.md + any other relevant docs to avoid using types where we don't own the API evolution, e.g. corev1

[codyhartsook]

On the STYLE.md note: updated STYLE.md and docs/kubernetes-api.md. References use kagent-owned types, not corev1 ones. Existing corev1 fields keep their type until they need to change.