Reference

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

KindPlural (FQ name)ShortCategory/statusPurpose
Applicationapplications.telark.iotapptelarkyesA discovered application: workloads grouped into one unit.
ProtectionPlanprotectionplans.telark.iotplantelarkyesPolicy templates bound to a scope and a time window.
TelarkConfigtelarkconfigs.telark.iotcfgtelarkyesCluster-wide settings. Singleton named default.
Categorycategories.telark.iotcattelarknoClassification categories. Singleton list named categories.
Userusers.telark.iotusertelarknoA user in the role model.
Groupgroups.telark.iotgrouptelarknoA named set of users and the roles they inherit.
AccessRoleaccessroles.telark.iotroletelarknoScopes granted at a level, plus deny rules.
Passkeypasskeys.telark.iotpktelark-authnoA registered WebAuthn credential.
Sessionsessions.telark.iotsesstelark-authnoAn 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 telark

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

FieldNotes
spec.name, spec.displayName, spec.description, spec.managedIdentity. 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.resourceCountWhat the application is made of.
status.healthstatus (healthy, degraded, down, unknown), reason, readyReplicas, totalReplicas.
status.images, status.ports, status.envVarKeys, status.configMapRefs, status.secretRefs, status.serviceMappings, status.ingressRules, status.metricsInventory, change metrics and workload usage.
status.historygeneration, 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.lastForceSyncjobId, phase (queued, running, completed, failed), requestedAt, startedAt, completedAt, requestedBy, reason, error.
status.conditionsType Published: status True or False, reason Pending, Created or Failed.
status.createdAt, status.lastUpdatedAudit.

ProtectionPlan

Discovery owns the lifecycle; the exporter stores the plan. See Protection plans.

FieldNotes
spec.name, spec.descriptionAt most 64 and 512 characters.
spec.severity, spec.prioritylow, medium, high or critical; an integer from −100 to 100.
spec.scope.typeapplications (scope.applicationRefs) or namespaces (scope.namespaces).
spec.scope.exclusionskinds[] (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.modeaudit or enforce.
spec.timeMode, spec.timeRange.{startAt, endAt}, spec.repeatpermanent, 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.approvalModeautomatic 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.lastUpdatedByAudit.
status.phase, status.reasonpending_approval, scheduled, active, terminated, canceled or failed. The schema also accepts draft, which no code path sets.
status.conditions, status.observedGenerationConditions 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.terminatedByLifecycle stamps.
status.approvalstate (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.windowA 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.

FieldNotes
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.autoAnalyzeInsights switch, model tag, and automatic analysis. Fresh install: true, granite4:350m, false.
spec.snapshots.maxPerAppSnapshot generations kept per application (fresh install: 5).
spec.oidc.enabled, spec.oidc.googleClientID, spec.oidc.egressAllowedGoogle sign-in; egressAllowed lets auth fetch Google's signing keys. Written only by auth, for the bootstrap admin.
spec.selfRegistration.enabledPasskey self-registration (fresh install: false). Written only by auth, for the bootstrap admin.
spec.breakGlassAlerts.notifyAdminsWhether 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.versionCluster version, written by discovery.
status.lastMigration, status.rollbackMigrationThe 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.bootstrapThe 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

FieldNotes
spec.username, spec.fullname, spec.emailProfile. The username allows letters, digits, _ and -, at most 50 characters.
spec.roleRefs[], spec.groupRefs[]Roles assigned directly, and group memberships.
spec.bootstrapMarks 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.lastLoginAtactive, inactive or suspended. Only active users are granted anything.
spec.status.inviteissuedAt, 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.inviteAcceptedAtWhen a passkey last closed a pending enrollment link (Members shows Enrolled). Written only by auth.
spec.avatar, spec.settings, spec.creationDate, spec.lastUpdateDateProfile 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

FieldNotes
spec.name, spec.description, spec.version, spec.categoryRefIdentity.
spec.type, spec.prioritybuilt-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.protectionpreventDeletion, preventModification, preventScopeChanges, lockName, lockCategory, softDelete. With softDelete, a delete marks the role Deleted (with deletedAt) instead of removing it.
spec.statusActive, Inactive, Deprecated or Deleted.
spec.validitytype (permanent, temporary, sessionBased), expiresAt, durationHours, autoRevoke.
Audit fieldscreationDate, 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-id and app.kubernetes.io/managed-by=telark, and the annotations telark.io/plan-name, telark.io/created-by and telark.io/render-hash.
  • Workloads changed through admission carry the annotations telark.io/last-modified-by, telark.io/last-modified-at and telark.io/last-modified-operation, stamped by the chart's telark-inject-modifier Kyverno MutatingPolicy (Secrets excluded).
  • Users, groups and access roles carry the finalizers telark.io/user-cleanup, telark.io/group-cleanup and telark.io/role-cleanup, which the auth service clears.

What this list does not include

  • Kyverno NamespacedValidatingPolicy objects (policies.kyverno.io/v1): the admission policies a protection plan deploys, named telark-<plan id>-<template code>-<hash>. Discovery creates and deletes them; Telark reads them for health.
  • PolicyViolation events 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.