kubricate
Version:
A TypeScript framework for building reusable, type-safe Kubernetes infrastructure — without the YAML mess.
159 lines • 6.32 kB
TypeScript
import type { BaseLogger, PreparedEffect } from '@kubricate/core';
import { SecretManagerEngine, type MergedSecretManager } from './SecretManagerEngine.js';
import type { SecretsOrchestratorOptions } from './types.js';
/**
* SecretsOrchestrator
*
* @description
* Central orchestration engine responsible for:
* - Validating secret configuration and managers
* - Loading and resolving all declared secrets
* - Preparing provider-specific effects
* - Applying conflict resolution strategies (intraProvider, crossProvider, crossManager)
* - Producing a fully merged, finalized list of secret effects ready for output (e.g., YAML, JSON, etc.)
*
* @remarks
* - Acts as the internal core behind `kubricate secret apply`.
* - Ensures predictable, auditable, and conflict-safe secret generation.
* - Delegates provider-specific behavior to registered providers (e.g., mergeSecrets, prepare).
*
* @usage
* Typically called via:
*
* ```ts
* const orchestrator = SecretsOrchestrator.create(options);
* const effects = await orchestrator.apply();
* ```
*
* @throws {Error}
* If configuration, validation, or merging fails at any stage.
*/
export declare class SecretsOrchestrator {
private engine;
private logger;
private providerCache;
constructor(engine: SecretManagerEngine, logger: BaseLogger);
/**
* Factory method to create a SecretsOrchestrator instance from options.
*/
static create(options: SecretsOrchestratorOptions): SecretsOrchestrator;
/**
* Validates the project configuration and all registered secret managers.
*
* @remarks
* This is automatically called by commands like `kubricate secret apply` and `kubricate secret validate`.
*
* @description
* Performs full validation across:
* - Configuration schema (e.g., strictConflictMode rules, secret manager presence)
* - SecretManager instances and their attached connectors
* - Ensures all declared secrets can be loaded without error
*
* Logs important validation steps for traceability.
*
* @returns {Promise<MergedSecretManager>} A fully validated set of collected secret managers.
*
* @throws {Error}
* - If a configuration violation is detected (e.g., invalid strictConflictMode usage).
* - If a SecretManager or connector fails to validate or load secrets.
*/
validate(): Promise<MergedSecretManager>;
/**
* Prepares a fully validated and merged set of provider-ready secret effects.
*
* @remarks
* This is the core orchestration method called by commands like `kubricate secret apply`.
*
* @description
* Executes the full secret orchestration lifecycle:
* - Validates project configuration and all secret managers
* - Loads and resolves all secrets across managers
* - Prepares raw provider effects for each secret
* - Merges effects according to conflict strategies (intraProvider, crossProvider, etc.)
*
* Logs context and important processing steps for debugging and traceability.
*
* @returns {Promise<PreparedEffect[]>} A list of finalized secret effects ready for output (e.g., Kubernetes manifests).
*
* @throws {Error}
* - If configuration validation fails (e.g., strictConflictMode violations).
* - If loading or preparing secrets fails.
* - If conflict resolution encounters an unrecoverable error (based on config).
*/
apply(): Promise<PreparedEffect[]>;
private logOrchestratorContext;
private loadSecretsFromManagers;
private prepareEffects;
/**
* Resolves the canonical conflict key for a given prepared secret effect.
*
* @description
* This key is used to group and detect conflicts between secrets during the orchestration phase.
*
* Normally, the conflict key includes:
* - `managerName`
* - `providerClassName` (inferred from secretType)
* - `identifier` (logical resource name)
*
* This ensures strict isolation between different SecretManagers or stacks.
*
* However, if the `crossManager` conflict strategy is explicitly configured as `'autoMerge'`,
* the orchestrator intentionally ignores the `managerName` prefix — allowing secrets from
* multiple managers to merge into the same logical resource (e.g., Kubernetes Secret, Vault path).
*
* ---
*
* Example behavior:
*
* Default (strict isolation):
* ```text
* frontend:Kubricate.OpaqueSecretProvider:app-secret
* backend:Kubricate.OpaqueSecretProvider:app-secret
* ```
* ➔ Different managers, different keys ➔ Conflict detected.
*
* CrossManager autoMerge mode:
* ```text
* Kubricate.OpaqueSecretProvider:app-secret
* ```
* ➔ Same key ➔ Secrets will be merged.
*
* ---
*
* @param effect - The prepared effect to calculate the conflict key for.
* @returns The canonical string key used for grouping and conflict resolution.
*/
private resolveConflictKey;
private mergePreparedEffects;
/**
* Resolves a provider instance from its name by scanning all SecretManagers.
* Caches resolved providers for performance.
*
* @throws If the provider name is not found in any manager
*/
private resolveProviderByName;
/**
* Resolves the merge strategy for a given level using config or fallback defaults.
*/
private resolveStrategyForLevel;
/**
* Validates core secrets-related configuration inside the project config.
*
* @param config - The Kubricate project configuration object.
*
* @throws {Error} If the secret manager is missing or invalid.
*/
private validateConfig;
/**
* Validates conflict resolution options, especially when `strictConflictMode` is enabled.
*
* - If `strictConflictMode` is true, all conflict strategies must be set to 'error'.
* - Throws early if an invalid combination is detected.
*
* @param conflictOptions - The secret conflict configuration object.
*
* @throws {Error} If strict mode is enabled but a non-'error' strategy is found.
*/
private validateConflictOptions;
}
//# sourceMappingURL=SecretsOrchestrator.d.ts.map