CRD reference
Every custom resource Telark defines, who writes it, and the fields that matter.
Telark stores its state as Kubernetes custom resources, defined by the
telark-crds chart. Every CRD is in the group telark.io, version
v1alpha1, namespaced in the release namespace, and kept on
uninstall (helm.sh/resource-policy: keep).
The exporter writes every Telark resource; discovery also patches
applications/status to record rollbacks. The other services go
through the exporter's HTTP API. The CRD write guard (app.security.crdGuard,
on and enforcing by default) rejects direct writes to telark.io
resources, /status included, from any other identity.
Kinds
| Kind | Plural (FQ name) | Short | Category | /status | Purpose |
|---|---|---|---|---|---|
Application | applications.telark.io | tapp | telark | yes | A discovered application: workloads grouped into one unit. |
ProtectionPlan | protectionplans.telark.io | tplan | telark | yes | Policy templates bound to a scope and a time window. |
TelarkConfig | telarkconfigs.telark.io | tcfg | telark | yes | Cluster-wide settings. Singleton named default. |
Category | categories.telark.io | tcat | telark | no | Classification categories. Singleton list named categories. |
User | users.telark.io | tuser | telark | no | A user in the role model. |
Group | groups.telark.io | tgroup | telark | no | A named set of users and the roles they inherit. |
AccessRole | accessroles.telark.io | trole | telark | no | Scopes granted at a level, plus deny rules. |
Passkey | passkeys.telark.io | tpk | telark-auth | no | A registered WebAuthn credential. |
Session | sessions.telark.io | tsess | telark-auth | no | An authenticated session. |
kubectl get telark -n telark lists every Telark object except
passkeys and sessions (kubectl get telark-auth -n telark). Several
plurals collide with other CRDs (Argo CD installs
applications.argoproj.io), so address Telark objects by their fully
qualified or short names:
kubectl get applications.telark.io -n telark
kubectl get tplan -n telarkIdentity and references
The object name (metadata.name) is the identity; there is no
spec.id. The REST API returns the name as id on every read.
References hold names: roleRefs, groupRefs, userRefs,
participantRefs and scope.applicationRefs name objects, while
categoryRef, environmentRef, kindRef and tagRefs name items of the
categories object, which keep their own id (cat-…).
Application, ProtectionPlan and TelarkConfig keep observed state
in .status: a write to spec never changes .status, and the
reverse. The REST API flattens .status into the top level of each
object.
Application
Built by discovery from the workloads it groups; the notifier persists it through the exporter. See Applications.
| Field | Notes |
|---|---|
spec.name, spec.displayName, spec.description, spec.managed | Identity. Users may change only the display name (at most 200 characters) and description (at most 1,000). managed holds by, chart and version. |
status.namespaces, status.resources, status.resourceSummary, status.resourceCount | What the application is made of. |
status.health | status (healthy, degraded, down, unknown), reason, readyReplicas, totalReplicas. |
status.images, status.ports, status.envVarKeys, status.configMapRefs, status.secretRefs, status.serviceMappings, status.ingressRules, status.metrics | Inventory, change metrics and workload usage. |
status.history | generation, hasDrift, lastModifiedBy, lastModifiedAt, and changeLog[]: generation, detectedAt, changeClass, severity, changedBy, fingerprint, isIncident, isRecovery, changes. See change classes. |
status.snapshots[] | id, generation, changeClass, severity, takenAt, namespace, path. |
status.rollbacks[] | id, targetSnapshotId, targetGeneration, targetPath, triggeredBy, triggeredAt, completedAt, status (pending, in_progress, success, failed, aborted), error, restoredGeneration, namespace. See rollback. |
status.lastForceSync | jobId, phase (queued, running, completed, failed), requestedAt, startedAt, completedAt, requestedBy, reason, error. |
status.conditions | Type Published: status True or False, reason Pending, Created or Failed. |
status.createdAt, status.lastUpdated | Audit. |
ProtectionPlan
Discovery owns the lifecycle; the exporter stores the plan. See Protection plans.
| Field | Notes |
|---|---|
spec.name, spec.description | At most 64 and 512 characters. |
spec.severity, spec.priority | low, medium, high or critical; an integer from −100 to 100. |
spec.scope.type | applications (scope.applicationRefs) or namespaces (scope.namespaces). |
spec.scope.exclusions | kinds[] (at most 50) for either scope type; resources[] (kind, name, namespace, at most 200) with type=applications only. |
spec.policies[] | templateID and params. See Policy templates. |
spec.mode | audit or enforce. |
spec.timeMode, spec.timeRange.{startAt, endAt}, spec.repeat | permanent, time_range or repeating. repeat holds days (mon to sun), startTime and endTime (HH:MM) and an IANA timeZone, and is required with repeating. |
spec.approvalMode | automatic or required; absent means automatic. Derived by the server; Production is always required. |
spec.environmentRef, spec.kindRef, spec.tagRefs[] | One plan environment, one plan kind and at most 20 plan tags. kindRef names a plan-kinds category and is not looked up, so a deleted kind reads as none. |
spec.participantRefs[] | Users associated with the plan. |
spec.createdAt, spec.createdBy, spec.lastUpdatedAt, spec.lastUpdatedBy | Audit. |
status.phase, status.reason | pending_approval, scheduled, active, terminated, canceled or failed. The schema also accepts draft, which no code path sets. |
status.conditions, status.observedGeneration | Conditions Ready, Approved and PoliciesHealthy. |
status.renderedPolicies[] | Names of the admission policies deployed for the plan. |
status.health, status.healthCheckedAt, status.healthDetail[] | unknown, healthy, drifted or degraded, with per-policy detail. |
status.startedAt, status.startedBy, status.terminatedAt, status.terminatedBy | Lifecycle stamps. |
status.approval | state (pending, approved, rejected), requestedBy, requestedAt, decidedBy, decidedAt, comment (at most 500 characters), and history[] (event, by, at, comment; at most 20). Written only by discovery. |
status.window | A repeating plan's open or next window (startAt, endAt). Written only by discovery. |
TelarkConfig
The single cluster-wide configuration object. The schema accepts only
the name default.
| Field | Notes |
|---|---|
spec.excludedNamespaces[] | Namespaces hidden from discovery and refused as plan targets. Fresh install: default, kube-system, kube-public, kube-node-lease. |
spec.ai.enabled, spec.ai.model, spec.ai.autoAnalyze | Insights switch, model tag, and automatic analysis. Fresh install: true, granite4:350m, false. |
spec.snapshots.maxPerApp | Snapshot generations kept per application (fresh install: 5). |
spec.oidc.enabled, spec.oidc.googleClientID, spec.oidc.egressAllowed | Google sign-in; egressAllowed lets auth fetch Google's signing keys. Written only by auth, for the bootstrap admin. |
spec.selfRegistration.enabled | Passkey self-registration (fresh install: false). Written only by auth, for the bootstrap admin. |
spec.breakGlassAlerts.notifyAdmins | Whether Admins on ALL see break-glass recovery requests and hear when one opens or is canceled (default true). A link break-glass is issuing and a completed request reach them either way. Written only by auth, for the bootstrap admin. |
status.cluster.version | Cluster version, written by discovery. |
status.lastMigration, status.rollbackMigration | The exporter's migration record: the last step it ran, and the last step of the release before. Written only at exporter startup and left out of the REST view. See Migrations. |
status.bootstrap | The pinned bootstrap account (userID, email, pinnedAt) and requests[], the newest 20 break-glass recovery requests (id, kind recover or replace, targetEmail, state pending, approved, canceled or completed, reason, and their timestamps). Written only by the exporter and left out of the config view, which refuses the key. |
The optional Google JWK set is not stored here: it lives in the Secret
telark-oidc-trust-secret (key googleJwkJson), which the exporter
writes when the bootstrap admin saves it through auth.
GET /api/v1/config merges it back under oidc.googleJwkJson.
Category
One object named categories holds every category in
spec.categories[]: id (cat-…), name, scope (groups,
roles, plan-environments, plan-tags or plan-kinds), type
(built-in or custom), and creationDate. Built-in plan environments
are Production, Staging and Development; built-in plan tags are
Compliance, Security and Baseline; built-in plan kinds are QA, Testing,
Release and Maintenance window.
User
| Field | Notes |
|---|---|
spec.username, spec.fullname, spec.email | Profile. The username allows letters, digits, _ and -, at most 50 characters. |
spec.roleRefs[], spec.groupRefs[] | Roles assigned directly, and group memberships. |
spec.bootstrap | Marks the bootstrap admin; never settable through the API. One account, pinned in the TelarkConfig's status.bootstrap: once it is pinned, no caller, services included, moves the marker. |
spec.identities[] | provider, issuer, subject of each external identity. |
spec.status.phase, spec.status.lastLoginAt | active, inactive or suspended. Only active users are granted anything. |
spec.status.invite | issuedAt, expiresAt and issuedBy (a user ID) of a pending enrollment link. Written only by auth, for display: the link itself expires in Redis. |
spec.status.inviteAcceptedAt | When a passkey last closed a pending enrollment link (Members shows Enrolled). Written only by auth. |
spec.avatar, spec.settings, spec.creationDate, spec.lastUpdateDate | Profile and audit. |
Group
spec.name, spec.description, spec.userRefs[] (members),
spec.roleRefs[] (roles the members inherit), spec.categoryRef, and
the audit fields creationDate, lastUpdateDate, createdBy,
lastUpdatedBy.
AccessRole
| Field | Notes |
|---|---|
spec.name, spec.description, spec.version, spec.categoryRef | Identity. |
spec.type, spec.priority | built-in or custom; an ordering hint. Sessions cannot create or change a built-in role. |
spec.scopesAndPermissions[] | scope, level (ReadOnly, Contributor, Owner, Admin), and deny rules[] (<scope>.<action>.deny). See Access control. |
spec.protection | preventDeletion, preventModification, preventScopeChanges, lockName, lockCategory, softDelete. With softDelete, a delete marks the role Deleted (with deletedAt) instead of removing it. |
spec.status | Active, Inactive, Deprecated or Deleted. |
spec.validity | type (permanent, temporary, sessionBased), expiresAt, durationHours, autoRevoke. |
| Audit fields | creationDate, lastUpdateDate, createdBy, lastUpdatedBy, deprecatedAt, deletedAt. |
Passkey
spec.userId, spec.credentialId, spec.publicKey,
spec.deviceName, spec.deviceType (platform or
cross-platform), spec.backupEligible, spec.backupState,
spec.creationTimestamp, spec.lastUsedTimestamp.
Session
Named session-<sha256(token)> (the schema rejects any other name),
so the token itself is never stored. spec.userId,
spec.createdTimestamp, spec.expiresTimestamp, spec.ipAddress,
and spec.deviceMetadata (browser, device, os, location,
userAgent).
Labels and finalizers
- The admission policies rendered for a protection plan carry the
labels
telark.io/protection-plan=<plan id>,telark.io/template-idandapp.kubernetes.io/managed-by=telark, and the annotationstelark.io/plan-name,telark.io/created-byandtelark.io/render-hash. - Workloads changed through admission carry the annotations
telark.io/last-modified-by,telark.io/last-modified-atandtelark.io/last-modified-operation, stamped by the chart'stelark-inject-modifierKyvernoMutatingPolicy(Secrets excluded). - Users, groups and access roles carry the finalizers
telark.io/user-cleanup,telark.io/group-cleanupandtelark.io/role-cleanup, which the auth service clears.
What this list does not include
- Kyverno
NamespacedValidatingPolicyobjects (policies.kyverno.io/v1): the admission policies a protection plan deploys, namedtelark-<plan id>-<template code>-<hash>. Discovery creates and deletes them; Telark reads them for health. PolicyViolationevents raised by Kyverno. Telark reads them for the plan's admission decisions and reports.- Snapshots and protection-plan reports: files on the exporter's volumes, not custom resources.