Community Core Operations

Konduo Community Core provides the shared operating layer for plugin-based resource registration, access control, audit records, alert workflows, metric linkage, dashboards, and diagnostics. Domain-specific behavior belongs to plugins; Core keeps registration, rendering, permissions, and lifecycle behavior consistent across those plugins.

Primary Responsibilities

1. Register and manage resource, metric source, and alert channel plugins.
2. Handle users, roles, resource permissions, and audit records through one common model.
3. Render resource dashboards, diagnostics, and alert-rule pages from host-rendered schemas.
4. Run plugin health checks, alert evaluation, and delivery sessions through shared workflows.
5. Connect resource-owned logical metrics to concrete metric source queries through mapping packs.

Operating Flow

• Review available resource plugins, metric sources, and alert channels in admin settings.
• Register resources with plugin-specific connection settings and metric linkage.
• Run connection tests and resource health checks after registration.
• Use dashboards and diagnostics together to review current state, historical risk, and metric coverage.
• Some event panels show a check and a short label such as “No errors” when a supported query succeeds with no event series in its requested scope. Timelines keep the selected time axis, a faint dashed guide and the caption “No events observed in this range”; they can be expanded even when empty. The guide is not a measured zero. Query information explains the query mode and range; an instant value does not cover the whole selected range or prove resource health. Actual zero samples remain charts, and missing metrics and query failures keep their unknown/error state.
• Tune alert rules, routes, workflows, and delivery history per resource.

Unified Resource Alert Rules

Resource Alerts shows one list with Built-in and Custom labels beside rule names. Search, a status filter, Rule/Severity header sorting and pagination operate on the same inventory. Clicking a sorted header reverses its direction. System access is monitored automatically and is omitted from this inventory, including search and counts. Its incidents, history and notification delivery settings remain available. Core rules, including metric collection rules, are read-only. Managed rules allow condition tuning; custom rules allow full editing, toggling and deletion. Configure delivery workflows/routes and silences separately from rule definitions.

Resource Metric Details And Custom Threshold Alerts

Use Existing Metric Name Prefix and New Metric Name Prefix in the resource's Metrics settings. Leave the existing prefix empty and enter prefix_ as the new prefix to prepend it to every mapped name. Set existing pg_ and new prefix_ to query prefix_up instead of pg_up; unmatched names stay unchanged. An empty new prefix removes the existing prefix; both empty keep original names. Dashboards, alerts, inspection, and diagnostic evidence share these settings. Keep resource label filters; other exporter name or unit differences still need mapping corrections. Removal that produces an invalid metric name is rejected.

Use the information button on a resource metric panel to open Metric details and settings. It has four tabs:

• Metric information describes the panel, metric, and display unit.
• Chart Filter controls which returned series are displayed for that panel.
• Alerts creates a resource-specific custom threshold rule when the panel is eligible.
• Query details shows the query blueprint, mapping-pack resolution, and resolved query evidence.

Create A Threshold Rule From A Chart

Open Alerts to review the rules already registered for the chart's logical metrics, including plugin-managed and custom rules that are disabled. The tab shows a related-rule count after a successful lookup. A failed lookup is shown as an error, not as an empty rule list.

Review each rule's condition, severity, enabled state, metric source, and query scope before adding another rule. A shared logical metric does not guarantee the same aggregation or series filter. Enabled configuration does not prove that evaluation or notification delivery is currently healthy. Resource-read permission allows this review; creation still requires resource-management permission.

Choose Add new rule to open the custom-rule form in that tab. The editor is part of Metric details and settings; it does not open another modal or add a separate chart action. The unified Alert Rules list, showing Custom labels, on the Resource Alert Page remains the place to review, edit, enable, disable, or delete the saved rules.

Opening the tab does not open a draft. A rule is created only after you enter a threshold and save it. Konduo does not infer a threshold from displayed samples or from the dashboard's selected time range. After saving, the related rules are refreshed. Back to rules returns to the list and asks before discarding an edited draft. Existing rule settings remain available through their rule page links, including on charts that do not support creating a new rule.

The initial chart-to-alert path accepts only a semantically safe, single logical-metric time-series preset: it must have one top-level query blueprint, or exactly one blueprint in queries. The draft carries that blueprint's logical metric key, operation, aggregation, query window, grouping, and parameters. The rule belongs to the selected resource and queries its linked metric-source instance. For a resource that provides its own metrics, the resource itself is the source. These IDs can differ; the target resource still determines the managed query scope.

The Alerts tab explains why creation is unavailable when the panel has no resource context or query blueprint, uses multiple metrics, contains dynamic variables or placeholders, has a query-stage filter, has temporary dashboard job or instance filters, uses a custom or unsupported instance selector, reduces values in the display (such as stat, gauge, bar, or pie panels), or declares a display transform such as top-N. A resource scope defined in the resource configuration remains eligible because alert evaluation rebuilds that managed selector independently.

A display-stage Chart Filter can seed the new rule only when it is an exact post-query series include or exclude filter. It then limits the alert's returned series after the metric query. Saving a Chart Filter never changes an existing alert rule, collected metrics, or the underlying metric query.

Set The Evaluation Correctly

The dashboard range is a viewing range for chart history. It does not define the alert evaluation window, the required duration, or the threshold.

When the chart blueprint specifies a Query Window, the draft preserves it as read-only. Otherwise, Window (seconds) sets the evaluation data window. For (seconds) is how long the condition must remain true before the rule fires. Enter the threshold as the underlying numeric sample value, before the chart applies display scaling. A panel's unit or axis-unit metadata controls presentation and is not a conversion guarantee for the alert value. Do not enter a value converted for a formatted chart label; for example, use the underlying byte value when the chart displays a scaled byte unit.

There is no editable no-data policy in this custom-rule form. When a successful query returns no sample for a series, Konduo does not create a new alert for that series. When a previously pending or firing series disappears, its state becomes inactive, resolving a firing alert. Query or plugin errors remain telemetry-unavailable and do not resolve the current alert state.

Custom rules use the existing resource-manager-protected resource alert API and the same Core resource permissions as the Resource Alert Page. A Global Admin or an authorized delegated Resource Admin can manage the resource-scoped rule; this does not grant global connector, template, or silence administration. Creating a rule does not create a delivery route. Configure or review its receivers, routes, and delivery behavior through the existing resource alert delivery settings after saving the rule.

Initial Administrator Provisioning

Konduo does not create a known default administrator password in production. After schema migration and reference-data seeding, a new database without an active administrator reports setup_required from /readyz and admin-bootstrap-status. An operator must then create the initial administrator with the one-time command.

Docker Compose

Connect to the server running Docker Compose and open a Bash terminal in the directory containing the compose.yml and .env used for installation. Run these commands on the server, not in the browser or a shell inside the container.

The backend and database must be running. If your installation uses different file names or paths, replace --env-file and -f in every command below with the options used during installation.

docker compose --env-file .env -f compose.yml exec -T backend \
  /app/konduo-backend admin-bootstrap-status

If the state is setup_required, create the initial administrator below. Password input is hidden and passed through standard input.

read -rsp 'Initial administrator password: ' INITIAL_ADMIN_PASSWORD
echo
printf '%s\n' "$INITIAL_ADMIN_PASSWORD" |
  docker compose --env-file .env -f compose.yml exec -T backend \
    /app/konduo-backend admin-bootstrap --username admin --password-stdin
unset INITIAL_ADMIN_PASSWORD

• This example creates the username admin. Change --username to use another name.
• The password must meet the current authentication policy. INITIAL_ADMIN_PASSWORD is a temporary shell variable used by this command; adding it to .env does not create an account.
• Run the status command again after creation and confirm that it reports complete.
• If the state is already complete, use the existing administrator account. Running bootstrap again does not change its password.

Kubernetes

Create a one-shot Job that uses the same scratch image, database/TLS settings, and encryption key as the backend. Run the binary directly: no shell or staging container is needed. Mount the Secret at /run/konduo-bootstrap with defaultMode: 0440 and run the Pod as UID/GID and fsGroup 10001 so the Kubernetes password -> ..data/password projection remains readable only by the workload group. Set activeDeadlineSeconds to at least 600, and run:

admin-bootstrap --username admin --password-file /run/konduo-bootstrap/password

Do not wait for backend /readyz: a new installation remains setup_required until this Job succeeds. The command waits up to five minutes for concurrent automatic schema migration and seed completion, then fails on a deadline or a ledger integrity error. Job retries are safe. Once bootstrap is complete, another attempt succeeds without changing the existing password. Confirm the complete state, then delete the initial-password Secret and Job.

For an isolated Kubernetes release, use the checksum-verified offline bundle's kubernetes/install.py and packaged charts with a JSON configuration that names an explicit kubeconfig and context. The configuration contains only image references and Secret names/keys. Create Secret values through the platform secret system; do not add them to Helm values, JSON, shell arguments, or logs. The bundle does not install CloudNativePG, CRDs, or the operator. Import every image archive into every Kubernetes node runtime, or mirror them to the private registry first: loading an archive into a workstation Docker daemon does not make it available to the cluster. For the independent CNPG database, use its stable -rw Service and verify-full TLS CA configuration.

Run release smoke only with an explicit kubeconfig, context, and namespace. The smoke target must match the installer configuration; it never falls back to the current kubectl context. Preserve database and runtime Secret identities during upgrades. Changing bundled, operator, or external database mode is a separate migration with a verified data copy or restore.

Login and Recovery Boundaries

• The first login must change the password immediately.
• The password must satisfy the current local authentication policy.
• Running bootstrap again in the complete state does not change the existing account or password.
• If no active administrator remains after bootstrap completed, the state becomes recovery_required. Do not use bootstrap to create a replacement; follow the approved password-reset or verified-backup recovery procedure.
• A successful password reset revokes existing login sessions and refresh tokens and requires another password change at the next login.

read -rsp 'Temporary password: ' TEMPORARY_PASSWORD
echo
printf '%s\n' "$TEMPORARY_PASSWORD" | \
  docker compose --env-file .env -f compose.yml exec -T backend \
    /app/konduo-backend password-reset --user admin --password-stdin
unset TEMPORARY_PASSWORD

Boundaries

• Core owns shared lifecycle, permissions, audit, alert workflow, and UI hosting.
• Plugins own domain configuration schemas, diagnostic evidence, logical metrics, mapping packs, and management actions.
• Sensitive credentials are used only at the storage and execution boundary and must not be exposed in health or diagnostic payloads.
• Plugin-specific UI behavior should be exposed through schemas and contributions, not hard-coded into Core.

Related Documents

• docs/community-edition-boundary.md
• docs/plugin-extension-point-policy.md
• docs/frontend-plugin-ui-contract.md
• docs/plugin-diagnostics-contract.md
• docs/manual-source-contract.md
• backend/docs/administrator-bootstrap.md