models

package
v0.65.6 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: AGPL-3.0 Imports: 13 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 DetectValues added in v0.63.2

func DetectValues(withNone bool) []string

DetectValues returns the values a detect list may hold: "all", "none" when withNone is set, and every category in threat.Categories.

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.

func ParseScheduleDuration added in v0.65.6

func ParseScheduleDuration(s string) (time.Duration, error)

ParseScheduleDuration parses a duration like time.ParseDuration does and in addition accepts a whole number of days with the suffix "d" (e.g. "7d"), which time.ParseDuration lacks. The duration must not be negative.

func ParseScheduleTime added in v0.65.6

func ParseScheduleTime(raw string, loc *time.Location) (time.Time, error)

ParseScheduleTime parses a schedule time: an RFC 3339 timestamp, or a time without an offset which is read in loc (the local zone when loc is nil).

A time that does not exist in loc, because the clocks jump over it when daylight saving time starts, is moved forward by the length of the jump. A time that happens twice, when daylight saving time ends, is the first of the two.

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 Announcement added in v0.57.0

type Announcement struct {
	ID int32 `json:"id"`

	// Name is an admin-facing label only — not translated, not shown to end
	// users — so admins can tell announcements apart in a listing.
	Name string `json:"name"`

	// Translations carries the announcement's body in one or more
	// languages; every announcement has at least one.
	Translations []AnnouncementTranslation `json:"translations"`

	CreatedBy string `json:"createdBy"` // username of the author

	// Orgs names the organizations this announcement applies to; empty
	// means every organization (global).
	Orgs []string `json:"orgs,omitempty"`

	// Roles further scopes the announcement to users holding at least one
	// of these roles within the applicable org(s); empty means every role.
	Roles []string `json:"roles,omitempty"`

	// Active toggles whether this announcement is shown in the user-facing
	// listings without deleting it; it always remains visible via the
	// admin-facing Get/List calls.
	Active bool `json:"active"`

	// StartsAt/EndsAt bound the announcement's optional validity period. A
	// nil bound is open on that side. An announcement outside its period is
	// excluded from an unread listing even when a user hasn't read it yet,
	// but remains retrievable through a full listing.
	StartsAt *time.Time `json:"startsAt,omitempty"`
	EndsAt   *time.Time `json:"endsAt,omitempty"`

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

	// ReadCount is computed — the number of distinct users who have read
	// this announcement. Populated by the admin-facing Get/List calls, zero
	// elsewhere.
	ReadCount int32 `json:"readCount,omitempty"`

	// IsRead/ReadAt are computed per requesting user — populated only by a
	// user-facing listing that reports read status, empty otherwise.
	IsRead bool       `json:"isRead,omitempty"`
	ReadAt *time.Time `json:"readAt,omitempty"`

	// EmailEnabled marks this announcement as eligible to be sent by email,
	// in addition to a user's own announcementsByEmail opt-in (stored in
	// UserSettings.Data) — an announcement is only emailed to a user when
	// both are true. No sender exists yet; this only records the flag.
	EmailEnabled bool `json:"emailEnabled"`
}

Announcement is a platform message rendered as markdown by clients. It is either global (Orgs empty) or scoped to one or more organizations/roles, and optionally bounded to a validity period (StartsAt/EndsAt).

type AnnouncementCreateRequest added in v0.57.0

type AnnouncementCreateRequest struct {
	Name         string                    `json:"name"`
	Translations []AnnouncementTranslation `json:"translations"`
	Orgs         []string                  `json:"orgs,omitempty"`
	Roles        []string                  `json:"roles,omitempty"`
	Active       *bool                     `json:"active,omitempty"`
	StartsAt     *time.Time                `json:"startsAt,omitempty"`
	EndsAt       *time.Time                `json:"endsAt,omitempty"`
	EmailEnabled *bool                     `json:"emailEnabled,omitempty"`
}

AnnouncementCreateRequest is the HTTP request body for POST /announcements, which creates a new announcement. Name is required and admin-facing only (not translated, not shown to end users). Translations must carry at least one entry — every announcement must be readable in at least one language. Orgs scopes the announcement to specific organizations; empty (or omitted) makes it global. Roles further scopes it to users holding at least one of these roles within Orgs; empty means every role. Active defaults to true when omitted. EmailEnabled defaults to false when omitted — announcements are not email-eligible unless explicitly enabled; no sender exists yet, this only records the flag. StartsAt/EndsAt bound its optional validity period; omit either for an open bound. CreatedBy is never read from the body — the handler sets it from the authenticated caller. Note: proto counterpart is identityv1.CreateAnnouncementRequest.

type AnnouncementTranslation added in v0.57.0

type AnnouncementTranslation struct {
	Lang string `json:"lang"` // BCP 47 language tag, e.g. "en", "en-US"
	Body string `json:"body"` // markdown content
}

AnnouncementTranslation carries an Announcement's body in a single language. Every Announcement has at least one.

type AnnouncementUpdateRequest added in v0.57.0

type AnnouncementUpdateRequest struct {
	Name         *string                   `json:"name,omitempty"`
	Translations []AnnouncementTranslation `json:"translations,omitempty"`
	Orgs         []string                  `json:"orgs,omitempty"`
	// ClearOrgs makes the announcement global; Orgs must be empty when this
	// is set.
	ClearOrgs bool     `json:"clearOrgs,omitempty"`
	Roles     []string `json:"roles,omitempty"`
	// ClearRoles makes the announcement apply to every role; Roles must be
	// empty when this is set.
	ClearRoles bool       `json:"clearRoles,omitempty"`
	Active     *bool      `json:"active,omitempty"`
	StartsAt   *time.Time `json:"startsAt,omitempty"`
	// ClearStartsAt removes the lower validity bound (open-started).
	ClearStartsAt bool       `json:"clearStartsAt,omitempty"`
	EndsAt        *time.Time `json:"endsAt,omitempty"`
	// ClearEndsAt removes the upper validity bound (open-ended).
	ClearEndsAt bool `json:"clearEndsAt,omitempty"`
	// EmailEnabled marks the announcement eligible (or ineligible) to be
	// sent by email; see models.Announcement.EmailEnabled.
	EmailEnabled *bool `json:"emailEnabled,omitempty"`
}

AnnouncementUpdateRequest is the HTTP request body for PATCH /announcements/{id}, which partially updates an announcement's name, translations, org/role scope, active/emailEnabled flags, and/or validity period. Only non-nil/non-empty fields are applied (PATCH semantics), except Translations, when given, which replaces the announcement's entire translation set — it can never be replaced with an empty set, since every announcement must keep at least one language. Because JSON can't distinguish an absent field from an explicitly cleared one, clearing the org/role scope or a validity bound back to "every org/role"/"open" requires the matching Clear* flag rather than sending a nil/empty value — mirroring identityv1.UpdateAnnouncementRequest's clear_orgs/clear_roles/clear_starts_at/clear_ends_at fields. Set at most one of a bound (or Orgs/Roles) and its own Clear* flag. Note: proto counterpart is identityv1.UpdateAnnouncementRequest.

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"`

	Subject AuditSubject `json:"subject"`

	// 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"`

	// Resource mirrors the authz Resource: the owner is Attributes["owner"].
	Resource AuditResource `json:"resource"`

	// Context mirrors EvaluateRequest.context. Scope (above) is derived from
	// a subset of its keys for display. Oversized values are replaced by a
	// "<truncated: N bytes, sha256:...>" marker.
	Context map[string]string `json:"context,omitempty"`

	// Result mirrors EvaluateResponse, plus Error.
	Result AuditResult `json:"result"`

	// 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 AuditResource added in v0.63.5

type AuditResource struct {
	Type       string            `json:"type"`
	ID         string            `json:"id"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

AuditResource mirrors the authz Resource of the evaluated request.

type AuditResult added in v0.63.5

type AuditResult struct {
	Allowed     bool              `json:"allowed"`
	Reason      string            `json:"reason,omitempty"`
	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"`
}

AuditResult mirrors the authz EvaluateResponse, plus Error.

type AuditSubject added in v0.63.5

type AuditSubject struct {
	Username string   `json:"username"`
	Roles    []string `json:"roles"`
	Org      string   `json:"org"`
}

AuditSubject is the caller of an audited evaluation, from the JWT claims.

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 */
	// RuntimeClassName sets the pod's runtimeClassName (e.g. kata-qemu).
	RuntimeClassName     string                 `yaml:"runtimeClassName,omitempty" json:"runtimeClassName,omitempty" validate:"omitempty,plainhostname"`
	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:"{}"`
	// Schedule limits how long workspaces of this blueprint may run. Nil means
	// no limit. It is deliberately absent from CustomBlueprint: a repository's
	// k8shell file must not be able to lift an organization's schedule.
	Schedule *Schedule `yaml:"schedule,omitempty" json:"schedule,omitempty"`
}

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"`
	// Revision is a short content hash of the blueprint fully merged with its
	// inherited templates. It changes whenever the blueprint's effective
	// content changes, including through a change to any ancestor template.
	Revision string `json:"revision,omitempty"`
}

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 DetectionOverride added in v0.63.2

type DetectionOverride struct {
	Workspace string `json:"workspace"`
	// Detect lists the categories watched on the workspace: ["all"], ["none"]
	// or category names.
	Detect []string `json:"detect"`
	// SetBy is the username that set the override.
	SetBy string `json:"setBy,omitempty"`
	// SetAt is the unix time (seconds) the override was set.
	SetAt int64 `json:"setAt,omitempty"`
}

DetectionOverride is a workspace's detection override as returned by the API.

func (DetectionOverride) JSONSchemaExtend added in v0.63.2

func (DetectionOverride) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend enumerates the detect values from threat.Categories.

type DetectionOverrideRequest added in v0.63.2

type DetectionOverrideRequest struct {
	Detect []string `json:"detect" binding:"required,min=1" jsonschema:"required"`
}

DetectionOverrideRequest is the body of PUT /workspaces/{name}/detection-override. Detect lists the threat categories worktrace watches on the workspace, replacing what the threat:detect policy decided; ["all"] watches every category and ["none"] disables detection.

func (DetectionOverrideRequest) JSONSchemaExtend added in v0.63.2

func (DetectionOverrideRequest) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend enumerates the accepted detect values from threat.Categories, so the schema follows the category list.

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 NodeSelectorKey added in v0.65.4

type NodeSelectorKey struct {
	Key    string              `json:"key"`
	Values []NodeSelectorValue `json:"values"`
}

NodeSelectorKey is a node selector key the provisioner is configured with and the values currently present on cluster nodes, sorted by value.

type NodeSelectorOptions added in v0.65.4

type NodeSelectorOptions struct {
	Keys []NodeSelectorKey `json:"keys"`
}

NodeSelectorOptions is the response of GET /nodes/selectors.

type NodeSelectorValue added in v0.65.4

type NodeSelectorValue struct {
	Value            string `json:"value"`
	NodeCount        int32  `json:"nodeCount"`
	ReadyCount       int32  `json:"readyCount"`
	SchedulableCount int32  `json:"schedulableCount"`
}

NodeSelectorValue is one label value found on cluster nodes for a node selector key, with how many nodes carry it.

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"`
	UsernamePattern string   `json:"usernamePattern"`
	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/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"`
	// Revision is the blueprint's merged-content revision (see
	// BlueprintSummary.Revision). It is computed by the provisioner, not
	// stored in the database.
	Revision string `json:"revision,omitempty"`
}

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"`

	// NodeSelectors is the desired Kubernetes nodeSelector for the org's
	// workspaces (label key -> single value). Desired state only; never
	// counts or readiness.
	NodeSelectors map[string]string `yaml:"nodeSelectors" json:"nodeSelectors"`
}

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 OrganizationNodeSelectorsUpdateRequest added in v0.65.4

type OrganizationNodeSelectorsUpdateRequest struct {
	NodeSelectors map[string]string `json:"nodeSelectors"`
}

OrganizationNodeSelectorsUpdateRequest is the HTTP request body for PUT /organizations/{name}/nodeselectors. NodeSelectors replaces the org's stored map wholesale; an empty map clears it.

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 Overcommit added in v0.65.2

type Overcommit struct {
	CPU    *float64 `yaml:"cpu,omitempty" json:"cpu,omitempty" validate:"omitempty,gte=1"`
	Memory *float64 `yaml:"memory,omitempty" json:"memory,omitempty" validate:"omitempty,gte=1"`
}

Overcommit is the ratio between a limit and the request derived from it, per resource (request = limit / ratio). An unset ratio keeps the default fixed request.

type ParsedSchedule added in v0.65.6

type ParsedSchedule struct {
	// Location is the zone times without an offset were read in.
	Location       *time.Location
	From           *time.Time
	To             *time.Time
	StopGrace      time.Duration
	TerminateGrace time.Duration
	// HasTerminateGrace reports whether TerminateGrace was set. When false a
	// stopped workspace is never terminated.
	HasTerminateGrace bool
}

ParsedSchedule is a Schedule with its values parsed. A nil time is unset. StopGrace is zero when unset. TerminateGrace needs HasTerminateGrace to tell an unset value from an explicit zero.

func ParseSchedule added in v0.65.6

func ParseSchedule(s *Schedule, def *time.Location) (*ParsedSchedule, error)

ParseSchedule parses and validates s, reading times without an offset in its Timezone or, when that is unset, in def (the local zone when nil). A nil s yields a nil result and no error. The error, if any, is a *ScheduleError.

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 PlatformVersions added in v0.58.0

type PlatformVersions struct {
	// PlatformVersion is the version of the k8Shell release the services were
	// deployed from (the Helm chart's app version).
	PlatformVersion string `json:"platformVersion"`
	// Services maps a service name (e.g. "apiServer", "k8shelld") to the
	// version of the image the release deployed it from. The set of services
	// comes from the release itself, so it grows with the platform rather than
	// with this struct.
	Services map[string]string `json:"services"`
	// Infra maps an infrastructure dependency name (e.g. "postgresql", "nats")
	// to its version, mirroring Services. These aren't part of the k8Shell
	// release, so they are published separately by the k8shell-infra-versions
	// ConfigMap rather than the release's k8shell-versions ConfigMap.
	Infra map[string]string `json:"infra"`
}

PlatformVersions is the api-server's GET /api/v1/versions response: the versions of the deployed k8Shell release, as published by the deployment's k8shell-versions ConfigMap, plus the infrastructure versions the api-server observes at runtime.

type Podman

type Podman struct {
	Enabled bool `yaml:"enabled" json:"enabled" default:"false"`
	// Profile selects a built-in set of defaults for the podman sidecar.
	Profile   string    `` /* 154-byte string literal not displayed */
	Image     string    `yaml:"image" json:"image" validate:"required_if=Enabled true"`
	Resources Resources `yaml:"resources" json:"resources" default:"{cpu:500m,memory:512Mi}"`
	// StartupScript is a shell snippet run as root before the podman service starts.
	StartupScript string `yaml:"startupScript,omitempty" json:"startupScript,omitempty"`
	// InitContainers are extra init containers run before the workspace starts.
	InitContainers []PodmanInitContainer `yaml:"initContainers,omitempty" json:"initContainers,omitempty" validate:"omitempty,dive"`
	// SocketMedium sets the emptyDir medium of the podman socket volume.
	SocketMedium string `yaml:"socketMedium,omitempty" json:"socketMedium,omitempty" validate:"omitempty,oneof=Memory" jsonschema:"enum=Memory"`
	// CacheTrimSeconds drops the guest's page cache every so many seconds so a
	// VM-based runtime class (e.g. Kata) returns cold cache to the host. Needs
	// runtimeClassName, since in a plain container it would drop the node's cache.
	// Unset takes the profile default; 0 disables it.
	CacheTrimSeconds *int `yaml:"cacheTrimSeconds,omitempty" json:"cacheTrimSeconds,omitempty"`
	// StorageImage keeps the podman graph storage in a loop-mounted ext4 image
	// (mode file) or on a raw block volume (mode block).
	StorageImage            *PodmanStorageImage    `yaml:"storageImage,omitempty" json:"storageImage,omitempty"`
	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 PodmanInitContainer added in v0.65.2

type PodmanInitContainer struct {
	Name    string   `yaml:"name" json:"name" validate:"required,plainhostname"`
	Image   string   `yaml:"image" json:"image" validate:"required"`
	Command []string `yaml:"command" json:"command" validate:"required,min=1"`
	// Storages lists the names of podman storages to mount.
	Storages []string `yaml:"storages,omitempty" json:"storages,omitempty"`
}

PodmanInitContainer is an extra init container of the workspace pod.

type PodmanStorageImage added in v0.65.2

type PodmanStorageImage struct {
	// Mode is file (sparse ext4 image on a filesystem volume) or block (raw block volume).
	Mode string `yaml:"mode" json:"mode" validate:"required,oneof=file block" jsonschema:"enum=file,enum=block"`
	// Storage is the name of the podman storage holding the image or device. Defaults to graphdb.
	Storage string `yaml:"storage,omitempty" json:"storage,omitempty" default:"graphdb"`
	// DiskPath is where the volume is mounted (file) or the device appears (block).
	DiskPath string `yaml:"diskPath,omitempty" json:"diskPath,omitempty" validate:"omitempty,startswith=/"`
	// MountPath is where the ext4 filesystem is mounted. Defaults to /var/lib/containers/storage.
	MountPath string `yaml:"mountPath,omitempty" json:"mountPath,omitempty" validate:"omitempty,startswith=/"`
	// Size is the image size for mode file. Defaults to 90% of the claim.
	Size string `yaml:"size,omitempty" json:"size,omitempty"`
	// InitImage provides mkfs.ext4 for mode file.
	InitImage string `yaml:"initImage,omitempty" json:"initImage,omitempty"`
}

PodmanStorageImage configures how podman storage sits on a podman volume.

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 RecordingOverride added in v0.62.8

type RecordingOverride struct {
	Workspace string `json:"workspace"`
	// Record lists the recording types applied to every new session to the
	// workspace; ["none"] means recording is disabled.
	Record []string `json:"record"`
	// SetBy is the username that set the override.
	SetBy string `json:"setBy,omitempty"`
	// SetAt is the unix time (seconds) the override was set.
	SetAt int64 `json:"setAt,omitempty"`
}

RecordingOverride is a workspace's recording override as returned by the API.

type RecordingOverrideRequest added in v0.62.8

type RecordingOverrideRequest struct {
	Record []string `` /* 159-byte string literal not displayed */
}

RecordingOverrideRequest is the body of PUT /workspaces/{name}/recording-override. Record lists the recording types to apply to every new session to the workspace, replacing what the session:record policy would decide; ["none"] disables recording.

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"`
	// Overcommit derives the container requests from the limits. Only the
	// workspace level resources use it; it applies to the main container and the
	// podman sidecar.
	Overcommit *Overcommit `yaml:"overcommit,omitempty" json:"overcommit,omitempty"`
}

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"`
	// Recordings references the session's non-exec recordings by start time.
	// Filled when sessions are listed; ignored when a session is stored.
	Recordings []SessionRecordingRef `yaml:"recordings,omitempty" json:"recordings,omitempty"`
	// ExecRecordings is the number of exec recordings, which are not listed
	// in Recordings. Filled when sessions are listed.
	ExecRecordings int `yaml:"execRecordings,omitempty" json:"execRecordings,omitempty"`
}

SSHSession represents an SSH session for a user

type Schedule added in v0.65.6

type Schedule struct {
	// Timezone is the IANA name (e.g. Europe/Prague) of the zone times
	// without an offset are read in. Unset means the deployment's default.
	Timezone string `yaml:"timezone,omitempty" json:"timezone,omitempty"`
	// From is the earliest time the workspace may be provisioned.
	From string `yaml:"from,omitempty" json:"from,omitempty"`
	// To is the time the workspace expires. Unset means the workspace never
	// expires.
	To string `yaml:"to,omitempty" json:"to,omitempty"`
	// StopGrace is the period between To and the stop of the workspace. It is
	// a duration such as 15m, 2h or 1d. Unset means no grace period.
	StopGrace string `yaml:"stopGrace,omitempty" json:"stopGrace,omitempty"`
	// TerminateGrace is the period a stopped workspace is kept before it is
	// terminated. It is a duration such as 12h or 7d. Unset means a stopped
	// workspace is never terminated.
	TerminateGrace string `yaml:"terminateGrace,omitempty" json:"terminateGrace,omitempty"`
}

Schedule limits how long a workspace may run. It is declared on a blueprint and inherits through the blueprint's template field one key at a time, so a child can override a single value.

The timeline of a workspace with a schedule:

To                      the run ends, the stop grace period begins and
                        the user is warned
To + StopGrace          the workspace pod is stopped
stopped + TerminateGrace  the stopped workspace is terminated (deleted)

All fields are strings so that they merge as scalars; ParseSchedule turns them into typed values. Every field is optional. An empty field is unset.

A time is either absolute, an RFC 3339 timestamp with an offset or Z (2026-11-10T08:00:00Z, 2026-11-10T09:00:00+01:00), or a local time without an offset (2026-11-10T09:00, 2026-11-10 09:00:00), which is read in Timezone, or in the deployment's default zone when that is unset.

func (*Schedule) Location added in v0.65.6

func (s *Schedule) Location(def *time.Location) (*time.Location, error)

Location returns the zone times without an offset are read in: the schedule's Timezone, or def when it is unset (the local zone when def is nil too). The error is a *ScheduleError.

func (*Schedule) Normalize added in v0.65.6

func (s *Schedule) Normalize(def *time.Location) (*Schedule, error)

Normalize returns a copy of s in which every time without an offset has been resolved to an RFC 3339 timestamp, in the zone it was read in. Times that already carry an offset are kept as written, and the Timezone is kept. Resolving once, when a workspace is provisioned, keeps its schedule from moving when the default zone changes later. A nil s gives nil.

type ScheduleError added in v0.65.6

type ScheduleError struct {
	Field string
	Msg   string
}

ScheduleError is a schedule validation failure. Field is the YAML key the failure applies to (e.g. "to", "stopGrace"), not including the "schedule." prefix.

func (*ScheduleError) Error added in v0.65.6

func (e *ScheduleError) Error() string

Error implements error.

type SessionRecordingRef added in v0.62.5

type SessionRecordingRef struct {
	// ID is the recording ID used to fetch details or download the file.
	ID string `yaml:"id" json:"id"`
	// Type is the recording type: shell, exec, tcpip, sftp or
	// vscode_terminal.
	Type string `yaml:"type" json:"type"`
	// ParentRecordingID is the recording this one was derived from: for a
	// vscode_terminal, the session's tcpip pcap-ng recording of the same
	// destination. Empty for most recordings.
	ParentRecordingID string `yaml:"parentRecordingId,omitempty" json:"parentRecordingId,omitempty"`
}

SessionRecordingRef identifies one recording of a session.

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 Threat added in v0.63.6

type Threat struct {
	ID         string    `json:"id"`
	DetectedAt time.Time `json:"detectedAt"`
	ReceivedAt time.Time `json:"receivedAt"`

	// Severity is "low", "medium", "high" or "critical", derived from
	// Confidence when the controller stored the threat.
	Severity   string  `json:"severity"`
	Confidence float64 `json:"confidence"`

	Title       string `json:"title"`
	Description string `json:"description,omitempty"`

	// DetectionPipeline is "direct", "correlation" or "behavioral".
	DetectionPipeline string `json:"detectionPipeline"`

	// RuleID is the detection rule or attack path that fired. Empty for
	// behavioral anomalies.
	RuleID string `json:"ruleId,omitempty"`

	Namespace     string `json:"namespace,omitempty"`
	WorkspaceID   string `json:"workspaceId,omitempty"`
	NodeName      string `json:"nodeName,omitempty"`
	ContainerName string `json:"containerName,omitempty"`

	// Mode is "shadow" for a threat of a rule rolled out in shadow mode
	// (recorded, never alerted on); empty otherwise.
	Mode string `json:"mode,omitempty"`

	// MergedInto is the ID of the threat this one was merged into (same
	// process, within the dedup window). Empty for a reported threat.
	MergedInto string `json:"mergedInto,omitempty"`

	// Occurrences is set on a dedup summary: how many threats for the same
	// rule and workspace its window saw.
	Occurrences int32 `json:"occurrences,omitempty"`

	// Evidence carries rule-specific details (process, file path, syscall
	// arguments, ...).
	Evidence map[string]any `json:"evidence,omitempty"`
}

Threat is a threat as stored by the worktrace controller, returned by its QueryThreats RPC. It differs from ThreatEvent by what the controller adds: severity, the time it stored the threat, and its deduplication state.

type ThreatEvent added in v0.63.1

type ThreatEvent struct {
	// ID uniquely identifies the threat; it is also the NATS message ID, which
	// lets JetStream drop redelivered duplicates, and the key consumers should
	// use to make their handling idempotent.
	ID         string    `json:"id"`
	DetectedAt time.Time `json:"detectedAt"`
	Confidence float64   `json:"confidence"`

	Title       string `json:"title"`
	Description string `json:"description,omitempty"`

	// DetectionPipeline is the detector pipeline that produced the threat
	// ("direct", "correlation" or "behavioral").
	DetectionPipeline string `json:"detectionPipeline"`

	// RuleID is the detection rule (direct pipeline) or attack path
	// (correlation pipeline) that fired. Empty for behavioral anomalies.
	RuleID string `json:"ruleId,omitempty"`

	// Where the threat was observed. WorkspaceID is empty for events without
	// pod context (e.g. node-level activity).
	Namespace     string `json:"namespace,omitempty"`
	WorkspaceID   string `json:"workspaceId,omitempty"`
	NodeName      string `json:"nodeName,omitempty"`
	ContainerName string `json:"containerName,omitempty"`

	// Evidence carries rule-specific details (process, file path, occurrences).
	Evidence map[string]any `json:"evidence,omitempty"`
}

ThreatEvent is a threat reported by a worktrace detector over NATS and consumed by the worktrace controller. It is the JSON payload of messages on the subjects built by nats.ThreatSubject.

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 UserSettings added in v0.59.0

type UserSettings struct {
	Username  string          `json:"username"`
	Version   int32           `json:"version"`
	Data      json.RawMessage `json:"data,omitempty"`
	UpdatedAt time.Time       `json:"updatedAt"`
}

UserSettings is a user's opaque settings blob. A user with no row is represented by the zero value of this type, not a nil/not-found signal — GetUserSettings never errors on a missing row. Data is json.RawMessage (not []byte) so it serializes as an embedded JSON value rather than a base64 string.

Data is never parsed by api-server or Identity; keys are an agreement between producers/consumers of the blob. Known keys:

  • "announcementsByEmail" (bool): the user opted in to receiving product/service announcements by email. Nothing currently sends that email — this only records the preference.

type UserSettingsUpdateRequest added in v0.60.0

type UserSettingsUpdateRequest struct {
	Version int32           `json:"version"`
	Data    json.RawMessage `json:"data,omitempty"`
}

UserSettingsUpdateRequest is the HTTP request body for PUT /users/{username}/settings and /me/settings, which fully replaces a user's settings blob (last-write-wins, no merge — Version is informational only, not used for optimistic-concurrency conflict detection). Data is an opaque JSON value the server never parses. Note: proto counterpart is identityv1.PutUserSettingsRequest.

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"`
	Alias        string `yaml:"alias,omitempty" json:"alias,omitempty" validate:"omitempty,webproxyalias"`
}

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).

Alias is an optional friendly name for the route, unique within the workspace's organization. It may be a static value or a !cel expression (e.g. to derive it from the username); a CEL result is validated by the provisioner after evaluation. When the alias is already held by another workspace of the org, the workspace is provisioned without one and WorkspaceDetails.WebProxyAliasMessage says why.

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"`
	// WebProxyAlias is the alias the web-proxy route is reachable under,
	// unique within the organization. It has the same live-view and revert
	// semantics as WebProxyPort. Empty when no alias is applied.
	WebProxyAlias string `json:"webProxyAlias,omitempty"`
	// WebProxyAliasMessage explains why the blueprint's alias was not applied
	// (e.g. held by another workspace, or invalid after CEL evaluation). Empty
	// when the alias was applied or the blueprint declares none.
	WebProxyAliasMessage string `json:"webProxyAliasMessage,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"`
	// BlueprintRevision is the content revision of the blueprint the
	// workspace was provisioned from (see BlueprintSummary.Revision). Empty
	// for a workspace provisioned before revisions were recorded.
	BlueprintRevision string `json:"blueprintRevision,omitempty" example:"3f9c1a2b7d4e"`
	// BlueprintOutdated reports whether Blueprint's current revision differs
	// from BlueprintRevision, i.e. whether a re-provision would change the
	// workspace's blueprint. Nil when that cannot be determined: no recorded
	// revision, the blueprint no longer exists, or the workspace was built
	// from a repository's k8shell file, whose current content the
	// provisioner does not track.
	BlueprintOutdated *bool `json:"blueprintOutdated,omitempty" example:"false"`
	// Runtime is the Kubernetes runtime class the workspace pod runs in (e.g.
	// "kata-qemu"). Empty when the pod uses the cluster's default runtime.
	// It is independent of WorkspaceType.
	Runtime string `json:"runtime,omitempty" example:"kata-qemu"`
	// NodeSelectors is the node placement constraint applied to the workspace
	// pod, key to label value. A comma-separated value means the node may carry
	// any one of the listed values. Empty when the pod can run on any node.
	NodeSelectors map[string]string `json:"nodeSelectors,omitempty"`
	// NodeName is the node the workspace pod is scheduled on. Empty while the
	// pod is not yet scheduled and for a stopped workspace.
	NodeName string `json:"nodeName,omitempty" example:"worker-1"`
	// Schedule is the run schedule the workspace was provisioned with. Nil
	// when its blueprint declares none.
	Schedule *WorkspaceSchedule `json:"schedule,omitempty"`
}

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

type WorkspaceDetection added in v0.63.2

type WorkspaceDetection struct {
	Workspace string `json:"workspace"`
	// Source is "override" when a detection override is set, "policy" when
	// the stored threat:detect result decides, and "default" when neither
	// does and worktrace applies its configured default.
	Source string `json:"source" jsonschema:"enum=override,enum=policy,enum=default"`
	// Detect lists the categories watched, with the same values as
	// DetectionOverrideRequest.Detect except "none": an empty list means
	// nothing is watched. Empty when Source is "default".
	Detect []string `json:"detect"`
	// EvaluatedFor is the subject the policy was evaluated as when the
	// workspace was provisioned. Set when a policy result is stored.
	EvaluatedFor string `json:"evaluatedFor,omitempty"`
	// EvaluatedAt is the unix time (seconds) of that evaluation.
	EvaluatedAt int64 `json:"evaluatedAt,omitempty"`
	// Override is the stored override; set only when Source is "override".
	Override *DetectionOverride `json:"override,omitempty"`
}

WorkspaceDetection describes which threat categories worktrace watches on a workspace: the stored override when there is one, otherwise the threat:detect policy result stored when the workspace was provisioned.

func (WorkspaceDetection) JSONSchemaExtend added in v0.63.2

func (WorkspaceDetection) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend enumerates the detect values from threat.Categories; "none" is never listed, an empty list means nothing is watched.

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"`
	// WebProxyAlias changes the alias of the web-proxy route independently of
	// ReplaceWebProxy: nil leaves it unchanged, "" clears it. Setting it
	// requires the route in effect after the update, which a route published
	// in the same request satisfies; without one, or when the alias is taken,
	// the whole update is rejected unapplied. Like the other network settings it reverts
	// to the blueprint's alias on the next re-provision. Clearing the route
	// (ReplaceWebProxy with WebProxyPort 0) clears the alias too.
	WebProxyAlias *string `json:"webProxyAlias,omitempty" validate:"omitempty,webproxyalias"`
}

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 WorkspaceRecording added in v0.62.8

type WorkspaceRecording struct {
	Workspace string `json:"workspace"`
	// Source is "override" when a recording override is set for the
	// workspace, "policy" when the session:record policy decides.
	Source string `json:"source" jsonschema:"enum=override,enum=policy"`
	// EvaluatedFor is the user the policy was evaluated as: the workspace
	// owner. Set only when Source is "policy".
	EvaluatedFor string `json:"evaluatedFor,omitempty"`
	// Record lists the recording types applied, with the same values as
	// RecordingOverrideRequest.Record except "none": an empty list means
	// nothing is recorded. It applies to SSH and webshell alike; webshell
	// sessions only ever use "shell".
	Record []string `json:"record"`
	// Override is the stored override; set only when Source is "override".
	Override *RecordingOverride `json:"override,omitempty"`
}

WorkspaceRecording describes what is recorded in new sessions to a workspace: the stored override when there is one, otherwise the session:record policy evaluated as the workspace's owner. The policy result is exact only for sessions the owner opens; the policy may record other users' sessions differently.

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 WorkspaceSchedule added in v0.65.6

type WorkspaceSchedule struct {
	// From is the earliest time the workspace could be provisioned.
	From *time.Time `json:"from,omitempty" example:"2026-11-10T08:00:00Z"`
	// To is the time the workspace expires and its stop grace period begins.
	To *time.Time `json:"to,omitempty" example:"2026-11-10T18:00:00Z"`
	// StopGrace is the period between To and the stop, e.g. "15m".
	StopGrace string `json:"stopGrace,omitempty" example:"15m"`
	// TerminateGrace is the period a stopped workspace is kept before it is
	// terminated, e.g. "7d". Empty means never.
	TerminateGrace string `json:"terminateGrace,omitempty" example:"7d"`
	// StopsAt is when the workspace pod is stopped: To plus StopGrace. Nil
	// when To is unset.
	StopsAt *time.Time `json:"stopsAt,omitempty" example:"2026-11-10T18:15:00Z"`
	// TerminatesAt is when the stopped workspace is terminated: To plus
	// StopGrace plus TerminateGrace. Nil when To or TerminateGrace is unset.
	TerminatesAt *time.Time `json:"terminatesAt,omitempty" example:"2026-11-17T18:15:00Z"`
}

WorkspaceSchedule is the effective run schedule of a workspace, resolved from its blueprint when it was provisioned. See Schedule for the timeline.

type WorkspaceScheduleUpdateRequest added in v0.65.6

type WorkspaceScheduleUpdateRequest struct {
	To             *string `json:"to,omitempty" example:"2026-11-12T18:00:00Z"`
	StopGrace      *string `json:"stopGrace,omitempty" example:"15m"`
	TerminateGrace *string `json:"terminateGrace,omitempty" example:"7d"`
	Revert         bool    `json:"revert,omitempty"`
}

WorkspaceScheduleUpdateRequest is the HTTP request body for PATCH /workspaces/{workspace_name}/schedule, which overrides the run schedule of a running workspace. A nil field keeps its value and "" clears it ("to": "" means no expiry). Revert drops the override and restores the blueprint's schedule; it can't be combined with values. To is absolute with an offset or Z; without one it is read in the blueprint's timezone or the deployment's default zone, never the caller's. At least one field or Revert must be set. Gated by workspace:update with data type schedule. Note: proto counterpart is provisionerv1.SetWorkspaceScheduleRequest.

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"
	// WorkspaceStatusNodeLost means the workspace pod is being deleted but its
	// node is unreachable, so the deletion cannot finish until the node returns.
	WorkspaceStatusNodeLost WorkspaceStatusMessage = "NodeLost"
	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