Skip to content

Commit c53f4b2

Browse files
authored
Allowlist snapshot storage location path segments (agent-substrate#2784)
Snapshots are stored under `<location>/atespaces/<atespace>/{actors,tags}/<uid>`. A `storageLocation` that already contained that layout (for example `gs://snaps/root/atespaces/team-a/actors/<uid>`) put one template's snapshots inside another actor's prefix, grant and cleanup. Where a location is set (template create, `--snapshot-location`, `ate-setup deploy`), each path segment may now contain only ASCII letters, digits, `_` and `-`, and may not be `atespaces` in any letter case. The bucket is not restricted. - Creating a tag checks the template's location against the same rules and returns `FAILED_PRECONDITION` on a bad one. - Parsing of recorded snapshot URIs stays lenient, so stored snapshots still resume and get collected. Breaking change: if the path of your `--snapshot-location` (`SNAPSHOT_LOCATION`) has a segment outside `^[A-Za-z0-9_-]+$` (a dot, `%`, an empty segment, non-ASCII) or equal to `atespaces` in any case, change it before upgrading. Otherwise ate-api-server refuses to start. - [x] Tests pass (touched packages, `hack/verify-all.sh`) - [x] Docs updated AI use: I used Claude Code to implement and review this change, and reviewed the diff myself. --------- Signed-off-by: Anish Ramasekar <[email protected]>
1 parent 46b6ea9 commit c53f4b2

12 files changed

Lines changed: 162 additions & 41 deletions

File tree

‎api/ateapi/v1/ateapi.pb.go‎

Lines changed: 4 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎api/ateapi/v1/ateapi.proto‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1269,7 +1269,10 @@ message SnapshotConfig {
12691269
// storage_location is the base object-storage URI snapshots of actors on
12701270
// this version are stored under. If unset, ate-api-server's
12711271
// --snapshot-location is used. Requires the PerTemplateSnapshotLocation preview
1272-
// gate.
1272+
// gate. Each path segment may contain only ASCII letters, digits, '_' and
1273+
// '-'. Each owner's snapshots are stored under
1274+
// <storage_location>/atespaces/..., so no segment may be "atespaces" in any
1275+
// letter case.
12731276
//
12741277
// +ate:preview=PerTemplateSnapshotLocation
12751278
// +k8s:ifDisabled(PerTemplateSnapshotLocation)=+k8s:forbidden

‎cmd/ateapi/internal/apivalidation/actor_template.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -163,9 +163,9 @@ func ValidateCustom_Container_Image(_ context.Context, _ operation.Operation, fl
163163
return resources.ValidatePinnedImage(fldPath, *value)
164164
}
165165

166-
// ValidateCustom_SnapshotConfig_StorageLocation ensures an
167-
// ActorTemplate's snapshotConfig.storageLocation is a well-formed
168-
// URI with a bucket, so a bad location fails fast.
166+
// ValidateCustom_SnapshotConfig_StorageLocation checks an ActorTemplate's
167+
// snapshotConfig.storageLocation with resources.ValidateSnapshotLocation, so a
168+
// bad location fails fast.
169169
func ValidateCustom_SnapshotConfig_StorageLocation(_ context.Context, _ operation.Operation, fldPath *field.Path, value, _ *string) field.ErrorList {
170170
if err := resources.ValidateSnapshotLocation(*value); err != nil {
171171
return field.ErrorList{field.Invalid(fldPath, *value, err.Error())}

‎cmd/ateapi/internal/apivalidation/actor_template_test.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,18 @@ func TestValidateCreateActorTemplateRequest(t *testing.T) {
184184
tmpl.SnapshotConfig.StorageLocation = "gs://my-bucket/snapshots?versions=true"
185185
})},
186186
field.ErrorList{field.Invalid(field.NewPath("actor_template", "snapshot_config", "storage_location"), "gs://my-bucket/snapshots?versions=true", "")},
187+
}, {
188+
"storage_location under another actor's prefix",
189+
&ateapi.CreateActorTemplateRequest{ActorTemplate: validActorTemplate(func(tmpl *ateapi.ActorTemplate) {
190+
tmpl.SnapshotConfig.StorageLocation = "gs://my-bucket/snapshots/atespaces/team-a/actors/0b4e7c4e-2f3a-4d43-9a5e-0f6d1c2b3a4d"
191+
})},
192+
field.ErrorList{field.Invalid(field.NewPath("actor_template", "snapshot_config", "storage_location"), "gs://my-bucket/snapshots/atespaces/team-a/actors/0b4e7c4e-2f3a-4d43-9a5e-0f6d1c2b3a4d", "")},
193+
}, {
194+
"storage_location with a dot in a path segment",
195+
&ateapi.CreateActorTemplateRequest{ActorTemplate: validActorTemplate(func(tmpl *ateapi.ActorTemplate) {
196+
tmpl.SnapshotConfig.StorageLocation = "gs://my-bucket/snapshots.v1"
197+
})},
198+
field.ErrorList{field.Invalid(field.NewPath("actor_template", "snapshot_config", "storage_location"), "gs://my-bucket/snapshots.v1", "")},
187199
}, {
188200
// preferred_fidelity has no default of its own at this layer, so leaving it
189201
// unset is a required violation.

‎cmd/ateapi/internal/controlapi/workflow_tag.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -274,7 +274,7 @@ func (w *ActorWorkflow) checkTagCreatable(ctx context.Context, tagRef resources.
274274
return err
275275
}
276276
if err := resources.ValidateSnapshotLocation(location); err != nil {
277-
return fmt.Errorf("invalid storage location for tag %s: %w", tagRef, err)
277+
return apierror.FailedPrecondition("invalid storage location for tag %s: %w", tagRef, err)
278278
}
279279
return nil
280280
}

‎cmd/ateapi/internal/controlapi/workflow_tag_test.go‎

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,34 @@ func TestTagActorSnapshot_ActorRepointedToAnotherTemplate(t *testing.T) {
158158
}
159159
}
160160

161+
// TestTagActorSnapshot_LocationOutsideSegmentRules verifies that a tag of a
162+
// template whose stored location breaks the segment rules fails with
163+
// FailedPrecondition.
164+
func TestTagActorSnapshot_LocationOutsideSegmentRules(t *testing.T) {
165+
ctx := context.Background()
166+
persistence := newTestPersistence(t)
167+
template, err := persistence.CreateActorTemplate(ctx, &ateapi.ActorTemplate{
168+
Metadata: &ateapi.ResourceMetadata{Atespace: "team-a", Name: "sub-tmpl"},
169+
SnapshotConfig: &ateapi.SnapshotConfig{StorageLocation: "gs://ate-snapshots/a.b/"},
170+
})
171+
if err != nil {
172+
t.Fatalf("CreateActorTemplate: %v", err)
173+
}
174+
w, objects := newFinalizeWorkflow(persistence)
175+
actor, _ := seedTagSource(t, ctx, persistence, objects, template, "actor-1", "manifest.json")
176+
177+
_, err = w.TagActorSnapshot(ctx, tagToCreate(resources.ActorRefFromActor(actor), "v1"))
178+
if code := apierror.Code(err); code != codes.FailedPrecondition {
179+
t.Fatalf("TagActorSnapshot error = %v (code %v), want code %v", err, code, codes.FailedPrecondition)
180+
}
181+
if !strings.Contains(err.Error(), "invalid storage location") {
182+
t.Errorf("TagActorSnapshot error = %v, want it to name the invalid storage location", err)
183+
}
184+
if _, err := persistence.GetTag(ctx, resources.TagRef{Atespace: "team-a", Name: "v1"}); !errors.Is(err, store.ErrNotFound) {
185+
t.Errorf("GetTag after failed create: err = %v, want ErrNotFound", err)
186+
}
187+
}
188+
161189
// TestTagActorSnapshot_Preconditions verifies what a tag may be taken from:
162190
// a suspended actor's finished external snapshot, and nothing else.
163191
func TestTagActorSnapshot_Preconditions(t *testing.T) {
@@ -316,7 +344,8 @@ func TestTagActorSnapshot_PromotesLocalSnapshot(t *testing.T) {
316344
nodeLost bool
317345
// nameTaken seeds a tag under the name the create asks for.
318346
nameTaken bool
319-
// badLocation points the template at an unusable storage location.
347+
// badLocation points the template at a storage location with an
348+
// atespaces segment.
320349
badLocation bool
321350
// noTemplateUID records no template the local snapshot was built
322351
// under, a broken row.
@@ -354,9 +383,9 @@ func TestTagActorSnapshot_PromotesLocalSnapshot(t *testing.T) {
354383
wantCode: codes.AlreadyExists,
355384
},
356385
{
357-
name: "the storage location is unusable",
386+
name: "the template's storage location has an atespaces segment",
358387
badLocation: true,
359-
wantCode: codes.Internal,
388+
wantCode: codes.FailedPrecondition,
360389
},
361390
{
362391
name: "the paused snapshot records no template",
@@ -494,7 +523,7 @@ func TestTagActorSnapshot_PromotesLocalSnapshot(t *testing.T) {
494523
}
495524
if tt.badLocation {
496525
_, err := persistence.UpdateActorTemplate(ctx, resources.ActorTemplateRefFromActorTemplate(template), store.PreconditionFrom(template), func(tmpl *ateapi.ActorTemplate) error {
497-
tmpl.SnapshotConfig.StorageLocation = "gs://ate-snapshots/team-a/?query"
526+
tmpl.SnapshotConfig.StorageLocation = "gs://ate-snapshots/root/atespaces/team-b/actors/cc10"
498527
return nil
499528
})
500529
if err != nil {

‎docs/guides/operator-install.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,8 @@ demos, the [benchmarks](benchmarking.md#settings), and the
332332

333333
ate-api-server stores every actor and tag snapshot under a cluster-wide
334334
`--snapshot-location`, an object-storage URI such as `gs://BUCKET/PREFIX/`.
335+
Its path segments may contain only ASCII letters, digits, `_` and `-` (see
336+
[Snapshot Storage Layout](../reference/api-guide.md#snapshot-storage-layout)).
335337
Set it with `SNAPSHOT_LOCATION` (or ate-setup's `--snapshot-location`). It has
336338
no default, and ate-setup fails before deploying without it unless the
337339
`PerTemplateSnapshotLocation` preview gate is enabled. Even with the gate, the

‎docs/reference/api-guide.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -442,6 +442,10 @@ records its snapshot's URI in `status.snapshot` right after it is reserved,
442442
before anything is copied, so a tag whose creation failed still names any
443443
partial copy to collect.
444444

445+
Every owner's prefix starts with `<location>/atespaces/`. So where a location is set, through `--snapshot-location` or a template's `storageLocation`, each path segment may contain only ASCII letters, digits, `_` and `-`, and no segment may be `atespaces` in any letter case. The bucket is not restricted. A location such as `gs://my-bucket/atespaces/team-a/actors/<actor uid>` would otherwise put one owner's objects under another owner's or atespace's prefix, inside its grants and its cleanup.
446+
447+
ate-api-server refuses to start with a `--snapshot-location` that breaks these rules, `ate-setup deploy` rejects it, and creating a template rejects such a `storageLocation`. Creating a tag checks the location the tag is stored under and fails with `FAILED_PRECONDITION` on one that breaks them.
448+
445449
An owner is collected by deleting everything under its prefix, and it can delete nothing else. That is what makes a borrowed snapshot safe: an actor created from a tag points at a URI under `tags/`, which its own prefix does not cover. See [Snapshot lifetime](#snapshot-lifetime).
446450

447451
An `Actor` reports its snapshots in the server-managed `status.snapshots` (and

‎internal/resources/snapshot.go‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -56,12 +56,9 @@ func (p StoragePrefix) String() string { return p.uri }
5656
// snapshot URI or an owner's prefix. It rejects a bare bucket, so a prefix
5757
// can never name every object in a bucket.
5858
func ParseStoragePrefix(uri string) (StoragePrefix, error) {
59-
if err := ValidateSnapshotLocation(uri); err != nil {
60-
return StoragePrefix{}, err
61-
}
62-
u, err := url.Parse(uri)
59+
u, err := parseStorageURI(uri)
6360
if err != nil {
64-
return StoragePrefix{}, fmt.Errorf("invalid storage prefix %q: %v", uri, err)
61+
return StoragePrefix{}, fmt.Errorf("invalid storage prefix %q: %w", uri, err)
6562
}
6663
if strings.Trim(u.Path, "/") == "" {
6764
return StoragePrefix{}, fmt.Errorf("invalid storage prefix %q: missing path", uri)
@@ -125,8 +122,8 @@ func (o SnapshotOwner) Prefix(location string) (StoragePrefix, error) {
125122
if err := o.validate(); err != nil {
126123
return StoragePrefix{}, err
127124
}
128-
if err := ValidateSnapshotLocation(location); err != nil {
129-
return StoragePrefix{}, err
125+
if _, err := parseStorageURI(location); err != nil {
126+
return StoragePrefix{}, fmt.Errorf("invalid snapshot location %q: %w", location, err)
130127
}
131128
uri, err := url.JoinPath(location, atespacesPathSegment, o.atespace, o.kind, o.id)
132129
if err != nil {

‎internal/resources/snapshot_test.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
package resources
1616

1717
import (
18+
"strings"
1819
"testing"
1920
)
2021

@@ -607,13 +608,17 @@ func TestParseStoragePrefix(t *testing.T) {
607608
{uri: "gs://bucket/", wantErr: true},
608609
{uri: "gs:///root", wantErr: true},
609610
{uri: "gs://bucket/root?x=1", wantErr: true},
611+
{uri: "gs://bucket/root?", wantErr: true},
610612
{uri: "gs://user@bucket/root", wantErr: true},
611613
} {
612614
got, err := ParseStoragePrefix(tc.uri)
613615
if (err != nil) != tc.wantErr {
614616
t.Errorf("ParseStoragePrefix(%q) error = %v, wantErr %v", tc.uri, err, tc.wantErr)
615617
continue
616618
}
619+
if err != nil && !strings.HasPrefix(err.Error(), "invalid storage prefix ") {
620+
t.Errorf("ParseStoragePrefix(%q) error = %v, want an invalid storage prefix error", tc.uri, err)
621+
}
617622
if err == nil && got.String() != tc.uri {
618623
t.Errorf("ParseStoragePrefix(%q) = %q", tc.uri, got)
619624
}

0 commit comments

Comments
 (0)