Feat: add AgentRuntime CRD types and documentation by varshaprasad96 · Pull Request #212 · kagenti/kagenti-operator

varshaprasad96 · 2026-03-10T23:47:05Z

Summary

Introduce the Agent Runtime custom resource for configuring agent parameters including identity (SPIFFE, IdP client registration) and observability (OTEL traces) on agent and tool workloads via targetRef-based binding.

Add AgentRuntimeSpec with type (agent|tool), targetRef, identity, and trace fields
Add AgentRuntimeStatus with phase, configuredPods, and conditions
Generate CRD manifest and deepcopy functions
Enable allowDangerousTypes for float64 sampling rate
Document AgentRuntime in api-reference.md and architecture.md

Next step: Configure the controller.

Signed-off-by: Varsha Prasad Narsing varshaprasad96@gmail.com
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

Related issue(s)

Related: kagenti/kagenti#862

(Optional) Testing Instructions

Fixes #

varshaprasad96 · 2026-03-10T23:49:29Z

kagenti-operator/Makefile

 .PHONY: manifests
 manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
-	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+	$(CONTROLLER_GEN) rbac:roleName=manager-role crd:allowDangerousTypes=true webhook paths="./..." output:crd:artifacts:config=config/crd/bases


Controller-gen rejects float32 and float64 types in CRD schemas because floating-point numbers can have precision issues when serialized to/from JSON. But this was intentional because float64 seemed a reasonable choice for sampling rate. The other option is to use resource.Quantity (string based decimal) or an integer percentage. Open to any specific suggestions.

K8s best practice here seems to be representing floats as strings when possible. resource.Quantity seems OK to me.

varshaprasad96 · 2026-03-10T23:51:06Z

cc: @cwiklik ptal

pdettori

Review Summary

Clean introduction of the AgentRuntime CRD for per-workload identity (SPIFFE, IdP client registration) and observability (OTEL traces). Good API design that reuses the existing TargetRef type from AgentCard. Documentation is thorough with YAML examples and kubectl usage.

Areas reviewed: Go API types, CRD YAML, Deep Copy, Makefile, go.mod, Docs
Commits: 1 commit, signed-off ✓
CI status: Build/E2E/Lint/Unit pending, DCO passed

One item to address in the architecture diagram (see inline comment). Rest are minor.

🤖 Reviewed with Claude Code

kagenti-operator/docs/architecture.md

kagenti-operator/api/v1alpha1/agentruntime_types.go

kagenti-operator/go.mod

grs · 2026-03-11T12:08:52Z

kagenti-operator/api/v1alpha1/agentruntime_types.go

+	// If empty, the operator flag value is used.
+	// +optional
+	// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9]([a-zA-Z0-9\-\.]*[a-zA-Z0-9])?$`
+	TrustDomain string `json:"trustDomain,omitempty"`


Is this something that will vary per-workload? (Rather than an aspect of how SPIRE is configured for the cluster as a whole)

This follows the same pattern already established in AgentCard's identityBinding.trustDomain (

kagenti-operator/kagenti-operator/api/v1alpha1/agentcard_types.go

Line 48 in f49ff3f

TrustDomain string `json:"trustDomain,omitempty"`

). One scenario could be federated SPIRE deployments where workloads in the same cluster may belong to different trust domains. I'm not sure if this is a use case we are addressing in Kagenti. Open to removing it if it makes more sense.

Right. In the AgentCard my thinking was to support federation scenarios like e.g., someone represents an agent from out of cluster and wants to verify its signature. This came up during discussions where folks pointed out the idea of representing out of cluster agents in the fashion of a MultiClusterService.

grs · 2026-03-11T12:10:02Z

kagenti-operator/api/v1alpha1/agentruntime_types.go

+}
+
+// ClientRegistration configures IdP client registration for an AgentRuntime.
+type ClientRegistration struct {


My understanding was that client registration was a temporary workaround until Keycloak supported authentication using kube and SPIFFE credentials (which it supposedly does as of 26.4).

Removed ClientRegistration from IdentitySpec - identity now only covers SPIFFE configuration.

grs · 2026-03-11T12:10:33Z

kagenti-operator/api/v1alpha1/agentruntime_types.go

+type ClientRegistration struct {
+	// Provider is the IdP provider type (e.g., "keycloak")
+	// +kubebuilder:validation:MinLength=1
+	Provider string `json:"provider"`


Would there not need to be a url at which the IdP could be found?

IIUC client registration is currently handled externally via Helm jobs in the kagenti repo, removing it in favor of Keycloak.

r3v5

Great work, @varshaprasad96 ! One suggestion, can we add some unit tests for new structures?

cwiklik

Clean introduction of the AgentRuntime CRD with well-structured API types, proper code generation, and thorough documentation. Good reuse of existing TargetRef from AgentCard and standard K8s patterns (metav1.Condition, status subresource, printer columns). All CI passes.

Adding supplementary notes alongside existing reviews from @pdettori, @grs, and @r3v5. I agree that @grs's questions about whether trust domain and client registration belong as per-workload config are important architectural decisions to resolve.

Also: thorough API reference docs with YAML examples and kubectl usage — well done.

Inline notes:

agentruntime_types.go:188: Nit — K8s convention is to not use omitempty on Spec since it should always be present. Status with omitempty is fine.
agentruntime_types.go:134: Security note for the controller implementation: corev1.SecretReference includes a namespace field, allowing cross-namespace secret references. When the controller is implemented, ensure RBAC and/or webhook validation prevent workloads from referencing secrets in namespaces they don't own. Aligns with @grs's broader questions about the identity section.

Areas reviewed: Go API types, CRD YAML, DeepCopy, Docs, Security
Commits: 1 commit, signed-off: yes
CI status: All 5 checks passing

Introduce the Agent Runtime custom resource for configuring agent parameters including identity (SPIFFE, IdP client registration) and observability (OTEL traces) on agent and tool workloads via targetRef-based binding. - Add AgentRuntimeSpec with type (agent|tool), targetRef, identity, and trace fields - Add AgentRuntimeStatus with phase, configuredPods, and conditions - Generate CRD manifest and deepcopy functions - Enable allowDangerousTypes for float64 sampling rate - Document AgentRuntime in api-reference.md and architecture.md Signed-off-by: Varsha Prasad Narsing <varshaprasad96@gmail.com> Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>

- Remove ClientRegistration from IdentitySpec — Keycloak 26.4 federated client auth makes operator-managed registration unnecessary, and it is currently handled externally via Helm jobs - Remove omitempty from Spec json tag per K8s convention - Remove misleading webhook validation edge for AgentRuntime in architecture diagram (no webhook implemented yet) - Revert prometheus/client_model back to indirect dependency Signed-off-by: Varsha Prasad Narsing <varshaprasad96@gmail.com> Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>

varshaprasad96 · 2026-03-11T22:48:02Z

One suggestion, can we add some unit tests for new structures?

@r3v5 The PR currently defines only Go structs for the API, hence there are no tests. There is a controller implementation PR in the follow up. Will have unit tests in there, where we have the actual logic of calling/performing CRUD on these API instances.

varshaprasad96 · 2026-03-11T22:48:30Z

@grs @cwiklik @r3v5 - addressed review comments, ptal.

usize

I added some context. This looks like a great start. I appreciate the scaffolding. I'm going to wait for @cwiklik to approve since he has touched more of the operator than I have.

usize · 2026-03-11T23:01:22Z

kagenti-operator/api/v1alpha1/agentruntime_types.go

+	// If empty, the operator flag value is used.
+	// +optional
+	// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9]([a-zA-Z0-9\-\.]*[a-zA-Z0-9])?$`
+	TrustDomain string `json:"trustDomain,omitempty"`


Right. In the AgentCard my thinking was to support federation scenarios like e.g., someone represents an agent from out of cluster and wants to verify its signature. This came up during discussions where folks pointed out the idea of representing out of cluster agents in the fashion of a MultiClusterService.

usize · 2026-03-11T23:03:59Z

kagenti-operator/Makefile

 .PHONY: manifests
 manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
-	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+	$(CONTROLLER_GEN) rbac:roleName=manager-role crd:allowDangerousTypes=true webhook paths="./..." output:crd:artifacts:config=config/crd/bases


K8s best practice here seems to be representing floats as strings when possible. resource.Quantity seems OK to me.

cwiklik

lgtm - lets start with this and modify as needed. Thank you.

varshaprasad96 requested a review from a team as a code owner March 10, 2026 23:47

varshaprasad96 commented Mar 10, 2026

View reviewed changes

pdettori added the safe-to-test Maintainer reviewed - safe to run E2E tests label Mar 11, 2026

pdettori reviewed Mar 11, 2026

View reviewed changes

kagenti-operator/docs/architecture.md Outdated Show resolved Hide resolved

kagenti-operator/api/v1alpha1/agentruntime_types.go Show resolved Hide resolved

kagenti-operator/go.mod Outdated Show resolved Hide resolved

grs reviewed Mar 11, 2026

View reviewed changes

r3v5 reviewed Mar 11, 2026

View reviewed changes

cwiklik reviewed Mar 11, 2026

View reviewed changes

cwiklik mentioned this pull request Mar 11, 2026

feat: Per-workload config resolution pipeline for webhook kagenti/kagenti-extensions#217

Draft

9 tasks

varshaprasad96 added 2 commits March 11, 2026 15:44

varshaprasad96 force-pushed the feat-agent-runtime branch from 6fd63e9 to b3aa892 Compare March 11, 2026 22:44

usize self-requested a review March 11, 2026 22:48

varshaprasad96 requested review from cwiklik, grs, pdettori and r3v5 March 11, 2026 22:54

usize reviewed Mar 11, 2026

View reviewed changes

cwiklik approved these changes Mar 11, 2026

View reviewed changes

cwiklik merged commit 8ad9f60 into kagenti:main Mar 11, 2026
5 checks passed

cwiklik mentioned this pull request Mar 11, 2026

feat: Move kagenti-webhook from kagenti-extensions into kagenti-operator #217

Open

Conversation

varshaprasad96 commented Mar 10, 2026

Summary

Related issue(s)

(Optional) Testing Instructions

Uh oh!

varshaprasad96 Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

varshaprasad96 commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pdettori left a comment

Choose a reason for hiding this comment

Review Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

usize Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

r3v5 left a comment

Choose a reason for hiding this comment

Uh oh!

cwiklik left a comment

Choose a reason for hiding this comment

Uh oh!

varshaprasad96 commented Mar 11, 2026

Uh oh!

varshaprasad96 commented Mar 11, 2026

Uh oh!

usize left a comment

Choose a reason for hiding this comment

Uh oh!

usize Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwiklik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

varshaprasad96 Mar 10, 2026 •

edited

Loading

varshaprasad96 commented Mar 10, 2026 •

edited

Loading

usize Mar 11, 2026 •

edited

Loading

usize Mar 11, 2026 •

edited

Loading