models

package
v0.55.0 Latest Latest
Warning

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

Go to latest
Published: Sep 14, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// InitScriptDir is the workspace directory the provisioner writes init
	// script files into and k8shelld reads them from.
	InitScriptDir = "/usr/local/k8shell/system"

	// BlueprintFilePath is where the composed blueprint is mounted in the
	// workspace. It is authoritative for init script behavior.
	BlueprintFilePath = "/etc/k8shell/blueprint.yaml"
)

Init script delivery contract between the provisioner and k8shelld.

The provisioner materializes every blueprint InitScript as an executable file in the workspace's system directory (InitScriptDir), named by InitScriptFileName. k8shelld discovers those files, sorts them lexically (the zero-padded ordinal makes lexical order match blueprint order) and executes them in order.

The file name is only a delivery and correlation key. Behavior — whether a script re-runs on every start (InitScript.Always), and anything added later — is read from the blueprint itself (mounted at BlueprintFilePath), which is the single source of truth. k8shelld maps a file back to its InitScript with ParseInitScriptFileName: the ordinal is the join key (1-based, matching the order of Blueprint.InitScripts); the trailing name is human-readable only.

View Source
const WORKSPACE_PORT = 2822 // port that workspace containers listen on for grpc connections

Variables

View Source
var ErrActiveSessionNotFound = errors.New("active session not found")
View Source
var ErrAlreadyOnboarded = errors.New("user already onboarded")
View Source
var ErrInvalidParameters = errors.New("invalid parameters")

ErrInvalidParameters is returned when the provided parameters are invalid

View Source
var ErrMethodNotSupported = errors.New("method not supported")
View Source
var ErrOnboardingPending = errors.New("onboarding pending")
View Source
var ErrSessionNotFound = errors.New("session not found")
View Source
var ErrUserIsNotValid = errors.New("user is not valid")
View Source
var ErrUserNotAllowedOnboard = errors.New("user not allowed to onboard")
View Source
var ErrUserNotFound = errors.New("user not found")
View Source
var ErrUserNotOnboarded = errors.New("user not onboarded")
View Source
var ErrUserTokenNotSupported = errors.New("user token not supported by provider")
View Source
var ErrWorkspaceNotFound = errors.New("workspace not found")

ErrWorkspaceNotFound is returned when a workspace is not found

Functions

func BlueprintJSONSchema added in v0.48.0

func BlueprintJSONSchema() *jsonschema.Schema

BlueprintJSONSchema returns the JSON Schema describing the shape of a blueprint's YAML/JSON representation, as returned by k8shelld's GetBlueprint RPC. It's generated by reflecting over Blueprint's json tags so it always mirrors the field names that representation actually uses.

func InitScriptFileName added in v0.49.0

func InitScriptFileName(index int, name string) string

InitScriptFileName returns the file name for the init script at the given zero-based position in Blueprint.InitScripts. name is expected to already satisfy the "plainhostname" constraint enforced on InitScript.Name.

func ParseInitScriptFileName added in v0.49.0

func ParseInitScriptFileName(filename string) (index int, name string, ok bool)

ParseInitScriptFileName is the inverse of InitScriptFileName. It reports whether filename names an init script file and, if so, returns its zero-based index into Blueprint.InitScripts and the trailing name. filename may be a full path; only its final element is inspected.

Types

type AccessToken

type AccessToken struct {
	ID           int64
	Username     string
	Name         string
	Scopes       []string
	ExpiresAt    *time.Time
	CreatedAt    time.Time
	LastUsedAt   *time.Time
	IsActive     bool
	TokenPreview *string
}

AccessToken is a Personal Access Token (PAT) tied to a user. It carries an explicit scopes list that caps what actions the token may perform. The raw token value is never stored here; only the DB layer holds the hash.

type AccessTokenCreateRequest added in v0.34.0

type AccessTokenCreateRequest struct {
	Name      string   `json:"name"`
	Scopes    []string `json:"scopes"`
	ExpiresAt *string  `json:"expires_at,omitempty"` // RFC3339, omit for non-expiring
	Renew     bool     `json:"renew,omitempty"`
	Active    *bool    `json:"active,omitempty"`
}

AccessTokenCreateRequest is the HTTP request body for POST /users/{username}/tokens (and /me/tokens), which issues a new Personal Access Token for a user. Name and Scopes are required. Renew, when true, rotates an existing active token with the same name in place instead of creating a new one. Active, when set to false, creates the token disabled. Note: proto counterpart is identityv1.CreateAccessTokenRequest.

type AccessTokenCreated added in v0.34.0

type AccessTokenCreated struct {
	ID    int64  `json:"id"`
	Token string `json:"token"`
}

AccessTokenCreated is the HTTP response body for POST /users/{username}/tokens (and /me/tokens). Token is the raw secret value; it is returned exactly once and cannot be retrieved again. Note: proto counterpart is identityv1.CreateAccessTokenResponse.

type AccessTokenUpdateRequest added in v0.34.0

type AccessTokenUpdateRequest struct {
	Active *bool     `json:"active,omitempty"`
	Scopes *[]string `json:"scopes,omitempty"`
}

AccessTokenUpdateRequest is the HTTP request body for PATCH /users/{username}/tokens/{id} (and /me/tokens/{id}), which partially updates an access token's active state and/or scopes. Only non-nil fields are applied (PATCH semantics); name and expiry are immutable after creation. Scopes set to a non-nil, possibly-empty slice replaces the token's scopes; a nil Scopes leaves them unchanged. Note: proto counterpart is identityv1.UpdateAccessTokenRequest.

type AppSpec

type AppSpec struct {
	Name              string        `yaml:"name" json:"name" validate:"required_if=Enabled true"`
	Enabled           bool          `yaml:"enabled" json:"enabled" default:"false"`
	Binary            string        `yaml:"binary" json:"binary" validate:"required_if=Enabled true"`
	VersionCmd        []string      `yaml:"versionCmd,omitempty" json:"versionCmd,omitempty"`
	VersionRegex      string        `yaml:"versionRegex,omitempty" json:"versionRegex,omitempty"`
	Install           string        `yaml:"install,omitempty" json:"install,omitempty"`
	Start             []string      `yaml:"start" json:"start" validate:"required_if=Enabled true"`
	Listen            int           `yaml:"listen,omitempty" json:"listen,omitempty"`
	RestartPolicy     string        `` /* 154-byte string literal not displayed */
	MaxRestartBackoff time.Duration `yaml:"maxRestartBackoff,omitempty" json:"maxRestartBackoff,omitempty"`
	InstallAsRoot     bool          `yaml:"installAsRoot,omitempty" json:"installAsRoot,omitempty" default:"false"`
	AutoStart         bool          `yaml:"autoStart,omitempty" json:"autoStart,omitempty" default:"false"`
	Protocol          string        `` /* 173-byte string literal not displayed */
}

type AuditRecord added in v0.39.0

type AuditRecord struct {
	ID         int64     `json:"id"`
	ReqID      string    `json:"reqId"`
	OccurredAt time.Time `json:"occurredAt"`

	Package string `json:"package"`
	Action  string `json:"action"`

	// Scope is the compound "domain:action[:qualifier]" display form of
	// Action — e.g. "user:auth:ssh" — the same convention
	// authz.CapabilityCheck.Action uses. Equal to Action for actions with no
	// qualifier. Display/audit convenience only; never used for policy
	// routing or PAT scope matching, both of which stay keyed on Action.
	Scope string `json:"scope,omitempty"`

	Username string   `json:"username"`
	Roles    []string `json:"roles"`
	Org      string   `json:"org"`

	// PATPreview is the display prefix of the Personal Access Token
	// exchanged for the caller's JWT, when the request came in that way.
	PATPreview string `json:"patPreview,omitempty"`

	ResourceType       string            `json:"resourceType"`
	ResourceID         string            `json:"resourceId"`
	ResourceOwner      string            `json:"resourceOwner,omitempty"`
	ResourceAttributes map[string]string `json:"resourceAttributes,omitempty"`

	// Context carries ambient attributes not present in the JWT or resource —
	// the same map passed to Evaluate/BatchEvaluate as EvaluateRequest's
	// context (auth surface, credential type, connect type, ...). Scope
	// (above) is derived from a subset of these keys for display; Context
	// itself is returned in full for investigative completeness.
	Context map[string]string `json:"context,omitempty"`

	Allowed     bool              `json:"allowed"`
	Obligations map[string]string `json:"obligations,omitempty"`

	// Error is populated when policy evaluation itself failed (compile/eval
	// error, no result returned), rather than reflecting a normal deny.
	Error string `json:"error,omitempty"`

	// DurationUS is how long the OPA evaluation itself took, in microseconds.
	DurationUS int64 `json:"durationUs"`

	// DupCount is how many identical decisions were folded into this row
	// within its dedup window, including the one that created it.
	DupCount int32 `json:"dupCount"`

	// LastOccurredAt is the most recent occurrence folded into this row.
	// OccurredAt remains the first occurrence.
	LastOccurredAt time.Time `json:"lastOccurredAt"`
}

AuditRecord is a single recorded policy-evaluation decision, as returned by authz's QueryAudit RPC. Repeated calls that resolved to the identical decision within a short window are folded server-side into one AuditRecord rather than returned as separate entries — see DupCount/ LastOccurredAt.

type Blueprint

type Blueprint struct {
	Metadata             BlueprintMetadata      `yaml:"metadata" json:"metadata"`
	Name                 string                 `yaml:"name" json:"name" validate:"required,min=1,max=40" jsonschema:"required"`
	Description          string                 `yaml:"description,omitempty" json:"description,omitempty" validate:"max=500"`
	IsTemplate           bool                   `yaml:"isTemplate,omitempty" json:"isTemplate,omitempty" default:"false"`
	Splash               string                 `yaml:"splash,omitempty" json:"splash,omitempty"`
	Template             string                 `yaml:"template" json:"template"`
	Hostname             string                 `yaml:"hostname,omitempty" json:"hostname,omitempty" validate:"omitempty,plainhostname"`
	Subdomain            string                 `yaml:"subdomain,omitempty" json:"subdomain,omitempty" validate:"omitempty,plainhostname"`
	Image                string                 `yaml:"image" json:"image" validate:"required" jsonschema:"required"`
	ImagePullPolicy      string                 `` /* 172-byte string literal not displayed */
	K8shelld             K8shelld               `yaml:"k8shelld" json:"k8shelld" validate:"required" jsonschema:"required"`
	Env                  map[string]string      `yaml:"env,omitempty" json:"env,omitempty" default:"{}"`
	Network              Network                `yaml:"network,omitempty" json:"network,omitempty" default:"{networkPolicyClass:workspace}"`
	Resources            Resources              `yaml:"resources,omitempty" json:"resources,omitempty" default:"{limits:{cpu:500m,memory:512Mi}}"`
	Podman               Podman                 `yaml:"podman,omitempty" json:"podman,omitempty" default:"{enabled:false}"`
	Storages             map[string]Storage     `yaml:"storages,omitempty" json:"storages,omitempty" default:"{}"`
	InitScripts          []InitScript           `yaml:"initScripts,omitempty" json:"initScripts,omitempty" default:"[]" validate:"dive"`
	ShowInitScriptStatus bool                   `yaml:"showInitScriptStatus,omitempty" json:"showInitScriptStatus,omitempty" default:"false"`
	SecurityContext      map[string]interface{} `yaml:"securityContext,omitempty" json:"securityContext,omitempty" default:"{}"`
	ExtFiles             map[string]string      `yaml:"extFiles,omitempty" json:"extFiles,omitempty" default:"{}"`
	EnableApps           bool                   `yaml:"enableApps,omitempty" json:"enableApps,omitempty" default:"false"`
	Apps                 map[string]AppSpec     `yaml:"apps,omitempty" json:"apps,omitempty" default:"{}"`
}

Blueprint represents a single blueprint configuration

func (*Blueprint) Validate

func (b *Blueprint) Validate() v.Validator

Validate validates the blueprint and returns user-friendly errors

type BlueprintMetadata

type BlueprintMetadata struct {
	Name        string `yaml:"name" json:"name"`
	RepoName    string `yaml:"repoName" json:"repoName"`
	RepoRef     string `yaml:"repoRef" json:"repoRef"`
	RepoOwner   string `yaml:"repoOwner" json:"repoOwner"`
	RepoAddress string `yaml:"repoAddress" json:"repoAddress"`
}

BlueprintMetadata holds metadata information for a blueprint.

type BlueprintSummary

type BlueprintSummary struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	IsTemplate  bool   `json:"isTemplate,omitempty"`
	// Org is the organization the blueprint is scoped to, or empty for a
	// file-based, global blueprint. Always emitted so a client can rely on
	// the field being present (paired with IsGlobal).
	Org string `json:"org"`
	// IsGlobal is true when the blueprint is not scoped to an organization
	// (Org is empty) and is therefore available to every organization.
	IsGlobal bool `json:"isGlobal,omitempty"`
	// Template is the name of the parent template this blueprint derives from,
	// or empty when it does not inherit from one.
	Template string `json:"template,omitempty"`
	// CreatedAt is when the blueprint was first registered. For an org-scoped
	// database blueprint this is the row's creation time; for a file-based
	// blueprint it is the source file's last-modified time (equal to
	// UpdatedAt), since a file has no separate creation record.
	CreatedAt time.Time `json:"createdAt"`
	// UpdatedAt is when the blueprint was last changed. For an org-scoped
	// database blueprint this is the row's last-update time; for a file-based
	// blueprint it is the source file's last-modified time (equal to
	// CreatedAt).
	UpdatedAt time.Time `json:"updatedAt"`
}

type BlueprintValidation added in v0.48.0

type BlueprintValidation struct {
	Valid     bool                        `yaml:"valid" json:"valid"`
	Errors    []*BlueprintValidationError `yaml:"errors,omitempty" json:"errors,omitempty"`
	Blueprint any                         `yaml:"blueprint,omitempty" json:"blueprint,omitempty"`
}

BlueprintValidation reports whether a submitted blueprint is valid, lists every problem found, if any, and carries the resolved blueprint document (the submission merged with its referenced Template, if any). Blueprint is decoded generically rather than into Blueprint/CustomBlueprint above, since unresolved CEL expressions may appear in place of their normal field type — mirroring how GetBlueprintResponse's raw content is handled. It's only populated when Valid is true: a caller should fix the reported Errors first rather than preview a document built from an invalid submission.

type BlueprintValidationError added in v0.48.0

type BlueprintValidationError struct {
	Line    int32  `yaml:"line,omitempty" json:"line,omitempty"`
	Column  int32  `yaml:"column,omitempty" json:"column,omitempty"`
	Field   string `yaml:"field,omitempty" json:"field,omitempty"`
	Message string `yaml:"message" json:"message"`
}

BlueprintValidationError describes a single problem found while validating a blueprint.

type Capability added in v0.32.1

type Capability struct {
	Action      string            `json:"action"`
	Allowed     bool              `json:"allowed"`
	Reason      string            `json:"reason"`
	Obligations map[string]string `json:"obligations,omitempty"`
}

Capability describes whether a single policy-governed action is permitted for the authenticated user, as returned by GET /me/capabilities.

type CompleteUserWebFlow

type CompleteUserWebFlow struct {
	Code  string `json:"code"`
	State string `json:"state"`
}

CompleteUserWebFlow represents the data needed to complete a web onboarding flow

type Conn

type Conn struct {
	AllowAnyNS bool `yaml:"allowAnyNS,omitempty" json:"allowAnyNS,omitempty"`
	AllowAnySA bool `yaml:"allowAnySA,omitempty" json:"allowAnySA,omitempty"`
}

type CustomBlueprint

type CustomBlueprint struct {
	Metadata             BlueprintMetadata  `yaml:"metadata" json:"metadata"`
	Name                 string             `yaml:"name,omitempty" json:"name,omitempty"`
	Template             string             `yaml:"template" json:"template" validate:"required"`
	Splash               string             `yaml:"splash,omitempty" json:"splash,omitempty"`
	Image                string             `yaml:"image,omitempty" json:"image,omitempty"`
	Env                  map[string]string  `yaml:"env,omitempty" json:"env,omitempty"`
	Network              Network            `yaml:"network,omitempty" json:"network,omitempty"`
	Resources            Resources          `yaml:"resources,omitempty" json:"resources,omitempty"`
	Storages             map[string]Storage `yaml:"storages,omitempty" json:"storages,omitempty"`
	InitScripts          []InitScript       `yaml:"initScripts,omitempty" json:"initScripts,omitempty"`
	ShowInitScriptStatus bool               `yaml:"showInitScriptStatus,omitempty" json:"showInitScriptStatus,omitempty"`
	EnableApps           bool               `yaml:"enableApps,omitempty" json:"enableApps,omitempty"`
	Apps                 map[string]AppSpec `yaml:"apps,omitempty" json:"apps,omitempty"`
}

CustomBlueprint represents a custom blueprint configuration

func ValidateK8shellFile

func ValidateK8shellFile(k8shellFile K8shellFile) (*CustomBlueprint, []string)

type EnvVar added in v0.46.0

type EnvVar struct {
	Key       string    `json:"key"`
	Value     string    `json:"value"`
	IsSecret  bool      `json:"isSecret"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`

	// Redacted is true when Value is empty because this entry was returned
	// by a list call and IsSecret is true — Value is only ever populated for
	// a secret by a single-key get, or by the create/update response for the
	// write that just set it.
	Redacted bool `json:"redacted,omitempty"`

	// Origin is "org" or "user", identifying which table this entry's
	// effective value came from. Set only when building a user's merged
	// effective env var view; empty for organization-scoped reads.
	Origin string `json:"origin,omitempty"`
}

EnvVar is a single environment variable belonging to an organization or a user. Keys are case-insensitive and normalized to upper case before being stored or looked up.

type EnvVarCreateRequest added in v0.46.0

type EnvVarCreateRequest struct {
	Key      string `json:"key"`
	Value    string `json:"value"`
	IsSecret bool   `json:"isSecret,omitempty"`
}

EnvVarCreateRequest is the HTTP request body for POST /organizations/{name}/envvars, /users/{username}/envvars, and /me/envvars, which creates a new environment variable. Key and Value are required. Key is case-insensitive and normalized to upper case by identity, which also rejects anything but a valid POSIX environment variable name. Note: proto counterpart is identityv1.AddOrganizationEnvVarRequest / identityv1.AddUserEnvVarRequest.

type EnvVarUpdateRequest added in v0.46.0

type EnvVarUpdateRequest struct {
	Value    *string `json:"value,omitempty"`
	IsSecret *bool   `json:"isSecret,omitempty"`
}

EnvVarUpdateRequest is the HTTP request body for PATCH /organizations/{name}/envvars/{key} (and the /users/{username}/envvars/{key} and /me/envvars/{key} equivalents), which partially updates an environment variable's value and/or is_secret flag. Only non-nil fields are applied (PATCH semantics); the key is immutable. Note: proto counterpart is identityv1.UpdateOrganizationEnvVarRequest / identityv1.UpdateUserEnvVarRequest.

type FailedConnectionEvent

type FailedConnectionEvent struct {
	ClientIP    string   `json:"clientIP"`
	ClientPort  int      `json:"clientPort"`
	Username    string   `json:"username"`
	Timestamp   string   `json:"timestamp"`
	FailureInfo []string `json:"failureInfo"`
	ProxyID     string   `json:"proxyID"`
}

FailedConnectionEvent represents a failed SSH connection attempt

type InitScript

type InitScript struct {
	Name   string `yaml:"name" json:"name" validate:"required,plainhostname"`
	Script string `yaml:"script" json:"script" validate:"required"`
	// Always, when true, runs the script on every workspace start instead of
	// only the first time. By default an init script runs once and is skipped
	// on subsequent starts (e.g. after a workspace restart).
	Always bool `yaml:"always,omitempty" json:"always,omitempty"`
}

InitScript represents a named initialization script.

Name must satisfy the "plainhostname" constraint (1-63 chars, alphanumeric start/end, alphanumeric or '-' in between) because the provisioner uses it, verbatim, as the trailing segment of the on-disk file name it materializes for k8shelld. See InitScriptFileName.

type InjectNamespaces added in v0.38.0

type InjectNamespaces struct {
	// Namespaces are the namespaces open to injection. Empty means injection
	// is disabled.
	Namespaces []string `json:"namespaces"`
	// ClusterWide is true when the provisioner is configured to allow
	// injection into every namespace ("*"), in which case Namespaces is a
	// live snapshot of the namespaces that currently exist rather than a
	// fixed allow-list.
	ClusterWide bool `json:"clusterWide,omitempty"`
}

InjectNamespaces lists the namespaces a workspace may be injected into.

type InjectWorkload added in v0.38.0

type InjectWorkload struct {
	// Namespace is the Kubernetes namespace holding the workload.
	Namespace string `json:"namespace"`
	// Kind is the workload kind: "deployment", "statefulset", or "daemonset".
	Kind string `json:"kind"`
	// Name is the workload name. Together with Kind and Namespace it forms
	// the "workload=<kind>/<name>+ns=<namespace>" part of an inject-mode userstr.
	Name string `json:"name"`
	// Replicas is the workload's desired replica count. Injecting produces
	// one workspace per replica.
	Replicas int32 `json:"replicas"`
	// Injected is true when this workload already hosts an injected
	// workspace. A workload holds at most one, so a caller must treat an
	// injected workload as unavailable until it is ejected.
	Injected bool `json:"injected,omitempty"`
	// Workspace is the canonical id of the workspace currently injected into
	// this workload. Empty unless Injected is true.
	Workspace string `json:"workspace,omitempty"`
	// Username is the owner of the currently injected workspace, and
	// Organization their tenant. Both are empty unless Injected is true.
	Username     string `json:"username,omitempty"`
	Organization string `json:"organization,omitempty"`
	// Blueprint is the blueprint the injected workspace was created from.
	// Empty unless Injected is true.
	Blueprint string `json:"blueprint,omitempty"`
}

InjectWorkload is a workload a workspace can be injected into, together with its current injection state.

type K8shellFile

type K8shellFile struct {
	Blueprint CustomBlueprint `yaml:"blueprint" validate:"required"`
}

K8shellFile represents the overall structure of a k8shell YAML file

type K8shelld

type K8shelld struct {
	Image           string   `yaml:"image" json:"image" validate:"required" jsonschema:"required"`
	ImagePullPolicy string   `` /* 172-byte string literal not displayed */
	IgnoreOrphans   []string `yaml:"ignoreOrphans,omitempty" json:"ignoreOrphans,omitempty" default:"[]"`
	Connection      Conn     `yaml:"connection,omitempty" json:"connection,omitempty"`
}

K8shelld represents k8shelld configuration

type Network

type Network struct {
	// NetworkPolicyClass selects a predefined network policy class (workspace, system, isolated, user, organization).
	NetworkPolicyClass string `` /* 224-byte string literal not displayed */
	// AllowEgressToCIDRs is a convenience shorthand for permitting egress to specific CIDR ranges.
	AllowEgressToCIDRs []string `yaml:"allowEgressToCIDRs,omitempty" json:"allowEgressToCIDRs,omitempty" validate:"dive,cidr"`
	// AllowEgressToPods is a convenience shorthand for permitting egress to pods matching label selectors.
	AllowEgressToPods []map[string]string `yaml:"allowEgressToPods,omitempty" json:"allowEgressToPods,omitempty"`
	// WebProxy exposes a TCP port listening inside the workspace through the
	// web proxy, restricted to callers holding one of AllowedRoles. Nil means
	// the workspace publishes nothing through the proxy.
	WebProxy *WebProxy `yaml:"webProxy,omitempty" json:"webProxy,omitempty"`
}

Network defines network policy and egress rules for a workspace.

type OnboardAction added in v0.36.0

type OnboardAction string

OnboardAction is the decision an OnboardRule resolves to.

const (
	OnboardActionAllow    OnboardAction = "allow"
	OnboardActionReject   OnboardAction = "reject"
	OnboardActionWaitlist OnboardAction = "waitlist"

	// OnboardActionNotDefined means no rule resolved to a concrete decision
	// for the user, e.g. an OnboardUserRule CEL template did not set one.
	OnboardActionNotDefined OnboardAction = "not-defined"
)

type OnboardCapability

type OnboardCapability struct {
	Provider   string `json:"provider"`
	Username   string `json:"username"`
	CanOnboard bool   `json:"canOnboard"`
}

OnboardCapability represents the capability of a user to onboard

type OnboardRule added in v0.36.0

type OnboardRule struct {
	ID              int32  `json:"id"`
	IDP             string `json:"idp"`             // provider name, "local", or "*" (any)
	UsernamePattern string `json:"usernamePattern"` // exact username, or a pattern containing '*'

	// Org is the destination organization a matching user is placed into —
	// not a scope filter — replacing whatever the identity provider itself
	// reported. Always set; there is no "global" org for this table.
	Org string `json:"org"`

	Action   OnboardAction `json:"action"`
	Status   OnboardStatus `json:"status"`   // outcome of an actual onboarding attempt; see OnboardStatus*
	Priority int32         `json:"priority"` // lower wins among matching rows of the same specificity

	// Roles/Sudo are the attributes applied to the user when this row
	// resolves to OnboardActionAllow (replacing what OPA's onboarding
	// obligations used to grant). Roles must be valid within Org
	// (org-scoped-or-global).
	Roles []string `json:"roles,omitempty"`
	Sudo  bool     `json:"sudo,omitempty"`

	// Fullname/Email are display metadata for system-inserted (waitlist-hit)
	// rows, so an admin can see who's asking without a fresh provider
	// round-trip.
	Fullname string `json:"fullname,omitempty"`
	Email    string `json:"email,omitempty"`

	Note string `json:"note,omitempty"` // admin comment / rejection reason

	RequestedAt *time.Time `json:"requestedAt,omitempty"` // set only for system-inserted rows
	DecidedAt   *time.Time `json:"decidedAt,omitempty"`   // set when Action moves out of "waitlist"
	DecidedBy   string     `json:"decidedBy,omitempty"`   // admin username who approved/rejected

	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

OnboardRule controls whether a new user may onboard, and what they get when they do. A row is either a pattern rule (UsernamePattern contains '*'), an admin-authored standing policy, or a concrete decision (UsernamePattern has no '*'): a one-off admin-authored allow/reject for a specific person, or a row the system inserted the first time that exact user hit a "waitlist" pattern rule. There is no separate waitlist table — approving a pending row is simply flipping its Action from "waitlist" to "allow".

type OnboardRuleCreateRequest added in v0.36.0

type OnboardRuleCreateRequest struct {
	IDP             string   `json:"idp"`
	UsernamePattern string   `json:"usernamePattern"`
	Action          string   `json:"action"`
	Priority        int32    `json:"priority,omitempty"`
	Roles           []string `json:"roles,omitempty"`
	Sudo            bool     `json:"sudo,omitempty"`
	Note            string   `json:"note,omitempty"`
}

OnboardRuleCreateRequest is the HTTP request body for POST /organizations/{org}/onboard-rules, which registers a new onboard rule (a standing pattern policy, or a one-off decision for a specific username). Org is always taken from the route, never from this body. Note: proto counterpart is identityv1.CreateOnboardRuleRequest.

type OnboardRuleRejectRequest added in v0.36.0

type OnboardRuleRejectRequest struct {
	Note string `json:"note,omitempty"`
}

OnboardRuleRejectRequest is the optional HTTP request body for POST /organizations/{org}/onboard-rules/{id}/reject. DecidedBy is never taken from the body — it's always the authenticated caller's own username. Note: proto counterpart is identityv1.RejectOnboardRuleRequest, minus DecidedBy.

type OnboardRuleUpdateRequest added in v0.36.0

type OnboardRuleUpdateRequest struct {
	Action   string   `json:"action"`
	Priority int32    `json:"priority,omitempty"`
	Roles    []string `json:"roles,omitempty"`
	Sudo     bool     `json:"sudo,omitempty"`
	Note     string   `json:"note,omitempty"`

	// Fullname/Email let an admin correct the display metadata recorded for
	// system-inserted (waitlist-hit) rows; see OnboardRule.Fullname/Email.
	Fullname string `json:"fullname,omitempty"`
	Email    string `json:"email,omitempty"`
}

OnboardRuleUpdateRequest is the HTTP request body for PATCH /organizations/{org}/onboard-rules/{id}, which fully replaces the mutable fields of an onboard rule. Idp/UsernamePattern/Org are immutable — taken from the existing row, never from this body; delete and recreate the rule to change them. Note: proto counterpart is identityv1.UpdateOnboardRuleRequest.

type OnboardStatus added in v0.36.0

type OnboardStatus string

OnboardStatus tracks the outcome of an actual onboarding attempt against an OnboardRule, separate from Action (the configured policy/decision).

const (
	// OnboardStatusNone is the default: no onboarding attempt has resolved
	// against this row yet (e.g. a standing pattern rule, or a proactive
	// admin-authored one-off nobody has attempted to onboard through yet).
	OnboardStatusNone OnboardStatus = "none"
	// OnboardStatusPending means a user hit this row as a "waitlist"
	// decision and no admin decision has been made yet.
	OnboardStatusPending OnboardStatus = "pending"
	// OnboardStatusApproved means an admin approved a previously-waitlisted
	// request (Action is now "allow"), but the user has not yet actually
	// onboarded — they haven't logged in / completed a web flow since being
	// approved, so no identity.users row exists for them yet. Transitions to
	// OnboardStatusOnboarded the moment they do.
	OnboardStatusApproved OnboardStatus = "approved"
	// OnboardStatusRejected means a user was rejected, either directly by
	// an OnboardActionReject rule at attempt time, or by an admin
	// rejecting a previously-waitlisted request.
	OnboardStatusRejected OnboardStatus = "rejected"
	// OnboardStatusOnboarded means the user was actually created in
	// identity.users (and exists in Org's user list).
	OnboardStatusOnboarded OnboardStatus = "onboarded"
)

type OnboardUserDeviceFlow

type OnboardUserDeviceFlow struct {
	Provider        string `json:"provider"`
	Username        string `json:"username"`
	UserCode        string `json:"userCode"`
	VerificationUrl string `json:"verificationUrl"`
	ExpiresIn       int    `json:"expiresIn"`
}

OnboardUserDeviceFlow represents a user being onboarded via OAuth device flow

type OnboardUserRule added in v0.40.0

type OnboardUserRule struct {
	Username     string        `json:"username"`
	Fullname     string        `json:"fullname,omitempty"`
	Email        string        `json:"email,omitempty"`
	Organization string        `json:"organization,omitempty"`
	UID          uint32        `json:"uid,omitempty"`
	GID          uint32        `json:"gid,omitempty"`
	Sudo         *bool         `json:"sudo,omitempty"`
	Action       OnboardAction `json:"action"`
	Roles        []string      `json:"roles,omitempty"`
}

OnboardUserRule is the onboarding decision an identity provider computes for a single user, typically by evaluating a CEL template against the identity data it holds for that user (see models.User, built the same way). Unlike OnboardRule, it is not a persisted policy row: it is the provider's proposed disposition for this one user, returned inline from a flow such as CompleteUserWebFlow.

type OnboardUserWebFlow

type OnboardUserWebFlow struct {
	Provider         string `json:"provider"`
	AuthorizationURL string `json:"authorizationUrl"`
	State            string `json:"state"`
	ExpiresIn        int    `json:"expiresIn"`
}

OnboardUserWebFlow represents a user being onboarded via OAuth web flow

type OperationCode added in v0.30.1

type OperationCode string

OperationCode is a short code identifying the kind of SSH session activity (shell, pty, port-forward, sftp, scp, exec, agent-forward, system-exec).

const (
	OpShell        OperationCode = "sh"
	OpPty          OperationCode = "pt"
	OpPortForward  OperationCode = "pf"
	OpSFTP         OperationCode = "sf"
	OpSCP          OperationCode = "sc"
	OpExec         OperationCode = "ex"
	OpForwardAgent OperationCode = "af"
	OpSystemExec   OperationCode = "se"
)

type OrgBlueprint added in v0.48.0

type OrgBlueprint struct {
	Name        string    `json:"name"`
	Org         string    `json:"org"`
	Description string    `json:"description,omitempty"`
	YAML        []byte    `json:"yaml"`
	IsTemplate  bool      `json:"isTemplate,omitempty"`
	CreatedAt   time.Time `json:"createdAt"`
	UpdatedAt   time.Time `json:"updatedAt"`
}

OrgBlueprint is a blueprint definition stored in the database and scoped to a single organization, as opposed to the file-based, global blueprints (Blueprint/BlueprintSummary above). Name and Org together identify it.

type OrgBlueprintDocument added in v0.49.0

type OrgBlueprintDocument struct {
	Blueprint    any    `json:"blueprint" yaml:"blueprint"`
	OwnBlueprint any    `json:"ownBlueprint" yaml:"ownBlueprint"`
	Template     string `json:"template,omitempty" yaml:"template,omitempty"`
	Org          string `json:"org,omitempty" yaml:"org,omitempty"`
}

OrgBlueprintDocument is the API's response shape for a single org blueprint: the fully merged spec (Blueprint), the fields defined directly on the blueprint itself (OwnBlueprint), the name of its immediate parent Template, if any, and the Org the view is scoped to. A field present in Blueprint but absent from OwnBlueprint is inherited rather than set on this blueprint — comparing the two tells the frontend which fields are inherited versus own. Clients editing a blueprint should only write back fields present in OwnBlueprint (plus whatever the user changed), so unmodified inherited values aren't pinned onto the child. Org is metadata of this wrapper, not part of the blueprint spec — the editor carries it into the save request since the blueprint YAML has no org of its own. Blueprint/OwnBlueprint are decoded generically rather than into Blueprint above, since unevaluated "!cel:"-prefixed placeholders may appear in place of a field's normal type.

type OrgBlueprintWriteRequest added in v0.49.0

type OrgBlueprintWriteRequest struct {
	Org  string `json:"org,omitempty"`
	YAML []byte `json:"yaml"`
}

OrgBlueprintWriteRequest is the HTTP request body shared by POST /blueprints and PUT /blueprints/{name}, which register or replace an org-scoped blueprint. YAML is the full blueprint document (base64-encoded when the body is sent as JSON); name, description and isTemplate are read from it. Org is optional — it defaults to the caller's own organization (from the JWT claims) when omitted. Proto counterpart is provisionerv1.CreateBlueprintRequest / UpdateBlueprintRequest.

type Organization

type Organization struct {
	Name        string    `yaml:"name" json:"name"`
	Description string    `yaml:"description" json:"description"`
	CreatedAt   time.Time `yaml:"createdAt" json:"createdAt"`

	// AdminUsernames and UserCount are computed fields populated by
	// ListOrganizations — not stored on the organization itself, and left
	// empty/zero by CreateOrganization's response.
	AdminUsernames []string `yaml:"adminUsernames" json:"adminUsernames"` // users in this org holding the "org-admin" role
	UserCount      int      `yaml:"userCount" json:"userCount"`

	// ReadOnly is true for the built-in "default" organization only: it
	// cannot be updated or deleted, since it's the fallback organization
	// every k8Shell deployment is seeded with. Computed from Name, not
	// stored.
	ReadOnly bool `yaml:"readOnly" json:"readOnly"`
}

Organization represents an organization in the system

type OrganizationCreateRequest added in v0.35.0

type OrganizationCreateRequest struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

OrganizationCreateRequest is the HTTP request body for POST /organizations, which registers a new organization. Note: proto counterpart is identityv1.CreateOrganizationRequest.

type OrganizationDeleteRequest added in v0.36.0

type OrganizationDeleteRequest struct {
	// MoveUsersToOrg, when set, moves every user out of the org being
	// deleted into this org instead of deleting them — the same mechanism
	// as PATCH /users/{username}/profile's org field. Mutually exclusive
	// with plain deletion: when set, no user in the org is deleted.
	MoveUsersToOrg string `json:"moveUsersToOrg,omitempty"`

	// PreserveWorkspaces, when true, skips workspace cleanup. Its meaning
	// depends on MoveUsersToOrg:
	//   - unset: each user being deleted keeps their workspaces instead of
	//     having them deleted via provisioner.DeleteUserWorkspaces.
	//   - set: each moved user keeps their workspaces even though their new
	//     org's roles may not match those workspaces — normally an org
	//     change deletes them (see UserUpdateRequest.PreserveWorkspaces)
	//     precisely because of that mismatch; this opts back out of it.
	PreserveWorkspaces bool `json:"preserveWorkspaces,omitempty"`
}

OrganizationDeleteRequest is the optional HTTP request body for DELETE /organizations/{name}. identity.DeleteOrganization always fails closed (rejects deletion while any user remains), so api-server always resolves the org's users first — either deleting them or, if MoveUsersToOrg is set, re-homing them to another org — before deleting the org itself (which also removes its now-unreferenced roles). Note: no proto counterpart — these are api-server-only orchestration flags.

type OrganizationUpdateRequest added in v0.35.0

type OrganizationUpdateRequest struct {
	Description *string `json:"description,omitempty"`
}

OrganizationUpdateRequest is the HTTP request body for PATCH /organizations/{name}, which partially updates an organization's description. Name is immutable and cannot be changed through this endpoint — it is taken from the route, never from this body. Note: proto counterpart is identityv1.UpdateOrganizationRequest.

type PasswordResetConfirmRequest added in v0.34.1

type PasswordResetConfirmRequest struct {
	Token    string `json:"token"`
	Password string `json:"password"`
}

PasswordResetConfirmRequest is the HTTP request body for POST /auth/password/reset/confirm, which exchanges a reset token (from the emailed link) for setting Password as the account's new local password.

type PasswordResetRequest added in v0.34.1

type PasswordResetRequest struct {
	Email string `json:"email"`
}

PasswordResetRequest is the HTTP request body for POST /auth/password/reset, which starts a forgot-password flow by emailing a single-use reset link to the account associated with Email, if one exists.

type Podman

type Podman struct {
	Enabled                 bool                   `yaml:"enabled" json:"enabled" default:"false"`
	Image                   string                 `yaml:"image" json:"image" validate:"required_if=Enabled true"`
	Resources               Resources              `yaml:"resources" json:"resources" default:"{cpu:500m,memory:512Mi}"`
	CreateDockerSockSymlink bool                   `yaml:"createDockerSockSymlink" json:"createDockerSockSymlink" default:"false"`
	ParentStorages          bool                   `yaml:"parentStorages" json:"parentStorages" default:"true"`
	ExtFiles                map[string]string      `yaml:"extFiles,omitempty" json:"extFiles,omitempty" default:"{}"`
	Storages                map[string]Storage     `yaml:"storages,omitempty" json:"storages,omitempty" default:"{}"`
	SecurityContext         map[string]interface{} `yaml:"securityContext,omitempty" json:"securityContext,omitempty" default:"{}"`
}

Podman represents Podman configuration

type ProviderInfo

type ProviderInfo struct {
	Status     string    `yaml:"status" json:"status"`
	CreatedAt  time.Time `yaml:"createdAt" json:"createdAt"`
	UpdatedAt  time.Time `yaml:"updatedAt" json:"updatedAt"`
	Username   string    `yaml:"username" json:"username"`
	Provider   string    `yaml:"provider" json:"provider"`
	UserCode   string    `yaml:"userCode" json:"userCode"`
	DeviceCode string    `yaml:"deviceCode" json:"deviceCode"`
	// DeviceCodeExpiresAt is when the device/user code from the OAuth device flow
	// expires while the record is "pending" — unrelated to token expiry.
	DeviceCodeExpiresAt *time.Time `yaml:"deviceCodeExpiresAt" json:"deviceCodeExpiresAt"`
	VerificationURI     string     `yaml:"verificationURI" json:"verificationURI"`
	AccessToken         string     `yaml:"accessToken" json:"accessToken"`
	RefreshToken        string     `yaml:"refreshToken" json:"refreshToken"`
	// TokenExpiresAt is when AccessToken expires, for providers (e.g. GitHub Apps with
	// expiring user tokens enabled) that issue short-lived tokens. Nil means the
	// provider did not report an expiry (token does not expire, or is not expiry-tracked).
	TokenExpiresAt *time.Time `yaml:"tokenExpiresAt" json:"tokenExpiresAt"`
	// RefreshTokenExpiresAt is when RefreshToken itself expires. Once past this time,
	// RefreshToken can no longer be used and the user must re-onboard.
	RefreshTokenExpiresAt *time.Time `yaml:"refreshTokenExpiresAt" json:"refreshTokenExpiresAt"`
}

ProviderInfo holds information about a identity provider

type ProvisionJob

type ProvisionJob struct {
	ID            string                 `json:"id"`
	WorkspaceName string                 `json:"workspaceName,omitempty"`
	Username      string                 `json:"username,omitempty"`
	Status        ProvisionJobStatus     `json:"status"`
	CreatedAt     time.Time              `json:"createdAt"`
	UpdatedAt     time.Time              `json:"updatedAt"`
	FinishedAt    time.Time              `json:"finishedAt,omitempty"`
	Events        []WorkspaceStreamEvent `json:"events,omitempty"`
}

ProvisionJob represents the state of a workspace provisioning job, The provisioning job is stored in a JetStream KV store, and updated as new events are received from the provisioner service.

type ProvisionJobStatus

type ProvisionJobStatus string
const (
	ProvisionJobRunning   ProvisionJobStatus = "running"
	ProvisionJobCompleted ProvisionJobStatus = "completed"
)

type QueryCondition added in v0.35.0

type QueryCondition struct {
	Field string
	Op    string
	Value []string
}

QueryCondition is the JSON shape of a single filter condition in a client-issued query payload. Value accepts either a single string or an array of strings in JSON, since a condition's operator determines how many operands it takes (e.g. "in" takes several, "eq" takes one).

func (*QueryCondition) UnmarshalJSON added in v0.35.0

func (c *QueryCondition) UnmarshalJSON(data []byte) error

type QueryDescriptor added in v0.35.0

type QueryDescriptor struct {
	Resource    string                 `json:"resource"`
	Fields      []QueryFieldDescriptor `json:"fields"`
	DefaultSort []QuerySort            `json:"defaultSort,omitempty"`
}

QueryDescriptor is the JSON shape returned by a resource's _schema endpoint, describing which fields are queryable/sortable.

type QueryFieldDescriptor added in v0.35.0

type QueryFieldDescriptor struct {
	Name      string   `json:"name"`
	Type      string   `json:"type"`
	Operators []string `json:"operators"`
}

QueryFieldDescriptor is the JSON shape of a single queryable/sortable field of a resource, as advertised by that resource's _schema endpoint.

type QueryFilters added in v0.35.0

type QueryFilters struct {
	Op         string           `json:"op"`
	Conditions []QueryCondition `json:"conditions"`
}

QueryFilters is the JSON shape of a query payload's filter group.

type QueryPage added in v0.35.0

type QueryPage struct {
	Limit  int32 `json:"limit"`
	Offset int32 `json:"offset"`
}

QueryPage is the JSON shape of a query payload's paging window.

type QueryPayload added in v0.35.0

type QueryPayload struct {
	Filters *QueryFilters `json:"filters,omitempty"`
	Sort    []QuerySort   `json:"sort,omitempty"`
	Page    *QueryPage    `json:"page,omitempty"`
}

QueryPayload is the JSON shape of a client-issued query against a resource's queryable fields, as advertised by that resource's _schema endpoint.

type QuerySort added in v0.35.0

type QuerySort struct {
	Field string `json:"field"`
	Dir   string `json:"dir"`
}

QuerySort is the JSON shape of a single sort key, used both in a QueryDescriptor's default sort and in a client-issued QueryPayload.

type Repo added in v0.38.0

type Repo struct {
	Name string `json:"name"`
	// FullName is "<owner_login>/<name>".
	FullName      string `json:"fullName"`
	Description   string `json:"description,omitempty"`
	Private       bool   `json:"private,omitempty"`
	DefaultBranch string `json:"defaultBranch,omitempty"`
	HTMLURL       string `json:"htmlUrl,omitempty"`
}

Repo is a repository owned by a RepoOwner, as seen on a user's identity provider.

type RepoOwner added in v0.38.0

type RepoOwner struct {
	Login string `json:"login"`
	// Kind is "user" for the caller's personal account or "organization" for a group.
	Kind        string `json:"kind"`
	Description string `json:"description,omitempty"`
	AvatarURL   string `json:"avatarUrl,omitempty"`
}

RepoOwner is an entity that can own repositories on a user's identity provider: their own personal account, or an organization/group they belong to. Its Login is passed as the owner of a subsequent Repo listing.

type Resources

type Resources struct {
	CPU    string `yaml:"cpu" json:"cpu" validate:"required" jsonschema:"required"`
	Memory string `yaml:"memory" json:"memory" validate:"required" jsonschema:"required"`
}

Resources represents resource limits

type Role

type Role string

User roles

type RoleBlueprintsRequest added in v0.36.0

type RoleBlueprintsRequest struct {
	Blueprints []string `json:"blueprints"`
}

RoleBlueprintsRequest is the HTTP request body for adding or removing blueprints on a role (POST/DELETE /organizations/{org}/roles/{name}/blueprints). Note: proto counterpart is identityv1.RoleBlueprintsRequest.

type RoleCreateRequest added in v0.35.0

type RoleCreateRequest struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

RoleCreateRequest is the HTTP request body for POST /roles (global roles) and POST /organizations/{name}/roles (org-scoped roles) — org is always taken from the route, never from this body. Note: proto counterpart is identityv1.CreateRoleRequest.

type RoleInfo added in v0.35.0

type RoleInfo struct {
	Name        string    `yaml:"name" json:"name"`
	Description string    `yaml:"description" json:"description"`
	Org         string    `yaml:"org" json:"org"`
	CreatedAt   time.Time `yaml:"createdAt" json:"createdAt"`
	UserCount   int       `yaml:"userCount" json:"userCount"`

	// Blueprints are the blueprint names this role grants. A user's
	// effective blueprint access is the union of blueprints across every
	// role they hold.
	Blueprints []string `yaml:"blueprints" json:"blueprints"`
}

RoleInfo is a registered entry in the role registry: the set of role names that may be assigned to a User via its Roles field. It answers only whether a role exists — any meaning encoded in its name (e.g. the "<group>-admin" convention) is interpreted at the policy layer, not here.

type RoleUpdateRequest added in v0.35.0

type RoleUpdateRequest struct {
	Description *string `json:"description,omitempty"`
}

RoleUpdateRequest is the HTTP request body for PATCH /roles/{name} (global roles) and PATCH /organizations/{org}/roles/{name} (org-scoped roles). Name and org are immutable — both are taken from the route, never from this body. Note: proto counterpart is identityv1.UpdateRoleRequest.

type SSHSession

type SSHSession struct {
	SessionID   string     `yaml:"sessionID" json:"sessionID"`
	Username    string     `yaml:"username" json:"username"`
	K8shelldVer string     `yaml:"k8shelldVer" json:"k8shelldVer"`
	Client      string     `yaml:"client" json:"client"`
	ClientIP    string     `yaml:"clientIP" json:"clientIP"`
	StartTime   *time.Time `yaml:"startTime" json:"startTime"`
	EndTime     *time.Time `yaml:"endTime" json:"endTime"`
	Workspace   string     `yaml:"workspace" json:"workspace"`
	BytesIn     int64      `yaml:"bytesIn" json:"bytesIn"`
	BytesOut    int64      `yaml:"bytesOut" json:"bytesOut"`
	Operations  []string   `yaml:"operations" json:"operations"`
	Blueprint   string     `yaml:"blueprint" json:"blueprint"`
	UpdatedAt   *time.Time `yaml:"updatedAt" json:"updatedAt"`
	PtyName     string     `yaml:"ptyName" json:"ptyName"`
}

SSHSession represents an SSH session for a user

type ServiceVersionInfo added in v0.49.0

type ServiceVersionInfo struct {
	// Version is the service's released semantic version, or a caller-chosen
	// fallback (e.g. "0.0.0") when the service did not report one.
	Version string `json:"version"`
	// CommitID is the git commit the service binary was built from.
	CommitID string `json:"commit_id,omitempty"`
	// Description is a short human-readable summary of what the service does.
	Description string `json:"description,omitempty"`
	// Error is set when the GetVersionInfo call itself failed; Version then
	// carries the fallback and CommitID/Description are empty.
	Error string `json:"error,omitempty"`
}

ServiceVersionInfo is a backend service's build metadata, as reported by its common.v1 GetVersionInfo RPC and surfaced by the api-server's GET /api/v1/version endpoint.

type Storage

type Storage struct {
	Enabled  bool   `yaml:"enabled" json:"enabled" default:"false"`
	Id       string `yaml:"id,omitempty" json:"id,omitempty" validate:"omitempty,alphanum"`
	Type     string `` /* 177-byte string literal not displayed */
	Path     string `yaml:"path" json:"path" validate:"required_if=Enabled true,startswith=/"`
	Readonly bool   `yaml:"readonly" json:"readonly" default:"false"`
	// SizeLimit applies to emptyDir and memory types (maps to emptyDir.sizeLimit)
	SizeLimit            string                 `yaml:"sizeLimit,omitempty" json:"sizeLimit,omitempty"`
	ExistingClaim        string                 `yaml:"existingClaim,omitempty" json:"existingClaim,omitempty" validate:"required_if=Type shared Enabled true"`
	FsOwnerUid           *int                   `yaml:"fsOwnerUid,omitempty" json:"fsOwnerUid,omitempty"`
	FsOwnerGid           *int                   `yaml:"fsOwnerGid,omitempty" json:"fsOwnerGid,omitempty"`
	ClaimSpec            map[string]interface{} `yaml:"claimSpec,omitempty" json:"claimSpec,omitempty" default:"{}"`
	ClaimSpecAnnotations map[string]string      `yaml:"claimSpecAnnotations,omitempty" json:"claimSpecAnnotations,omitempty" default:"{}"`
}

Storage represents storage configuration

type User

type User struct {
	Username     string    `yaml:"username" json:"username"`
	Organization string    `yaml:"organization" json:"organization"`
	IsValid      bool      `yaml:"isValid" json:"isValid"`
	ExpiresAt    time.Time `yaml:"expiresAt" json:"expiresAt"`
	UID          uint32    `yaml:"uid" json:"uid"`
	GID          uint32    `yaml:"gid" json:"gid"`
	Fullname     string    `yaml:"fullname" json:"fullname"`
	Email        string    `yaml:"email" json:"email"`
	Password     string    `yaml:"password,omitempty" json:"password,omitempty"`
	Locked       bool      `yaml:"locked" json:"locked"`
	Roles        []Role    `yaml:"roles" json:"roles"`
	Blueprints   []string  `yaml:"blueprints" json:"blueprints"`
	Source       string    `yaml:"source" json:"source"`
	Shell        string    `yaml:"shell" json:"shell"`
	Sudo         bool      `yaml:"sudo" json:"sudo"`

	// ManageRepos carries the management link an identity provider returns
	// alongside this user's onboarding decision (e.g. prompting a GitHub
	// user to install the GitHub App), kept in sync from FindUser and
	// CompleteUserWebFlow. Empty when the provider has no such link.
	ManageRepos string `yaml:"manageRepos,omitempty" json:"manageRepos,omitempty"`
	// GitAddress is the address the identity provider has defined for git
	// operations (e.g. "https://github.com"), kept in sync from FindUser and
	// CompleteUserWebFlow. Empty when the provider has no such address.
	GitAddress string `yaml:"gitAddress,omitempty" json:"gitAddress,omitempty"`
}

User represents a user in the system

func (*User) HasBlueprint

func (u *User) HasBlueprint(blueprintName string) bool

type UserAuthKey added in v0.32.0

type UserAuthKey struct {
	Index  int    `json:"index"`
	Key    string `json:"key"`
	Source string `json:"source"`
}

UserAuthKey represents a single SSH public key registered for a user. Index is the key's position in the list, used to identify it for removal via RemoveUserAuthKey.

type UserCreateRequest added in v0.32.0

type UserCreateRequest struct {
	Username string `json:"username"`
	Org      string `json:"org"`
	Fullname string `json:"fullname,omitempty"`
	Email    string `json:"email,omitempty"`
	Password string `json:"password,omitempty"`
	Roles    []Role `json:"roles,omitempty"`
	Shell    string `json:"shell,omitempty"`
	Sudo     bool   `json:"sudo,omitempty"`
	Locked   bool   `json:"locked,omitempty"`
	UID      uint32 `json:"uid,omitempty"`
	GID      uint32 `json:"gid,omitempty"`
}

UserCreateRequest is the HTTP request body for POST /users, which creates a new local user record with no backing identity provider (unlike onboarding). Note: proto counterpart is identityv1.CreateUserRequest (different wire format, no json tags).

type UserCredential

type UserCredential struct {
	ID               uint32     `json:"id"`
	Username         string     `json:"username"`
	ServiceName      string     `json:"serviceName"`
	ServiceScope     string     `json:"serviceScope"`
	CredentialSource string     `json:"credentialSource"`
	Subject          string     `json:"subject"`
	Secret           string     `json:"secret,omitempty"`
	IsActive         bool       `json:"isActive"`
	CreatedAt        time.Time  `json:"createdAt"`
	UpdatedAt        time.Time  `json:"updatedAt"`
	ExpiresAt        *time.Time `json:"expiresAt,omitempty"`
	LastUsedAt       *time.Time `json:"lastUsedAt,omitempty"`
}

UserCredential represents external service credentials for a user

type UserCredentialUpdateRequest added in v0.32.0

type UserCredentialUpdateRequest struct {
	Scope   *string `json:"scope,omitempty"`
	Subject *string `json:"subject,omitempty"`
	Secret  *string `json:"secret,omitempty"`
	Active  *bool   `json:"active,omitempty"`
}

UserCredentialUpdateRequest is the HTTP request body for PATCH /users/{username}/credentials/{id}, which partially updates a credential. Only non-nil pointer fields are applied (PATCH semantics). Note: proto counterpart is identityv1.UpdateUserCredentialRequest.

type UserDeleteRequest added in v0.36.0

type UserDeleteRequest struct {
	// PreserveWorkspaces, when true, skips the workspace cleanup that
	// otherwise runs unconditionally when a user is deleted (see
	// provisioner.DeleteUserWorkspaces). Default false — deleting a user
	// deletes their workspaces too, unless this is set.
	PreserveWorkspaces bool `json:"preserveWorkspaces,omitempty"`
}

UserDeleteRequest is the optional HTTP request body for DELETE /users/{username}. An empty/absent body is equivalent to the zero value (PreserveWorkspaces: false). Note: no proto counterpart — PreserveWorkspaces is an api-server-only orchestration flag, never sent to identity.

type UserGitCredentialRequest added in v0.32.0

type UserGitCredentialRequest struct {
	Scope   string `json:"scope"`
	Subject string `json:"subject"`
	Secret  string `json:"secret"`
}

UserGitCredentialRequest is the HTTP request body for POST /users/{username}/credentials/git, which stores a Git credential for a user. Note: proto counterpart is identityv1.AddGitUserCredentialRequest.

type UserKeysRequest added in v0.29.12

type UserKeysRequest struct {
	Keys []string `json:"keys"`
}

UserKeysRequest is the HTTP request body for adding SSH public keys on a user. Note: proto counterpart is identityv1.UserAuthKeysRequest.

type UserKubernetesCredentialRequest added in v0.32.0

type UserKubernetesCredentialRequest struct {
	Scope   string `json:"scope"`
	Subject string `json:"subject"`
}

UserKubernetesCredentialRequest is the HTTP request body for POST /users/{username}/credentials/kubernetes, which provisions a Kubernetes service-account credential for a user. Note: proto counterpart is identityv1.AddKubernetesUserCredentialRequest.

type UserLoginRequest added in v0.32.1

type UserLoginRequest struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

UserLoginRequest is the HTTP request body for POST /auth/login, which authenticates a user against the identity service's "local" password provider.

type UserPasswordRequest added in v0.31.0

type UserPasswordRequest struct {
	Password        *string `json:"password"`
	CurrentPassword *string `json:"current_password,omitempty"`
}

UserPasswordRequest is the HTTP request body for setting or clearing a user's local password. Password is a pointer so an explicit empty string (clear the password) can be distinguished from an absent field. Note: proto counterpart is identityv1.SetUserPasswordRequest.

type UserProfile added in v0.32.1

type UserProfile struct {
	Username     string   `json:"username"`
	Organization string   `json:"organization"`
	Fullname     string   `json:"fullname"`
	Email        string   `json:"email"`
	UID          uint32   `json:"uid"`
	GID          uint32   `json:"gid"`
	Shell        string   `json:"shell"`
	Sudo         bool     `json:"sudo"`
	Source       string   `json:"source"`
	Roles        []Role   `json:"roles"`
	Blueprints   []string `json:"blueprints"`

	// IsValid mirrors models.User.IsValid: false means the backing identity
	// provider (Source) no longer confirms this account exists, or its
	// session couldn't be freshly re-verified (e.g. an expired OAuth
	// refresh token) — distinct from AccountLocked, which is an explicit
	// admin action rather than a provider-driven state.
	IsValid bool `json:"is_valid"`

	// AccountLocked is the administrative lock an admin sets explicitly; it
	// blocks all auth surfaces (SSH, PAT, session, password).
	AccountLocked bool `json:"account_locked"`

	// PasswordLocked reflects api-server's local, transient brute-force
	// lockout for password-based auth specifically — other auth surfaces
	// (e.g. SSH publickey) keep working while this is true.
	PasswordLocked      bool   `json:"password_locked"`
	PasswordLockedUntil string `json:"password_locked_until,omitempty"`

	// ManageRepos is an optional management link to present to the user,
	// e.g. prompting a GitHub user to install the GitHub App.
	ManageRepos string `json:"manage_repos,omitempty"`
}

UserProfile is the HTTP response body for GET /me/profile and GET /users/{username}/profile — the frontend's canonical view of a user account. Fields are copied explicitly rather than reusing models.User directly, so this contract only changes when a profile field is deliberately added or removed here, independent of what models.User carries for other (non-HTTP-facing) consumers.

type UserRegistryCredentialRequest added in v0.32.0

type UserRegistryCredentialRequest struct {
	Scope   string `json:"scope"`
	Subject string `json:"subject"`
	Secret  string `json:"secret"`
}

UserRegistryCredentialRequest is the HTTP request body for POST /users/{username}/credentials/registry, which stores a container registry credential for a user. Note: proto counterpart is identityv1.AddRegistryUserCredentialRequest.

type UserResult added in v0.40.0

type UserResult struct {
	OnboardRule OnboardUserRule `json:"onboardRule"`
	// ManageRepos is a link the client should present to the user for
	// managing their repository access on the provider, e.g. prompting a
	// GitHub user to install the GitHub App now that they've authorized it.
	// Empty when the provider has no such link.
	ManageRepos string `json:"manageRepos,omitempty"`
	// GitAddress is the address the identity provider has defined for git
	// operations, e.g. "https://github.com".
	GitAddress string `json:"gitAddress"`
}

UserResult is an identity provider's onboarding decision for a user, returned by FindUser (re-evaluated for an already-onboarded user) and by CompleteUserWebFlow (evaluated for a user who just completed the provider's web onboarding flow).

type UserRolesRequest added in v0.29.12

type UserRolesRequest struct {
	Roles []Role `json:"roles"`
}

UserRolesRequest is the HTTP request body for adding or removing roles on a user. Note: proto counterpart is identityv1.UserRolesRequest.

type UserToken

type UserToken struct {
	Provider string `json:"provider"`
	Address  string `json:"address"`
	Username string `json:"username"`
	Token    string `json:"token"`
}

UserToken represents a token for a user

type UserUpdateRequest added in v0.29.12

type UserUpdateRequest struct {
	Fullname *string `json:"fullname,omitempty"`
	Shell    *string `json:"shell,omitempty"`
	Email    *string `json:"email,omitempty"`
	Org      *string `json:"org,omitempty"`
	Roles    []Role  `json:"roles,omitempty"`
	Sudo     *bool   `json:"sudo,omitempty"`
	Locked   *bool   `json:"locked,omitempty"`
	UID      *uint32 `json:"uid,omitempty"`
	GID      *uint32 `json:"gid,omitempty"`

	// PreserveWorkspaces, when true, keeps a user's workspaces intact across
	// an org change. Ignored unless Org is set and actually differs from the
	// user's current organization — the default (false) is destructive: on a
	// real org move, api-server deletes every workspace the user owns via
	// provisioner.DeleteUserWorkspaces.
	PreserveWorkspaces bool `json:"preserveWorkspaces,omitempty"`
}

UserUpdateRequest is the HTTP request body for PATCH /users/{username}. Only non-nil pointer fields and non-empty slices are applied (PATCH semantics). Note: proto counterpart is identityv1.UpdateUserRequest (different wire format, no json tags) — PreserveWorkspaces has no proto counterpart at all; it's an api-server-only orchestration flag, never sent to identity.

type WebProxy added in v0.50.0

type WebProxy struct {
	Port         int    `yaml:"port" json:"port" validate:"required,min=1,max=65535" jsonschema:"required"`
	AllowedRoles []Role `yaml:"allowedRoles,omitempty" json:"allowedRoles,omitempty" validate:"omitempty,dive,min=1"`
}

WebProxy publishes a single TCP port from inside the workspace through the web proxy. Port is the in-workspace listener; AllowedRoles is the set of user roles permitted to reach it (an empty list means no role is allowed, i.e. the route is effectively closed until roles are added).

type WorkspaceDetails

type WorkspaceDetails struct {
	WorkspaceStatus
	AppVersion   string `json:"appVersion" example:"1.0.0"`
	Name         string `json:"name"`
	Username     string `json:"username"`
	RepoOwner    string `json:"repoOwner,omitempty"`
	RepoName     string `json:"repoName,omitempty"`
	RepoRef      string `json:"repoRef,omitempty"`
	Blueprint    string `json:"blueprint"`
	Origin       string `json:"origin"`
	Organization string `json:"organization"`
	CPU          string `json:"cpu" example:"500m"`
	Memory       string `json:"memory" example:"256Mi"`
	ServerName   string `json:"serverName"`
	PodIP        string `json:"podIP"`
	Port         int    `json:"port"`
	TLSEnabled   bool   `json:"tlsEnabled"`
	Namespace    string `json:"namespace"`
	Hostname     string `json:"hostname,omitempty"`
	JobId        string `json:"jobId,omitempty"`
	// NetworkPolicyClass is the predefined network policy class the workspace
	// pod belongs to (e.g. "user", "organization"). Empty when the workspace
	// has no network policy class.
	NetworkPolicyClass string `json:"networkPolicyClass,omitempty" example:"user"`
	// AllowEgressToCIDRs and AllowEgressToPods are the egress shortcuts in force
	// on the workspace pod. They report the settings live on the pod now: a call
	// to the update API can change them, and they revert to the blueprint's
	// values on the next re-provision. Both are empty for an injected workspace.
	AllowEgressToCIDRs []string            `json:"allowEgressToCIDRs,omitempty"`
	AllowEgressToPods  []map[string]string `json:"allowEgressToPods,omitempty"`
	// WebProxyPort and WebProxyRoles report the web-proxy route live on the
	// workspace pod now: the update API can change them and they revert to the
	// blueprint on the next re-provision. WebProxyPort is 0 (and WebProxyRoles
	// empty) when the workspace publishes no route, and for an injected
	// workspace.
	WebProxyPort  int    `json:"webProxyPort,omitempty"`
	WebProxyRoles []Role `json:"webProxyRoles,omitempty"`
	// WorkspaceType tells standalone workspaces apart from injected ones.
	WorkspaceType WorkspaceType `json:"workspaceType" example:"standalone"`
	// WorkloadKind and WorkloadName identify the workload an injected
	// workspace lives in. Both are empty for a standalone workspace.
	WorkloadKind string `json:"workloadKind,omitempty" example:"deployment"`
	WorkloadName string `json:"workloadName,omitempty" example:"api-server"`
	// ReplicaIndex is which replica of the workload this workspace is, and
	// ReplicaCount the workload's desired replica count. Both are nil for a
	// standalone workspace — a pointer rather than a plain int so that replica
	// 0, the ordinary case, stays distinguishable from "not applicable".
	// ReplicaIndex is a stable ordinal for a StatefulSet; for a Deployment it
	// is derived from pod-name order and can shift when a pod is replaced.
	ReplicaIndex *int32 `json:"replicaIndex,omitempty" example:"0"`
	ReplicaCount *int32 `json:"replicaCount,omitempty" example:"3"`
}

WorkspaceDetails represents the details of a workspace It contains information about the workspace pod status and in addition

type WorkspaceNetworkUpdateRequest added in v0.49.0

type WorkspaceNetworkUpdateRequest struct {
	NetworkPolicyClass string                 `json:"networkPolicyClass,omitempty"`
	ReplaceEgress      bool                   `json:"replaceEgress,omitempty"`
	AllowEgressToCidrs []string               `json:"allowEgressToCidrs,omitempty"`
	AllowEgressToPods  []WorkspacePodSelector `json:"allowEgressToPods,omitempty"`
	// ReplaceWebProxy must be true for WebProxyPort and WebProxyRoles to be
	// applied; the route is replaced wholesale, so ReplaceWebProxy with
	// WebProxyPort 0 clears it.
	ReplaceWebProxy bool `json:"replaceWebProxy,omitempty"`
	// WebProxyPort is the in-workspace TCP port to publish through the web
	// proxy (0 clears the route). Applied only when ReplaceWebProxy is true.
	WebProxyPort int `json:"webProxyPort,omitempty"`
	// WebProxyRoles is the set of user roles allowed to reach the web-proxy
	// route. Applied only when ReplaceWebProxy is true.
	WebProxyRoles []Role `json:"webProxyRoles,omitempty"`
}

WorkspaceNetworkUpdateRequest is the HTTP request body for PATCH /workspaces/{workspace_name}/network, which changes a workspace's network policy class, egress rules, and/or web-proxy route. Gated by the workspace:update:network data type. AllowEgressToCidrs and AllowEgressToPods take effect only when ReplaceEgress is true, in which case they replace the workspace's egress rules wholesale (passing them empty clears every custom rule). WebProxyPort and WebProxyRoles take effect only when ReplaceWebProxy is true, in which case they replace the web-proxy route wholesale (passing WebProxyPort 0 clears the route). When both replace flags are false only NetworkPolicyClass is considered. Note: proto counterpart is provisionerv1.WorkspaceNetworkRules.

type WorkspacePodSelector added in v0.49.0

type WorkspacePodSelector struct {
	MatchLabels map[string]string `json:"matchLabels,omitempty"`
}

WorkspacePodSelector is a set of pod labels a workspace egress rule is allowed to reach, used in WorkspaceNetworkUpdateRequest. Note: proto counterpart is provisionerv1.WorkspacePodSelector.

type WorkspaceResourcesUpdateRequest added in v0.49.0

type WorkspaceResourcesUpdateRequest struct {
	CPU    *string `json:"cpu,omitempty" example:"500m"`
	Memory *string `json:"memory,omitempty" example:"256Mi"`
}

WorkspaceResourcesUpdateRequest is the HTTP request body for PATCH /workspaces/{workspace_name}/resources, which changes a running workspace's CPU and/or memory limits. Both fields are pointers for PATCH semantics (nil means "leave unchanged"); at least one must be set. Each present field is gated by its own workspace:update data type — cpu, memory — so a caller authorized only to bump memory can't also change the CPU limit. Note: proto counterpart is provisionerv1.WorkspaceResourceLimits (no json tags, no pointers).

type WorkspaceStatus

type WorkspaceStatus struct {
	Created         time.Time              `json:"created" example:"2025-08-05T10:30:00Z"`
	Status          WorkspaceStatusMessage `json:"status" example:"Running"`
	Message         string                 `json:"message" example:"Workspace is running"`
	Restarts        int32                  `json:"restarts" example:"0"`
	LastFailMessage string                 `json:"lastFailMessage,omitempty" example:""`
}

WorkspaceStatus represents the status of a workspace pod

type WorkspaceStatusMessage

type WorkspaceStatusMessage string

WorkspaceStatusMessage is the user-friendly status reported for a workspace pod.

const (
	WorkspaceStatusProvisioning WorkspaceStatusMessage = "Starting"
	WorkspaceStatusWarning      WorkspaceStatusMessage = "Warning"
	WorkspaceStatusPulling      WorkspaceStatusMessage = "Pulling"
	WorkspaceStatusRunning      WorkspaceStatusMessage = "Running"
	WorkspaceStatusFailing      WorkspaceStatusMessage = "Failing"
	WorkspaceStatusStopping     WorkspaceStatusMessage = "Stopping"
	WorkspaceStatusTerminating  WorkspaceStatusMessage = "Terminating"
	WorkspaceStatusStopped      WorkspaceStatusMessage = "Stopped"
	WorkspaceStatusError        WorkspaceStatusMessage = "Error"
	WorkspaceStatusUnknown      WorkspaceStatusMessage = "Unknown"
)

type WorkspaceStreamEvent

type WorkspaceStreamEvent struct {
	Id         int64                    `json:"id" example:"123456789"`
	Type       WorkspaceStreamEventType `json:"type" example:"event"`
	Timestamp  string                   `json:"timestamp,omitempty" example:"2025-08-05T10:30:00Z"`
	ObjectName string                   `json:"objectName,omitempty" example:"dev-user123"`
	Message    string                   `json:"message,omitempty" example:"Pod is starting"`
	Status     WorkspaceStatusMessage   `json:"status,omitempty" example:"Running"`
}

StreamEvent represents a streaming event response

func (WorkspaceStreamEvent) String

func (e WorkspaceStreamEvent) String() string

type WorkspaceStreamEventType

type WorkspaceStreamEventType string
const (
	WorkspaceStreamEventTypeEvent    WorkspaceStreamEventType = "event"
	WorkspaceStreamEventTypeStatus   WorkspaceStreamEventType = "status"
	WorkspaceStreamEventTypeProgress WorkspaceStreamEventType = "progress"
)

type WorkspaceTerminalSession added in v0.44.0

type WorkspaceTerminalSession struct {
	SessionID  string `json:"session_id"`
	Owner      string `json:"owner"`
	Shell      string `json:"shell"`
	CreatedAt  string `json:"created_at"`
	DetachedAt string `json:"detached_at,omitempty"`
}

WorkspaceTerminalSession is the HTTP-facing view of a shell session on a workspace pod that is currently available to be joined (see k8shelld's AcquireSession) rather than started fresh.

type WorkspaceType added in v0.38.0

type WorkspaceType string

WorkspaceType is how a workspace is deployed.

const (
	// WorkspaceTypeStandalone is a workspace running as its own Helm release.
	WorkspaceTypeStandalone WorkspaceType = "standalone"
	// WorkspaceTypeInjected is a workspace injected into an existing workload.
	WorkspaceTypeInjected WorkspaceType = "injected"
)

Jump to

Keyboard shortcuts

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