allocations

package
v1.29.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

README

pkg/handler/allocations

This package records the consumption ledger checked against organization quotas.

Intent

Allocations are the usage-side of the quota system.

They record committed and reserved quantities for a referenced resource within a project context, and they are validated against the organization-wide quota envelope before being written.

So this package is not generic project-scoped CRUD. It is the ledger half of the quota/allocation subsystem.

What Is Specific Here

Project-Scoped Consumption Records

Allocations are stored in the project namespace and carry organization, project, and referenced resource identity in metadata and labels.

That makes them the per-resource consumption record that ties an abstract quota number back to an actual project-scoped object.

Serialized Capacity Decisions

Allocation create/update and quota update operations hold a per-organization Kubernetes Lease. The Lease lasts three seconds, and the holder stops writing one second before its expiry. The Lease is deleted on success, and on failure unless a write was cut off in flight; a crashed or cut-off holder delays only that organization until the first contender has observed its unchanged Lease for a full duration.

Contenders receive a retryable HTTP 409 when their request context expires; its description says that another change for the organization is in progress. A holder whose read or write is cut off by its bounded context receives the same 409; any other failure, such as a rejected request, keeps its own status. A write that was sent and then cut off may still be committed by the API server, so the holder leaves its Lease to expire instead of releasing it, and contenders wait out a full Lease duration before they read. A caller that retries a cut-off create may therefore find the first allocation was made after all. The server's request deadline (eight seconds by default, see pkg/server) leaves room for a takeover and the critical section after it, and ends early enough for Lease cleanup and the 409 or success response to be written before the write timeout.

Different organizations use different Leases and do not wait for each other. The holder checks its bounded context immediately before writing, although an API-server write sent before that deadline can still be committed after the Lease expires.

Each acquisition, critical section and release is counted by outcome on the application meter, so takeovers, abandoned writes, contenders that give up and Leases left behind are visible without logs. The instruments are listed in docs/observability.md.

This is a clear example of the handler layer implementing application-level accounting discipline on top of Kubernetes storage.

Referenced Resource Identity

Each allocation is tied to a referenced resource through kind and ID labels today.

That identity should likely converge with the shared reference model documented in ../core/pkg/manager, so allocation identity can reuse the platform's existing referenced-resource contract instead of maintaining a parallel allocation-ID linkage model.

Invariants

  • allocations are the consumption ledger checked against organization quotas
  • allocation writes must pass quota-consistency checks before being persisted
  • committed and reserved quantities are both part of the effective used total
  • allocation and quota decisions are serialized per organization

Caveats

  • Allocation identity is still weaker than it should be. The current model labels the referenced resource, but does not yet treat that reference identity as the canonical unique key.
  • Like quotas, this package is part of a best-effort accounting system built on Kubernetes objects rather than transactional storage.
  • The current model records project/resource consumption, but not project-level quota envelopes or ring-fenced budget partitions.

TODO

  • Adopt the shared core reference identity as the canonical allocation identifier so logical uniqueness is enforced naturally and owning resources do not need a parallel allocation-ID linkage.
  • Reject duplicate logical allocations for the same referenced resource until that shared-reference identity model is in place.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNamespace = goerrors.New("unable to resolve project namespace")
)

Functions

This section is empty.

Types

type Client

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

func New

func New(client client.Client, namespace string) *Client

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, organizationID ids.OrganizationID, projectID ids.ProjectID, allocationID string) error

func (*Client) Get

func (c *Client) Get(ctx context.Context, organizationID ids.OrganizationID, projectID ids.ProjectID, allocationID string) (*openapi.AllocationRead, error)

type SyncClient added in v1.12.0

type SyncClient struct {
	*Client
}

func NewSync added in v1.12.0

func NewSync(client client.Client, namespace string) *SyncClient

func (*SyncClient) Create added in v1.12.0

func (c *SyncClient) Create(ctx context.Context, organizationID ids.OrganizationID, projectID ids.ProjectID, request *openapi.AllocationWrite) (*openapi.AllocationRead, error)

func (*SyncClient) Update added in v1.12.0

func (c *SyncClient) Update(ctx context.Context, organizationID ids.OrganizationID, projectID ids.ProjectID, allocationID string, request *openapi.AllocationWrite) (*openapi.AllocationRead, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL