metering

type Billing ¶ added in v0.2.34

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

Billing holds what the seam needs: discovery for the deployment's URL and token, and the kcp-admin client into the metering workspace for reads.

func NewBilling(d Installed, store dynamic.Interface, logger klog.Logger) *Billing

func (b *Billing) Checkout(ctx context.Context, org, plan, successURL, cancelURL string) (string, error)

func (b *Billing) CheckoutQuoted(ctx context.Context, org, plan, expectedPrice, successURL, cancelURL string) (string, error)

func (b *Billing) ForwardWebhook(w http.ResponseWriter, r *http.Request)

func (b *Billing) Portal(ctx context.Context, org, returnURL string) (string, error)

func (b *Billing) Summary(ctx context.Context, org string) (OrgBilling, error)

type BillingError ¶ added in v0.2.34

type BillingError struct {
	Status  int
	Message string
}

BillingError carries the deployment's answer (or the seam's refusal) to the REST caller with its status.

func (e *BillingError) Error() string

type Discovery ¶

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

Discovery polls the metering workspace for the published objects.

func NewDiscovery(base *rest.Config, workspace string, logger klog.Logger) (*Discovery, error)

func (d *Discovery) Current() (Endpoints, bool)

func (d *Discovery) Installed() (installed, known bool)

func (d *Discovery) Refresh(ctx context.Context) (Endpoints, bool)

func (d *Discovery) Run(ctx context.Context)

type Endpoints ¶

type Endpoints struct {
	PortalURL  string `json:"portalURL"`
	WebhookURL string `json:"webhookURL,omitempty"`
	AuditURL   string `json:"auditURL,omitempty"`
	Version    string `json:"version,omitempty"`
	Workspace  string `json:"workspace"`
	// contains filtered or unexported fields
}

Endpoints is what the hub learned about the deployment.

type EntitlementUpdate ¶

type EntitlementUpdate struct {
	Plan      string  `json:"plan"`
	Overrides []Limit `json:"overrides"`
}

EntitlementUpdate is the body of PUT .../entitlements/{name}.

type Handler ¶

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

Handler serves the admin-area view of metering. Mount it under the admin subrouter: the gate is the caller's.

func NewHandler(d *Discovery) *Handler

func (h *Handler) Register(r *mux.Router)

func (h *Handler) WithWriter(w *Writer) *Handler

type Installed ¶

type Installed interface {
	Current() (Endpoints, bool)
}

Installed answers whether metering is discovered; Discovery implements it and tests substitute a constant.

type Limit ¶

type Limit struct {
	Meter   string `json:"meter"`
	Shape   string `json:"shape,omitempty"`
	Enforce string `json:"enforce"`
	Max     string `json:"max,omitempty"`
}

Limit is one per-meter row, the wire shape of contrib-metering's PlanLimit.

type OrgBilling ¶ added in v0.2.34

type OrgBilling struct {
	// Installed is whether metering is discovered at all; without it there
	// are no plans, limits or usage to show.
	Installed bool `json:"installed"`
	// Enabled is whether the deployment sells plans: Checkout and the
	// Customer Portal are available.
	Enabled bool `json:"enabled"`
	// Livemode is false when the deployment runs its provider's test
	// environment.
	Livemode    bool   `json:"livemode"`
	DefaultPlan string `json:"defaultPlan,omitempty"`
	// Plan is the organization's current plan (its Entitlement's spec.plan;
	// the default plan until the Entitlement exists).
	Plan            string `json:"plan,omitempty"`
	PlanDisplayName string `json:"planDisplayName,omitempty"`
	// ManagedBy is who set the plan: "billing" (a subscription), "operator"
	// (a platform admin), empty for the default plan.
	ManagedBy string  `json:"managedBy,omitempty"`
	Limits    []Limit `json:"limits"`
	// Overrides persist across plan changes. Expose their declaration even
	// when equal to the current plan's allowance: effective limits alone do
	// not reveal whether a different plan would change the allowance.
	// The empty list confirms that no overrides apply.
	Overrides     []Limit           `json:"overrides"`
	Usage         map[string]string `json:"usage"`
	Window        *UsageWindow      `json:"window,omitempty"`
	OverSoftLimit bool              `json:"overSoftLimit"`
	OverHardLimit bool              `json:"overHardLimit"`
	// Subscription is the provider's view, when the deployment has synced
	// one.
	Subscription *OrgSubscription `json:"subscription,omitempty"`
	Plans        []PlanOffer      `json:"plans"`
}

OrgBilling is GET /api/orgs/{org}/billing: the organization's plan and what it buys, what it uses, the subscription behind it, and the plans on offer.

type OrgSubscription ¶ added in v0.2.34

type OrgSubscription struct {
	EntitledPlan      string `json:"entitledPlan,omitempty"`
	Status            string `json:"status,omitempty"`
	CurrentPeriodEnd  string `json:"currentPeriodEnd,omitempty"`
	CancelAtPeriodEnd bool   `json:"cancelAtPeriodEnd"`
	SyncedAt          string `json:"syncedAt,omitempty"`
}

OrgSubscription is Entitlement.status.billing as the portal shows it.

type OrganizationOptions ¶

type OrganizationOptions struct {
	// Discovery gates the work: no metering, nothing is written.
	Discovery Installed
	// Metering is a client scoped to the metering workspace.
	Metering dynamic.Interface
	// Workspaces returns a client scoped to a kcp workspace path, for reading
	// an organization's Workspace objects.
	Workspaces func(path string) (dynamic.Interface, error)
	// DefaultPlan is the Plan an organization's Entitlement names while
	// Organization.spec.plan is empty.
	DefaultPlan string
	Logger      klog.Logger
}

OrganizationOptions configures the reconciler.

type OrganizationReconciler ¶

type OrganizationReconciler struct {
	client.Client
	// contains filtered or unexported fields
}

OrganizationReconciler gives every Organization its own billing objects in the metering workspace: an Account and a MembershipReport the hub owns and keeps current, and an Entitlement whose plan follows Organization.spec.plan (the default plan while that is empty). The Entitlement is otherwise left alone: its overrides, and a plan an admin set on it directly, are never reset by a resync. When an Organization is gone, its three objects go too.

One account per organization is the design (docs/organizations.md O-5): the organization is the tenancy boundary everywhere else in the hub and so is the billing unit too. How many free organizations one person may hold is a cap the hub applies when an organization is created, not something metering attributes to a user.

func (r *OrganizationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

type PlanOffer ¶ added in v0.2.34

type PlanOffer struct {
	Name        string             `json:"name"`
	DisplayName string             `json:"displayName,omitempty"`
	Sellable    bool               `json:"sellable"`
	Current     bool               `json:"current"`
	Limits      []Limit            `json:"limits"`
	Price       *SubscriptionPrice `json:"price,omitempty"`
}

PlanOffer is one plan: its limits, whether the deployment sells it, and whether the organization is on it.

type PlanUpdate ¶

type PlanUpdate struct {
	DisplayName string  `json:"displayName"`
	Limits      []Limit `json:"limits"`
}

PlanUpdate is the body of PUT .../plans/{name}; the plan is created when it does not exist yet.

type ProviderGetter ¶

type ProviderGetter interface {
	Get(ctx context.Context, clusterName multicluster.ClusterName, key types.NamespacedName) (*adminv1alpha1.Provider, error)
}

ProviderGetter reads one Provider from the cluster the request names; the multicluster manager implements it and tests substitute a map.

type ProviderOptions ¶

type ProviderOptions struct {
	// Discovery is the feature gate: until metering's init has published its
	// endpoints in the metering workspace, no provider workspace is touched.
	Discovery Installed
	// Providers reads Provider objects; defaults to the manager's clients.
	Providers ProviderGetter
	// Workspaces returns a client scoped to a kcp workspace path, for the
	// APIBinding in each provider's workspace.
	Workspaces func(path string) (dynamic.Interface, error)
	Logger     klog.Logger
}

ProviderOptions configures the reconciler.

type ProviderReconciler ¶

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

ProviderReconciler binds metering's provider export into every platform provider workspace once metering is installed. The binding is what lets a provider emit UsageRecords (docs/usage-contract.md in contrib-metering): metering's controller engages any workspace that binds the export, so the binding is the whole wiring. The reconciler is additive. It never removes a binding, because kcp refuses to delete one while bound objects remain and the records in a provider workspace are its usage history.

func (r *ProviderReconciler) Reconcile(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error)

type SubscriptionPrice ¶ added in v0.2.43

type SubscriptionPrice struct {
	ID            string `json:"id"`
	Amount        string `json:"amount"`
	Currency      string `json:"currency"`
	Interval      string `json:"interval"`
	IntervalCount int64  `json:"intervalCount"`
	TaxBehavior   string `json:"taxBehavior,omitempty"`
}

SubscriptionPrice is supplied by the metering billing provider, never by a hub-authored price label. Amount is a decimal in major currency units.

type UsageWindow ¶ added in v0.2.34

type UsageWindow struct {
	Start string `json:"start"`
	End   string `json:"end"`
}

UsageWindow is the window the usage values cover.

type WorkspaceNotifier ¶ added in v0.2.34

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

WorkspaceNotifier tells the organization reconciler that an organization's child workspaces changed, from any replica. The hub serves workspace creates and runs the soft-delete cascade on whichever replica holds the request or the lease, but reconciles metering membership on the leader only, so an in-process signal is lost whenever those differ. Notify instead stamps WorkspacesChangedAnnotation on the Organization; the leader's watch on Organizations turns that into a reconcile. A failed stamp is logged, not returned: the periodic re-list covers it.

The REST workspace create and the soft-delete workspace cascade call it. The organization bootstrap controller, which creates an organization's first workspace, does not: it writes the Organization's status in the same reconcile, and a stamp there would make that write conflict on every pass. Its status update re-enqueues this reconciler anyway.

func NewWorkspaceNotifier(users dynamic.Interface, logger klog.Logger) *WorkspaceNotifier

func (n *WorkspaceNotifier) Notify(ctx context.Context, orgUUID string)

type Writer ¶

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

Writer performs the admin writes against the metering workspace.

func NewWriter(client dynamic.Interface, defaultPlan string, caller func(context.Context) string, logger logr.Logger) *Writer

func (wr *Writer) ArchivePlan(ctx context.Context, name string) error

func (wr *Writer) PutPlan(ctx context.Context, name string, body PlanUpdate) (*unstructured.Unstructured, bool, error)

func (wr *Writer) UpdateEntitlement(ctx context.Context, name string, body EntitlementUpdate) (*unstructured.Unstructured, error)