typekro 0.22.0 → 0.23.0

package/dist/factories/clickhouse/index.js

@@ -0,0 +1,70 @@
+/**
+ * ClickHouse (Altinity clickhouse-operator) Integration for TypeKro
+ *
+ * Provides type-safe factories for managing ClickHouse clusters on Kubernetes
+ * using the OFFICIAL Altinity clickhouse-operator (build-around: the official
+ * `altinity-clickhouse-operator` chart from https://helm.altinity.com,
+ * Apache-2.0 — never hand-rolled manifests).
+ *
+ * ONE OPERATOR PER CLUSTER: the operator is cluster-scoped and owns the
+ * ClickHouse CRDs; install exactly one `clickhouseOperatorBootstrap` per
+ * cluster and point every CHI/CHK at it.
+ *
+ * BUILD-TIME vs RUNTIME: topology (`zones`/`replicas`/`shards`/keeper
+ * presence/user names) is fixed at CONSTRUCTION time via
+ * `makeClickHouseCluster(topology)`; everything else (name, namespace,
+ * version, storage, credentials, keeper host) is proxy-safe RUNTIME spec.
+ *
+ * ## Compositions
+ * - `makeClickHouseCluster(topology)` — build-time topology constructor;
+ *   returns a composition whose runtime spec is fully schema-ref safe and
+ *   whose status exposes the typed connection contract
+ * - `clickHouseCluster` — the default single-node topology
+ * - `clickhouseOperatorBootstrap` — complete operator deployment
+ *   (namespace + shared Helm repo singleton + release)
+ * - `clickhouseHelmRepositoryBootstrap` — shared HelmRepository singleton owner
+ *
+ * ## Resources
+ * - `clickHouseInstallation()` — LOW-LEVEL typed CHI (concrete topology only;
+ *   zone-pinned replica layout, SigNoz-compatible `cluster` name default)
+ * - `clickHouseKeeperInstallation()` — typed CHK (coordination service)
+ * - `clickhouseHelmRepository()` — Altinity Helm chart repository
+ * - `clickhouseOperatorHelmRelease()` — operator installation via Helm
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   clickhouseOperatorBootstrap,
+ *   makeClickHouseCluster,
+ * } from 'typekro/clickhouse';
+ *
+ * // Install the operator (once per cluster)
+ * const operatorFactory = clickhouseOperatorBootstrap.factory('kro', {
+ *   namespace: 'clickhouse-system',
+ * });
+ * await operatorFactory.deploy({ name: 'clickhouse-operator' });
+ *
+ * // Fix the topology at construction, deploy with runtime spec
+ * const clickhouse = makeClickHouseCluster({
+ *   zones: ['us-east-2a', 'us-east-2b'],
+ *   replicas: 2,
+ *   users: [{ name: 'signoz' }],
+ * });
+ * await clickhouse.factory('kro', { namespace: 'observability' }).deploy({
+ *   name: 'signoz-clickhouse',
+ *   namespace: 'observability',
+ *   version: '25.12.5',
+ *   storage: { size: '100Gi', storageClassName: 'gp3-expandable' },
+ *   keeper: { host: 'keeper-signoz.observability.svc.cluster.local' },
+ *   users: { signoz: { passwordSha256Hex: '<sha256-hex>' } },
+ * });
+ * ```
+ *
+ * @see https://github.com/Altinity/clickhouse-operator
+ * @module
+ */
+export * from './compositions/index.js';
+export * from './resources/index.js';
+export * from './types.js';
+export * from './utils/index.js';
+//# sourceMappingURL=index.js.map

package/dist/factories/clickhouse/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/factories/clickhouse/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}

package/dist/factories/clickhouse/resources/helm.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ClickHouse Operator Helm Resource Factories
+ *
+ * Wrappers around the generic Helm factories with Altinity-specific defaults.
+ * Used by the `clickhouseOperatorBootstrap` composition to install the
+ * OFFICIAL Altinity clickhouse-operator (build-around: we wrap the official
+ * chart rather than hand-rolling operator manifests).
+ *
+ * Chart: `altinity-clickhouse-operator` from https://helm.altinity.com
+ * (Apache-2.0). The operator is cluster-scoped and owns the ClickHouse CRDs —
+ * exactly ONE install per cluster.
+ */
+import type { Composable, Enhanced } from '../../../core/types/index.js';
+import { type HelmRepositorySpec, type HelmRepositoryStatus } from '../../helm/helm-repository.js';
+import type { HelmReleaseSpec, HelmReleaseStatus } from '../../helm/types.js';
+import type { ClickHouseHelmRepositoryConfig, ClickHouseOperatorHelmReleaseConfig } from '../types.js';
+/** Official Altinity Helm chart repository URL. */
+export declare const DEFAULT_CLICKHOUSE_REPO_URL = "https://helm.altinity.com";
+/** Default Flux HelmRepository name for the Altinity chart repository. */
+export declare const DEFAULT_CLICKHOUSE_REPO_NAME = "altinity";
+/** Official operator chart name. */
+export declare const CLICKHOUSE_OPERATOR_CHART_NAME = "altinity-clickhouse-operator";
+/** Default altinity-clickhouse-operator chart version. */
+export declare const DEFAULT_CLICKHOUSE_OPERATOR_VERSION = "0.27.1";
+/**
+ * Create a Flux HelmRepository for the official Altinity chart repository.
+ *
+ * @param config - Repository configuration with Altinity defaults
+ * @returns Enhanced HelmRepository resource
+ *
+ * @example
+ * ```typescript
+ * const repo = clickhouseHelmRepository({
+ *   name: 'altinity',
+ *   namespace: 'flux-system',
+ *   id: 'clickhouseHelmRepository',
+ * });
+ * ```
+ */
+export declare function clickhouseHelmRepository(config: Composable<ClickHouseHelmRepositoryConfig>): Enhanced<HelmRepositorySpec, HelmRepositoryStatus>;
+/**
+ * Create a Flux HelmRelease for the Altinity clickhouse-operator.
+ *
+ * IMPORTANT: the operator owns the ClickHouse CRDs and watches cluster-wide —
+ * install exactly ONE release per cluster (enforced by convention via the
+ * `shared` default in `clickhouseOperatorBootstrap`).
+ *
+ * @param config - Release configuration with Altinity defaults
+ * @returns Enhanced HelmRelease resource
+ *
+ * @example
+ * ```typescript
+ * const release = clickhouseOperatorHelmRelease({
+ *   name: 'clickhouse-operator',
+ *   namespace: 'clickhouse-system',
+ *   version: '0.27.1',
+ *   id: 'clickhouseOperatorHelmRelease',
+ * });
+ * ```
+ */
+export declare function clickhouseOperatorHelmRelease(config: Composable<ClickHouseOperatorHelmReleaseConfig>): Enhanced<HelmReleaseSpec, HelmReleaseStatus>;
+//# sourceMappingURL=helm.d.ts.map

package/dist/factories/clickhouse/resources/helm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helm.d.ts","sourceRoot":"","sources":["../../../../src/factories/clickhouse/resources/helm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAEzE,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,KAAK,EACV,8BAA8B,EAC9B,mCAAmC,EACpC,MAAM,aAAa,CAAC;AAErB,mDAAmD;AACnD,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AAEvE,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,aAAa,CAAC;AAEvD,oCAAoC;AACpC,eAAO,MAAM,8BAA8B,iCAAiC,CAAC;AAE7E,0DAA0D;AAC1D,eAAO,MAAM,mCAAmC,WAAW,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,UAAU,CAAC,8BAA8B,CAAC,GACjD,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAgBpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,UAAU,CAAC,mCAAmC,CAAC,GACtD,QAAQ,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAqB9C"}

package/dist/factories/clickhouse/resources/helm.js

@@ -0,0 +1,94 @@
+/**
+ * ClickHouse Operator Helm Resource Factories
+ *
+ * Wrappers around the generic Helm factories with Altinity-specific defaults.
+ * Used by the `clickhouseOperatorBootstrap` composition to install the
+ * OFFICIAL Altinity clickhouse-operator (build-around: we wrap the official
+ * chart rather than hand-rolling operator manifests).
+ *
+ * Chart: `altinity-clickhouse-operator` from https://helm.altinity.com
+ * (Apache-2.0). The operator is cluster-scoped and owns the ClickHouse CRDs —
+ * exactly ONE install per cluster.
+ */
+import { DEFAULT_FLUX_NAMESPACE } from '../../../core/config/defaults.js';
+import { setMetadataField } from '../../../core/metadata/resource-metadata.js';
+import { helmRelease } from '../../helm/helm-release.js';
+import { createHelmRepositoryReadinessEvaluator, helmRepository, } from '../../helm/helm-repository.js';
+import { createLabeledHelmReleaseEvaluator } from '../../helm/readiness-evaluators.js';
+/** Official Altinity Helm chart repository URL. */
+export const DEFAULT_CLICKHOUSE_REPO_URL = 'https://helm.altinity.com';
+/** Default Flux HelmRepository name for the Altinity chart repository. */
+export const DEFAULT_CLICKHOUSE_REPO_NAME = 'altinity';
+/** Official operator chart name. */
+export const CLICKHOUSE_OPERATOR_CHART_NAME = 'altinity-clickhouse-operator';
+/** Default altinity-clickhouse-operator chart version. */
+export const DEFAULT_CLICKHOUSE_OPERATOR_VERSION = '0.27.1';
+/**
+ * Create a Flux HelmRepository for the official Altinity chart repository.
+ *
+ * @param config - Repository configuration with Altinity defaults
+ * @returns Enhanced HelmRepository resource
+ *
+ * @example
+ * ```typescript
+ * const repo = clickhouseHelmRepository({
+ *   name: 'altinity',
+ *   namespace: 'flux-system',
+ *   id: 'clickhouseHelmRepository',
+ * });
+ * ```
+ */
+export function clickhouseHelmRepository(config) {
+    const repo = helmRepository({
+        name: config.name || DEFAULT_CLICKHOUSE_REPO_NAME,
+        namespace: config.namespace || DEFAULT_FLUX_NAMESPACE,
+        url: config.url || DEFAULT_CLICKHOUSE_REPO_URL,
+        interval: config.interval || '5m',
+        ...(config.id && { id: config.id }),
+    }).withReadinessEvaluator(createHelmRepositoryReadinessEvaluator('ClickHouse'));
+    // The chart repository is one cluster-level Flux source shared by every
+    // consumer — never torn down with an individual instance.
+    setMetadataField(repo, 'scopes', ['cluster']);
+    return repo;
+}
+/**
+ * Create a Flux HelmRelease for the Altinity clickhouse-operator.
+ *
+ * IMPORTANT: the operator owns the ClickHouse CRDs and watches cluster-wide —
+ * install exactly ONE release per cluster (enforced by convention via the
+ * `shared` default in `clickhouseOperatorBootstrap`).
+ *
+ * @param config - Release configuration with Altinity defaults
+ * @returns Enhanced HelmRelease resource
+ *
+ * @example
+ * ```typescript
+ * const release = clickhouseOperatorHelmRelease({
+ *   name: 'clickhouse-operator',
+ *   namespace: 'clickhouse-system',
+ *   version: '0.27.1',
+ *   id: 'clickhouseOperatorHelmRelease',
+ * });
+ * ```
+ */
+export function clickhouseOperatorHelmRelease(config) {
+    // Pass values directly — the core proxy system handles serialization.
+    return helmRelease({
+        name: config.name,
+        namespace: config.namespace || 'clickhouse-system',
+        chart: {
+            repository: DEFAULT_CLICKHOUSE_REPO_URL,
+            name: CLICKHOUSE_OPERATOR_CHART_NAME,
+            version: config.version || DEFAULT_CLICKHOUSE_OPERATOR_VERSION,
+        },
+        sourceRef: {
+            name: config.repositoryName || DEFAULT_CLICKHOUSE_REPO_NAME,
+            namespace: DEFAULT_FLUX_NAMESPACE,
+            kind: 'HelmRepository',
+        },
+        driftDetection: { mode: 'enabled' },
+        values: config.values || {},
+        ...(config.id && { id: config.id }),
+    }).withReadinessEvaluator(createLabeledHelmReleaseEvaluator('ClickHouse'));
+}
+//# sourceMappingURL=helm.js.map

package/dist/factories/clickhouse/resources/helm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helm.js","sourceRoot":"","sources":["../../../../src/factories/clickhouse/resources/helm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,6CAA6C,CAAC;AAE/E,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EACL,sCAAsC,EACtC,cAAc,GAGf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,iCAAiC,EAAE,MAAM,oCAAoC,CAAC;AAOvF,mDAAmD;AACnD,MAAM,CAAC,MAAM,2BAA2B,GAAG,2BAA2B,CAAC;AAEvE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,4BAA4B,GAAG,UAAU,CAAC;AAEvD,oCAAoC;AACpC,MAAM,CAAC,MAAM,8BAA8B,GAAG,8BAA8B,CAAC;AAE7E,0DAA0D;AAC1D,MAAM,CAAC,MAAM,mCAAmC,GAAG,QAAQ,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAkD;IAElD,MAAM,IAAI,GAAG,cAAc,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,4BAA4B;QACjD,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,sBAAsB;QACrD,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,2BAA2B;QAC9C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;KACpC,CAAC,CAAC,sBAAsB,CACvB,sCAAsC,CAAC,YAAY,CAAC,CACC,CAAC;IAExD,wEAAwE;IACxE,0DAA0D;IAC1D,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAE9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAuD;IAEvD,sEAAsE;IACtE,OAAO,WAAW,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,mBAAmB;QAClD,KAAK,EAAE;YACL,UAAU,EAAE,2BAA2B;YACvC,IAAI,EAAE,8BAA8B;YACpC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,mCAAmC;SAC/D;QACD,SAAS,EAAE;YACT,IAAI,EAAE,MAAM,CAAC,cAAc,IAAI,4BAA4B;YAC3D,SAAS,EAAE,sBAAsB;YACjC,IAAI,EAAE,gBAAgB;SACvB;QACD,cAAc,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QACnC,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;QAC3B,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;KACpC,CAAC,CAAC,sBAAsB,CACvB,iCAAiC,CAAC,YAAY,CAAC,CACA,CAAC;AACpD,CAAC"}

package/dist/factories/clickhouse/resources/index.d.ts

@@ -0,0 +1,4 @@
+export * from './helm.js';
+export * from './installation.js';
+export * from './keeper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/factories/clickhouse/resources/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/factories/clickhouse/resources/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}

package/dist/factories/clickhouse/resources/index.js

@@ -0,0 +1,4 @@
+export * from './helm.js';
+export * from './installation.js';
+export * from './keeper.js';
+//# sourceMappingURL=index.js.map

package/dist/factories/clickhouse/resources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/factories/clickhouse/resources/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}

package/dist/factories/clickhouse/resources/installation.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ClickHouseInstallation (CHI) Factory
+ *
+ * Compiles a high-level typed config into a `clickhouse.altinity.com/v1`
+ * ClickHouseInstallation managed by the Altinity clickhouse-operator.
+ *
+ * THE POINT of this typed factory is the zone-pinned layout: the operator's
+ * `podDistribution` supports only the `kubernetes.io/hostname` topologyKey
+ * (Altinity/clickhouse-operator#772), so per-zone spreading must be compiled
+ * as a per-replica `layout.replicas:` list with zone-pinned pod templates.
+ * On EKS, EBS volumes are zonal — a replica rescheduled into another AZ
+ * strands its PVC (production incident) — so `zones` should be set for any
+ * multi-replica production CHI.
+ *
+ * CHI shape follows the official examples
+ * (docs/chi-examples/01-simple-layout-01-1shard-1repl.yaml and
+ * 14-zones-distribution-01.yaml in the operator repo).
+ */
+import type { Composable, Enhanced, ResourceStatus } from '../../../core/types/index.js';
+import type { ClickHouseInstallationConfig, ClickHouseInstallationSpec, ClickHouseInstallationStatus } from '../types.js';
+/**
+ * Known CHI/CHK reconcile status strings.
+ *
+ * Source: clickhouse-operator `pkg/apis/clickhouse.altinity.com/v1/type_status.go`
+ * (StatusInProgress/StatusCompleted/StatusAborted/StatusTerminating). The
+ * operator writes them to `status.status`; `Completed` means the installation
+ * is fully reconciled.
+ */
+export declare const CHI_STATUS: {
+    readonly IN_PROGRESS: "InProgress";
+    readonly COMPLETED: "Completed";
+    readonly ABORTED: "Aborted";
+    readonly TERMINATING: "Terminating";
+};
+/**
+ * CHI/CHK Readiness Evaluator
+ *
+ * Keys off the operator-reported `status.status` reconcile state (see
+ * CHI_STATUS). Unlike condition-based CRDs, the clickhouse-operator reports a
+ * single status string plus host progress counters.
+ */
+export declare function chiReadinessEvaluator(liveResource: unknown): ResourceStatus;
+/**
+ * Default logical cluster name.
+ *
+ * SIGNOZ COMPATIBILITY: SigNoz's ClickHouse migrations hardcode the cluster
+ * name `cluster`, so a CHI consumed by SigNoz MUST keep this default.
+ */
+export declare const DEFAULT_CHI_CLUSTER_NAME = "cluster";
+/**
+ * ClickHouseInstallation Factory (LOW-LEVEL, concrete topology)
+ *
+ * Creates a ClickHouse cluster managed by the Altinity clickhouse-operator.
+ *
+ * BUILD-TIME topology fields (`shards`, `replicas`, `zones`, user names) must
+ * be concrete JS values — the factory throws loudly if any receives a schema
+ * reference (the compiler enumerates templates/replica entries from them).
+ * Prefer `makeClickHouseCluster()` in compositions: it fixes the topology at
+ * construction time and exposes only proxy-safe runtime spec.
+ *
+ * @param config - High-level installation configuration
+ * @returns Enhanced ClickHouseInstallation resource with readiness evaluation
+ *
+ * @example
+ * ```typescript
+ * const chi = clickHouseInstallation({
+ *   name: 'signoz-clickhouse',
+ *   namespace: 'observability',
+ *   version: '25.12.5',                     // SigNoz-coupled server version
+ *   shards: 1,
+ *   replicas: 2,
+ *   zones: ['us-east-2a', 'us-east-2b'],    // zone-pinned replicas (EBS is zonal)
+ *   storage: { size: '100Gi', storageClassName: 'gp3-expandable' },
+ *   users: [{ name: 'signoz', passwordSha256Hex: '...', networksIp: ['::/0'] }],
+ *   keeper: { host: 'keeper-signoz.observability.svc.cluster.local' },
+ *   id: 'signozClickhouse',
+ * });
+ * ```
+ */
+declare function createClickHouseInstallationResource(config: Composable<ClickHouseInstallationConfig>): Enhanced<ClickHouseInstallationSpec, ClickHouseInstallationStatus>;
+export declare const clickHouseInstallation: typeof createClickHouseInstallationResource;
+export {};
+//# sourceMappingURL=installation.d.ts.map

package/dist/factories/clickhouse/resources/installation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../../../../src/factories/clickhouse/resources/installation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGzF,OAAO,KAAK,EAEV,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,EAC7B,MAAM,aAAa,CAAC;AAIrB;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;;CAKb,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,OAAO,GAAG,cAAc,CAoD3E;AAKD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,YAAY,CAAC;AA6LlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iBAAS,oCAAoC,CAC3C,MAAM,EAAE,UAAU,CAAC,4BAA4B,CAAC,GAC/C,QAAQ,CAAC,0BAA0B,EAAE,4BAA4B,CAAC,CAmBpE;AAED,eAAO,MAAM,sBAAsB,6CAAuC,CAAC"}

package/dist/factories/clickhouse/resources/installation.js

@@ -0,0 +1,316 @@
+/**
+ * ClickHouseInstallation (CHI) Factory
+ *
+ * Compiles a high-level typed config into a `clickhouse.altinity.com/v1`
+ * ClickHouseInstallation managed by the Altinity clickhouse-operator.
+ *
+ * THE POINT of this typed factory is the zone-pinned layout: the operator's
+ * `podDistribution` supports only the `kubernetes.io/hostname` topologyKey
+ * (Altinity/clickhouse-operator#772), so per-zone spreading must be compiled
+ * as a per-replica `layout.replicas:` list with zone-pinned pod templates.
+ * On EKS, EBS volumes are zonal — a replica rescheduled into another AZ
+ * strands its PVC (production incident) — so `zones` should be set for any
+ * multi-replica production CHI.
+ *
+ * CHI shape follows the official examples
+ * (docs/chi-examples/01-simple-layout-01-1shard-1repl.yaml and
+ * 14-zones-distribution-01.yaml in the operator repo).
+ */
+import { isCelExpression, isKubernetesRef } from '../../../utils/type-guards.js';
+import { createResource } from '../../shared.js';
+import { assertPositiveIntegerCount } from '../utils/validation.js';
+import { compileZonePinnedLayout } from '../utils/zone-layout.js';
+/**
+ * Known CHI/CHK reconcile status strings.
+ *
+ * Source: clickhouse-operator `pkg/apis/clickhouse.altinity.com/v1/type_status.go`
+ * (StatusInProgress/StatusCompleted/StatusAborted/StatusTerminating). The
+ * operator writes them to `status.status`; `Completed` means the installation
+ * is fully reconciled.
+ */
+export const CHI_STATUS = {
+    IN_PROGRESS: 'InProgress',
+    COMPLETED: 'Completed',
+    ABORTED: 'Aborted',
+    TERMINATING: 'Terminating',
+};
+/**
+ * CHI/CHK Readiness Evaluator
+ *
+ * Keys off the operator-reported `status.status` reconcile state (see
+ * CHI_STATUS). Unlike condition-based CRDs, the clickhouse-operator reports a
+ * single status string plus host progress counters.
+ */
+export function chiReadinessEvaluator(liveResource) {
+    const resource = liveResource;
+    const status = resource?.status;
+    if (!status || status.status === undefined) {
+        return {
+            ready: false,
+            message: 'Installation has no status yet',
+            reason: 'StatusMissing',
+        };
+    }
+    if (status.status === CHI_STATUS.COMPLETED) {
+        return {
+            ready: true,
+            message: `Installation reconciled (${status.hostsCompletedCount ?? status.hostsCount ?? 0}/${status.hostsCount ?? 0} hosts)`,
+            reason: 'Completed',
+        };
+    }
+    if (status.status === CHI_STATUS.IN_PROGRESS) {
+        return {
+            ready: false,
+            message: `Reconcile in progress (${status.hostsCompletedCount ?? 0}/${status.hostsCount ?? 0} hosts)`,
+            reason: 'InProgress',
+        };
+    }
+    if (status.status === CHI_STATUS.ABORTED) {
+        return {
+            ready: false,
+            message: `Reconcile aborted${status.errors?.length ? `: ${status.errors[0]}` : ''}`,
+            reason: 'Aborted',
+        };
+    }
+    if (status.status === CHI_STATUS.TERMINATING) {
+        return {
+            ready: false,
+            message: 'Installation is terminating',
+            reason: 'Terminating',
+        };
+    }
+    return {
+        ready: false,
+        message: `Unknown installation status: ${status.status}`,
+        reason: 'UnknownStatus',
+    };
+}
+/** Default ClickHouse server image repository. */
+const DEFAULT_CLICKHOUSE_IMAGE_REPOSITORY = 'clickhouse/clickhouse-server';
+/**
+ * Default logical cluster name.
+ *
+ * SIGNOZ COMPATIBILITY: SigNoz's ClickHouse migrations hardcode the cluster
+ * name `cluster`, so a CHI consumed by SigNoz MUST keep this default.
+ */
+export const DEFAULT_CHI_CLUSTER_NAME = 'cluster';
+/** Name of the generated data volume claim template. */
+const DATA_VOLUME_TEMPLATE = 'data-volume';
+/** Base name for generated pod templates. */
+const POD_TEMPLATE_BASE = 'clickhouse';
+/** True when the value is a graph reference (KubernetesRef or CEL expression). */
+function isGraphRef(value) {
+    return isKubernetesRef(value) || isCelExpression(value);
+}
+/**
+ * LOUD build-time validation: the CHI compiler BRANCHES on these fields
+ * (zone round-robin, template enumeration, path-keyed user settings), so a
+ * KubernetesRef/CEL expression here can never work — it would either crash
+ * graph construction or serialize garbage paths. Fail fast with a pointer to
+ * the build-time constructor instead of leaking `__KUBERNETES_REF__` markers.
+ */
+function assertConcreteTopology(config) {
+    const reject = (field) => {
+        throw new Error(`clickHouseInstallation: '${field}' is a BUILD-TIME topology field and received a ` +
+            `schema reference or CEL expression. The compiler enumerates pod templates and ` +
+            `per-replica layout entries from it, so it must be a concrete JS value. ` +
+            `For schema-driven compositions, fix the topology at construction time with ` +
+            `makeClickHouseCluster({ zones, replicas, shards, users }) and pass only runtime ` +
+            `fields (name, version, storage, credentials, keeper host) through the spec.`);
+    };
+    if (isGraphRef(config.shards))
+        reject('shards');
+    if (isGraphRef(config.replicas))
+        reject('replicas');
+    if (isGraphRef(config.zones))
+        reject('zones');
+    if (Array.isArray(config.zones)) {
+        for (const zone of config.zones) {
+            if (isGraphRef(zone))
+                reject('zones[]');
+        }
+    }
+    if (isGraphRef(config.users))
+        reject('users');
+    if (Array.isArray(config.users)) {
+        config.users.forEach((user, index) => {
+            if (isGraphRef(user))
+                reject(`users[${index}]`);
+            if (isGraphRef(user.name))
+                reject(`users[${index}].name`);
+        });
+    }
+}
+/**
+ * Flatten the typed users ARRAY to the operator's path-keyed format.
+ *
+ * User names become path fragments (`<user>/password_sha256_hex`) — they are
+ * validated concrete by `assertConcreteTopology`. The password hash and
+ * networks are plain VALUES and may be schema references (they serialize to
+ * CEL cleanly).
+ */
+function compileUsers(users) {
+    const compiled = {};
+    for (const user of users) {
+        if (user.passwordSha256Hex !== undefined) {
+            compiled[`${user.name}/password_sha256_hex`] = user.passwordSha256Hex;
+        }
+        if (user.networksIp !== undefined) {
+            compiled[`${user.name}/networks/ip`] = user.networksIp;
+        }
+    }
+    return compiled;
+}
+/** Compile the high-level config into a full CHI spec. */
+function compileInstallationSpec(config) {
+    assertConcreteTopology(config);
+    const shards = config.shards ?? 1;
+    const replicas = config.replicas ?? 1;
+    // SHARED count validation for BOTH layout paths: the plain homogeneous
+    // layout would otherwise emit `shardsCount: 0` / `replicasCount: 0` —
+    // invalid operator input the zone-pinned path already rejected.
+    assertPositiveIntegerCount('clickHouseInstallation', 'shards', shards);
+    assertPositiveIntegerCount('clickHouseInstallation', 'replicas', replicas);
+    const clusterName = config.clusterName ?? DEFAULT_CHI_CLUSTER_NAME;
+    const image = config.image ?? `${DEFAULT_CLICKHOUSE_IMAGE_REPOSITORY}:${config.version}`;
+    const zones = config.zones ?? [];
+    // Shared ClickHouse server pod spec (per-zone templates add affinity).
+    const podSpec = {
+        containers: [
+            {
+                name: 'clickhouse',
+                image,
+                ...(config.podResources && { resources: config.podResources }),
+            },
+        ],
+    };
+    // Storage claim: only storageClassName is set from input. On EKS the class
+    // should be a WaitForFirstConsumer + allowVolumeExpansion gp3 StorageClass
+    // so the PVC binds in the zone the scheduler picks (and can expand later);
+    // WaitForFirstConsumer is a StorageClass property, not a PVC field.
+    const volumeClaimTemplates = [
+        {
+            name: DATA_VOLUME_TEMPLATE,
+            spec: {
+                accessModes: ['ReadWriteOnce'],
+                resources: { requests: { storage: config.storage.size } },
+                ...(config.storage.storageClassName && {
+                    storageClassName: config.storage.storageClassName,
+                }),
+            },
+        },
+    ];
+    let layout;
+    let podTemplates;
+    let defaultPodTemplate;
+    if (zones.length > 0) {
+        // Zone-pinned per-replica layout: NO replicasCount — the explicit
+        // replicas list defines the replica count, and each replica references
+        // its zone's nodeAffinity-pinned pod template (round-robin across zones
+        // when replicas > zones.length). See utils/zone-layout.ts.
+        const zonePinned = compileZonePinnedLayout({
+            replicaCount: replicas,
+            zones,
+            podTemplateBaseName: POD_TEMPLATE_BASE,
+            podSpec,
+        });
+        podTemplates = zonePinned.podTemplates;
+        layout = {
+            clusters: [
+                {
+                    name: clusterName,
+                    layout: {
+                        shardsCount: shards,
+                        replicas: zonePinned.replicas,
+                    },
+                },
+            ],
+        };
+    }
+    else {
+        // Plain homogeneous layout: shardsCount x replicasCount with one shared
+        // pod template applied via defaults.
+        podTemplates = [{ name: POD_TEMPLATE_BASE, spec: podSpec }];
+        defaultPodTemplate = POD_TEMPLATE_BASE;
+        layout = {
+            clusters: [
+                {
+                    name: clusterName,
+                    layout: {
+                        shardsCount: shards,
+                        replicasCount: replicas,
+                    },
+                },
+            ],
+        };
+    }
+    return {
+        defaults: {
+            templates: {
+                ...(defaultPodTemplate && { podTemplate: defaultPodTemplate }),
+                dataVolumeClaimTemplate: DATA_VOLUME_TEMPLATE,
+            },
+        },
+        configuration: {
+            ...layout,
+            // The operator's `zookeeper` section serves clickhouse-keeper too.
+            ...(config.keeper && {
+                zookeeper: {
+                    nodes: [
+                        { host: config.keeper.host, port: config.keeper.port ?? 2181 },
+                    ],
+                },
+            }),
+            ...(config.users && { users: compileUsers(config.users) }),
+        },
+        templates: {
+            podTemplates,
+            volumeClaimTemplates,
+        },
+    };
+}
+/**
+ * ClickHouseInstallation Factory (LOW-LEVEL, concrete topology)
+ *
+ * Creates a ClickHouse cluster managed by the Altinity clickhouse-operator.
+ *
+ * BUILD-TIME topology fields (`shards`, `replicas`, `zones`, user names) must
+ * be concrete JS values — the factory throws loudly if any receives a schema
+ * reference (the compiler enumerates templates/replica entries from them).
+ * Prefer `makeClickHouseCluster()` in compositions: it fixes the topology at
+ * construction time and exposes only proxy-safe runtime spec.
+ *
+ * @param config - High-level installation configuration
+ * @returns Enhanced ClickHouseInstallation resource with readiness evaluation
+ *
+ * @example
+ * ```typescript
+ * const chi = clickHouseInstallation({
+ *   name: 'signoz-clickhouse',
+ *   namespace: 'observability',
+ *   version: '25.12.5',                     // SigNoz-coupled server version
+ *   shards: 1,
+ *   replicas: 2,
+ *   zones: ['us-east-2a', 'us-east-2b'],    // zone-pinned replicas (EBS is zonal)
+ *   storage: { size: '100Gi', storageClassName: 'gp3-expandable' },
+ *   users: [{ name: 'signoz', passwordSha256Hex: '...', networksIp: ['::/0'] }],
+ *   keeper: { host: 'keeper-signoz.observability.svc.cluster.local' },
+ *   id: 'signozClickhouse',
+ * });
+ * ```
+ */
+function createClickHouseInstallationResource(config) {
+    const spec = compileInstallationSpec(config);
+    return createResource({
+        apiVersion: 'clickhouse.altinity.com/v1',
+        kind: 'ClickHouseInstallation',
+        metadata: {
+            name: config.name,
+            ...(config.namespace && { namespace: config.namespace }),
+        },
+        spec,
+        ...(config.id && { id: config.id }),
+    }, { scope: 'namespaced', dnsAddressable: true }).withReadinessEvaluator(chiReadinessEvaluator);
+}
+export const clickHouseInstallation = createClickHouseInstallationResource;
+//# sourceMappingURL=installation.js.map