GarageBucket
garage.rajsingh.info / v1beta1
apiVersion: garage.rajsingh.info/v1beta1
kind: GarageBucket
metadata:
name: example
apiVersion
string
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kind
string
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadata
object
spec object required
GarageBucketSpec defines the desired state of GarageBucket
bucketId
string
BucketID pins this resource to a pre-existing Garage bucket ID.
When set, the operator will never create a new bucket — it only manages
settings and key permissions for the identified bucket. Takes priority
over GlobalAlias-based lookup. Useful for importing existing buckets and
for recovery after cluster incidents.
clusterRef object required
ClusterRef references the GarageCluster this bucket belongs to
kubeConfigSecretRef object
KubeConfigSecretRef is reserved for a future remote Kubernetes client integration.
It is currently rejected by admission because the operator does not use it.
key
string required
The key of the secret to select from. Must be a valid secret key.
name
string
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
optional
boolean
Specify whether the Secret or its key must be defined
name
string required
Name of the GarageCluster resource.
namespace
string
Namespace of the GarageCluster. Defaults to the referencing resource's namespace.
Cross-namespace references require a GarageReferenceGrant where supported by
the owning resource. GarageNode and GarageAdminToken reject them.
deletionPolicy
string
DeletionPolicy controls whether deleting this resource also deletes the
corresponding Garage bucket. The default is Delete.
enum:
Delete, Retain
globalAlias
string
GlobalAlias is the global alias for this bucket (optional)
If not set, the bucket name from metadata.name is used
keyPermissions []object
KeyPermissions grants access to specific GarageKeys.
Note: Permissions can be granted from either direction:
- Here (GarageBucket.keyPermissions): Grant keys access to this bucket
- On GarageKey (GarageKey.bucketPermissions): Grant the key access to buckets
Both approaches are equivalent and result in the same Garage API calls.
Use whichever is more convenient for your workflow:
- Bucket-centric: Define all key access on the bucket
- Key-centric: Define all bucket access on the key
If the same permission is defined in both places, they are merged (not conflicting).
keyRef object required
KeyRef references the GarageKey by name (and optionally namespace).
name
string required
Name of the GarageKey.
namespace
string
Namespace of the GarageKey. Defaults to the GarageBucket's namespace.
Cross-namespace references require a GarageReferenceGrant in the target namespace.
owner
boolean
Owner allows bucket owner operations
read
boolean
Read allows reading objects
write
boolean
Write allows writing objects
lifecycle object
Lifecycle configures bucket lifecycle policies (object expiration,
abort of incomplete multipart uploads).
Garage exposes lifecycle only via the S3 API, not the admin API. The
operator applies rules using an internal access key it manages per
GarageCluster. Garage supports a strict subset of the AWS S3 lifecycle
spec: only Expiration (days or date, no ExpiredObjectDeleteMarker) and
AbortIncompleteMultipartUpload. Filters support prefix and object size
bounds; tag filters and the deprecated rule-level Prefix are not
accepted.
Garage's lifecycle worker runs daily at midnight (UTC by default), so
rule evaluation is asynchronous from reconciliation.
rules []object
Rules to apply. The operator replaces the bucket's lifecycle
configuration with this exact set on each reconcile.
abortIncompleteMultipartUploadDays
integer
AbortIncompleteMultipartUploadDays aborts multipart uploads that have
been pending for at least this many days.
format:
int32minimum:
1
expirationDate
string
ExpirationDate expires current objects on or after this UTC date.
format:
date-time
expirationDays
integer
ExpirationDays expires current objects this many days after creation.
format:
int32minimum:
1filter object
Filter narrows the rule to a subset of objects. If unset, the rule
applies to every object in the bucket.
objectSizeGreaterThan
integer
ObjectSizeGreaterThan matches objects strictly larger than this many
bytes.
format:
int64minimum:
0
objectSizeLessThan
integer
ObjectSizeLessThan matches objects strictly smaller than this many
bytes.
format:
int64minimum:
1
prefix
string
Prefix matches object keys starting with this string.
id
string required
ID is the rule identifier. Must be unique within the bucket.
minLength:
1
status
string
Status enables or disables this rule. Disabled rules are sent to
Garage but skipped by the lifecycle worker.
enum:
Enabled, DisabledlocalAliases []object
LocalAliases are per-key local aliases for this bucket
alias
string required
Alias is the bucket name this key will use to access the bucket.
Must be unique within the key's alias namespace.
keyRef
string required
KeyRef is the name of the GarageKey in the same namespace that owns this alias.
quotas object
Quotas configures bucket quotas
maxObjects
integer
MaxObjects is the maximum number of objects
format:
int64
maxSize
string | integer
MaxSize is the maximum bucket size in bytes
string pattern:
^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$website object
Website configures static website hosting for this bucket.
Note: Only indexDocument and errorDocument are supported via the Admin API.
For advanced features (routing rules, redirectAll), use S3 PutBucketWebsite API directly.
enabled
boolean
Enabled enables static website hosting.
errorDocument
string
ErrorDocument is the error document to serve for 404s
indexDocument
string
IndexDocument is the default index document (default: index.html)
websiteExposure object
WebsiteExposure optionally exposes a website-enabled bucket through
Kubernetes HTTP routing: an Ingress or a Gateway API HTTPRoute, created
in this bucket's namespace and pointing at the referenced cluster's web
API Service. At most one of Ingress and Gateway may be set. Requires
spec.website.enabled. See the websiteExposure documentation for the
hostname semantics (Garage resolves the bucket from the Host header).
backendRef object
BackendRef overrides the Service the exposure routes to. When unset,
the operator targets the referenced cluster's web API Service
(<cluster>-gateway for unified clusters, <cluster> otherwise). For an
Ingress the referent must be a core/v1 Service in the bucket's
namespace (Ingress backends cannot cross namespaces). For an
HTTPRoute any referent valid for spec.rules[].backendRefs is
accepted, including cross-namespace ones (which additionally need a
gateway API ReferenceGrant).
group
string
Group of the referent. Defaults to "" (the core API group).
maxLength:
253
kind
string
Kind of the referent. Defaults to Service.
maxLength:
253
name
string required
Name of the referent.
minLength:
1maxLength:
253
namespace
string
Namespace of the referent. Defaults to the bucket's namespace (the
exposure resource's namespace). For an Ingress it must stay the
bucket's namespace: Ingress backends cannot cross namespaces.
minLength:
1maxLength:
63gateway object
Gateway configures the generated Gateway API HTTPRoute. Mutually
exclusive with Ingress. Requires the Gateway API CRDs to be installed;
without them the operator reports a condition and does not fail the
bucket.
annotations
object
Annotations to add to the HTTPRoute.
labels
object
Labels to add to the HTTPRoute (for example external-dns or
argo-rollouts annotations). Operator-managed labels take precedence
on conflict.
parentRefs []object required
ParentRefs are passed through verbatim to the HTTPRoute's
spec.parentRefs (Gateway names, optional sectionName, and optional
cross-namespace references). At least one is required.
minItems:
1
group
string
Group is the group of the referent.
When unspecified, "gateway.networking.k8s.io" is inferred.
To set the core API group (such as for a "Service" kind referent),
Group must be explicitly set to "" (empty string).
Support: Core
pattern:
^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$maxLength:
253
kind
string
Kind is kind of the referent.
There are two kinds of parent resources with "Core" support:
* Gateway (Gateway conformance profile)
* Service (Mesh conformance profile, ClusterIP Services only)
Support for other resources is Implementation-Specific.
pattern:
^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$minLength:
1maxLength:
63
name
string required
Name is the name of the referent.
Support: Core
minLength:
1maxLength:
253
namespace
string
Namespace is the namespace of the referent. When unspecified, this refers
to the local namespace of the Route.
Note that there are specific rules for ParentRefs which cross namespace
boundaries. Cross-namespace references are only valid if they are explicitly
allowed by something in the namespace they are referring to. For example:
Gateway has the AllowedRoutes field, and ReferenceGrant provides a
generic way to enable any other kind of cross-namespace reference.
<gateway:experimental:description>
ParentRefs from a Route to a Service in the same namespace are "producer"
routes, which apply default routing rules to inbound connections from
any namespace to the Service.
ParentRefs from a Route to a Service in a different namespace are
"consumer" routes, and these routing rules are only applied to outbound
connections originating from the same namespace as the Route, for which
the intended destination of the connections are a Service targeted as a
ParentRef of the Route.
</gateway:experimental:description>
Support: Core
pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$minLength:
1maxLength:
63
port
integer
Port is the network port this Route targets. It can be interpreted
differently based on the type of parent resource.
When the parent resource is a Gateway, this targets all listeners
listening on the specified port that also support this kind of Route(and
select this Route). It's not recommended to set `Port` unless the
networking behaviors specified in a Route must apply to a specific port
as opposed to a listener(s) whose port(s) may be changed. When both Port
and SectionName are specified, the name and port of the selected listener
must match both specified values.
<gateway:experimental:description>
When the parent resource is a Service, this targets a specific port in the
Service spec. When both Port (experimental) and SectionName are specified,
the name and port of the selected port must match both specified values.
</gateway:experimental:description>
Implementations MAY choose to support other parent resources.
Implementations supporting other types of parent resources MUST clearly
document how/if Port is interpreted.
For the purpose of status, an attachment is considered successful as
long as the parent resource accepts it partially. For example, Gateway
listeners can restrict which Routes can attach to them by Route kind,
namespace, or hostname. If 1 of 2 Gateway listeners accept attachment
from the referencing Route, the Route MUST be considered successfully
attached. If no Gateway listeners accept attachment from this Route,
the Route MUST be considered detached from the Gateway.
Support: Extended
format:
int32minimum:
1maximum:
65535
sectionName
string
SectionName is the name of a section within the target resource. In the
following resources, SectionName is interpreted as the following:
* Gateway: Listener name. When both Port (experimental) and SectionName
are specified, the name and port of the selected listener must match
both specified values.
* Service: Port name. When both Port (experimental) and SectionName
are specified, the name and port of the selected listener must match
both specified values.
Implementations MAY choose to support attaching Routes to other resources.
If that is the case, they MUST clearly document how SectionName is
interpreted.
When unspecified (empty string), this will reference the entire resource.
For the purpose of status, an attachment is considered successful if at
least one section in the parent resource accepts it. For example, Gateway
listeners can restrict which Routes can attach to them by Route kind,
namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from
the referencing Route, the Route MUST be considered successfully
attached. If no Gateway listeners accept attachment from this Route, the
Route MUST be considered detached from the Gateway.
Support: Core
pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$minLength:
1maxLength:
253
hostnames
[]string
Hostnames are the external hostnames the exposure routes on. When
empty, the operator uses the single canonical hostname
<globalAlias><webApi.rootDomain>. Wildcards and duplicates are not
supported (duplicates are rejected by the validating webhook; the CRD
schema cannot express uniqueItems).
For an HTTPRoute any hostname is accepted: a hostname that is neither
canonical nor the global alias gets a URLRewrite filter rewriting the
Host header back to the canonical host, so Garage still resolves it to
this bucket. For an Ingress, only the canonical hostname and the
global alias are accepted — an Ingress cannot rewrite the Host header,
so any other hostname is refused on the WebsiteExposed condition.
maxItems:
16ingress object
Ingress configures the generated Kubernetes Ingress. Mutually
exclusive with Gateway. Only valid when the bucket and the referenced
cluster share a namespace.
annotations
object
Annotations to add to the Ingress (for example the TLS or
proxy-protocol annotations your ingress controller expects).
ingressClassName
string
IngressClassName is the ingress class the Ingress must match
(spec.ingressClassName). When empty, the Ingress is left without a
class so the cluster's default ingress controller picks it up.
minLength:
1maxLength:
253
labels
object
Labels to add to the Ingress. Operator-managed labels take precedence
on conflict.
tlsSecretName
string
TLSSecretName is the name of a TLS Secret in the bucket's namespace
(where the generated Ingress lives), attached to the Ingress
(spec.tls). The Secret must already exist; the operator does not
provision certificates.
minLength:
1maxLength:
253status object
GarageBucketStatus defines the observed state of GarageBucket
bucketId
string
BucketID is the internal Garage bucket ID
conditions []object
Conditions represent the current state
lastTransitionTime
string required
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
format:
date-time
message
string required
message is a human readable message indicating details about the transition.
This may be an empty string.
maxLength:
32768
observedGeneration
integer
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance.
format:
int64minimum:
0
reason
string required
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty.
pattern:
^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$minLength:
1maxLength:
1024
status
string required
status of the condition, one of True, False, Unknown.
enum:
True, False, Unknown
type
string required
type of condition in CamelCase or in foo.example.com/CamelCase.
pattern:
^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$maxLength:
316
createdAt
string
CreatedAt is when the bucket was created in Garage
format:
date-time
globalAlias
string
GlobalAlias is the assigned global alias
incompleteUploadBytes
integer
IncompleteUploadBytes is the total bytes in incomplete multipart uploads
format:
int64
incompleteUploadParts
integer
IncompleteUploadParts is the count of parts in incomplete multipart uploads
format:
int64
incompleteUploads
integer
IncompleteUploads is the count of incomplete multipart uploads
format:
int64keys []object
Keys contains keys with access to this bucket
keyId
string
KeyID is the access key ID
name
string
Name is the key name
permissions object
Permissions granted to this key
owner
boolean
Owner permission
read
boolean
Read permission
write
boolean
Write permission
lifecycleRules []object
LifecycleRules summarises lifecycle rules currently applied to the
bucket in Garage. Spec is the source of truth for rule contents; this
list reports id and enabled state only.
id
string required
ID of the rule.
status
string required
Status is Enabled or Disabled.
enum:
Enabled, DisabledlocalAliases []object
LocalAliases tracks per-key local aliases for this bucket
alias
string
Alias is the local alias name
keyId
string
KeyID is the access key ID that owns this alias
keyName
string
KeyName is the friendly name of the key
managedGlobalAlias
string
ManagedGlobalAlias is the global alias reserved or successfully managed from
spec.globalAlias (or the bucket name when spec.globalAlias is empty).
It is separate from GlobalAlias, which reports observed Garage state, so
aliases created outside the operator are never removed accidentally.
managedKeyGrants
[]string
ManagedKeyGrants lists access key IDs with reserved or active operator
ownership from this bucket's spec.keyPermissions. IDs are recorded before
the first remote mutation and removed only after exact convergence, allowing
crash-safe revocation when a declaration is dropped without disturbing
grants managed through GarageKey or by hand.
managedLocalAliases []object
ManagedLocalAliases lists the per-key aliases reserved or successfully
managed from spec.localAliases. IDs are recorded before the first remote
add so an interrupted add can still be removed safely.
alias
string
Alias is the local alias name
keyId
string
KeyID is the access key ID that owns this alias
keyName
string
KeyName is the friendly name of the key
observedGeneration
integer
ObservedGeneration is the last observed generation
format:
int64
pendingGlobalAlias
string
PendingGlobalAlias reserves a replacement before its first remote add.
ManagedGlobalAlias retains the old alias until the replacement succeeds,
so a failed rename never leaves the bucket without its prior alias.
phase
string
Phase represents the current phase
enum:
Pending, Creating, Ready, Deleting, Failed, UnknownquotaUsage object
QuotaUsage shows current quota consumption
objectCount
integer
ObjectCount is the current object count
format:
int64
objectLimit
integer
ObjectLimit is the configured object limit (0 = unlimited)
format:
int64
objectPercent
integer
ObjectPercent is the percentage of object quota used
format:
int32
sizeBytes
integer
SizeBytes is the current size in bytes
format:
int64
sizeLimit
integer
SizeLimit is the configured size limit in bytes (0 = unlimited)
format:
int64
sizePercent
integer
SizePercent is the percentage of size quota used
format:
int32
size
string
Size is the current bucket size
websiteConfig object
WebsiteConfig shows the current website configuration details
errorDocument
string
ErrorDocument is the configured error document
indexDocument
string
IndexDocument is the configured index document
websiteEnabled
boolean
WebsiteEnabled indicates if website hosting is currently enabled
websiteExposure object
WebsiteExposure reports the operator-generated HTTP routing resource
(Ingress or HTTPRoute) when spec.websiteExposure is set.
hostnames
[]string
Hostnames are the hostnames the generated resource routes on.
name
string
Name is the name of the generated resource, in the bucket's namespace.
parents []object
Parents mirrors the route's status.parents for an HTTPRoute: the
per-parent Accepted/ResolvedRefs/Ready conditions the Gateway
controllers publish. Empty for an Ingress, which has no per-parent
readiness model.
accepted
boolean
Accepted is true when the parent accepted the route
(status.parents[].conditions[Accepted]=True).
message
string
Message carries the parent's condition message when not ready.
parent
string
Parent is the parent Gateway (or other parent) as namespace/name.
ready
boolean
Ready is true when the parent reports the route Ready
(status.parents[].conditions[Ready]=True).
resolvedRefs
boolean
ResolvedRefs is true when the route's backend references resolved on
that parent (status.parents[].conditions[ResolvedRefs]=True).
type
string
Type is the kind of routing resource the operator manages for this
bucket: Ingress or HTTPRoute.
enum:
Ingress, HTTPRoute
websiteUrl
string
WebsiteURL is the computed website URL (if website hosting is enabled)
No matches. Try .spec.bucketId for an exact path