Skip to content

GarageKey v1beta1

API version: garage.rajsingh.info/v1beta1. Scope: Namespaced.

The custom-resource guide explains operational behavior. The JSON schemas are the validation source of truth.

Spec

GarageKeySpec defines the desired state of GarageKey

Field path Type Constraints Description
allBuckets object AllBuckets grants this key a baseline permission set on every bucket in the cluster. Useful for admin tools, backup agents, or monitoring that need cluster-wide access. How it works: the operator calls Garage's allow/deny APIs for every bucket to enforce exactly the flags set here — false actively revokes, not just leaves unset. BucketPermissions entries are then applied on top, so you can grant broader access via allBuckets and restrict specific buckets via bucketPermissions. Warning: this applies to ALL Garage buckets, including buckets not managed by the operator (created directly via the S3 API). Plan accordingly.
allBuckets.owner boolean default: false Owner allows bucket owner operations on all buckets
allBuckets.read boolean default: false Read allows reading objects from all buckets
allBuckets.write boolean default: false Write allows writing objects to all buckets
bucketPermissions array of object max items: 100 BucketPermissions grants this key access to buckets. Note: Permissions can be granted from either direction: - Here (GarageKey.bucketPermissions): Grant this key access to buckets - On GarageBucket (GarageBucket.keyPermissions): Grant keys access to the bucket Both approaches are equivalent and result in the same Garage API calls. Use whichever is more convenient for your workflow: - Key-centric: Define all bucket access on the key - Bucket-centric: Define all key access on the bucket If the same permission is defined in both places, they are merged (not conflicting).
bucketPermissions[].bucketId string BucketID references the bucket by its Garage-internal ID.
bucketPermissions[].bucketRef object BucketRef references a GarageBucket by name (and optionally namespace). Mutually exclusive with BucketID and GlobalAlias.
bucketPermissions[].bucketRef.name string required Name of the GarageBucket.
bucketPermissions[].bucketRef.namespace string Namespace of the GarageBucket. Defaults to the GarageKey's namespace. Cross-namespace references require a GarageReferenceGrant in the target namespace.
bucketPermissions[].globalAlias string GlobalAlias references the bucket by its global alias.
bucketPermissions[].owner boolean default: false Owner allows bucket owner operations (delete bucket, configure website, etc.)
bucketPermissions[].read boolean default: false Read allows reading objects from the bucket.
bucketPermissions[].write boolean default: false Write allows writing objects to the bucket.
clusterRef object required ClusterRef references the GarageCluster this key belongs to
clusterRef.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.
clusterRef.kubeConfigSecretRef.key string required The key of the secret to select from. Must be a valid secret key.
clusterRef.kubeConfigSecretRef.name string default: "" 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
clusterRef.kubeConfigSecretRef.optional boolean Specify whether the Secret or its key must be defined
clusterRef.name string required Name of the GarageCluster resource.
clusterRef.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.
expiresAt string format: "date-time" ExpiresAt sets when this key expires. After this time Garage will reject requests using the key. The operator sets the KeyExpired condition when expired but does NOT automatically delete or rotate the key. Mutually exclusive with neverExpires.
importKey object ImportKey imports an existing key instead of generating new credentials
importKey.accessKeyId string AccessKeyID is the existing Garage access key ID. Garage v2.3 and newer accept at least 8 characters from ASCII letters, digits, '-', '_' and '.' (so keys from other S3 providers can be migrated). Garage v2.0 to v2.2 accept only "GK" followed by 24 hex characters and reject anything else with a 400 that is reported in the Ready condition. Use secretRef instead to avoid storing credentials in the CR.
importKey.accessKeyIdKey string AccessKeyIDKey is the key name within secretRef for the access key ID. Defaults to "access-key-id". Only valid when secretRef is set.
importKey.secretAccessKey string SecretAccessKey is the existing secret access key. Garage v2.3 and newer accept at least 16 graphic ASCII characters (U+0021 to U+007E: no spaces, control characters or non-ASCII text). Garage v2.0 to v2.2 accept only 64 hex characters and reject anything else with a 400 that is reported in the Ready condition. Use secretRef instead to avoid storing credentials in the CR.
importKey.secretAccessKeyKey string SecretAccessKeyKey is the key name within secretRef for the secret access key. Defaults to "secret-access-key". Only valid when secretRef is set.
importKey.secretRef object SecretRef references a Kubernetes secret containing the credentials. Mutually exclusive with inline accessKeyId/secretAccessKey. The namespace must be empty or match the GarageKey namespace.
importKey.secretRef.name string name is unique within a namespace to reference a secret resource.
importKey.secretRef.namespace string namespace defines the space within which the secret name must be unique.
name string Name is a friendly name for this access key If not set, metadata.name is used
neverExpires boolean NeverExpires explicitly marks this key as having no expiration. Sets the Garage key expiration to "never" rather than leaving it unset. Mutually exclusive with expiration.
permissions object Permissions configures key-level permissions Note: For admin API access, use admin tokens configured in GarageCluster
permissions.createBucket boolean default: false CreateBucket allows this key to create new buckets via the S3 CreateBucket API
secretTemplate object SecretTemplate configures how the secret is generated
secretTemplate.accessKeyIdKey string default: "access-key-id" AccessKeyIDKey is the key name for the access key ID
secretTemplate.additionalData map of string AdditionalData includes additional key-value pairs in the secret
secretTemplate.annotations map of string Annotations to add to the secret
secretTemplate.bucketNameKey string default: "bucket" BucketNameKey is the data key under which the bucket name is written in the Secret. Defaults to "bucket". Only used when IncludeBucketName is true.
secretTemplate.credentialsFileKey string default: "credentials" CredentialsFileKey is the data key under which an AWS shared credentials file is written. Defaults to "credentials". Only used when IncludeCredentialsFile is true.
secretTemplate.credentialsFileProfile string default: "default"; max length: 128; pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]*$" CredentialsFileProfile is the profile name used in the AWS shared credentials file. Defaults to "default". Only used when IncludeCredentialsFile is true.
secretTemplate.endpointKey string default: "endpoint" EndpointKey is the key name for the S3 endpoint (includes http:// scheme)
secretTemplate.hostKey string default: "host" HostKey is the key name for the S3 host (without scheme, e.g., "host:port")
secretTemplate.includeBucketName boolean IncludeBucketName controls whether the bucket name is written to the Secret. Defaults to false. When true, the bucket name is populated only if the key references exactly one bucket (via bucketRef or globalAlias); omitted otherwise.
secretTemplate.includeCredentialsFile boolean IncludeCredentialsFile controls whether an AWS shared credentials file is written to the Secret. Defaults to false. The file contains only the access key ID and secret access key under CredentialsFileProfile.
secretTemplate.includeEndpoint boolean IncludeEndpoint includes the S3 endpoint in the secret Defaults to true if not specified
secretTemplate.includeRegion boolean IncludeRegion includes the S3 region in the secret Defaults to true if not specified
secretTemplate.includeWebsiteUrl boolean IncludeWebsiteURL controls whether the referenced bucket's observed website URL is written to the Secret. Defaults to false. The value is populated only when the key references exactly one GarageBucket via bucketRef and that bucket has a non-empty status.websiteUrl.
secretTemplate.labels map of string Labels to add to the secret
secretTemplate.name string Name is the name of the secret to create Defaults to the GarageKey name
secretTemplate.regionKey string default: "region" RegionKey is the key name for the S3 region
secretTemplate.schemeKey string default: "scheme" SchemeKey is the key name for the endpoint scheme (http or https)
secretTemplate.secretAccessKeyKey string default: "secret-access-key" SecretAccessKeyKey is the key name for the secret access key
secretTemplate.type string default: "Opaque" Type is the secret type
secretTemplate.websiteUrlKey string default: "website-url" WebsiteURLKey is the data key under which the bucket website URL is written in the Secret. Defaults to "website-url". Only used when IncludeWebsiteURL is true.

Status

GarageKeyStatus defines the observed state of GarageKey

Field path Type Constraints Description
accessKeyId string AccessKeyID is the S3 access key ID
buckets array of object Buckets lists buckets this key has access to
buckets[].bucketId string BucketID is the bucket ID
buckets[].globalAlias string GlobalAlias is the bucket's global alias
buckets[].localAlias string LocalAlias is this key's local alias for the bucket
buckets[].owner boolean default: false Owner permission
buckets[].read boolean default: false Read permission
buckets[].write boolean default: false Write permission
clusterWide boolean ClusterWide records reserved or active operator ownership of permissions managed through spec.allBuckets. It is set before the first remote allow and remains set until every resulting permission has been removed.
conditions array of object Conditions represent the current state
conditions[].lastTransitionTime string required; format: "date-time" 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.
conditions[].message string required; max length: 32768 message is a human readable message indicating details about the transition. This may be an empty string.
conditions[].observedGeneration integer format: "int64"; min: 0 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.
conditions[].reason string required; min length: 1; max length: 1024; pattern: "^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$" 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.
conditions[].status string required; enum: ["True", "False", "Unknown"] status of the condition, one of True, False, Unknown.
conditions[].type string required; max length: 316; 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])$" type of condition in CamelCase or in foo.example.com/CamelCase.
createdAt string format: "date-time" CreatedAt is when the key was created in Garage
effectivePermissions array of object EffectivePermissions is retained for API compatibility but is not currently populated. Status.Buckets reports Garage's authoritative effective bucket access.
effectivePermissions[].bucketAlias string BucketAlias is the bucket's global alias (if set)
effectivePermissions[].bucketId string BucketID is the bucket ID
effectivePermissions[].owner boolean default: false Owner permission
effectivePermissions[].read boolean default: false Read permission
effectivePermissions[].source string Source indicates where this permission was defined ("bucket", "key", or "both")
effectivePermissions[].write boolean default: false Write permission
expiresAt string format: "date-time" ExpiresAt is when this key expires (if set)
keyId string KeyID is the Garage-assigned key ID
managedBucketGrants array of string ManagedBucketGrants lists Garage bucket IDs with reserved or active operator ownership from this key's spec.bucketPermissions. IDs are recorded before the first remote mutation and removed only after exact convergence, allowing crash-safe removal or downgrade without touching manual grants. Cluster-wide spec.allBuckets ownership is represented by ClusterWide.
observedGeneration integer format: "int64" ObservedGeneration is the last observed generation
permissions object Permissions shows the current permissions for this key
permissions.createBucket boolean default: false CreateBucket allows this key to create new buckets via the S3 CreateBucket API
phase string enum: ["Pending", "Creating", "Ready", "Deleting", "Failed", "Expired", "Unknown"] Phase represents the current phase
secretRef object SecretRef references the created secret
secretRef.name string name is unique within a namespace to reference a secret resource.
secretRef.namespace string namespace defines the space within which the secret name must be unique.