common

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: 34 Imported by: 10

Documentation

Index

Constants

View Source
const (

	// OrganizationLeaseReleaseTimeout bounds Lease cleanup, which may run after the
	// request deadline has passed.
	OrganizationLeaseReleaseTimeout = time.Second

	// OrganizationLeaseTakeoverBudget is the request time needed to take over a crashed
	// holder's Lease and still have the full critical section.
	OrganizationLeaseTakeoverBudget = organizationLeaseDuration + organizationLeaseBackoff*organizationLeaseRetry + organizationLeaseDuration - organizationLeaseMargin
)

Variables

View Source
var (
	ErrLeaseDeadline = goerrors.New("organization allocation lease deadline passed")
	ErrLeaseMargin   = goerrors.New("organization lease duration and margin leave no critical section")
)

Functions

func AllowGroupMembershipAddition added in v1.19.2

func AllowGroupMembershipAddition(ctx context.Context, cli client.Client, namespace string, organizationID ids.OrganizationID, group *unikornv1.Group) error

AllowGroupMembershipAddition returns nil if the calling principal may add a member to the given group. Adding a member confers the group's roles, so the caller must be able to grant every role the group carries.

A role reference that does not resolve refuses the addition rather than being skipped. Role IDs are derived from the role name, so a role that is deleted and later re-applied comes back with the same ID and immediately re-binds to every group still referencing it; a member added during the gap would then hold a role nobody was ever asked to grant, and for a service account that authority rides a long-lived token. Refusing also keeps this consistent with ACL construction, which treats the same dangling reference as a consistency failure rather than an empty permission set.

Only additions go through here. Removing a member, and deleting a principal (which strips its memberships as cleanup), take authority away rather than handing it out, so neither is gated. Dropping a dangling role from a group is likewise allowed — role removals are not grant-checked at all, as validateRoleIDs in pkg/handler/groups explains. The asymmetry is deliberate: skipping an unresolvable role errs towards less authority on a removal and towards more on an addition, so only the removal side is safe to skip.

func IdentityMetadataMutator added in v1.4.0

func IdentityMetadataMutator(required, current metav1.Object) error

IdentityMetadataMutator is called on an update and preserves identity information.

func Normalise added in v1.21.0

func Normalise(quota *unikornv1.Quota, metadata []unikornv1.QuotaMetadata) ([]unikornv1.ResourceQuota, error)

Normalise returns a new quota list that holds every kind in metadata, in metadata order. It takes the quantity from quota when quota has the kind. Otherwise it takes the metadata default. It drops retired kinds. quota can be nil, which means a virtual quota. The quantity pointers in the list point into the inputs, so callers must not change them. A nil quantity is a data fault and returns an error.

func ProjectNamespace added in v1.5.0

func ProjectNamespace(ctx context.Context, cli client.Client, organizationID ids.OrganizationID, projectID ids.ProjectID) (*corev1.Namespace, error)

ProjectNamespace is shared by higher order services.

func ReleaseOrganizationLease added in v1.26.0

func ReleaseOrganizationLease(ctx context.Context, lease *OrganizationLease)

ReleaseOrganizationLease keeps cleanup bounded after the request has ended.

func RoleDisplayName added in v1.19.2

func RoleDisplayName(role *unikornv1.Role) string

RoleDisplayName returns the name a caller knows a role by, for use in errors that have to say which role blocked a write. Roles are stored under a generated ID, so the human name lives in a label; fall back to the ID when the label is absent.

func SetIdentityMetadata added in v1.4.0

func SetIdentityMetadata(ctx context.Context, meta *metav1.ObjectMeta) error

SetIdentityMetadata sets identity specific metadata on a resource during generation.

This sets attribution only (creator and principal scope). For resources that also carry placement labels prefer SetIdentityMetadataOrganizationScope or SetIdentityMetadataProjectScope, which set the placement organization/project from typed IDs in the same call.

func SetIdentityMetadataOrganizationScope added in v1.17.7

func SetIdentityMetadataOrganizationScope(ctx context.Context, meta *metav1.ObjectMeta, organizationID ids.OrganizationID) error

SetIdentityMetadataOrganizationScope stamps the organization placement label from a typed ID and then sets the identity attribution metadata (see SetIdentityMetadata).

Prefer this over conversion.NewObjectMetadata(...).WithOrganization(organizationID.String()): core's builder is necessarily string-based (core cannot import pkg/ids without a circular dependency), so calling it forces a .String() at the call site. This keeps the typed ID to the lowest layer and stamps placement plus attribution scope in a single call.

func SetIdentityMetadataProjectScope added in v1.17.7

func SetIdentityMetadataProjectScope(ctx context.Context, meta *metav1.ObjectMeta, organizationID ids.OrganizationID, projectID ids.ProjectID) error

SetIdentityMetadataProjectScope stamps the organization and project placement labels from typed IDs and then sets the identity attribution metadata (see SetIdentityMetadata).

Prefer this over conversion.NewObjectMetadata(...).WithOrganization(...).WithProject(...) for the same reason as SetIdentityMetadataOrganizationScope: it keeps the typed IDs to the lowest layer rather than forcing .String() at the call site.

func ValidateGroupsExist added in v1.20.0

func ValidateGroupsExist(groupIDs []string, groups *unikornv1.GroupList) error

ValidateGroupsExist returns an error naming the first requested group that is not in the organization's group list.

Membership reconciliation walks the groups that exist and asks of each whether the request names it, so a requested ID matching nothing matches no branch: without this the principal is neither joined to it nor told, and the response reports only the memberships that did apply.

func WithOrganizationLease added in v1.26.0

func WithOrganizationLease[T any](ctx context.Context, cli client.Client, namespace string, organizationID ids.OrganizationID, fn func(ctx context.Context, lease *OrganizationLease) (T, error), options ...LeaseOption) (T, error)

WithOrganizationLease runs fn under the organization Lease with the bounded context and reports a call cut off by the deadline as a retryable conflict. It releases the Lease afterwards, unless the cut-off call may have been the write itself, in which case the Lease is left to expire.

Types

type Client

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

Client wraps up control plane related management handling.

func New

func New(client client.Client) *Client

New returns a new client with required parameters.

func (*Client) CheckQuotaConsistency

func (c *Client) CheckQuotaConsistency(ctx context.Context, organizationID ids.OrganizationID, quota *unikornv1.Quota, allocation *unikornv1.Allocation) error

CheckQuotaConsistency by default loads up the organization's quota and all allocations and checks that the total of alloocations does not exceed the quota. If you pass in a quota argument, i.e. when updating the quotas, this will override the read from the organization. If you pass in an allocation, i.e. when creating or updating an allocation, this will be unioned with the organization's allocations, overriding an existing one if it exists.

func (*Client) GetAllocations

func (c *Client) GetAllocations(ctx context.Context, organizationID ids.OrganizationID) (*unikornv1.AllocationList, error)

func (*Client) GetQuota

func (c *Client) GetQuota(ctx context.Context, organizationID ids.OrganizationID) (*unikornv1.Quota, bool, error)

func (*Client) ProjectNamespace

func (c *Client) ProjectNamespace(ctx context.Context, organizationID ids.OrganizationID, projectID ids.ProjectID) (*corev1.Namespace, error)

type IssuerValue added in v1.11.0

type IssuerValue struct {
	// URL is the OAuth2/OIDC issuer URL (e.g., "https://identity.example.com")
	// This is used when minting tokens and populating subject records.
	URL string
	// Hostname is just the hostname part (e.g., "identity.example.com")
	// This is used for audience claims and other non-issuer uses.
	Hostname string
}

IssuerValue is a value that can be used with pflag.Var, so as to set an issuer URL and hostname with the same argument.

func (*IssuerValue) Set added in v1.11.0

func (v *IssuerValue) Set(value string) error

func (*IssuerValue) String added in v1.11.0

func (v *IssuerValue) String() string

func (*IssuerValue) Type added in v1.11.0

func (*IssuerValue) Type() string

type LeaseOption added in v1.26.0

type LeaseOption func(*leaseOptions)

type OrganizationLease added in v1.26.0

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

OrganizationLease serializes quota and allocation decisions for one organization.

func AcquireOrganizationLease added in v1.26.0

func AcquireOrganizationLease(ctx context.Context, cli client.Client, namespace string, organizationID ids.OrganizationID, options ...LeaseOption) (*OrganizationLease, context.Context, error)

AcquireOrganizationLease waits for the organization Lease, then returns a context whose deadline leaves time to abandon an overdue write.

func (*OrganizationLease) Check added in v1.26.0

func (l *OrganizationLease) Check(ctx context.Context) error

Check rejects a write once the holder's critical-section deadline has passed, and otherwise records that a write may now be in flight.

func (*OrganizationLease) Error added in v1.26.0

func (l *OrganizationLease) Error(ctx context.Context, err error) error

Error reports a failure inside the critical section. A call cut off by the critical-section deadline is the same retryable conflict as waiting too long for the Lease, whatever status the caller wrapped it in. Any other failure, such as a rejected request, is reported as it is.

func (*OrganizationLease) Release added in v1.26.0

func (l *OrganizationLease) Release(ctx context.Context) error

Release deletes the Lease only if it has not been taken over.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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