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.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 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} | permanent or time_range. |
spec.approvalMode | automatic or required; absent means automatic. Derived by the server; Production is always required. |
spec.environmentRef, spec.tagRefs[] | One plan environment and at most 20 plan tags. |
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. |
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.userSettings.fetchIntervalSeconds | How often the dashboard refreshes its data (fresh install: 60). |
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. |
status.cluster.version | Cluster version, written by discovery. |
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 an Admin saves it. 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 or plan-tags), 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.
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 a bootstrap admin; never settable through the API. |
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.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. |
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-modifierKyverno policy (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.
Renamed from chart 0.4
Chart 0.4 and older used three API groups and different kinds; there is no in-place migration (see Operations → Upgrading).
| 0.4 | Now |
|---|---|
ApplicationAsResource, GlobalConfig, UserAsResource, GroupAsResource, RoleAsResource (erpi.telark) | Application, TelarkConfig, User, Group, AccessRole |
UserPasskey, UserSession (auth.telark) | Passkey, Session |
CategoryAsClassification (classification.telark) | Category |
assignedRolesIDs, assignedGroupsIDs, assignedUsersIDs | roleRefs, groupRefs, userRefs |
categoryID, environmentID, tagIDs | categoryRef, environmentRef, tagRefs |
participantsIDs, scope.applicationIds | participantRefs, scope.applicationRefs |
crStatus | status.conditions (type Published) |
spec.id | removed (metadata.name) |
label telark.erpi/protection-plan | telark.io/protection-plan |
What this list does not include
- Kyverno
Policyobjects (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 violations feed and plan reports.- Snapshots and protection-plan reports: files on the exporter's volumes, not custom resources.