@kustodian/schema 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kustodian/schema",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "JSON Schema definitions for Kustodian YAML validation",
   "type": "module",
   "main": "./src/index.ts",
@@ -37,6 +37,5 @@
   },
   "dependencies": {
     "zod": "^3.25.30"
-  },
-  "devDependencies": {}
+  }
 }

package/src/cluster.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 
 import { api_version_schema, metadata_schema, values_schema } from './common.js';
 import { ssh_config_schema } from './node-list.js';
+import { preservation_mode_schema } from './template.js';
 
 /**
  * Git repository configuration for a cluster.
@@ -30,6 +31,22 @@ export const oci_config_schema = z.object({
 
 export type OciConfigType = z.infer<typeof oci_config_schema>;
 
+/**
+ * Kustomization override configuration within a cluster.
+ *
+ * Allows overriding kustomization enablement and preservation from template defaults.
+ */
+export const kustomization_override_schema = z.object({
+  enabled: z.boolean(),
+  preservation: z
+    .object({
+      mode: preservation_mode_schema,
+    })
+    .optional(),
+});
+
+export type KustomizationOverrideType = z.infer<typeof kustomization_override_schema>;
+
 /**
  * Template enablement configuration within a cluster.
  */
@@ -37,6 +54,15 @@ export const template_config_schema = z.object({
   name: z.string().min(1),
   enabled: z.boolean().optional().default(true),
   values: values_schema.optional(),
+  kustomizations: z
+    .record(
+      z.string(), // kustomization name
+      z.union([
+        z.boolean(), // Simple: just enabled/disabled
+        kustomization_override_schema, // Advanced: with preservation
+      ]),
+    )
+    .optional(),
 });
 
 export type TemplateConfigType = z.infer<typeof template_config_schema>;
@@ -72,6 +98,56 @@ export const github_config_schema = z.object({
 
 export type GithubConfigType = z.infer<typeof github_config_schema>;
 
+/**
+ * Bootstrap credential configuration for secret providers.
+ * Allows obtaining credentials from another secret provider.
+ */
+export const bootstrap_credential_schema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('1password'),
+    ref: z.string().min(1),
+  }),
+  z.object({
+    type: z.literal('doppler'),
+    project: z.string().min(1),
+    config: z.string().min(1),
+    secret: z.string().min(1),
+  }),
+]);
+
+export type BootstrapCredentialType = z.infer<typeof bootstrap_credential_schema>;
+
+/**
+ * Doppler secret provider configuration at cluster level.
+ */
+export const doppler_config_schema = z.object({
+  project: z.string().min(1),
+  config: z.string().min(1),
+  service_token: bootstrap_credential_schema.optional(),
+});
+
+export type DopplerConfigType = z.infer<typeof doppler_config_schema>;
+
+/**
+ * 1Password secret provider configuration at cluster level.
+ */
+export const onepassword_config_schema = z.object({
+  vault: z.string().min(1),
+  service_account_token: bootstrap_credential_schema.optional(),
+});
+
+export type OnePasswordConfigType = z.infer<typeof onepassword_config_schema>;
+
+/**
+ * Secret providers configuration at cluster level.
+ */
+export const secrets_config_schema = z.object({
+  doppler: doppler_config_schema.optional(),
+  onepassword: onepassword_config_schema.optional(),
+});
+
+export type SecretsConfigType = z.infer<typeof secrets_config_schema>;
+
 /**
  * Cluster specification.
  */
@@ -86,6 +162,7 @@ export const cluster_spec_schema = z
     plugins: z.array(plugin_config_schema).optional(),
     node_defaults: node_defaults_schema.optional(),
     nodes: z.array(z.string()).optional(),
+    secrets: secrets_config_schema.optional(),
   })
   .refine((data) => data.git || data.oci, {
     message: "Either 'git' or 'oci' must be specified",

package/src/common.ts

@@ -54,6 +54,31 @@ export const registry_config_schema = z.object({
 
 export type RegistryConfigType = z.infer<typeof registry_config_schema>;
 
+/**
+ * Helm repository configuration for helm chart version substitutions.
+ * Supports both traditional Helm repositories and OCI registries.
+ */
+export const helm_config_schema = z
+  .object({
+    /** Helm chart repository URL (e.g., https://traefik.github.io/charts) */
+    repository: z.string().url().optional(),
+    /** OCI registry URL for Helm charts (e.g., oci://ghcr.io/traefik/helm) */
+    oci: z.string().startsWith('oci://').optional(),
+    /** Chart name */
+    chart: z.string().min(1),
+  })
+  .refine(
+    (data) => {
+      // Either repository or oci must be provided
+      return data.repository !== undefined || data.oci !== undefined;
+    },
+    {
+      message: "Either 'repository' or 'oci' must be specified",
+    },
+  );
+
+export type HelmConfigType = z.infer<typeof helm_config_schema>;
+
 /**
  * Generic substitution (backward compatible, default type).
  */
@@ -86,6 +111,25 @@ export const version_substitution_schema = z.object({
 
 export type VersionSubstitutionType = z.infer<typeof version_substitution_schema>;
 
+/**
+ * Helm chart version substitution for tracking Helm chart versions.
+ */
+export const helm_substitution_schema = z.object({
+  type: z.literal('helm'),
+  name: z.string().min(1),
+  default: z.string().optional(),
+  /** Semver constraint: ^1.0.0, ~2.3.0, >=1.0.0 <2.0.0 */
+  constraint: z.string().optional(),
+  /** Helm repository configuration for fetching available chart versions */
+  helm: helm_config_schema,
+  /** Regex pattern for filtering valid tags (default: semver-like) */
+  tag_pattern: z.string().optional(),
+  /** Exclude pre-release versions (default: true) */
+  exclude_prerelease: z.boolean().optional(),
+});
+
+export type HelmSubstitutionType = z.infer<typeof helm_substitution_schema>;
+
 /**
  * Namespace substitution with Kubernetes naming validation.
  */
@@ -99,29 +143,46 @@ export type NamespaceSubstitutionType = z.infer<typeof namespace_substitution_sc
 
 /**
  * 1Password substitution for fetching secrets from 1Password vaults.
- * Uses the op:// secret reference format.
+ * Uses the op:// secret reference format, or shorthand with cluster defaults.
  */
-export const onepassword_substitution_schema = z.object({
-  type: z.literal('1password'),
-  name: z.string().min(1),
-  /** 1Password secret reference: op://vault/item[/section]/field */
-  ref: z.string().min(1),
-  /** Optional default value if secret cannot be fetched */
-  default: z.string().optional(),
-});
+export const onepassword_substitution_schema = z
+  .object({
+    type: z.literal('1password'),
+    name: z.string().min(1),
+    /** 1Password secret reference: op://vault/item[/section]/field, or shorthand item/field when vault is configured at cluster level */
+    ref: z.string().min(1).optional(),
+    /** Item name (shorthand, requires cluster-level vault configuration) */
+    item: z.string().min(1).optional(),
+    /** Field name (shorthand, requires cluster-level vault configuration) */
+    field: z.string().min(1).optional(),
+    /** Section name (optional, for shorthand references) */
+    section: z.string().optional(),
+    /** Optional default value if secret cannot be fetched */
+    default: z.string().optional(),
+  })
+  .refine(
+    (data) => {
+      // Either ref must be provided, or both item and field
+      return data.ref !== undefined || (data.item !== undefined && data.field !== undefined);
+    },
+    {
+      message: "Either 'ref' or both 'item' and 'field' must be specified",
+    },
+  );
 
 export type OnePasswordSubstitutionType = z.infer<typeof onepassword_substitution_schema>;
 
 /**
  * Doppler substitution for fetching secrets from Doppler projects.
+ * Project and config can be omitted if configured at cluster level.
  */
 export const doppler_substitution_schema = z.object({
   type: z.literal('doppler'),
   name: z.string().min(1),
-  /** Doppler project name */
-  project: z.string().min(1),
-  /** Doppler config name (e.g., 'dev', 'stg', 'prd') */
-  config: z.string().min(1),
+  /** Doppler project name (optional if configured at cluster level) */
+  project: z.string().min(1).optional(),
+  /** Doppler config name (optional if configured at cluster level, e.g., 'dev', 'stg', 'prd') */
+  config: z.string().min(1).optional(),
   /** Secret key name in Doppler */
   secret: z.string().min(1),
   /** Optional default value if secret cannot be fetched */
@@ -136,6 +197,7 @@ export type DopplerSubstitutionType = z.infer<typeof doppler_substitution_schema
  */
 export const substitution_schema = z.union([
   version_substitution_schema,
+  helm_substitution_schema,
   namespace_substitution_schema,
   onepassword_substitution_schema,
   doppler_substitution_schema,
@@ -151,6 +213,13 @@ export function is_version_substitution(sub: SubstitutionType): sub is VersionSu
   return 'type' in sub && sub.type === 'version';
 }
 
+/**
+ * Type guard for helm substitutions.
+ */
+export function is_helm_substitution(sub: SubstitutionType): sub is HelmSubstitutionType {
+  return 'type' in sub && sub.type === 'helm';
+}
+
 /**
  * Type guard for namespace substitutions.
  */

package/src/template.ts

@@ -9,6 +9,52 @@ import {
   substitution_schema,
 } from './common.js';
 
+/**
+ * Raw dependency reference to an external Flux Kustomization.
+ * Used for dependencies outside the kustodian-generated system.
+ */
+export const raw_dependency_ref_schema = z.object({
+  raw: z.object({
+    name: z.string().min(1),
+    namespace: z.string().min(1),
+  }),
+});
+
+export type RawDependencyRefType = z.infer<typeof raw_dependency_ref_schema>;
+
+/**
+ * Dependency reference - either a string or a raw reference object.
+ *
+ * Supports three formats:
+ * - Within-template: `database`
+ * - Cross-template: `secrets/doppler`
+ * - Raw external: `{ raw: { name: 'legacy-infrastructure', namespace: 'gitops-system' } }`
+ */
+export const dependency_ref_schema = z.union([z.string(), raw_dependency_ref_schema]);
+
+export type DependencyRefType = z.infer<typeof dependency_ref_schema>;
+
+/**
+ * Preservation mode for disabled kustomizations.
+ *
+ * - none: Delete all resources when disabled
+ * - stateful: Keep PVCs, Secrets, and ConfigMaps (default, safe)
+ * - custom: Keep only specified resource types
+ */
+export const preservation_mode_schema = z.enum(['none', 'stateful', 'custom']);
+
+export type PreservationModeType = z.infer<typeof preservation_mode_schema>;
+
+/**
+ * Preservation policy for a kustomization when disabled.
+ */
+export const preservation_policy_schema = z.object({
+  mode: preservation_mode_schema.default('stateful'),
+  keep_resources: z.array(z.string()).optional(),
+});
+
+export type PreservationPolicyType = z.infer<typeof preservation_policy_schema>;
+
 /**
  * A single kustomization within a template.
  * Maps to a Flux Kustomization resource.
@@ -17,7 +63,7 @@ export const kustomization_schema = z.object({
   name: z.string().min(1),
   path: z.string().min(1),
   namespace: namespace_config_schema.optional(),
-  depends_on: z.array(z.string()).optional(),
+  depends_on: z.array(dependency_ref_schema).optional(),
   substitutions: z.array(substitution_schema).optional(),
   health_checks: z.array(health_check_schema).optional(),
   health_check_exprs: z.array(health_check_expr_schema).optional(),
@@ -25,14 +71,39 @@ export const kustomization_schema = z.object({
   wait: z.boolean().optional().default(true),
   timeout: z.string().optional(),
   retry_interval: z.string().optional(),
+  enabled: z.boolean().optional().default(true),
+  preservation: preservation_policy_schema.optional(),
 });
 
 export type KustomizationType = z.infer<typeof kustomization_schema>;
 
+/**
+ * Node label requirement - requires specific labels to be present on cluster nodes.
+ */
+export const node_label_requirement_schema = z.object({
+  type: z.literal('nodeLabel'),
+  key: z.string().min(1),
+  value: z.string().optional(),
+  atLeast: z.number().int().positive().default(1),
+});
+
+export type NodeLabelRequirementType = z.infer<typeof node_label_requirement_schema>;
+
+/**
+ * Template requirement - validates cluster prerequisites before deployment.
+ * Currently supports node label requirements, extensible for future types.
+ */
+export const template_requirement_schema = z.discriminatedUnion('type', [
+  node_label_requirement_schema,
+]);
+
+export type TemplateRequirementType = z.infer<typeof template_requirement_schema>;
+
 /**
  * Template specification containing kustomizations.
  */
 export const template_spec_schema = z.object({
+  requirements: z.array(template_requirement_schema).optional(),
   kustomizations: z.array(kustomization_schema).min(1),
 });