Documentation
¶
Overview ¶
Package rgw prepares RADOS Gateway fixtures in disposable Ceph clusters: gateways, S3 users with tenants, Admin Ops capabilities, quotas, S3 key rotation, STS roles, reversible rate limits and storage counters, and native TLS with certificate replacement. Accounts are in package rgw/account, placement targets and storage classes in package rgw/placement, persistent notification queue observations in package rgw/notification, and multisite orchestration across clusters in package rgw/multisite; this package imports none of them.
Run starts a cluster with at least one gateway. Start adds a gateway to a cluster created by ceph.Run or another service package's Run, and WithGateways selects gateways for any of those Run functions.
Index ¶
- func WithGateways(configs ...Config) ceph.Option
- type AdminCapability
- type Config
- type Container
- type Gateway
- func (g *Gateway) Admin(ctx context.Context, args ...string) ([]byte, error)
- func (g *Gateway) CreateRole(ctx context.Context, config RoleConfig) (*Role, error)
- func (g *Gateway) CreateUser(ctx context.Context, config UserConfig) (*User, error)
- func (c *Gateway) DaemonEndpoint(ctx context.Context) (string, error)
- func (g Gateway) Format(f fmt.State, _ rune)
- func (g Gateway) GoString() string
- func (g *Gateway) Remove(ctx context.Context) error
- func (g *Gateway) ReplaceTLS(ctx context.Context, config TLSConfig) error
- func (c *Gateway) S3Endpoint(ctx context.Context) (string, error)
- func (g *Gateway) S3SecureEndpoint(ctx context.Context) (string, error)
- func (g Gateway) String() string
- type Quota
- type RateLimit
- type RateLimitOverrideHandle
- type RateLimitScope
- type Role
- type RoleConfig
- type RolePolicy
- type RootAccount
- type S3Key
- type TLSConfig
- type User
- func (u *User) CreateS3Key(ctx context.Context) (*S3Key, error)
- func (u *User) CreationKey() *S3Key
- func (u User) Format(f fmt.State, _ rune)
- func (u User) GoString() string
- func (u *User) ID() string
- func (u *User) Info(ctx context.Context) (UserInfo, error)
- func (u *User) OverrideRateLimit(ctx context.Context, scope RateLimitScope, limit RateLimit) (*RateLimitOverrideHandle, error)
- func (u *User) Remove(ctx context.Context) error
- func (u *User) SetBucketQuota(ctx context.Context, quota Quota) error
- func (u *User) SetQuota(ctx context.Context, quota Quota) error
- func (u User) String() string
- func (u *User) Suspend(ctx context.Context, suspended bool) error
- func (u *User) Usage(ctx context.Context) (UserUsage, error)
- type UserConfig
- type UserInfo
- type UserUsage
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithGateways ¶
WithGateways starts named gateways during Run. No arguments starts one default gateway. Repeated options replace the list. All gateways share this cluster's backing zone; multisite scope is configured separately by multisite.Run.
Types ¶
type AdminCapability ¶
AdminCapability is one admin capability of a user. Type is the capability type, such as users, usage, ratelimit or buckets; Permission is read, write, or * when both were granted (* does not mean global admin).
type Config ¶
type Config struct {
Name, Realm, Zonegroup, Zone, Region string
SkipUserCreation bool
TLS *TLSConfig
}
Config selects a gateway instance and optional native RGW multisite scope. Name defaults to default; different names allow multiple gateways in one zone. Realm, Zonegroup and Zone must already exist when supplied. Region defaults to us-east-1. SkipUserCreation is useful when sharing existing S3 credentials or configuring multisite users through radosgw-admin.
type Container ¶
Container is a cluster started by Run. It embeds *ceph.Container, so every cluster method is available on it; pass its Container field to functions that take a *ceph.Container, such as those of this and the other service packages.
func Run ¶
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
Run starts a disposable cluster for S3 and Swift clients. It accepts every ceph.Run option and the options of other service packages. When no WithGateways option is given, it starts the default gateway and creates its test user. Bootstrap options that leave the cluster without OSDs or managers for the gateway, such as ceph.ClusterConfig.WithNoInitialOSDs, are rejected; use ceph.Run for those stages. A non-nil Container returned with an error must still be terminated.
Example ¶
package main
import (
"context"
"log"
"github.com/JSYoo5B/ceph-testcontainers-go/ceph"
"github.com/JSYoo5B/ceph-testcontainers-go/rgw"
"github.com/testcontainers/testcontainers-go"
)
func main() {
ctx := context.Background()
cluster, err := rgw.Run(ctx, ceph.DefaultImage,
rgw.WithGateways(rgw.Config{Name: "s3", SkipUserCreation: true}),
)
defer func() {
if err := testcontainers.TerminateContainer(cluster); err != nil {
log.Printf("failed to terminate container: %s", err)
}
}()
if err != nil {
panic(err)
}
gateways, err := rgw.Gateways(ctx, cluster.Container)
if err != nil {
panic(err)
}
gateway := gateways[0]
user, err := gateway.CreateUser(ctx, rgw.UserConfig{ID: "app"})
if err != nil {
panic(err)
}
endpoint, err := gateway.S3Endpoint(ctx)
if err != nil {
panic(err)
}
// Sign S3 requests to endpoint with user.CreationKey().Credentials().
_, _ = user, endpoint
}
Output:
type Gateway ¶
type Gateway struct {
testcontainers.Container
GatewayName string
AccessKey string
SecretKey string
// Region is the SigV4 signing region: Config.Region, which defaults to
// us-east-1, or for a multisite gateway its zonegroup name. RGW itself
// is not configured with it.
Region string
// contains filtered or unexported fields
}
Gateway is an optional S3 gateway owned by its Ceph cluster. AccessKey and SecretKey belong to a generated ordinary S3 user for trusted tests.
Gateway embeds testcontainers.Container, so Stop, Start, Logs, Exec and Inspect act on the gateway container. Formatting a Gateway, User or TLSConfig with any fmt verb, including %+v and %#v, prints only an identifying label such as "RGW gateway s3"; credentials and TLS keys are read explicitly from the fields or User.CreationKey().Credentials(). A gateway runs with 4 worker threads: enough for functional tests, not for load tests. Rate limits are enforced by each gateway separately. Copies of a Gateway share its identity; Remove accepts only the descriptor that Start or Gateways returned.
func Gateways ¶
Gateways returns sorted owned gateway descriptors, including partial startup attempts, while bounding the wait for fixture topology by ctx.
func Start ¶
func Start(ctx context.Context, c *ceph.Container, config Config, opts ...testcontainers.ContainerCustomizer) (*Gateway, error)
Start starts an independently owned, named gateway on an existing cluster. A zero config starts the default gateway and creates its test user. Customizers are applied last; preserve the required command, network and listener settings. A non-nil result returned with an error remains owned by the cluster for cleanup.
In host mode the port is reserved on the Docker host and released just before the daemon binds it; if another process takes it in between, startup is retried with a new port, up to five attempts. Server-side RGW options are read when a gateway starts: set them with override.SetConfig on a cluster from ceph.Run, then call Start. RGW runs as client.admin, so options in a ceph.WithConfigFile file belong in [client] or [client.admin].
func (*Gateway) Admin ¶
Admin invokes radosgw-admin inside this running gateway, preserving its realm, zonegroup, zone, Ceph configuration and keyring. The RGW role image supplies the CLI. Native arguments are passed individually, without a shell. Success output may contain credentials; failed command output is redacted. This is an explicit escape hatch for native operations beyond typed helpers; do not race raw user edits with owned-user creation or mutation.
--format json is always added. Arguments must not contain control characters, so pass JSON documents (policies, trust documents) as single-line strings. Arguments that would change the scope or connection are refused with ceph.ErrInvalidRequest: --rgw-realm, --rgw-zonegroup, --rgw-zone and their ID and name variants, --conf/-c, --keyring/-k, --name/-n, --id, --mon-host/-m, --cluster and similar flags.
The call is bounded by ctx alone, like Container.Ceph: the cluster's startup timeout bounds bootstrap, readiness and the typed operations, not a native command whose duration the caller chooses, so give ctx the deadline the command needs. No radosgw-admin outlives the call: a small sh supervisor in the gateway container stops the command with SIGTERM, then SIGKILL after 2 s, 15 s before ctx's deadline (at half the remaining time for a short one; ceph.ErrNativeFailure, "radosgw-admin still ran after Ns and was stopped"), when ctx ends first (Admin then stops it under its own budget of about 10 s and returns ctx's error only after the command is gone; a call that ends before Docker started the command makes sure it never starts), or when the cluster's Terminate starts. When Admin cannot confirm the stop, for example because the gateway is paused or the engine is unreachable, it returns a *ceph.NativeCommandUnstoppedError whose Stop retries; Terminate retries too. Stopping radosgw-admin does not undo a request it already sent: the outcome of a stopped mutation is unknown and Admin never repeats it.
A failure keeps a *ceph.NativeFailure with the exit code and errno but no reason, so errors.Is(err, fs.ErrNotExist) works; run the same command with Exec to see the native text. When radosgw-admin reports a fatal signal, the error text also names the signal, its thread and the first backtrace frames, and says how many bytes of standard output it wrote and whether they are one complete JSON document, never what they say.
func (*Gateway) CreateRole ¶ added in v0.5.0
CreateRole creates a fresh native role with its trust policy through this gateway, with radosgw-admin role create, then puts its permission policies in order with role-policy put, so a test can hand the role's ARN to the SUT. An existing role of the same name is refused, never adopted or changed, and so is a name that another role handle of this cluster still tracks. Each mutation gets a separate role get to read back its outcome even if ctx ends after dispatch. The read keeps the admin operation deadline, with at least ten seconds for readback. No mutation is replayed:
- a nil error returns the role with all its policies;
- a non-nil role with an error is tracked and its Remove removes what the fixture created: when native state showed the role, ARN returns it and the error says what failed, such as a policy whose outcome is unknown; otherwise whether the role exists is unknown and ARN refuses it;
- a nil role with an error means that RGW shows that no role was created, or that nothing was attempted.
Native role edits of the same name from Admin or external clients must not race this operation.
func (*Gateway) CreateUser ¶
CreateUser creates a fresh S3 identity and, optionally, explicit Admin Ops capabilities. Existing IDs are rejected without changing their keys or policy. A non-nil handle with an error records an attempted or partial creation. If the generated credentials were confirmed, the handle supports Info and Remove even after a later capability setup failure. If the creation response is malformed, truncated or missing keys, credentials and ownership cannot be confirmed. Remove can establish absence after the create command has ended. A user still present requires inspection through Admin or termination of the disposable cluster. Native user edits from external clients must not race this operation.
With UserConfig.Account the user is that account's root user. The account must be active and created through a gateway of this gateway's cluster and scope; its native metadata lifetime is captured, and every later operation on the root user checks it again.
func (*Gateway) DaemonEndpoint ¶
DaemonEndpoint returns the HTTP address used by peers in the gateway's Docker network or daemon-host namespace. Host mode returns the advertised address; bridge mode returns the gateway's IP in its Ceph cluster network. The caller must share or reach that network. Use S3Endpoint for host application clients.
On a ceph.AddressDualStack cluster it returns the gateway's IPv4 address; the gateway listens on 0.0.0.0:7480 and [::]:7480, so clients in the cluster network reach it over its IPv6 address on port 7480 too.
func (Gateway) Format ¶ added in v0.4.0
Format prints String for every verb and flag, so no verb, such as %d or %t, walks the fields.
func (Gateway) GoString ¶
GoString formats the gateway like String, so %#v does not print its credentials.
func (*Gateway) Remove ¶ added in v0.4.0
Remove removes this owned gateway container. Zone configuration, S3 users, buckets and data remain available through other gateways or a replacement. Multisite period endpoints are not changed automatically. The last gateway can be removed because RGW is optional. Failed cleanup remains tracked. A gateway that Remove already removed, or that is not the one the cluster owns for its name, returns an error.
func (*Gateway) ReplaceTLS ¶ added in v0.5.0
ReplaceTLS replaces the certificate chain and private key that this gateway's native HTTPS listener serves, for a test of how the SUT meets a renewed certificate or a changed CA. Beast loads them only when the gateway starts, so ReplaceTLS installs them in the gateway container and restarts it: the gateway refuses connections while it restarts, connections established before are closed rather than moved to the new certificate, and requests in flight can fail with an unknown outcome. Only connections made afterwards see the new certificate. The restart completes when the listener presents the new leaf certificate, and every later start of the container expects it too.
In bridge mode the restarted gateway can get new mapped host ports: call S3SecureEndpoint and S3Endpoint again afterwards. In host mode it keeps its selected ports. The gateway must be running, and config must hold a valid PEM chain and its unencrypted private key; the bytes are copied. Trust is the SUT's own: ReplaceTLS changes no client configuration, so a test supplies the new CA to the SUT the way it reads its configuration. When the gateway does not stop, the previous material is put back; when it stopped and fails to start, the error is returned with the new material installed and no rollback, which would need another restart. To return to the previous certificate, call ReplaceTLS with it again; that restarts the gateway once more.
func (*Gateway) S3Endpoint ¶
S3Endpoint returns the HTTP endpoint for host S3 clients. Bridge mode uses its mapped port; host mode uses the selected daemon port. The default 127.0.0.1 address uses the Docker provider host, while a custom host address is returned directly, matching the gateway's bind address. Configure clients to use path-style addressing and the test credentials.
Sign with Gateway.Region. In bridge mode the mapped port can change whenever the gateway container restarts (placement activation of package rgw/placement, multisite sync group and zone changes, or the caller's own Stop and Start): call S3Endpoint again afterwards.
func (*Gateway) S3SecureEndpoint ¶
S3SecureEndpoint returns the native HTTPS listener's mapped or selected host endpoint. It returns an error when TLS was not configured. This method does not disable certificate verification or alter application TLS settings.
type Quota ¶
Quota uses bytes, matching modern radosgw-admin output. For each limit, -1 disables that limit; zero is an actual zero limit. Enabled controls whether the configured limits are enforced. Native RGW quota caches and asynchronous accounting can delay enforcement; reading this policy does not flush caches.
type RateLimit ¶ added in v0.5.0
RateLimit is one native RGW rate-limit policy, applied as a whole: the enabled flag and four budgets. Each budget counts requests (MaxReadOps, MaxWriteOps) or payload bytes (MaxReadBytes, MaxWriteBytes) per minute, and zero leaves that dimension unlimited; negative values are refused. GET and HEAD count as reads, every other method as a write.
Every gateway process enforces the budgets on its own, with its own counters: two gateways that serve the same user or bucket admit up to twice the budget between them. A policy is not a cluster-wide request budget.
type RateLimitOverrideHandle ¶ added in v0.5.0
type RateLimitOverrideHandle struct {
// contains filtered or unexported fields
}
RateLimitOverrideHandle manages the restoration of one rate-limit scope of an owned user, retaining the prior native policy, the identity of the scope and possibly uncertain application. Copies share restoration state.
User.OverrideRateLimit returns a non-nil handle for every outcome. A handle of a call that was refused before any native change owns nothing: its Restore returns nil and changes nothing. A handle returned with an error after the first native change records an uncertain outcome; keep it and call Restore with a fresh context, or terminate the disposable cluster.
The handle never owns a bucket: a bucket that the SUT created stays the SUT's, and the handle neither deletes it nor keeps it from being deleted. There is no expiry and no restoration at scope exit or Terminate.
func (*RateLimitOverrideHandle) Restore ¶ added in v0.5.0
func (change *RateLimitOverrideHandle) Restore(ctx context.Context) error
Restore returns the scope to the policy it had before the override, after confirming the same user and, for a bucket scope, the same bucket instance and owner. For a user that stored no policy it stores the native default, as OverrideRateLimit describes. A scope that already holds that policy needs no command. It refuses a scope whose identity changed and a policy that is neither that one nor one this override left, rather than overwriting an outside edit. It is idempotent across copies; after an uncertain failure, retry with a fresh context. A handle of a refused call returns nil.
Gateways see the restored policy after their metadata caches update; poll with new requests before relying on unthrottled access.
type RateLimitScope ¶ added in v0.5.0
type RateLimitScope struct {
Bucket string
}
RateLimitScope selects the native rate-limit scope that User.OverrideRateLimit changes. The zero value selects the user itself: the policy throttles every request that the user's credentials sign. Bucket names one existing bucket that the user natively owns, in the user's tenant, and the policy throttles every request to that bucket, whoever signs it; the user's other buckets are not affected.
The user scope needs Ceph 20 or later. A Ceph 19 gateway stores and reports a user's policy but never applies it to a request that the user's S3 keys sign, so OverrideRateLimit refuses it there; the bucket scope works on both.
type Role ¶ added in v0.5.0
type Role struct {
// contains filtered or unexported fields
}
Role is a native RGW role that CreateRole created, with the permission policies the fixture put on it. It names one native role for good: its role ID, read back after creation, so a role deleted and created again under the same name outside the fixture is a different role, which the handle refuses. Copies of a role handle share its state. Roles remain in Ceph when a gateway is removed, until Remove or the disposable cluster's termination; Remove runs through the first running registered gateway of the scope of the gateway that created the role.
The fixture creates the role and hands off its ARN; the SUT, or a test client playing it, calls STS AssumeRole and uses the temporary credentials. The gateways need STS enabled before they start (rgw_sts_key and rgw_s3_auth_use_sts, applied with override.SetConfig).
func (*Role) ARN ¶ added in v0.5.0
ARN returns the role's native ARN, read back after its creation, which the SUT passes to STS AssumeRole as RoleArn. It stays the same after Remove, so a test can hand a removed role to the SUT to check that STS refuses it. A role whose creation was not confirmed when CreateRole returned returns an error.
func (Role) Format ¶ added in v0.5.0
Format prints String for every verb and flag, so no verb, such as %d or %t, walks the fields.
func (Role) GoString ¶ added in v0.5.0
GoString formats the role like String, so %#v does not walk its state.
func (*Role) Name ¶ added in v0.5.0
Name returns the role's name, the one CreateRole generated when RoleConfig left it empty.
func (*Role) Remove ¶ added in v0.5.0
Remove deletes the fixture's permission policies of this role, with role-policy delete, and then the role, with role delete. It removes only what the fixture created: a role whose role ID, trust policy, tags or other metadata changed, that holds a permission policy the fixture did not put, or whose fixture policy changed outside the fixture, is refused with ceph.ErrInvalidRequest and left as it is. A role that native state no longer holds, and a role already removed, return nil.
A role whose creation outcome was unknown is settled first: a command of it that may still run is stopped, and the role is removed when native state holds the role the fixture requested. When a removal fails, its outcome is read back: what is gone stays removed, what is still present stays tracked, and Remove can be called again.
Removing a role does not revoke temporary credentials already issued for it in RGW's caches at once; poll with new requests.
type RoleConfig ¶ added in v0.5.0
type RoleConfig struct {
Name, Path string
TrustPolicy string
Policies []RolePolicy
}
RoleConfig describes a new native RGW role that a principal assumes with STS AssumeRole. Empty Name generates a unique name; Path defaults to "/". The role is created in the empty tenant, outside any account.
TrustPolicy is the role's assume-role policy document: which principals may assume it, such as {"Effect":"Allow","Principal":{"AWS": ["arn:aws:iam:::user/<user ID>"]},"Action":["sts:AssumeRole"]} in a statement list. Policies are the inline permission policies of the role, put in order, which bound what temporary credentials of the role may do. Documents are single-line JSON strings, stored as given.
type RolePolicy ¶ added in v0.5.0
type RolePolicy struct {
Name, Document string
}
RolePolicy is one inline permission policy of a role: its name, unique in the role, and its JSON document.
type RootAccount ¶ added in v0.5.0
type RootAccount interface {
// contains filtered or unexported methods
}
RootAccount is an owned account that UserConfig.Account names. It is sealed: only *account.Account, created by package rgw/account, satisfies it.
type S3Key ¶ added in v0.5.0
type S3Key struct {
// contains filtered or unexported fields
}
S3Key is one S3 access and secret key pair that the fixture created for an owned user: the key pair of the user's creation, from User.CreationKey, or one from User.CreateS3Key. A key handle names one key pair and never changes which: creating another key does not change what an existing handle, or credentials copied from it, mean. Copies of a key handle share its state. Formatting a key handle never includes its keys.
Creating a key or revoking one changes what RGW accepts; it does not show that the system under test reloaded its configuration or dropped a cached credential. Hand the new key to the SUT the way it reads its configuration, and assert its behavior with requests it makes after that.
func (*S3Key) Credentials ¶ added in v0.5.0
Credentials returns the access and secret keys of this key pair as explicit copies. They stay the same after the key is revoked or the user removed, so a test can hand a revoked key to the SUT to check that RGW refuses it; revocation does not erase copies. A key whose creation was not confirmed returns an error.
func (S3Key) Format ¶ added in v0.5.0
Format prints String for every verb and flag, so no verb, such as %d or %t, walks the fields.
func (S3Key) GoString ¶ added in v0.5.0
GoString formats the key like String, so %#v does not print its keys.
func (*S3Key) Revoke ¶ added in v0.5.0
Revoke removes this key pair from its user, irreversibly: RGW refuses new requests signed with it once its metadata caches see the removal, so poll with new requests. Nothing restores a revoked key; create another with User.CreateS3Key. The user, its data and its other keys stay.
Revoke refuses, with ceph.ErrInvalidRequest, the user's last active fixture-created key, which identifies the owned user to later operations, and a key whose secret changed outside the fixture. A key that native state no longer holds, a key of a removed user and a key already revoked return nil. A key whose creation outcome was unknown is settled first: a native command of it that may still run is stopped, and the key is removed when native state holds it.
When the removal fails, its outcome is read back: a key that is gone is revoked and Revoke returns nil; a key still present stays tracked and usable, and Revoke can be called again; an unknown outcome is settled by the next Revoke.
type TLSConfig ¶
type TLSConfig struct {
CertificatePEM, PrivateKeyPEM []byte
}
TLSConfig enables a native Beast HTTPS listener alongside HTTP. Supply a PEM certificate chain and matching unencrypted private key. No proxy is involved. Clients must explicitly trust its CA and use a matching hostname. Files live only in the owned RGW container; descriptors never log key bytes.
The bytes are copied; the certificate and key are written to /tc/rgw-tls.pem with mode 0600 inside the gateway container only. In bridge mode container ports 7480 (HTTP) and 7481 (HTTPS) are mapped to random host ports; in host mode two free host ports are reserved. Startup verifies that the gateway process owns the HTTPS socket and that the listener presents the configured certificate. ceph.NetworkConfig.WithMessengerMode does not enable HTTPS. Gateway.ReplaceTLS replaces the material of a running gateway.
func (TLSConfig) Format ¶ added in v0.4.0
Format prints String for every verb and flag, so no verb, such as %d or %t, walks the fields.
type User ¶
type User struct {
// contains filtered or unexported fields
}
User is an identity created through a gateway. Its S3 credentials are key handles: CreationKey for the key pair its creation generated and CreateS3Key for more; formatting this handle never includes secrets. Users remain in Ceph when a gateway is removed, until explicitly removed or the disposable cluster is terminated. Its operations run through the first running registered gateway, by name, in the scope of the gateway that created it, so they keep working after that gateway is removed if another one serves it. Copies of a user handle share its lifecycle state.
Every operation on the user checks the keys the fixture created for it: each active one must still be present with its secret, no revoked one may be present again, and at least one active one must remain. Keys created outside the fixture are neither checked nor changed.
func (*User) CreateS3Key ¶ added in v0.5.0
CreateS3Key creates one more S3 key pair for this owned user, keeping the user, its data and its other keys, so a test can hand the SUT a replacement credential and later revoke the old one with S3Key.Revoke. The fixture generates the access key and RGW the secret, and the new key is tracked as the fixture's before the native command runs. The user must be active, and its fixture-created keys must be as the fixture recorded them.
After dispatch, a read checks the outcome even if ctx ends. It keeps the admin operation deadline, with at least ten seconds for readback. The fixture sends the key creation command only once:
- a nil error returns the confirmed key;
- a non-nil key with an error is tracked: when native state showed the key, its Credentials work and the error keeps the call's failure, such as its context's; otherwise whether the key exists is unknown, Credentials refuses it, and its Revoke settles and removes it;
- a nil key with an error means that RGW shows that no key was created.
A new call always creates a different key; it does not retry an earlier one. Native key edits of this user from Admin or external clients must not race this operation.
func (*User) CreationKey ¶ added in v0.5.0
CreationKey returns the handle of the S3 key pair that this user's creation generated; nil when the creation response did not confirm one. It names that key pair even after it is revoked or after other keys were created.
func (User) Format ¶ added in v0.4.0
Format prints String for every verb and flag, so no verb, such as %d or %t, walks the fields.
func (*User) ID ¶
ID returns the canonical native ID, tenant$localID for a tenanted user. Empty-tenant identities retain their existing unprefixed IDs.
func (*User) Info ¶ added in v0.4.0
Info reads an owned user's quota, capabilities, suspension and placement defaults/tags. Placement tags control new bucket placement, not object access. It verifies the created key, original native user type and original account association remain present before returning the policy. Account roots also require the creation-owned account's native metadata lifetime to remain valid.
func (*User) OverrideRateLimit ¶ added in v0.5.0
func (u *User) OverrideRateLimit(ctx context.Context, scope RateLimitScope, limit RateLimit) (*RateLimitOverrideHandle, error)
OverrideRateLimit applies limit, as a whole, to one native rate-limit scope of this owned user and returns the handle that restores the prior policy. It binds the scope's native identity first: the user's created key, type and account association, and for a bucket scope the bucket's instance ID, marker, tenant and native owner, which must be this user. It reads the prior policy of that scope, changes it with radosgw-admin ratelimit set and enable or disable, and reads it back. Policy fields that RateLimit does not name are kept as they are. A second override of the same scope is refused while the first is not restored, even for the same policy.
A user that stores no policy of its own enforces the native default: every budget zero and disabled. Ceph 20 reports such a user's policy as that default; a Ceph 21 radosgw-admin ratelimit get fails with ENOENT instead, exactly as for a missing user. OverrideRateLimit takes the ENOENT as an unset prior policy only when the user's native metadata, read in the same call, names the user without a stored policy and the user is still the identity it created; otherwise it fails. radosgw-admin cannot delete a stored policy, so Restore of an unset prior policy stores the native default: the scope enforces what it did before, and ratelimit get then reports that default instead of failing.
The commands never pass through a policy that enforces a mix of the prior and requested budgets: limits are stored before the policy is enabled, and the policy is disabled before limits are stored.
Gateways learn the change through their metadata caches, and each gateway counts its own budget, so poll with new requests when testing rejection (503 SlowDown) or recovery after Restore. With a bucket scope, use a bucket that the SUT does not delete and create again while the handle is active.
Outcomes, as the handle it returns and the error:
- Applied and read back: real handle; nil.
- Invalid limit or bucket name: not applied handle; ceph.ErrInvalidRequest.
- User scope on a Ceph 19 cluster: not applied handle; ceph.ErrUnsupported, a *ceph.OperationError that names the release.
- Bucket not owned by this user: not applied handle; ceph.ErrInvalidRequest.
- The user is no longer the identity it created or is missing (also when a Ceph 21 ratelimit get reports ENOENT), the bucket is missing, the scope is already overridden, the context ended, or a read failed: not applied handle; the original error.
- A failure from the first native change on (command, readback, canceled context): real handle (uncertain); the original error.
func (*User) Remove ¶ added in v0.4.0
Remove removes an owned identity without purging buckets or objects. Deleting a present user requires its confirmed generated credentials. After an uncertain creation, Remove first settles the create command and checks the creation scope. Absence completes cleanup. A present identity whose creation was never confirmed stays untouched and Remove returns an error. Ceph refuses ordinary users that still own buckets; remove those through the S3 client first. Account buckets belong to the account and may outlive a root user's removal; removing the account independently refuses a nonempty one. Success is idempotent across copies of a handle. After an uncertain native failure, an absent user is accepted as completed removal; a user still present remains tracked and its fixture-created keys are verified before retrying. Removing the user removes all of its keys, so a later Revoke of one of its S3Key handles returns nil.
func (*User) SetBucketQuota ¶ added in v0.4.0
SetBucketQuota configures the per-bucket limits for all buckets owned by this user. Use Gateway.Admin for a policy on a single named bucket.
The limits apply to each bucket the user owns, individually. Quota enforcement depends on native statistics and caches, so a write right after a quota change, or right after the quota is reached, may still be accepted: poll with new writes when testing rejection.
func (*User) SetQuota ¶ added in v0.4.0
SetQuota replaces both user limits and the enabled state. If a later native command fails, a policy change may already have persisted; Info reads the authoritative state and the same request can safely be retried.
func (*User) Suspend ¶ added in v0.4.0
Suspend disables or re-enables S3 access for an owned user and reads back native state. Gateway metadata caches may delay the observed HTTP response; callers should poll new requests when testing suspension or re-enablement.
func (*User) Usage ¶ added in v0.4.0
Usage reads current storage counters for an owned user's effective native owner. For an account root it returns the account aggregate with Scope account and OwnerID equal to the originally owned account ID. It rechecks the user key, type, account lifetime and scope before returning; no user, account, bucket or statistics are created, changed, synchronized, reset or adopted.
Poll until the expected values appear. For an explicit synchronisation step run gateway.Admin(ctx, "user", "stats", "--uid", user.ID(), "--sync-stats") as separate setup.
type UserConfig ¶
type UserConfig struct {
ID, DisplayName, Email string
Tenant string
AdminCaps string
MaxBuckets *int
Account RootAccount
}
UserConfig describes a new S3 identity. Empty ID generates a unique ID; DisplayName defaults to Testcontainers. AdminCaps is an explicit native expression such as "users=read;usage=read" for the RGW Admin Ops REST API. Neither the global admin nor the multisite system flag is granted. MaxBuckets nil preserves Ceph's default; zero allows unlimited buckets and -1 forbids creating buckets. Tenant selects a native namespace; empty preserves the legacy namespace. ID is the local user ID, without a tenant prefix.
Tenant is letters, digits and underscores and must not look like an account ID; a tenant user's canonical ID is tenant$id, and buckets with the same name can exist in different tenants.
Account, when set, makes the new user the root user of that owned account, which package rgw/account created through a gateway of the same cluster and scope. Empty Tenant inherits the account tenant; a different tenant is rejected, and DisplayName must be a valid IAM user name. Account root grants permissions within the account; global admin and multisite system flags remain false. IAM operations remain on the consuming client.
type UserInfo ¶
type UserInfo struct {
ID, DisplayName, Email string
Tenant, LocalID, Namespace, Type, AccountID string
Suspended, Admin, System bool
MaxBuckets int
AdminCaps []AdminCapability
UserQuota, BucketQuota Quota
DefaultPlacement, DefaultStorageClass string
PlacementTags []string
}
UserInfo is a current native policy snapshot, deliberately excluding keys. BucketQuota applies individually to every bucket owned by this user. DefaultStorageClass preserves native representation: STANDARD on a named default placement is persisted and later read back as an empty string.
Type is rgw (or empty) for ordinary users and root for account root users. The fixture never sets Admin or System. PlacementTags allow the user to create buckets in tagged placement targets and grant no object access; package rgw/placement sets the placement default and tags.
type UserUsage ¶
type UserUsage struct {
UserID, Tenant, Scope, OwnerID string
// SizeBytes is native size; SizeActualBytes is native size_actual (rounded
// accounting bytes), not physical allocation or replica/billing bytes.
SizeBytes, SizeActualBytes, NumObjects uint64
// Preserve native timestamp strings, including native zero timestamps.
LastStatsSync, LastStatsUpdate string
}
UserUsage is a native storage-accounting snapshot, not dated request or bandwidth usage. Scope is "user" for an ordinary user and "account" for an account identity. OwnerID identifies that effective aggregation owner; account stats cover all of the account's users, roles and buckets, not only UserID. Native accounting updates asynchronously; this snapshot does not force sync, flush quota caches, prove quota enforcement or verify object content.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package account prepares native RGW accounts through an existing gateway: fresh accounts with their tenant, limits and quotas, whose root users are created by rgw.Gateway.CreateUser with rgw.UserConfig.Account.
|
Package account prepares native RGW accounts through an existing gateway: fresh accounts with their tenant, limits and quotas, whose root users are created by rgw.Gateway.CreateUser with rgw.UserConfig.Account. |
|
Package expect evaluates captured observations of RGW fixtures against the conditions a test states, and explains each mismatch.
|
Package expect evaluates captured observations of RGW fixtures against the conditions a test states, and explains each mismatch. |
|
internal
|
|
|
gwbase
Package gwbase is the foundation that package rgw and its feature packages (rgw/account, rgw/placement, rgw/notification and rgw/multisite) share for one gateway and the resources created through it: the gateway identity (its cluster, name, configured scope, listener and container), the admin command transport, the selection of the gateway that runs a resource handle's operations, the native runtime scope of a running gateway, and the private state of owned users and accounts.
|
Package gwbase is the foundation that package rgw and its feature packages (rgw/account, rgw/placement, rgw/notification and rgw/multisite) share for one gateway and the resources created through it: the gateway identity (its cluster, name, configured scope, listener and container), the admin command transport, the selection of the gateway that runs a resource handle's operations, the native runtime scope of a running gateway, and the private state of owned users and accounts. |
|
gwtest
Package gwtest holds the unit-test fixtures that the tests of package rgw and its feature packages share: the supervisor framing of radosgw-admin calls, canned native user documents, a synthetic cluster, a foundation core over a gateway container for the feature packages, which cannot construct an rgw.Gateway, and small models of the native zone, placement, period, user and account state that the typed operations read and change.
|
Package gwtest holds the unit-test fixtures that the tests of package rgw and its feature packages share: the supervisor framing of radosgw-admin calls, canned native user documents, a synthetic cluster, a foundation core over a gateway container for the feature packages, which cannot construct an rgw.Gateway, and small models of the native zone, placement, period, user and account state that the typed operations read and change. |
|
Package multisite orchestrates RGW multisite fixtures across independent Ceph clusters: one realm, zones and zonegroups, period transfer, sync status and sync policies.
|
Package multisite orchestrates RGW multisite fixtures across independent Ceph clusters: one realm, zones and zonegroups, period transfer, sync status and sync policies. |
|
Package notification observes the persistent queue of one RGW bucket notification topic through an existing gateway: the topic's native identity and delivery limits, its queue statistics and an optional bounded sample of the pending entries.
|
Package notification observes the persistent queue of one RGW bucket notification topic through an existing gateway: the topic's native identity and delivery limits, its queue statistics and an optional bounded sample of the pending entries. |
|
Package placement prepares bucket placement targets and storage classes through an existing gateway: a fresh, non-default placement target with its index, multipart and per-class data pools, its activation in a standalone gateway or a realm period, and a user's default placement.
|
Package placement prepares bucket placement targets and storage classes through an existing gateway: a fresh, non-default placement target with its index, multipart and per-class data pools, its activation in a standalone gateway or a realm period, and a user's default placement. |