feature: support for exact-name create-or-adopt flow

[Junjus]

Is your feature request related to a problem? Please describe.

Currently, I do not see a direct way to create a bucket with an exact, user-provided Garage bucket name.

The controller can create managed buckets, but the actual Garage bucket name is derived by the controller and includes a resource-derived suffix. This is useful for avoiding collisions, but it means the resulting bucket name is tied to the lifecycle of a particular Kubernetes object.
This is inconvenient for consumers that require a stable bucket name independent of the Kubernetes object lifecycle. I would like the bucket to survive cluster recreation and still be addressable by the same deterministic name afterwards.
This also matters for some GitOps workflows, where other resources need to reference the bucket by name ahead of time.

Describe the solution you'd like

I would like the controller to support creating or adopting a bucket with an exact Garage bucket name.

The desired behavior would be:

• if the exact bucket name does not exist, the controller creates it with exactly that name
• if the exact bucket name already exists, the controller can adopt/reclaim it when ownership proof is provided, similar to the current spec.existingBucket flow
• if the exact bucket name already exists but ownership cannot be proven, reconciliation fails with a clear collision/ownership error
• if no exact bucket name is requested, the controller can keep using generated bucket names to avoid collisions

[bmarinov]

This is something I hoped nobody will ask for. Do you have an idea how the API should look like?

I would like to keep the split between "existing" and "exact & new" at least until RC and reconsider then. So if the API breaks, it only breaks once, and the older v1alpha1 is "easier" and more explicit on the controller side.

apiVersion: garage.getclustered.net/v1alpha1
kind: Bucket
metadata:
  name: bucket-sample
spec:
  exactName: foo-final-bucket-name
  maxSize: 10Gi

And importing would then stay as:

apiVersion: garage.getclustered.net/v1alpha1
kind: Bucket
metadata:
  name: bucket-sample
spec:
  existingBucket:
    name: foo-final-bucket-name

The problem of course remains gitops, and I have two ideas I am currently exploring:

• store metadata in the Garage bucket itself (owning cluster, owning namespace)
• Have a "bulk import" / "bulk authorize" resource
  • a cluster administrator could precreate it before migrating workloads to the new cluster.
  • contains just a list of "preapproved" bucket names to namespaces.

These things get fuzzy fast though and I've postponed it until the next (beta) release.

[bmarinov]

One more option, nameOverride instead of exact to keep users away from it a bit better. Override = potential trouble ahead.

Here is a merged version with all fields side by side. This could be a good way forward, minus the breaking change / obsolete field:

# API schema proposal, NOT available or released:
apiVersion: garage.getclustered.net/v0beta0xxx
kind: Bucket
metadata:
  name: bucket-sample
spec:
  name: foo-bar-objects # create with UID-based sufix OR
  nameOverride: foo-final-bucket-name # override name ( specify exactly one name)
  existingBucket:
    ownerKeySecret: foo-owner-key # Secret reference, proof of ownership
    # name: foo-final-bucket-name  # field deprecated, replace with `spec.nameOverride`
  maxSize: 10Gi
  maxObjects: 9000

The existingBucket will be then required only if the bucket does not already exist. Of course improvements around easier reclaim / bulk (admin) approval would make that optional at some point.

This reminds me that I don't have the full API in a readable form anywhere.

[Junjus]

Hey Thank you for your quick response. I also think that for the current alpha version it makes sense to keep the split.

And I do see how the re-adoption flow is a bit bigger design problem. that maybe can be pushed back for now.

And I'm also fine with calling it nameOverride.

Thx :))

[Junjus]

While looking into a PR for this, I noticed an ownership issue that I do not think I fully appreciated before.

If modifying an existing Garage bucket requires proof of ownership, then exact-name buckets have a problem after creation:

1. Controller creates bucket foo-final-bucket-name.
2. At creation time, ownership is clear because the controller created it.
3. Later, the Bucket resource is reconciled again and wants to update bucket based on spec(.quota)
4. But unless the controller persisted some ownership proof from creation time, it no longer has an independent way to prove that this exact Garage bucket still belongs to this Kubernetes Bucket resource. Contrary to the suffixed bucket names.

So I think that exact-name creation+update and and re-adoption ownership cannot be fully separated. Even if we postpone the bigger GitOps re-adoption flow, the controller still needs some persisted proof of ownership for exact-name buckets if it should safely modify them later.

A possible smaller compromise, which might already cover most of my use case, is to focus on exact local aliases first.

If I understand local aliases correctly:

• local aliases are scoped to a access key
• they can only reference buckets that the namespace already owns or is authorized to access
• therefore, using the exact desired name as a local alias gives users a stable S3-facing name
  without allowing tenants to reconcile arbitrary globally named Garage buckets

That would also avoid most of the dangerous global collision/adoption problem. The real bucket could still use the controller’s generated/suffixed name, while the user gets a stable local alias such as foo-final-bucket-name.

So maybe the implementation path could be:

1. Add support for exact local aliases, possibly via localAliases field in accesspolicy.
2. Defer globally exact bucket names until the controller has a proper persisted ownership/adoption design.

That would not solve every case of global exact names, but it may provide 90% of the practical benefit for workloads that need a stable S3 bucket name, while avoiding the harder ownership-proof problem for now.

[bmarinov]

While looking into a PR for this, I noticed an ownership issue that I do not think I fully appreciated before.

If modifying an existing Garage bucket requires proof of ownership, then exact-name buckets have a problem after creation:

1. Controller creates bucket `foo-final-bucket-name`.

2. At creation time, ownership is clear because the controller created it.

3. Later, the Bucket resource is reconciled again and wants to update bucket based on spec(.quota)

4. But unless the controller persisted some ownership proof from creation time, it no longer has an independent way to prove that this exact Garage bucket still belongs to this Kubernetes Bucket resource. Contrary to the suffixed bucket names.

This is not a problem when creating a new bucket. A fully reconciled Bucket object counts as a proof that the namespace owns and manages the bucket. Having a regular "inferred" name or exact nameOverride does not change this. Only the strategy for the name generation changes.

Adopting the bucket later needs one of three things:

• secret acting as a proof of ownership;
• state stored on the Garage cluster itself (no tags support, annoying but doable with workarounds);
• New CRD with bulk allow "namespace:[]{buckets...}" pairs, but this is not around the corner.

I've thought about this and while there are some compromises to be made, they might only work in homelab scenarios. At least I wouldn't feel comfortable rolling this in an actual production environment where access control is non negotiable. Open to suggestions though, I'll think about it next week.