ebss3

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package ebss3 implements site-local cache generations with EBS snapshots and S3 state.

Index

Constants

View Source 
const (
	IAMCreateVolume      = "ec2:CreateVolume"
	IAMDeleteVolume      = "ec2:DeleteVolume"
	IAMDescribeVolumes   = "ec2:DescribeVolumes"
	IAMCreateSnapshot    = "ec2:CreateSnapshot"
	IAMDeleteSnapshot    = "ec2:DeleteSnapshot"
	IAMDescribeSnapshots = "ec2:DescribeSnapshots"

	IAMS3GetObject  = "s3:GetObject"
	IAMS3PutObject  = "s3:PutObject"
	IAMS3ListBucket = "s3:ListBucket"

	// KMS actions an EBS volume encrypted with a customer-managed key requires.
	// EBS uses grants: CreateGrant lets the EC2 service decrypt the volume for the
	// instance, and the data-key actions cover attach/detach of an encrypted disk.
	IAMKMSCreateGrant     = "kms:CreateGrant"
	IAMKMSDescribeKey     = "kms:DescribeKey"
	IAMKMSGenerateDataKey = "kms:GenerateDataKeyWithoutPlaintext"
	IAMKMSReEncrypt       = "kms:ReEncrypt*"
	IAMKMSDecrypt         = "kms:Decrypt"
)

IAM action names for the cache storage operations this package performs, kept beside the code that performs them. internal/awspolicy imports these and assembles the node's IAM policy; a drift test pins the result.

The delete actions are separated from the rest because they are the ones a bundled policy scopes with a tag condition (below): a node may create and read volumes freely, but may delete only what billet owns.

View Source 
const (
	OwnerTagKey      = ownerTag
	CacheOwnerTagKey = cacheOwnerTag
)

OwnerTagKey and CacheOwnerTagKey are the resource tags billet stamps on the EBS volumes and snapshots it owns. A bundled IAM policy conditions the delete actions on these so the node's role can remove only billet's own cache resources — billet rechecks the same tags in code, and IAM is the account-level backstop if state is corrupted or a future caller supplies the wrong id.

Variables

This section is empty.

Functions

func KMSCryptoIAMActions 

func KMSCryptoIAMActions() []string

KMSCryptoIAMActions are the direct-use permissions on a customer-managed EBS key. A bundled policy scopes them to the one key ARN and conditions them on kms:ViaService for EC2, so the key can be used only through EBS and not called directly by a compromised node role.

func KMSGrantIAMActions 

func KMSGrantIAMActions() []string

KMSGrantIAMActions is CreateGrant, which EBS uses to let the EC2 service decrypt the volume for the instance. A bundled policy conditions it on kms:GrantIsForAWSResource so the role can create grants only for AWS services, not delegate the key to an arbitrary principal.

func S3ListIAMActions 

func S3ListIAMActions() []string

S3ListIAMActions are the bucket-level permissions, scoped by prefix in the assembled statement's condition.

func S3ObjectIAMActions 

func S3ObjectIAMActions() []string

S3ObjectIAMActions are the per-object permissions the cache needs on its prefix.

func SnapshotCreateIAMActions 

func SnapshotCreateIAMActions() []string

SnapshotCreateIAMActions is CreateSnapshot, which a bundled policy conditions on the owner tag present in BOTH the request (the new snapshot) and on the resource (the source volume): billet always snapshots one of its own tagged volumes, so the source condition does not deny it and it stops the role from copying a foreign volume into a billet-tagged snapshot.

func StorageDeleteIAMActions 

func StorageDeleteIAMActions() []string

StorageDeleteIAMActions are the destructive EBS permissions a bundled policy scopes with the owner-tag condition on the RESOURCE.

func StorageDescribeIAMActions 

func StorageDescribeIAMActions() []string

StorageDescribeIAMActions are the read-only EBS describes, which act on "*".

func VolumeCreateIAMActions 

func VolumeCreateIAMActions() []string

VolumeCreateIAMActions is CreateVolume, which a bundled policy grants TWICE: once on "*" conditioned on the owner tag being PRESENT IN THE REQUEST (aws:RequestTag, the new volume), and once on the account-less snapshot ARN conditioned on the owner tag ON THE RESOURCE, because a clone authorizes its source snapshot as well as the volume it creates — measured, a policy with only the first statement refuses every clone. Two statements rather than one, since a request-tag condition cannot be satisfied in the snapshot's authorization and a resource-tag condition would deny a fresh volume.

Types

type CredentialSource 

type CredentialSource = awscreds.Source

CredentialSource supplies the temporary or static credential used for both EBS and S3. Implementations must redact their own diagnostic rendering.

AN ALIAS FOR awscreds.Source. It was a declaration, and so were the identically shaped ones in internal/archivestore and internal/provider/codebuild, because the chain lived inside internal/provider/ec2 and a store may not import a compute backend. Four names for one method, bridged by a conversion closure at every call site. The chain is a shared package now, and a store may import it.

type PurgeReport 

type PurgeReport struct {
	Snapshots      int
	Volumes        int
	StateObjects   int
	SkippedForeign int
}

PurgeReport counts what Purge removed.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store owns EBS cache snapshots and their strongly consistent S3 state objects.

func New 

func New(cfg config.EBSS3Config, owner string, credentials CredentialSource) (*Store, error)

New constructs the AWS cache store for one deployment and site.

func (Store) AcquireWriter 

func (s Store) AcquireWriter(
	ctx context.Context,
	key, holder string,
	ttl time.Duration,
) (storecontract.WriterLease, storecontract.FencingToken, error)

AcquireWriter conditionally records a newer lease and fencing token in S3.

func (Store) CheckAccess 

func (s Store) CheckAccess(ctx context.Context) error

CheckAccess probes the cache bucket with a GET under the owner's own state prefix — the path the node's policy actually grants. The VERDICT IS NOT BINARY, and the caller must not treat every error as broken: S3 answers 404 for a missing key only when the caller holds s3:ListBucket on the bucket, and billet's minimal policy conditions that grant on s3:prefix — a context key a GetObject request does not carry — so under exactly the generated policy a healthy miss can answer 403. The caller classifies 403 as inconclusive; everything else here is a real answer about the bucket.

AND A 404 IS A HEALTHY MISS ONLY WHEN S3 SAYS NoSuchKey. A bucket that does not exist answers 404 as well, and this probe used to print that a bucket billet had never reached "answers under this deployment's prefix". It is a refusal now, and it is the one place a misaddressed bucket is caught before a job runs.

func (Store) Clone 

func (s Store) Clone(
	ctx context.Context,
	key, generation string,
) (storecontract.Volume, error)

Clone allocates a writable EBS volume from a published snapshot.

func (Store) Create 

func (s Store) Create(
	ctx context.Context,
	key string,
	sizeBytes int64,
) (storecontract.Volume, error)

Create allocates a new encrypted, unformatted EBS volume.

func (Store) Current 

func (s Store) Current(ctx context.Context, key string) (string, error)

Current reports the generation named by a key's S3 state object.

func (Store) Discard 

func (s Store) Discard(ctx context.Context, volume storecontract.Volume) error

Discard deletes a writable EBS volume and then releases its active lease.

func (Store) Evict 

func (s Store) Evict(ctx context.Context, olderThan time.Duration) error

Evict removes inactive generations and abandoned candidates without touching live clones.

func (Store) Format 

func (s Store) Format(f fmt.State, _ rune)

Format keeps the credential-bearing API implementations behind the store out of every fmt verb.

func (Store) GoString 

func (s Store) GoString() string

GoString covers %#v.

func (Store) LogValue 

func (s Store) LogValue() slog.Value

LogValue is the redaction boundary used by slog.

func (Store) MarshalJSON 

func (s Store) MarshalJSON() ([]byte, error)

MarshalJSON keeps structural serializers from reaching the API implementations.

func (Store) Match 

func (s Store) Match(
	ctx context.Context,
	exact string,
	restorePrefixes []string,
) (string, string, error)

Match finds the exact key or the newest pointer under the first restore prefix.

func (Store) PublishCAS 

func (s Store) PublishCAS(
	ctx context.Context,
	key, expected string,
	candidate storecontract.Candidate,
	lease storecontract.WriterLease,
	fence storecontract.FencingToken,
) error

PublishCAS advances a pointer in the same conditional S3 write that consumes its writer.

func (Store) Purge 

func (s Store) Purge(ctx context.Context) (PurgeReport, error)

Purge removes every cache resource this store owns — snapshots, available volumes, and the S3 state index — for a full deployment teardown (billet decommission, before `terraform destroy`). It is NOT eviction: it ignores retention and age and takes everything.

It REFUSES while any state object records a LIVE active-clone lease, because that means billet still believes a job holds a clone — stop the node so compute drains first. A resource another deployment owns (one that shares this cache-owner tag but not this deployment-owner tag) is skipped, never deleted, the same as the orphan sweep.

func (Store) ReleaseWriter 

func (s Store) ReleaseWriter(
	ctx context.Context,
	lease storecontract.WriterLease,
	fence storecontract.FencingToken,
) error

ReleaseWriter clears exactly the recorded writer it is handed and nothing else.

func (Store) RenewActive 

func (s Store) RenewActive(
	ctx context.Context,
	volume storecontract.Volume,
	until time.Time,
) error

RenewActive extends a generation's eviction protection.

func (Store) Snapshot 

func (s Store) Snapshot(
	ctx context.Context,
	volume storecontract.Volume,
) (storecontract.Candidate, error)

Snapshot consumes a detached EBS volume and records its immutable candidate.

func (Store) String 

func (s Store) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.