OpenChoreo Documentation

website·Indexed 33 days ago

https://openchoreo.dev

A modular, open-source developer platform for Kubernetes. OpenChoreo provides a Kubernetes-native system organized into Control, Data, Workflow, and Observability planes, enabling platform engineers to build Internal Developer Platforms (IDPs) using custom ResourceTypes and ProjectTypes.

Tokens
251.3K
Snippets
958
Records
1.4K
Agent score
69%

What's inside OpenChoreo

  1. Overview of OpenChoreo AI Agents

    OpenChoreo provides a set of specialized AI agents to extend platform capabilities:

    • FinOps Agent: Analyzes cloud costs and identifies optimization opportunities.
    • Portal Assistant: Enables natural language interaction via the Backstage portal to inspect projects, components, and runtime telemetry.
    • SRE Agent: Assists platform and operations teams with incident diagnosis, observability data analysis, and remediation suggestions across deployments.
  2. Overview of Validation Rules in ComponentTypes and Traits

    Validation rules use Common Expression Language (CEL) expressions wrapped in ${} that must evaluate to true for validation to pass. They complement schema validation by enabling cross-field relationships, domain-specific invariants, rendering context validation, and custom error messages.

    Validations occur in two stages:

    1. Pre-render (preRenderValidations): Runs before rendering against static configuration (parameters, environmentConfigs, workload, etc.).
    2. Post-render (postRenderValidations): Runs after all traits are applied against the final rendered Kubernetes resources.

    Critical Constraint: ComponentTypes and Traits are environment-agnostic. Validation rules must never hard-code environment names (e.g., "production"). Instead, use environmentConfigs to vary behavior per environment.

  3. Overview of the Bulk Promote Workflow

    The Bulk Promote workflow allows developers to promote multiple Components to a target Environment (such as staging or production) in a single operation. Unlike build-and-release workflows, this process has no build phase; it operates purely on the GitOps repository to bind existing ComponentReleases to a target Environment.

    Prerequisite: Components must be previously built using build-and-release workflows. The bulk promote workflow can only bind existing ComponentReleases.

    Common Use Cases:

    • Coordinated multi-component promotions to staging.
    • Rolling out an entire project to production.
    • Bootstrapping a new Environment with all necessary Component bindings.
  4. Overview of ResourceType

    A ResourceType is a platform-defined template in the openchoreo.dev/v1alpha1 API that governs how managed infrastructure (e.g., databases, queues, caches, object stores) is provisioned on the data plane and exposed to consumers. It defines the Kubernetes manifests to be emitted, the parameters developers can supply, environment-specific overrides, and the named outputs that workloads consume via environment or file bindings.
  5. Overview of OpenChoreo Delivery Insights and DORA Metrics

    Delivery Insights is an alpha feature that reports the four DORA metrics for components deployed by OpenChoreo. Metrics can be sliced by environment and viewed at the namespace, project, or component scope. Data is aggregated by the Observer every five minutes.

    MetricAnswersDerived from
    Deployment FrequencyHow often do we ship?Rollouts that reached a healthy state
    Lead Time for ChangesHow long from commit to running?Commit authoring time to rollout ready time
    Change Failure RateHow often does shipping break something?Failed rollouts, and incidents attributed to a rollout
    Mean Time to RecoveryHow long until we are healthy again?Incidents, from trigger to resolution

    Each metric includes a value, a DORA classification (Elite, High, Medium, Low), a trend against the previous window of equal length, and a time-bucketed series (daily, weekly, or monthly).

  6. Overview of the OpenChoreo Developer Platform

    OpenChoreo is a modular, open-source developer platform for Kubernetes designed to help platform teams build Internal Developer Platforms (IDPs). It integrates several core capabilities into a single cohesive platform, including:

    • A Backstage-powered developer portal
    • Application CI/CD and GitOps
    • Observability (logs, metrics, traces, and alerts)
    • Development and architecture guardrails
    • AI-assisted engineering and built-in agents for SRE, cost control, and architecture

    Unlike platforms that hide Kubernetes, OpenChoreo uses Kubernetes-native APIs and controllers to augment Kubernetes, ensuring infrastructure teams maintain full control while providing application teams with simplified, intent-driven abstractions and 'golden paths'.

  7. Overview of OpenChoreo MCP Servers

    OpenChoreo provides two distinct MCP servers that allow AI assistants to interact with the platform. Each server is independently accessible and requires its own configuration:

    1. Control Plane MCP Server: Used for managing OpenChoreo resources such as namespaces, projects, components, builds, deployments, and infrastructure.
    2. Observability Plane MCP Server: Used for accessing observability data, including logs, metrics, traces, alerts, incidents, and FinOps cost insights.

    Recommended Workflow: Use both servers together. Use the Control Plane MCP server to discover resource names (e.g., via list_namespaces or list_projects) and then pass those names as parameters to the Observability Plane MCP tools to fetch specific data.

  8. Overview of ResourceTypes and ClusterResourceTypes

    A ResourceType is a platform-engineer-defined template that governs how managed-infrastructure resources (e.g., databases, queues, caches) are provisioned on the data plane and exposed to consumers. It defines the Kubernetes manifests to be emitted, the parameters developers can configure, environment-specific overrides, and the named outputs that workloads use to connect to the resource.

    There are two scopes available:

    • ResourceType: Namespace-scoped; used when a template should only be available within a specific namespace.
    • ClusterResourceType: Cluster-scoped; used for templates intended to be shared platform-wide. Both share the same specification structure.
  9. Overview of OpenChoreo Workflow Architecture

    OpenChoreo uses a split architecture between a Control Plane and a Workflow Plane to manage reusable pipelines:

    • Workflow Plane: Where the actual execution logic lives. It uses Argo Cluster Workflow Templates (written by Platform Engineers) to define steps like cloning, scanning, and pushing, and Argo Workflows (auto-generated) as the runtime instances.
    • Control Plane: Where the high-level definition lives. It uses Workflow (Templates) (written by Platform Engineers) to define the schema and parameters, and Workflow Runs (created by Developers) to instantiate the process in the Workflow Plane.
  10. Overview of OpenChoreo Components

    A Component is a single deployable unit within a Project. It relies on a platform-defined ComponentType template which determines the workload type (e.g., Deployment, StatefulSet, CronJob) and default configuration. Components can be configured to build from source code using workflows or deploy pre-built container images.
  11. Overview of Local Development with occ remote

    occ remote enables developers to run code on their local machine against real upstream dependencies in an environment. The architecture consists of a remote-agent-router (one per data plane) and a remote-agent (provisioned on demand per project and environment). occ connects to the router, which routes traffic to the appropriate agent based on the TLS ClientHello's SNI. TLS terminates at the agent, not the router. The agent authorizes streams via the openchoreo-api and dials the dependency.
  12. Overview of OpenChoreo Build and Release Workflows

    OpenChoreo provides automated workflows to handle the deployment of Components using a GitOps approach. The process is split into two phases:

    1. Build Phase: Clones the source repository, builds a container image (via Docker, Buildpacks, or Node.js + nginx), and pushes it to a registry.
    2. Release Phase: Clones the GitOps repository, creates a release branch, uses the occ CLI to generate the necessary GitOps resources, and opens a pull request.

    Once the PR is merged, a GitOps operator (like Flux CD) syncs the resources to the cluster.