DOCSEARCHbyAlgolia
Submit Docs

Holos

repository·main·Indexed 41 days ago

https://github.com/holos-run/holos

A configuration management tool for Kubernetes that implements the rendered manifests pattern. Holos uses CUE to unify Helm, Kustomize, and Kubernetes configurations into a validated pipeline for generating deployment manifests. The v1beta1 architecture introduces a platform-wide Directed Acyclic Graph (DAG) for concurrent execution and packages components as independently published CUE modules.

Tokens
53.5K
Snippets
154
Records
212
Agent score
51%

What's inside Holos

  1. Overview of Holos v1beta1 Design

    main

    Holos v1beta1 is a redesign of the platform architecture that focuses on composability, concurrency, and standardized packaging. Key improvements over v1alpha6 include:

    • TaskSet over BuildPlan: The BuildPlan is deprecated in favor of a TaskSet.
    • Platform-wide DAG: Instead of rendering one BuildPlan per component, all component TaskSets are composed into a single, platform-wide Directed Acyclic Graph (DAG).
    • Concurrent Execution: The composed DAG is executed using a topological sort, allowing for high levels of concurrency.
    • CUE Module Packaging: Components are packaged as independently published CUE modules, allowing for a robust package ecosystem.
    • Standardized Naming: The API follows Kubernetes-style lowerCamelCase for JSON field names (e.g., apiVersion, resourceVersion).

  2. Overview of Holos core concepts

    main

    Holos is a configuration management tool for Kubernetes that implements the rendered manifests pattern. It is designed to manage configurations ranging from single resources to multi-cluster platforms across different regions.

    Key Components

    • Platform schemas: Define how different components integrate with each other.
    • Building blocks: Unify Helm, Kustomize, and Kubernetes configurations using CUE.
    • BuildPlan pipeline: A pipeline used for generating, transforming, and validating manifests.

  3. Use Author Schemas to generate TaskSets

    main

    The author package provides standardized schemas used by component authors to generate core TaskSets.

    Important Note on Implementation: This package defines types only. The actual CUE logic that assembles a TaskSet from these wrapper fields is hand-written CUE provided by the platform scaffolding (via the holos init platform command).

    Design Philosophy:

    • Minimalism: The package defines only the minimal necessary structures to ensure stability and flexibility.
    • Customization: For organization-specific structures like cluster or environment, authors should define their own structures in topics rather than requesting additions to this package.
    • Composition: Use these schemas as building blocks for your own custom component definitions.

  4. What is a Service Mesh in Holos?

    main

    A Service Mesh is an infrastructure layer used to manage, observe, and secure service-to-service communication. It abstracts networking complexities away from application code by providing:

    • Traffic Management: Load balancing and traffic routing.
    • Service Discovery: Automated discovery of microservices.
    • Security: Implementing mutual TLS (mTLS) and access control policies.

  5. What is a Management Cluster?

    main

    A Management Cluster is a specialized Kubernetes cluster that manages a single Holos Platform. Its primary responsibilities include:

    • Hosting Controllers: Running essential Kubernetes controllers such as cert-manager, Cluster API, and Crossplane.
    • Secret Management: Serving as the centralized and secure control plane for storing and managing sensitive information (credentials, API keys, etc.).

  6. Overview of Holos Validators

    main

    Validators in Holos allow you to validate rendered manifests against policy definitions. This is useful for:

    1. Security Enforcement: Blocking specific resources (e.g., preventing Secret resources from being committed to version control and suggesting ExternalSecret instead).
    2. Schema Validation: Verifying that rendered resources match Kubernetes type definitions (e.g., ensuring a Deployment follows the correct schema).
    3. Final Artifact Validation: Validating the complete output after all generators and transformers have been applied.

    Validation is typically performed by mapping resource fields (like kind and name) to a CUE policy package using the holos cue vet command.

  7. What is Holos and the rendered manifests pattern

    main

    Holos is a Go command line tool designed to manage Kubernetes platforms by implementing the rendered manifests pattern as a data pipeline.

    Instead of managing individual Helm charts or Kustomize overlays in isolation, Holos treats manifest generation as a pipeline that can holistically integrate and render manifests from multiple sources, including:

    • Helm
    • Kustomize
    • CUE

    This approach helps solve common integration issues where individual charts or components do not work well together, and provides a way to manage complex configurations (like secrets or umbrella charts) without relying on fragile CI scripts.

  8. What is a Workload Cluster?

    main
    A Workload Cluster is a Kubernetes cluster dedicated to hosting and running actual application workloads. Unlike the Management Cluster, which focuses on control and secrets, Workload Clusters are optimized for executing services and applications. They leverage Kubernetes orchestration for deployment, scaling, and operation of containerized workloads.

  9. Pin module versions using Minimal Version Selection (MVS)

    main

    Holos uses CUE's Minimal Version Selection (MVS) to manage dependencies. Instead of a lockfile, versions are pinned in the platform module's cue.mod/module.cue file within the deps map.

    How to manage pins:

    • Use cue mod get <module>@<version> to write a pin to the deps map.
    • Use cue mod tidy to keep the deps map consistent with your imports.
    • Note: A pin is a floor, not a ceiling. If another dependency requires a higher version of the same module, MVS will select the higher version to satisfy all requirements.

    Example cue.mod/module.cue structure:

    module: "platform.example.com@v0"
language: version: "v0.15.1"

deps: {
	"example.com/holos/vault@v0": v: "v0.3.2"
	"example.com/holos/vault-observability@v0": v: "v0.7.1"
}
    // <platform-root>/cue.mod/module.cue
module: "platform.example.com@v0"
language: version: "v0.15.1"

deps: {
	"example.com/holos/vault@v0": v: "v0.3.2"
	"example.com/holos/vault-observability@v0": v: "v0.7.1"
}

  10. Comparison: v1alpha6 vs v1beta1 Packaging

    main

    Understanding the shift from v1alpha6 to v1beta1 is critical for migration and architectural planning:

    Featurev1alpha6v1beta1
    Primary FormatDirectory of CUE files in platform repoCUE Module (OCI Artifact)
    Reuse PatternCopy-paste across platformsModule dependency/import
    HermeticityNon-hermetic (fetches charts from network at render time)Hermetic (charts are embedded in the module)
    File AccessUses BuildContext temp-directory wiringBuildContext + Module-aware file resolution

    Note on BuildContext: v1beta1 preserves the BuildContext mechanism (injecting TempDir, RootDir, LeafDir, and HolosExecutable via the holos_build_context tag), but adds module-aware file resolution on top of it.

  11. Understand the Holos v1beta1 Layer Model

    main

    Holos v1beta1 uses a four-layer hierarchy to organize configuration. It is critical to distinguish between layers that are recognized by the Go tooling and those that are pure CUE conventions used for human organization.

    The Four Layers

    1. Platform: Represents a single site instance. This is the single entrypoint a site operator renders. It is Go-aware (internal/platform/).
    2. Profile: Represents a cluster class (e.g., management, nonprod workload, prod workload). It selects which Roles apply to clusters of that class. This is a pure CUE convention and is NOT visible to Go tooling.
    3. Role: A reusable capability composed of multiple components (e.g., ingress, observability). This is a pure CUE convention and is NOT visible to Go tooling.
    4. Component: The smallest deployable unit, packaged as a CUE module. It is Go-aware (internal/component/).

    Relationship Summary

    LayerMeaningAuthored byGo tooling awareness
    Platformone site instancesite operatorsyes — internal/platform/
    Profilecluster classsite operatorsnone — pure CUE convention
    Rolereusable capabilitydistribution / platform teamsnone — pure CUE convention
    Componentone deployable unitmodule authorsyes — internal/component/

    Composition Flow

    • A Profile selects Roles for a cluster class.
    • A Role selects Components and sets their #Config values.
    • The Platform instantiates Profiles per cluster.
    • The Go tooling collapses these layers, seeing only the Platform and its constituent Components.

  12. Task naming and canonical IDs

    main

    Holos uses a two-tier naming system to ensure uniqueness across a single component and across the entire platform.

    Local Task Names

    Within a single TaskSet, task names are the keys in the spec.tasks struct. They must follow the RFC 1123 label format:

    • Pattern: `^a-z0-9?$
    • Allowed: Lowercase alphanumerics and interior hyphens.
    • Forbidden: Colons, slashes, or uppercase letters.

    Canonical IDs (Platform-wide)

    When multiple components are merged into a platform DAG, tasks are namespaced using the format: <component-path>:<task-name>

    Example: components/vault:helm.

    Referencing Tasks

    • Local Reference: A bare key in dependsOn (e.g., dependsOn: validate: {}) resolves within the local TaskSet.
    • Cross-component Reference: A key containing a colon (e.g., dependsOn: "other-comp:task": {}) references a task in a different component.