Skip to content

Commit 2b3a9d3

Browse files
committed
feat(agents): mount an opt-in sub-agent token for orchestrating sessions
With pod_options.enable_subagents, the provider adds a projected, 600-second token for provider_config.service_account (plus the cluster CA and namespace) at /var/run/secrets/buzz-subagents, so an orchestrating agent can claim short-lived worker Sandboxes. The ambient ServiceAccount token stays off, the option is off by default, and enabling it changes the launch intent. The provider refuses enable_subagents without a service_account, so the token is never minted for the namespace's `default` ServiceAccount. The deployment scopes the token to SandboxClaims in the developer namespace. pod_options.priority_class_name sets the Pod's priorityClassName, so a deployment can count primary sessions and worker slots against separate quotas. The provider trims it and requires a DNS-subdomain name. The deployment must restrict which priority classes each developer namespace may use. Signed-off-by: Tee8z <[email protected]>
1 parent 8e2630f commit 2b3a9d3

4 files changed

Lines changed: 291 additions & 21 deletions

File tree

‎crates/buzz-backend-kubernetes/src/config.rs‎

Lines changed: 81 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,14 @@ pub struct PodOptions {
105105
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
106106
/// Expose the server-assigned Pod UID to a bounded owner setup gate.
107107
pub setup_pending: bool,
108+
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
109+
/// Mount a short-lived ServiceAccount token so an orchestrating agent can
110+
/// claim sub-agent Sandboxes (§Sub-agents). Off by default.
111+
pub enable_subagents: bool,
112+
#[serde(default, skip_serializing_if = "Option::is_none")]
113+
/// Optional priority class (a DNS subdomain name), also usable by
114+
/// namespace-scoped resource quotas.
115+
pub priority_class_name: Option<String>,
108116
}
109117

110118
impl PodOptions {
@@ -217,6 +225,20 @@ fn optional_u64(cfg: &serde_json::Value, field: &str) -> Result<Option<u64>, Str
217225
}
218226
}
219227

228+
/// An RFC 1123 subdomain (≤253 chars of dot-separated labels), the name
229+
/// format of cluster objects such as PriorityClasses.
230+
fn valid_dns_subdomain(name: &str) -> bool {
231+
name.len() <= 253
232+
&& name.split('.').all(|label| {
233+
!label.is_empty()
234+
&& label.starts_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
235+
&& label.ends_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
236+
&& label
237+
.chars()
238+
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
239+
})
240+
}
241+
220242
/// A Kubernetes namespace name: RFC 1123 label, ≤63 chars. Validated here so a
221243
/// typo fails with a named field instead of an apiserver rejection partway
222244
/// through a deploy.
@@ -277,11 +299,21 @@ pub fn parse(cfg: &serde_json::Value) -> Result<ProviderConfig, String> {
277299
Some(n) => Some(n),
278300
};
279301

280-
let pod_options: PodOptions = match cfg.get("pod_options") {
302+
let mut pod_options: PodOptions = match cfg.get("pod_options") {
281303
None => PodOptions::default(),
282304
Some(value) => serde_json::from_value(value.clone())
283305
.map_err(|e| format!("provider_config.pod_options: {e}"))?,
284306
};
307+
if let Some(name) = pod_options.priority_class_name.as_mut() {
308+
*name = name.trim().to_string();
309+
if !valid_dns_subdomain(name) {
310+
return Err(
311+
"provider_config.pod_options.priority_class_name must be a PriorityClass name \
312+
(DNS subdomain: lowercase letters, digits, '-' and '.')"
313+
.into(),
314+
);
315+
}
316+
}
285317
if pod_options.active_deadline_seconds.is_some_and(|n| n <= 0) {
286318
return Err("provider_config.pod_options.active_deadline_seconds must be positive".into());
287319
}
@@ -320,13 +352,24 @@ pub fn parse(cfg: &serde_json::Value) -> Result<ProviderConfig, String> {
320352
}
321353
}
322354

355+
let service_account = optional_string(cfg, "service_account")?;
356+
// Without a named ServiceAccount the token would be minted for the
357+
// namespace's `default` account, which the deployment does not scope.
358+
if pod_options.enable_subagents && service_account.is_none() {
359+
return Err(
360+
"provider_config.pod_options.enable_subagents requires provider_config.service_account: \
361+
the sub-agent token is minted for that ServiceAccount, never `default`"
362+
.into(),
363+
);
364+
}
365+
323366
Ok(ProviderConfig {
324367
context: optional_string(cfg, "context")?,
325368
namespace,
326369
image,
327370
resources,
328371
inactivity_seconds,
329-
service_account: optional_string(cfg, "service_account")?,
372+
service_account,
330373
pod_options,
331374
})
332375
}
@@ -410,7 +453,9 @@ pub fn config_schema() -> serde_json::Value {
410453
"ephemeral_storage_request": {"type": "string", "minLength": 1},
411454
"ephemeral_storage_limit": {"type": "string", "minLength": 1},
412455
"active_deadline_seconds": {"type": "integer", "minimum": 1},
413-
"setup_pending": {"type": "boolean", "default": false}
456+
"setup_pending": {"type": "boolean", "default": false},
457+
"enable_subagents": {"type": "boolean", "default": false},
458+
"priority_class_name": {"type": "string", "minLength": 1}
414459
}
415460
},
416461
"service_account": {
@@ -640,14 +685,45 @@ mod tests {
640685
serde_json::json!({"workspace_size_limit": " "}),
641686
serde_json::json!({"unknown": true}),
642687
serde_json::json!({"node_selector": "amd64"}),
688+
serde_json::json!({"priority_class_name": ""}),
689+
serde_json::json!({"priority_class_name": " "}),
690+
serde_json::json!({"priority_class_name": "Agent-Session"}),
691+
serde_json::json!({"priority_class_name": "agent_session"}),
692+
serde_json::json!({"priority_class_name": "agent..session"}),
693+
serde_json::json!({"priority_class_name": "-agent"}),
694+
serde_json::json!({"priority_class_name": "a".repeat(254)}),
695+
serde_json::json!({"priority_class_name": 5}),
696+
// No service account: the token would belong to `default`.
697+
serde_json::json!({"enable_subagents": true}),
643698
] {
644699
let mut cfg = minimal();
645-
cfg["pod_options"] = bad;
646-
assert!(parse(&cfg).unwrap_err().contains("pod_options"));
700+
cfg["pod_options"] = bad.clone();
701+
assert!(parse(&cfg).unwrap_err().contains("pod_options"), "{bad}");
647702
}
648703
assert!(parse(&minimal()).unwrap().pod_options.is_default());
649704
}
650705

706+
#[test]
707+
fn accepts_subagents_with_a_service_account_and_a_trimmed_priority_class() {
708+
let mut cfg = minimal();
709+
cfg["service_account"] = " agent-sa ".into();
710+
cfg["pod_options"] = serde_json::json!({
711+
"enable_subagents": true,
712+
"priority_class_name": " buzz-agent.session-1 ",
713+
});
714+
let parsed = parse(&cfg).unwrap();
715+
assert_eq!(parsed.service_account.as_deref(), Some("agent-sa"));
716+
assert!(parsed.pod_options.enable_subagents);
717+
assert_eq!(
718+
parsed.pod_options.priority_class_name.as_deref(),
719+
Some("buzz-agent.session-1")
720+
);
721+
cfg["pod_options"]["priority_class_name"] = "a".repeat(253).into();
722+
assert!(parse(&cfg).is_ok());
723+
cfg["service_account"] = " ".into();
724+
assert!(parse(&cfg).unwrap_err().contains("enable_subagents"));
725+
}
726+
651727
#[test]
652728
fn applies_spec_defaults() {
653729
let c = parse(&minimal()).unwrap();

‎crates/buzz-backend-kubernetes/src/pod.rs‎

Lines changed: 145 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,11 @@ use crate::naming::{
1212
AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_IMAGE, ANNOTATION_PUBKEY_FULL,
1313
};
1414
use k8s_openapi::api::core::v1::{
15-
Capabilities, Container, EmptyDirVolumeSource, EnvFromSource, EnvVar, EnvVarSource,
16-
ObjectFieldSelector, Pod, PodSecurityContext, PodSpec, ResourceRequirements, SeccompProfile,
17-
Secret, SecretEnvSource, SecurityContext, Volume, VolumeMount,
15+
Capabilities, ConfigMapProjection, Container, DownwardAPIProjection, DownwardAPIVolumeFile,
16+
EmptyDirVolumeSource, EnvFromSource, EnvVar, EnvVarSource, KeyToPath, ObjectFieldSelector, Pod,
17+
PodSecurityContext, PodSpec, ProjectedVolumeSource, ResourceRequirements, SeccompProfile,
18+
Secret, SecretEnvSource, SecurityContext, ServiceAccountTokenProjection, Volume, VolumeMount,
19+
VolumeProjection,
1820
};
1921
use k8s_openapi::apimachinery::pkg::api::resource::Quantity;
2022
use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
@@ -26,6 +28,61 @@ const WORKSPACE_VOLUME: &str = "workspace";
2628
/// The container name. Fixed: log and exec tooling addresses it by name.
2729
const CONTAINER_NAME: &str = "agent";
2830

31+
/// Where an orchestrating agent finds its sub-agent credentials (§Sub-agents):
32+
/// `token`, `ca.crt`, and `namespace`. Deliberately not the default
33+
/// ServiceAccount path, so tools do not pick the token up implicitly.
34+
pub const SUBAGENT_TOKEN_PATH: &str = "/var/run/secrets/buzz-subagents";
35+
/// Lifetime of the projected token; the kubelet rotates it before expiry.
36+
pub const SUBAGENT_TOKEN_SECONDS: i64 = 600;
37+
const SUBAGENT_TOKEN_VOLUME: &str = "subagent-token";
38+
39+
/// Short-lived API credentials for claiming sub-agent Sandboxes. RBAC in the
40+
/// developer namespace limits the token to SandboxClaims there.
41+
fn subagent_token_volume() -> Volume {
42+
Volume {
43+
name: SUBAGENT_TOKEN_VOLUME.to_string(),
44+
projected: Some(ProjectedVolumeSource {
45+
sources: Some(vec![
46+
VolumeProjection {
47+
service_account_token: Some(ServiceAccountTokenProjection {
48+
path: "token".to_string(),
49+
expiration_seconds: Some(SUBAGENT_TOKEN_SECONDS),
50+
..Default::default()
51+
}),
52+
..Default::default()
53+
},
54+
VolumeProjection {
55+
config_map: Some(ConfigMapProjection {
56+
name: "kube-root-ca.crt".to_string(),
57+
items: Some(vec![KeyToPath {
58+
key: "ca.crt".to_string(),
59+
path: "ca.crt".to_string(),
60+
..Default::default()
61+
}]),
62+
..Default::default()
63+
}),
64+
..Default::default()
65+
},
66+
VolumeProjection {
67+
downward_api: Some(DownwardAPIProjection {
68+
items: Some(vec![DownwardAPIVolumeFile {
69+
path: "namespace".to_string(),
70+
field_ref: Some(ObjectFieldSelector {
71+
field_path: "metadata.namespace".to_string(),
72+
..Default::default()
73+
}),
74+
..Default::default()
75+
}]),
76+
}),
77+
..Default::default()
78+
},
79+
]),
80+
..Default::default()
81+
}),
82+
..Default::default()
83+
}
84+
}
85+
2986
/// Build the per-attempt Secret holding the resolved environment.
3087
///
3188
/// `immutable: true` — the Secret is written once per attempt and never
@@ -144,11 +201,22 @@ pub fn build_pod(
144201
limits: Some(limits),
145202
..Default::default()
146203
}),
147-
volume_mounts: Some(vec![VolumeMount {
148-
name: WORKSPACE_VOLUME.to_string(),
149-
mount_path: WORKSPACE_PATH.to_string(),
150-
..Default::default()
151-
}]),
204+
volume_mounts: Some({
205+
let mut mounts = vec![VolumeMount {
206+
name: WORKSPACE_VOLUME.to_string(),
207+
mount_path: WORKSPACE_PATH.to_string(),
208+
..Default::default()
209+
}];
210+
if cfg.pod_options.enable_subagents {
211+
mounts.push(VolumeMount {
212+
name: SUBAGENT_TOKEN_VOLUME.to_string(),
213+
mount_path: SUBAGENT_TOKEN_PATH.to_string(),
214+
read_only: Some(true),
215+
..Default::default()
216+
});
217+
}
218+
mounts
219+
}),
152220
security_context: Some(SecurityContext {
153221
allow_privilege_escalation: Some(false),
154222
capabilities: Some(Capabilities {
@@ -177,6 +245,7 @@ pub fn build_pod(
177245
tolerations: (!cfg.pod_options.tolerations.is_empty())
178246
.then(|| cfg.pod_options.tolerations.iter().map(Into::into).collect()),
179247
active_deadline_seconds: cfg.pod_options.active_deadline_seconds,
248+
priority_class_name: cfg.pod_options.priority_class_name.clone(),
180249
restart_policy: Some(RESTART_POLICY.to_string()),
181250
termination_grace_period_seconds: Some(TERMINATION_GRACE_SECONDS),
182251
// The agent runs prompted, untrusted code while holding an nsec;
@@ -197,14 +266,20 @@ pub fn build_pod(
197266
}),
198267
..Default::default()
199268
}),
200-
volumes: Some(vec![Volume {
201-
name: WORKSPACE_VOLUME.to_string(),
202-
empty_dir: Some(EmptyDirVolumeSource {
203-
size_limit: cfg.pod_options.workspace_size_limit.clone().map(Quantity),
269+
volumes: Some({
270+
let mut volumes = vec![Volume {
271+
name: WORKSPACE_VOLUME.to_string(),
272+
empty_dir: Some(EmptyDirVolumeSource {
273+
size_limit: cfg.pod_options.workspace_size_limit.clone().map(Quantity),
274+
..Default::default()
275+
}),
204276
..Default::default()
205-
}),
206-
..Default::default()
207-
}]),
277+
}];
278+
if cfg.pod_options.enable_subagents {
279+
volumes.push(subagent_token_volume());
280+
}
281+
volumes
282+
}),
208283
..Default::default()
209284
}),
210285
..Default::default()
@@ -376,6 +451,42 @@ mod tests {
376451
);
377452
}
378453

454+
#[test]
455+
fn subagent_token_is_opt_in_short_lived_and_off_the_default_path() {
456+
let mut cfg = provider_config();
457+
let fp = intent_template(&cfg, ["A".into()]).fingerprint();
458+
let plain = build_pod(&identity(), &cfg, "g", &fp);
459+
assert_eq!(spec(&plain).volumes.as_ref().unwrap().len(), 1);
460+
assert_eq!(
461+
spec(&plain).containers[0]
462+
.volume_mounts
463+
.as_ref()
464+
.unwrap()
465+
.len(),
466+
1
467+
);
468+
469+
cfg.pod_options.enable_subagents = true;
470+
let changed = intent_template(&cfg, ["A".into()]).fingerprint();
471+
let pod = build_pod(&identity(), &cfg, "g", &changed);
472+
let spec = spec(&pod);
473+
// Still no ambient token at the default ServiceAccount path.
474+
assert_eq!(spec.automount_service_account_token, Some(false));
475+
let volume = &spec.volumes.as_ref().unwrap()[1];
476+
let sources = volume.projected.as_ref().unwrap().sources.as_ref().unwrap();
477+
let token = sources[0].service_account_token.as_ref().unwrap();
478+
assert_eq!(token.expiration_seconds, Some(SUBAGENT_TOKEN_SECONDS));
479+
assert!(token.audience.is_none());
480+
let mount = &spec.containers[0].volume_mounts.as_ref().unwrap()[1];
481+
assert_eq!(mount.name, volume.name);
482+
assert_eq!(mount.mount_path, SUBAGENT_TOKEN_PATH);
483+
assert_eq!(mount.read_only, Some(true));
484+
assert_ne!(
485+
SUBAGENT_TOKEN_PATH,
486+
"/var/run/secrets/kubernetes.io/serviceaccount"
487+
);
488+
}
489+
379490
#[test]
380491
fn each_optional_pod_control_changes_intent() {
381492
let cfg = provider_config();
@@ -388,6 +499,8 @@ mod tests {
388499
serde_json::json!({"ephemeral_storage_limit": "4Gi"}),
389500
serde_json::json!({"active_deadline_seconds": 28800}),
390501
serde_json::json!({"setup_pending": true}),
502+
serde_json::json!({"enable_subagents": true}),
503+
serde_json::json!({"priority_class_name": "agent-session"}),
391504
] {
392505
let mut changed = cfg.clone();
393506
changed.pod_options = serde_json::from_value(value).unwrap();
@@ -400,6 +513,23 @@ mod tests {
400513
assert!(original.get("pod_options").is_none());
401514
}
402515

516+
#[test]
517+
fn priority_class_reaches_the_pod_without_changing_default_intent() {
518+
let mut cfg = provider_config();
519+
assert!(serde_json::to_value(&cfg.pod_options)
520+
.unwrap()
521+
.get("priority_class_name")
522+
.is_none());
523+
cfg.pod_options.priority_class_name = Some("agent-session".into());
524+
let identity = identity();
525+
let fingerprint = intent_template(&cfg, ["A".into()]).fingerprint();
526+
let pod = build_pod(&identity, &cfg, "generation", &fingerprint);
527+
assert_eq!(
528+
pod.spec.unwrap().priority_class_name.as_deref(),
529+
Some("agent-session")
530+
);
531+
}
532+
403533
#[test]
404534
fn optional_placement_storage_and_lifetime_reach_pod_and_intent() {
405535
let mut cfg = provider_config();

‎desktop/src-tauri/src/managed_agents/backend_tests.rs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -521,6 +521,24 @@ esac"#,
521521
assert!(error.to_string().contains("[REDACTED]"), "{error}");
522522
}
523523

524+
#[test]
525+
fn subagent_capability_is_public_but_credentials_still_fail() {
526+
for enabled in [true, false] {
527+
assert!(
528+
validate_provider_config(&serde_json::json!({"pod_options": {
529+
"enable_subagents": enabled, "priority_class_name": "agent-session"
530+
}}))
531+
.is_ok()
532+
);
533+
}
534+
for credential in [
535+
serde_json::json!({"access_token":"secret"}),
536+
serde_json::json!({"api_key":"secret"}),
537+
] {
538+
assert!(validate_provider_config(&serde_json::json!({"pod_options":credential})).is_err());
539+
}
540+
}
541+
524542
#[test]
525543
fn validate_provider_config_rejects_secret_key() {
526544
let cfg = serde_json::json!({"api_key": "val"});

0 commit comments

Comments
 (0)