Skip to main content

Composition Dynamic Controller

The composition-dynamic-controller is an operator that is instantiated by the core-provider to manage the Custom Resources whose Custom Resource Definition is generated by the core-provider.

Summary

Architecture

composition-dynamic-controller architecture

Workflow

composition-dynamic-controller State Diagram

Composition Dynamic Controller (CDC) & Chart Inspector: Secure Helm Lifecycle Management

The Composition Dynamic Controller (CDC) is a specialized Kubernetes operator that orchestrates the end-to-end lifecycle of Krateo compositions. Acting as the reconciliation engine for Composition custom resources, it bridges declarative application definitions with Helm’s packaging system through intelligent automation. The Chart Inspector serves as its "safety advisor," enabling proactive decision-making via dry-run analysis.

Core CDC Workflow (with Chart Inspector Integration)

  1. Reconciliation Trigger

    • Watches for changes to Composition CRs or Helm chart versions.
    • Invokes the Chart Inspector to simulate installations/upgrades before execution.
  2. Dry-Run Analysis Phase (Chart Inspector)

    helm install --dry-run=server <chart> --version <ver>  # Returns:
    • Resource Manifest List: All Kubernetes objects (Deployments, CRDs, etc.) the chart would create along with filename to .
    • Dependency Graph: Order of operations (e.g., CRDs before custom resources).
  3. RBAC Auto-Provisioning (CDC)

    • Dynamically generates least-privilege Roles/ClusterRoles based on the Inspector’s output.
    • Ensures the CDC’s service account has exactly the permissions needed—no more, no less.
  4. Atomic Execution (CDC)

    • Proceeds with helm install/upgrade only after successful dry-run and RBAC setup.

Key Capabilities Enabled by This Collaboration

FeatureCDC’s RoleChart Inspector’s Contribution
Version-Sensitive ReconciliationDetects chart version drift; rolls forward/back.Identifies version-specific resource changes during dry-run.
Atomic UpgradesEnsures all-or-nothing upgrades.Pre-flights resource compatibility (e.g., CRD schema changes).
Self-HealingCorrects configuration drift.Provides baseline "desired state" for comparison.
Declarative EnforcementContinuously reconciles actual vs. desired state.Supplies the desired state before cluster changes.
Secure RBACGenerates minimal required permissions.Audits chart manifests for required API operations.

Why This Architecture Matters

  1. Safety Net

    • The Chart Inspector’s dry-run prevents "helm surprises" (e.g., undeclared CRD creations or namespace pollution).
    • Example: Blocks a chart upgrade if the new version requires a ClusterRole the CDC isn’t authorized to manage.
  2. GitOps Compliance

    • The CDC enforces declarative intent by reconciling against the dry-run’s output, not just Helm’s last-applied state.
    • Self-healing kicks in if manual changes violate the composition’s definition.
  3. Multi-Tenancy Ready

    • RBAC is scoped per-composition, isolating teams/projects.
    • The Inspector’s resource listing ensures no cross-tenant leakage (e.g., a composition can’t create resources in forbidden namespaces).

Real-World Example: Handling a Breaking Chart Change

  1. Scenario: A Helm chart v1.2.0 introduces a new CustomResourceDefinition (CRD).
  2. CDC+Inspector Flow:
    • Dry-run detects the new CRD and its required API group permissions.
    • CDC creates a ClusterRole granting create/get/list for the CRD.
    • Upgrade proceeds only after the CRD and RBAC are confirmed active.
  3. Result: Zero downtime; no "helm upgrade failed: CRD missing" errors.

Configuration

Operator Env Vars

These enviroment varibles can be changed in the Deployment of the composition-dynamic-controller we need to tweak.

NameDescriptionDefault ValueNotes
COMPOSITION_CONTROLLER_DEBUGdump verbose outputfalse
COMPOSITION_CONTROLLER_WORKERSnumber of workers1
COMPOSITION_CONTROLLER_RESYNC_INTERVALresync interval3m
COMPOSITION_CONTROLLER_GROUPresource api grouppopulated by core-provider
COMPOSITION_CONTROLLER_VERSIONresource api versionpopulated by core-provider
COMPOSITION_CONTROLLER_RESOURCEresource plural namepopulated by core-provider
COMPOSITION_CONTROLLER_SA_NAMEcdc deployment ServiceAccount namepopulated by core-provider
COMPOSITION_CONTROLLER_SA_NAMESPACEcdc deployment ServiceAccount namespacepopulated by core-provider
URL_PLURALSurl to krateo pluraliser servicehttp://snowplow.krateo-system.svc.cluster.local:8081/api-info/names
URL_CHART_INSPECTORurl to chart inspectorhttp://chart-inspector.krateo-system.svc.cluster.local:8081/
KRATEO_NAMESPACEnamespace where krateo is installedkrateo-system
HELM_REGISTRY_CONFIG_PATHdefault helm config path/tmp
HELM_MAX_HISTORYMax Helm History10
COMPOSITION_MAX_ERROR_RETRY_INTERVALThe maximum interval between retries when an error occurs. This should be less than the half of the poll interval.0m
COMPOSITION_MIN_ERROR_RETRY_INTERVALThe minimum interval between retries when an error occurs. This should be less than max-error-retry-interval.1m