From a0f26fc019ab6061efe278c694a3883ea6f38f4d Mon Sep 17 00:00:00 2001 From: Chalindu Kodikara Date: Fri, 16 Jan 2026 20:05:43 +0530 Subject: [PATCH] Add v0.11.0 docs --- docusaurus.config.ts | 9 +- versioned_docs/version-v0.11.x/_constants.mdx | 8 + .../concepts/developer-abstractions.md | 134 +++ .../concepts/platform-abstractions.md | 257 ++++++ .../concepts/resource-relationships.md | 169 ++++ .../version-v0.11.x/concepts/runtime-model.md | 120 +++ .../deploy-first-component.mdx | 159 ++++ .../getting-started/qsg-backstage-ui.png | Bin 0 -> 619762 bytes .../qsg-install-status-success.png | Bin 0 -> 125546 bytes .../getting-started/quick-start-guide.mdx | 307 ++++++ .../try-it-out/on-managed-kubernetes.mdx | 676 ++++++++++++++ .../try-it-out/on-self-hosted-kubernetes.mdx | 631 +++++++++++++ .../ci-integration.md | 303 ++++++ .../integrating-with-openchoreo/gitops.md | 746 +++++++++++++++ .../learn-from-examples/examples-catalog.mdx | 187 ++++ .../operations/api-management.mdx | 460 +++++++++ .../version-v0.11.x/operations/auto-build.mdx | 131 +++ .../operations/backstage-configuration.mdx | 519 +++++++++++ .../operations/cluster-agent-rbac.mdx | 270 ++++++ .../operations/deployment-topology.mdx | 403 ++++++++ .../gitops/fluxcd/getting-started.mdx | 234 +++++ .../operations/gitops/overview.md | 396 ++++++++ .../operations/identity-configuration.mdx | 286 ++++++ .../operations/multi-cluster-connectivity.mdx | 300 ++++++ .../operations/observability-alerting.mdx | 522 +++++++++++ .../version-v0.11.x/operations/rca-agent.mdx | 84 ++ .../operations/secret-management.mdx | 175 ++++ .../version-v0.11.x/operations/upgrades.mdx | 132 +++ .../version-v0.11.x/overview/architecture.mdx | 132 +++ .../overview/what-is-openchoreo.mdx | 66 ++ .../reference/api/application/build.md | 164 ++++ .../reference/api/application/component.md | 168 ++++ .../api/application/componentdeployment.md | 301 ++++++ .../api/application/componentworkflowrun.md | 336 +++++++ .../reference/api/application/project.md | 82 ++ .../api/application/scheduledtask.md | 98 ++ .../reference/api/application/service.md | 152 +++ .../api/application/webapplication.md | 98 ++ .../reference/api/application/workflowrun.md | 239 +++++ .../reference/api/application/workload.md | 253 +++++ .../reference/api/platform/buildplane.md | 297 ++++++ .../reference/api/platform/componenttype.md | 363 ++++++++ .../api/platform/componentworkflow.md | 407 ++++++++ .../reference/api/platform/dataplane.md | 351 +++++++ .../api/platform/deployment-pipeline.md | 98 ++ .../reference/api/platform/environment.md | 110 +++ .../api/platform/observabilityalertrule.md | 172 ++++ .../observabilityalertsnotificationchannel.md | 148 +++ .../api/platform/observabilityplane.md | 300 ++++++ .../reference/api/platform/organization.md | 79 ++ .../reference/api/platform/releasebinding.md | 320 +++++++ .../api/platform/scheduledtaskclass.md | 90 ++ .../reference/api/platform/secretreference.md | 244 +++++ .../reference/api/platform/serviceclass.md | 91 ++ .../reference/api/platform/trait.md | 403 ++++++++ .../api/platform/webapplicationclass.md | 93 ++ .../reference/api/platform/workflow.md | 264 ++++++ .../reference/api/runtime/componentrelease.md | 235 +++++ .../reference/api/runtime/release.md | 163 ++++ .../api/runtime/scheduledtaskbinding.md | 108 +++ .../reference/api/runtime/servicebinding.md | 196 ++++ .../api/runtime/webapplicationbinding.md | 188 ++++ .../reference/cel/built-in-functions.md | 181 ++++ .../reference/cel/configuration-helpers.md | 538 +++++++++++ .../reference/cel/context-variables.md | 272 ++++++ .../version-v0.11.x/reference/changelog.md | 28 + .../reference/cli-reference.md | 471 ++++++++++ .../reference/configuration-schema.md | 872 ++++++++++++++++++ .../version-v0.11.x/reference/faq.md | 125 +++ .../reference/helm/_category_.json | 5 + .../reference/helm/build-plane.mdx | 187 ++++ .../reference/helm/control-plane.mdx | 540 +++++++++++ .../reference/helm/data-plane.mdx | 330 +++++++ .../reference/helm/observability-plane.mdx | 489 ++++++++++ .../mcp-servers/mcp-configuration.md | 103 +++ .../reference/resource-limits.md | 162 ++++ .../openchoreo-cell-runtime-view.png | Bin 0 -> 217048 bytes .../openchoreo-development-abstractions.png | Bin 0 -> 264911 bytes .../openchoreo-diagram-v1-with-borders.png | Bin 0 -> 1041768 bytes .../openchoreo-platform-abstractions.png | Bin 0 -> 295345 bytes .../resources/openchoreo_components.svg | 1 + .../use-cases/api-management.mdx | 373 ++++++++ .../use-cases/api-management.png | Bin 0 -> 348995 bytes .../use-cases/deploy-prebuilt-image.mdx | 115 +++ .../user-guide/ci/additional-resources.md | 123 +++ .../ci/component-workflow-schema.md | 238 +++++ .../user-guide/ci/custom-workflows.md | 555 +++++++++++ .../ci/external-container-registry.mdx | 325 +++++++ .../version-v0.11.x/user-guide/ci/overview.md | 379 ++++++++ .../user-guide/ci/overview.png | Bin 0 -> 161488 bytes .../ci/private-repository-multiple.md | 215 +++++ .../user-guide/ci/private-repository.mdx | 131 +++ .../user-guide/component-types/overview.md | 290 ++++++ .../component-types/patching-syntax.md | 408 ++++++++ .../component-types/schema-syntax.md | 348 +++++++ .../component-types/templating-syntax.md | 383 ++++++++ .../version-v0.11.x-sidebars.json | 346 +++++++ versions.json | 1 + 98 files changed, 22958 insertions(+), 3 deletions(-) create mode 100644 versioned_docs/version-v0.11.x/_constants.mdx create mode 100644 versioned_docs/version-v0.11.x/concepts/developer-abstractions.md create mode 100644 versioned_docs/version-v0.11.x/concepts/platform-abstractions.md create mode 100644 versioned_docs/version-v0.11.x/concepts/resource-relationships.md create mode 100644 versioned_docs/version-v0.11.x/concepts/runtime-model.md create mode 100644 versioned_docs/version-v0.11.x/getting-started/deploy-first-component.mdx create mode 100644 versioned_docs/version-v0.11.x/getting-started/qsg-backstage-ui.png create mode 100644 versioned_docs/version-v0.11.x/getting-started/qsg-install-status-success.png create mode 100644 versioned_docs/version-v0.11.x/getting-started/quick-start-guide.mdx create mode 100644 versioned_docs/version-v0.11.x/getting-started/try-it-out/on-managed-kubernetes.mdx create mode 100644 versioned_docs/version-v0.11.x/getting-started/try-it-out/on-self-hosted-kubernetes.mdx create mode 100644 versioned_docs/version-v0.11.x/integrating-with-openchoreo/ci-integration.md create mode 100644 versioned_docs/version-v0.11.x/integrating-with-openchoreo/gitops.md create mode 100644 versioned_docs/version-v0.11.x/learn-from-examples/examples-catalog.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/api-management.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/auto-build.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/backstage-configuration.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/cluster-agent-rbac.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/deployment-topology.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/gitops/fluxcd/getting-started.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/gitops/overview.md create mode 100644 versioned_docs/version-v0.11.x/operations/identity-configuration.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/multi-cluster-connectivity.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/observability-alerting.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/rca-agent.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/secret-management.mdx create mode 100644 versioned_docs/version-v0.11.x/operations/upgrades.mdx create mode 100644 versioned_docs/version-v0.11.x/overview/architecture.mdx create mode 100644 versioned_docs/version-v0.11.x/overview/what-is-openchoreo.mdx create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/build.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/component.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/componentdeployment.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/componentworkflowrun.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/project.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/scheduledtask.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/service.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/webapplication.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/workflowrun.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/application/workload.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/buildplane.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/componenttype.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/componentworkflow.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/dataplane.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/deployment-pipeline.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/environment.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/observabilityalertrule.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/observabilityalertsnotificationchannel.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/observabilityplane.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/organization.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/releasebinding.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/scheduledtaskclass.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/secretreference.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/serviceclass.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/trait.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/webapplicationclass.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/platform/workflow.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/runtime/componentrelease.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/runtime/release.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/runtime/scheduledtaskbinding.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/runtime/servicebinding.md create mode 100644 versioned_docs/version-v0.11.x/reference/api/runtime/webapplicationbinding.md create mode 100644 versioned_docs/version-v0.11.x/reference/cel/built-in-functions.md create mode 100644 versioned_docs/version-v0.11.x/reference/cel/configuration-helpers.md create mode 100644 versioned_docs/version-v0.11.x/reference/cel/context-variables.md create mode 100644 versioned_docs/version-v0.11.x/reference/changelog.md create mode 100644 versioned_docs/version-v0.11.x/reference/cli-reference.md create mode 100644 versioned_docs/version-v0.11.x/reference/configuration-schema.md create mode 100644 versioned_docs/version-v0.11.x/reference/faq.md create mode 100644 versioned_docs/version-v0.11.x/reference/helm/_category_.json create mode 100644 versioned_docs/version-v0.11.x/reference/helm/build-plane.mdx create mode 100644 versioned_docs/version-v0.11.x/reference/helm/control-plane.mdx create mode 100644 versioned_docs/version-v0.11.x/reference/helm/data-plane.mdx create mode 100644 versioned_docs/version-v0.11.x/reference/helm/observability-plane.mdx create mode 100644 versioned_docs/version-v0.11.x/reference/mcp-servers/mcp-configuration.md create mode 100644 versioned_docs/version-v0.11.x/reference/resource-limits.md create mode 100644 versioned_docs/version-v0.11.x/resources/openchoreo-cell-runtime-view.png create mode 100644 versioned_docs/version-v0.11.x/resources/openchoreo-development-abstractions.png create mode 100644 versioned_docs/version-v0.11.x/resources/openchoreo-diagram-v1-with-borders.png create mode 100644 versioned_docs/version-v0.11.x/resources/openchoreo-platform-abstractions.png create mode 100644 versioned_docs/version-v0.11.x/resources/openchoreo_components.svg create mode 100644 versioned_docs/version-v0.11.x/use-cases/api-management.mdx create mode 100644 versioned_docs/version-v0.11.x/use-cases/api-management.png create mode 100644 versioned_docs/version-v0.11.x/use-cases/deploy-prebuilt-image.mdx create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/additional-resources.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/component-workflow-schema.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/custom-workflows.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/external-container-registry.mdx create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/overview.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/overview.png create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/private-repository-multiple.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/ci/private-repository.mdx create mode 100644 versioned_docs/version-v0.11.x/user-guide/component-types/overview.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/component-types/patching-syntax.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/component-types/schema-syntax.md create mode 100644 versioned_docs/version-v0.11.x/user-guide/component-types/templating-syntax.md create mode 100644 versioned_sidebars/version-v0.11.x-sidebars.json diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 4ef0e08..df3e721 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -55,8 +55,11 @@ const config: Config = { 'classic', { docs: { - lastVersion: 'v0.10.x', + lastVersion: 'v0.11.x', versions: { + 'v0.11.x': { + label: 'v0.11.x', + }, 'v0.10.x': { label: 'v0.10.x', }, @@ -114,9 +117,9 @@ const config: Config = { themeConfig: { announcementBar: { - id: 'release_v0_10_0', + id: 'release_v0_11_0', content: - '🎉️ OpenChoreo v0.10.0 has been released! Explore what’s new. 🎉', + '🎉️ OpenChoreo v0.11.0 has been released! Explore what’s new. 🎉', isCloseable: true, }, algolia: { diff --git a/versioned_docs/version-v0.11.x/_constants.mdx b/versioned_docs/version-v0.11.x/_constants.mdx new file mode 100644 index 0000000..be5ac08 --- /dev/null +++ b/versioned_docs/version-v0.11.x/_constants.mdx @@ -0,0 +1,8 @@ +[//] # (This file stores the constants used across the documentation.) + +export const versions = { + dockerTag: 'latest-dev', + githubRef: 'main', // Used for the GitHub Raw URL references. Example: main, latest, v0.1.0 + helmChart: '0.0.0-latest-dev', + helmSource: 'oci://ghcr.io/openchoreo/helm-charts', +}; diff --git a/versioned_docs/version-v0.11.x/concepts/developer-abstractions.md b/versioned_docs/version-v0.11.x/concepts/developer-abstractions.md new file mode 100644 index 0000000..5633d31 --- /dev/null +++ b/versioned_docs/version-v0.11.x/concepts/developer-abstractions.md @@ -0,0 +1,134 @@ +--- +title: Developer Abstractions +description: Developer abstractions for building and running applications +--- + +# Developer Abstractions + +Developer abstractions in OpenChoreo enable teams to build, deploy, and operate cloud-native applications without +managing infrastructure complexity. These abstractions provide a declarative model for expressing application +architecture, dependencies, and operational requirements while the platform handles the underlying Kubernetes resources, +networking, and security configurations automatically. + +## Project + +A **Project** represents a bounded context in Domain-Driven Design terms - a cohesive collection of components that +together implement a specific business capability or application domain. It serves as the primary organizational unit +for developers, defining clear boundaries for code ownership, deployment coordination, and operational responsibility. + +Projects establish both logical and physical boundaries in the platform. Logically, they group related components that +share common business logic, data models, and team ownership. Physically, they translate into isolated deployment units +with dedicated namespaces, network boundaries, and security policies. This alignment between organizational structure +and technical architecture enables teams to work autonomously while maintaining clear integration points with other +projects. + +The project boundary also defines the scope for internal communication and shared resources. Components within a project +can communicate freely with each other. This locality principle reduces complexity for +developers while maintaining security and isolation between different application domains. + +## Component + +A **Component** represents a deployable unit of software - the fundamental building block of applications in OpenChoreo. +Each component encapsulates a specific piece of functionality, whether it's a microservice handling business logic, a +web application serving user interfaces, or a background job processing data. + +Components use a **ComponentType** reference to determine their deployment characteristics. This reference follows the +format `{workloadType}/{componentTypeName}`, such as `deployment/web-service` or `cronjob/data-processor`. This explicit +typing allows platform engineers to define multiple variations of deployment patterns for the same workload type, each +tuned for different use cases. + +The Component resource connects four essential elements: + +**ComponentType Reference** specifies which platform-defined template governs this component's deployment. The +ComponentType defines the available configuration schema, resource templates, and allowed workflows. This separation +of concerns means developers work with a simplified interface while platform engineers maintain control over +infrastructure patterns. + +**Parameters** provide the component-specific configuration values that conform to the schema defined in the +ComponentType. When a ComponentRelease is created, these parameter values are captured in the release snapshot. The +same values then apply wherever that release is deployed—if you deploy the same ComponentRelease to dev, staging, and +prod, the parameters are identical across all environments. To change parameter values, you update the Component and +create a new ComponentRelease. Environment-specific values (like resource limits or storage sizes) are handled +separately through `envOverrides` in ReleaseBinding resources. + +**Traits** enable composition of additional capabilities into the component. Each trait instance adds specific +functionality like persistent storage, caching, or monitoring. Traits can be instantiated multiple times with +different configurations using unique instance names. For example, a component might attach multiple persistent volume +traits for different storage needs, each with its own size, storage class, and mount configuration. Traits use the +same schema-driven approach as ComponentTypes, with parameters set in the Component and environment-specific overrides +applied through ReleaseBinding resources. + +**Workflow Configuration** optionally specifies how to build the component from source code. This references a +Workflow and provides the developer-configured schema values needed to execute builds. The workflow integration +enables automated container image creation triggered by code changes or manual developer actions. + +The component abstraction thus becomes a declarative specification that combines: +- A ComponentType that defines *how* to deploy +- Parameters that configure *what* to deploy +- Traits that compose *additional capabilities* +- A Workflow that defines *how to build* + +This composition-based approach enables developers to assemble complex applications from reusable building blocks +while the platform ensures consistency, governance, and operational best practices through the underlying ComponentType +and Trait templates. + +## Workload + +A **Workload** defines the runtime contract of a component - specifying what the component needs to run. The workload +focuses on application requirements rather than infrastructure details, which are handled by the platform through Classes. + +Each component has one workload that describes its runtime needs through several key specifications: + +**Containers** define the container images to deploy, along with their commands, arguments, and environment variables. +This tells the platform what code to run and how to configure it. + +**Endpoints** specify the network interfaces that the component exposes - the ports and protocols it listens on. Each +endpoint declares its type (HTTP, gRPC, TCP, etc.) and port number. These definitions tell the platform what network +services the component provides, enabling automatic service creation and network policy generation. + +**Connections** declare the component's dependencies on other services, whether internal to the platform or external +third-party services. Each connection specifies how to inject service information into the component through environment +variables. This enables the platform to manage service discovery, configure network policies, and track dependencies. + +This declarative specification can be generated from configuration files in the source repository or applied directly +to the cluster. The separation between workload (what the application needs) and classes (how the platform provides it) +enables platform teams to control infrastructure policies while developers focus on application requirements. Resource +limits, scaling parameters, and operational policies come from the ServiceClass or WebApplicationClass, while the +workload simply declares what the application needs to function. + +## ComponentWorkflowRun + +A **ComponentWorkflowRun** represents a runtime execution instance of a ComponentWorkflow - a specialized workflow type +designed specifically for building components. While ComponentWorkflows define the build template and schema, +ComponentWorkflowRuns represent actual build executions with specific parameter values and ownership tracking. + +ComponentWorkflowRuns bridge the gap between developer intent and CI/CD execution for component builds. Developers +create ComponentWorkflowRun resources to trigger builds, providing component ownership information, repository details, +and build parameters. The platform handles all the complexity of rendering the final workflow specification, +synchronizing secrets, and managing execution in the build plane. + +Each ComponentWorkflowRun captures three essential pieces of information: + +**Ownership Tracking** links the build execution to a specific component and project. This enables traceability, +allowing the platform to track which builds belong to which components and maintain build history per component. The +ownership information includes both project name and component name, ensuring proper audit trails and enabling +component-specific build operations. + +**System Parameters** provide the structured repository information required for build-specific platform features. These +parameters follow a fixed structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, +and `repository.appPath` fields. This predictable structure enables the platform to support auto-builds triggered by +webhooks, manual build actions in the UI, build traceability linking images to source commits, and monorepo support by +identifying specific application paths within repositories. + +**Developer Parameters** provide values for the flexible configuration schema defined by the platform engineer in the +ComponentWorkflow. These might include build version numbers, test modes, resource allocations, timeout settings, +caching configurations, and retry limits. The schema validation ensures type correctness and constraint satisfaction +automatically. + +This abstraction provides a specialized interface for component builds, where developers interact with curated schemas +rather than complex CI/CD pipeline definitions. The separation of concerns allows platform engineers to control build +implementation and security policies through ComponentWorkflow templates while developers manage repository information +and build parameters through ComponentWorkflowRun instances. ComponentWorkflowRuns can be created manually for ad-hoc +builds or automatically by platform controllers in response to code changes, supporting both interactive development and +fully automated CI/CD pipelines while maintaining consistent execution patterns and governance specifically tailored for +component build operations. diff --git a/versioned_docs/version-v0.11.x/concepts/platform-abstractions.md b/versioned_docs/version-v0.11.x/concepts/platform-abstractions.md new file mode 100644 index 0000000..0f632d1 --- /dev/null +++ b/versioned_docs/version-v0.11.x/concepts/platform-abstractions.md @@ -0,0 +1,257 @@ +--- +title: Platform Abstractions +description: Platform abstractions for managing infrastructure +--- + +# Platform Abstractions + +Platform abstractions in OpenChoreo provide the foundational infrastructure layer that platform engineers use to build +and manage Internal Developer Platforms. These abstractions establish organizational boundaries, manage infrastructure +resources, and define the operational policies that enable developer self-service while maintaining security and +compliance. + +## Organization + +The **Organization** represents the highest level of tenancy in OpenChoreo, serving as the root container for all +platform resources. It establishes the fundamental isolation boundary between different business units, teams, or +customers in a multi-tenant platform. + +Organizations provide complete resource isolation through dedicated Kubernetes namespaces, ensuring that resources, +configurations, and workloads from different organizations never interact. This isolation extends beyond simple +namespace separation to include network policies, RBAC rules, and resource quotas, creating a secure multi-tenant +environment. + +Each organization maintains its own set of platform resources, application resources, and runtime configurations. This +hierarchical structure enables platform teams to manage multiple independent tenants on the same OpenChoreo +installation, each with their own governance policies, resource limits, and operational procedures. + +## Infrastructure Planes + +OpenChoreo separates infrastructure concerns into specialized planes, each serving a distinct purpose in the platform +architecture. This separation enables independent scaling, security isolation, and operational management of different +platform functions. + +### DataPlane + +A **DataPlane** represents a Kubernetes cluster where application workloads run. It abstracts the complexity of cluster +management, providing a unified interface for deploying applications across multiple clusters regardless of their +location or underlying infrastructure. + +DataPlanes encapsulate all the configuration needed to connect to and manage a Kubernetes cluster, including connection +credentials, TLS certificates, and cluster-specific settings. They enable platform teams to register multiple clusters - +whether on-premises, in public clouds, or at edge locations - and manage them through a single control plane. + +Each DataPlane can host multiple environments and projects, with OpenChoreo managing the creation of namespaces, network +policies, and other cluster resources automatically. This abstraction allows platform teams to treat clusters as +interchangeable infrastructure resources, enabling strategies like geographic distribution, compliance-based placement, +and disaster recovery. + +### BuildPlane + +A **BuildPlane** provides dedicated infrastructure for executing continuous integration and build workloads. By +separating build operations from runtime workloads, BuildPlanes ensure that resource-intensive compilation and testing +processes don't impact production applications. + +BuildPlanes integrate with Argo Workflows to provide a scalable, Kubernetes-native CI/CD execution environment. They +handle the complete build lifecycle, from source code retrieval through compilation, testing, and container image +creation. This separation also provides security benefits, isolating potentially untrusted build processes from +production environments. + +Platform engineers configure BuildPlanes with the necessary tools, credentials, and policies for building applications. +This includes container registry credentials, build tool configurations, and security scanning policies. BuildPlanes can +be scaled independently based on build demand and can be distributed geographically to reduce latency for development +teams. + +### Observability Plane + +The **Observability Plane** provides centralized logging infrastructure for the entire platform. It collects and +aggregates logs from all other planes - Control, Data, and Build - providing a unified view of platform operations and +application behavior. + +Built on OpenSearch, the Observability Plane offers full-text search capabilities and log retention management. The +Observer API provides authenticated access to log data, enabling integration with external monitoring tools and +dashboards. Unlike other planes, the Observability Plane has no custom resources to manage - it operates independently +after initial setup, receiving log streams from Fluentbit agents deployed across the platform. + +Platform engineers configure the Observability Plane once during initial setup, establishing log collection pipelines, +retention policies, and access controls. This centralized approach ensures that all platform activity is auditable and +debuggable while maintaining security boundaries between organizations. + +## Environment + +An **Environment** represents a stage in the software delivery lifecycle, such as development, staging, or production. +Environments provide the context for deploying and running applications, defining the policies, configurations, and +constraints that apply to workloads in that stage. + +Environments are not just labels or namespaces - they are first-class abstractions that define where applications +should be deployed (which DataPlane) and serve as targets for deployment pipelines. This abstraction enables platform +teams to organize different stages of the delivery pipeline. + +Each environment represents a distinct deployment target. Development environments might target smaller clusters or +shared infrastructure, while production environments target dedicated, high-availability clusters. The Environment +resource primarily defines the mapping to infrastructure (DataPlane) and serves as a reference point for deployments +and promotion workflows. + +## DeploymentPipeline + +A **DeploymentPipeline** defines the allowed progression paths for applications moving through environments. It +represents the organization's software delivery process as a declarative configuration, encoding promotion rules, +approval requirements, and quality gates. + +DeploymentPipelines go beyond simple environment ordering to define complex promotion topologies. They can specify +parallel paths for different types of releases and conditional progressions based on application characteristics. +This flexibility allows organizations to implement sophisticated delivery strategies while maintaining governance and +control. + +The pipeline abstraction also serves as an integration point for organizational processes. Manual approval gates can be +configured for sensitive environments, automated testing can be triggered at promotion boundaries, and compliance checks +can be enforced before production deployment. This ensures that all applications follow organizational standards +regardless of which team develops them. + +## ReleaseBinding + +A **ReleaseBinding** connects a ComponentRelease to a specific Environment. This is what actually deploys a release to +a data plane—but it's more than just a reference. + +ReleaseBinding provides a way to override configuration for a specific environment. Values defined in the ComponentType +schema's `envOverrides` and Trait schema's `envOverrides` can be customized per environment through the ReleaseBinding. +This is where environment-specific differences reside: scaling in production versus development, resource limits, +storage classes, and so on—while the ComponentRelease itself remains unchanged. + +Once a ReleaseBinding is created, the ReleaseBinding controller renders the ComponentType and Trait templates with the +combined configuration, generates the necessary Kubernetes resources (Deployments, Services, ConfigMaps, etc.), and +produces a **Release** resource that is applied to the target data plane. + +## Component Types + +A **ComponentType** is a platform engineer-defined template that governs how components are deployed and managed in +OpenChoreo. It represents the bridge between developer intent and platform governance, encoding organizational +policies, best practices, and infrastructure patterns as reusable templates. + +ComponentTypes implement the platform's claim/class pattern at the component level. While developers create Components +that express their application requirements, platform engineers define ComponentTypes that specify how those +requirements should be fulfilled. This separation enables developers to focus on application logic while platform +engineers maintain control over infrastructure policies, resource limits, security configurations, and operational +standards. + +Each ComponentType is built around a specific **workload type** - the primary Kubernetes resource that will run the +application. OpenChoreo supports four fundamental workload types: + +- **deployment**: For long-running services that need continuous availability +- **statefulset**: For applications requiring stable network identities and persistent storage +- **cronjob**: For scheduled tasks that run at specific times or intervals +- **job**: For one-time or on-demand batch processing tasks + +The ComponentType uses a **schema-driven architecture** that defines what developers can configure when creating +components. This schema consists of two types of parameters: + +**Parameters** are configurations captured in the ComponentRelease and applied uniformly wherever that release is +deployed. These include settings like replica counts, image pull policies, and container ports. When you deploy the +same ComponentRelease to multiple environments, the parameter values are identical. To change parameters, you update +the Component and create a new ComponentRelease. + +**EnvOverrides** are configurations that can be overridden on a per-environment basis through ReleaseBinding resources. +These typically include resource allocations, scaling limits, and environment-specific policies. This flexibility +allows platform engineers to provide generous resources in production while constraining development environments to +optimize infrastructure costs. + +The schema uses an inline type definition syntax that makes configuration requirements explicit and self-documenting. +For example, `"integer | default=1"` declares an integer parameter with a default value, while +`"string | enum=Always,IfNotPresent,Never"` restricts a string to specific allowed values. This syntax supports +validation rules like minimum/maximum values, required fields, and enumerated choices. + +ComponentTypes define **resource templates** that generate the actual Kubernetes resources for components. Each +template uses CEL (Common Expression Language) expressions to dynamically generate resource manifests based on +component specifications. Templates can access component metadata, schema parameters, and workload specifications +through predefined variables like `${metadata.name}` and `${parameters.replicas}`. + +Templates support advanced patterns through conditional inclusion and iteration. The `includeWhen` field uses CEL +expressions to conditionally create resources based on configuration, enabling optional features like autoscaling or +ingress. The `forEach` field generates multiple resources from lists, useful for creating ConfigMaps from multiple +configuration files or managing multiple service dependencies. + +ComponentTypes can also restrict which **Workflows** developers can use for building components through the +`allowedWorkflows` field. This enables platform engineers to enforce build standards, ensure security scanning, or +mandate specific build tools for different component types. For instance, a web application ComponentType might only +allow Workflows that use approved frontend build tools and security scanners. + +This schema-driven approach ensures consistency across the platform while providing flexibility for different +application patterns. Platform engineers create ComponentTypes that encode organizational knowledge about how to run +applications securely and efficiently, while developers benefit from simplified configuration and automatic compliance +with platform standards. + +## Traits + +A **Trait** is a platform engineer-defined template that augments components with operational behavior without modifying +the ComponentType. Traits enable composable, reusable capabilities that can be attached to any component—such as +persistent storage, autoscaling, network policies, or sidecar injection. + +Traits use the same schema-driven approach as ComponentTypes, with `parameters` for static configuration and +`envOverrides` for environment-specific values. Developers attach Traits to their Components with instance-specific +parameters, while platform engineers can override environment-specific values through ReleaseBindings. + +Each Trait defines two types of operations: + +**Creates** generate new Kubernetes resources that don't exist in the base ComponentType. For example, a storage Trait +might create PersistentVolumeClaims, or a monitoring Trait might create ServiceMonitor resources. + +**Patches** modify existing resources generated by the ComponentType. Using JSON Patch operations with array filtering, +Traits can inject environment variables, add volume mounts, attach sidecar containers, or add labels and annotations +to existing resources. + +This separation between ComponentTypes (base deployment patterns) and Traits (composable capabilities) enables platform +engineers to define orthogonal concerns independently. Rather than creating separate ComponentTypes for every combination +of features, platform engineers define focused Traits that developers can mix and match as needed. + +## ComponentWorkflow + +A **ComponentWorkflow** is a platform engineer-defined template specifically designed for building components in +OpenChoreo. Unlike generic automation workflows, ComponentWorkflows enforce a structured schema for repository +information while providing flexibility for additional build configuration, enabling powerful build-specific platform +features like auto-builds, webhooks, and build traceability. + +ComponentWorkflows address the unique requirements of component builds that generic workflows cannot solve. Component +builds need to power manual build actions in the UI, integrate with Git webhooks for auto-builds, maintain build +traceability linking container images to source commits, and support monorepo structures by identifying specific +application paths. These features require the platform to reliably locate critical repository fields, which is only +possible with a predictable schema structure. + +Each ComponentWorkflow defines three key sections: + +**System Parameters Schema** enforces a required structured schema for repository information. This schema must follow +a specific structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, and +`repository.appPath` fields, all of type string. Platform engineers can customize defaults, enums, and descriptions +within each field, but must maintain the field names, nesting structure, and types. This predictable structure enables +build-specific platform features to work reliably across all component workflows while still giving platform engineers +control over validation rules and default values. + +**Developer Parameters Schema** provides complete freedom for platform engineers to define additional build +configuration. This flexible schema can include any structure the platform engineer designs - build version numbers, +test modes, resource allocations, timeout settings, caching configurations, retry limits, and more. The schema supports +all types including integers, booleans, strings, arrays, and nested objects, with full validation through defaults, +minimums, maximums, and enums. This separation between required system parameters and flexible developer parameters +balances platform reliability with configuration freedom. + +**Run Template** contains the actual Kubernetes resource specification (typically an Argo Workflow) with template +variables for dynamic value injection. These expressions access context variables like `${metadata.workflowRunName}`, +`${metadata.componentName}`, `${metadata.projectName}`, and `${metadata.orgName}` for runtime information, system parameter values +through `${systemParameters.*}` for repository details, and developer parameter values through `${parameters.*}` for +custom configuration. Platform engineers can also hardcode platform-controlled parameters directly in the template, +such as builder images, registry URLs, security scanning settings, and organizational policies. + +ComponentTypes govern which ComponentWorkflows developers can use through the `allowedWorkflows` field. This enables +platform engineers to enforce build standards per component type, ensuring that web applications use approved frontend +build tools, backend services use appropriate security scanners, and different component types follow their specific +build requirements. + +Components reference ComponentWorkflows in their `workflow` field, providing the system parameters for repository +information and developer parameters for build configuration. The platform handles template rendering, secret +synchronization, and execution management in the build plane, with ComponentWorkflowRun resources tracking individual +build executions. + +The ComponentWorkflow abstraction thus provides a specialized interface for component builds that balances platform +needs with developer flexibility. Platform engineers control build implementation, security policies, and +infrastructure configurations while ensuring build-specific features work reliably. Developers get a simplified +interface for configuring builds without managing complex CI/CD pipeline definitions. The separation from generic +workflows makes clear that component builds have unique requirements deserving dedicated abstractions, while +maintaining the schema-driven approach that characterizes OpenChoreo's architecture. diff --git a/versioned_docs/version-v0.11.x/concepts/resource-relationships.md b/versioned_docs/version-v0.11.x/concepts/resource-relationships.md new file mode 100644 index 0000000..5e9df76 --- /dev/null +++ b/versioned_docs/version-v0.11.x/concepts/resource-relationships.md @@ -0,0 +1,169 @@ +--- +title: Resource Relationships +description: How resources connect and interact within the platform +--- + +# Resource Relationships + +OpenChoreo's resources form a carefully designed hierarchy that balances flexibility with governance. Understanding how +these resources relate to each other is essential for designing applications, troubleshooting issues, and managing the +platform effectively. These relationships define ownership, inheritance, and dependencies throughout the system. + +## Ownership Hierarchy + +The ownership model in OpenChoreo follows a strict hierarchical structure where each resource has a clear parent and +defined scope. This hierarchy provides namespace isolation, access control boundaries, and lifecycle management. + +### Organization as Root + +At the top of the hierarchy, the **Organization** serves as the root container for all resources. Every resource in +OpenChoreo ultimately belongs to an organization, establishing the fundamental tenant boundary in multi-tenant +deployments. Organizations own platform resources like DataPlanes and Environments, application resources like Projects +and Components, and runtime resources generated by the platform. + +This ownership model ensures complete isolation between different organizations. Resources from one organization cannot +reference or interact with resources from another organization. This isolation extends to the runtime level, where +different organizations' workloads run in separate namespaces with distinct security boundaries. + +### Project Ownership + +Within an organization, **Projects** form the next level of ownership for application resources. Projects own +Components, establishing team boundaries and application domains. This ownership relationship means that components +cannot exist without a parent project, and deleting a project removes all its components. + +The project ownership boundary also defines the scope for internal communication. Components within the same project +can reference each other directly and communicate without crossing security boundaries. This locality enables teams to +work efficiently within their domain while maintaining isolation from other projects. + +### ComponentType + +**ComponentTypes** define platform-level templates that govern how components are deployed. Each ComponentType +specifies a workload type (deployment, statefulset, cronjob, or job) and provides a schema for configurable +parameters. Platform engineers create ComponentTypes that encode organizational policies, resource templates, and +operational best practices. + +ComponentTypes serve as the platform's contract for component deployment. They define what developers can configure +through parameter schemas, what resources will be created through resource templates, and which workflows are allowed +for building components. By centralizing these definitions in ComponentTypes, platform teams ensure consistency across +all applications while maintaining control over infrastructure patterns. + +### Component to ComponentType + +**Components** reference a ComponentType using the format `{workloadType}/{componentTypeName}`. This relationship +establishes which template governs the component's deployment. The component provides parameter values that conform to +the schema defined in the ComponentType, and these parameters are validated automatically. + +The component-to-ComponentType relationship is fundamental to OpenChoreo's governance model. Components cannot be +created without referencing a valid ComponentType, ensuring all deployments follow platform standards. This +relationship also determines which resource templates will be used to generate the actual Kubernetes resources. + +### Trait Composition + +**Traits** attach additional capabilities to components through composition. Each component can instantiate multiple +traits, such as persistent storage, caching, or monitoring. Traits use the same schema-driven approach as +ComponentTypes, with parameters that can be overridden per environment through ReleaseBinding resources. + +Traits maintain an independent lifecycle from components but are applied together during deployment. This separation +enables platform engineers to define reusable capabilities that can be composed into different component types. The +trait relationship provides flexibility while maintaining governance through schema validation. + +### Workflow Integration + +**Workflows** define build and automation templates that components can reference through their workflow configuration. +ComponentTypes can restrict which workflows are allowed, ensuring components use appropriate build strategies. This +relationship between components, ComponentTypes, and Workflows enables platform teams to enforce build standards and +security policies. + +When a component references a Workflow, it provides schema values that configure the workflow execution. The Workflow +template uses these values along with platform-controlled parameters to generate the actual CI/CD pipeline. This +separation enables developers to trigger builds with simple configuration while platform engineers maintain control +over build infrastructure and security. + +### Component to WorkflowRun + +Components trigger **WorkflowRuns** through their workflow configuration to build container images. Each WorkflowRun +represents an execution instance of a Workflow template with specific parameter values. WorkflowRuns maintain a +relationship back to their originating component and the specific commit that triggered them. + +This relationship provides complete traceability from running containers back to source code. Platform operators can +trace any container image to the WorkflowRun that built it, which links to the component and ultimately to the source +repository and commit. This traceability is essential for debugging, compliance, and security auditing. + +### ComponentRelease and ReleaseBinding + +A **ComponentRelease** is an immutable snapshot of a component at a specific point in time. It captures the Component, +its Workload configuration, the selected ComponentType, and any attached Traits into a single versioned resource. This +snapshot works like a lock file—preserving the exact state so that the release remains stable and repeatable, even if +the original resources are later updated. + +To deploy a ComponentRelease to an environment, you create a **ReleaseBinding**. This resource binds the release to a +specific environment and provides environment-specific overrides for ComponentType and Trait parameters. The +ReleaseBinding controller renders the final Kubernetes manifests and produces a **Release** resource that is applied +to the target DataPlane. + +This relationship chain—Component → ComponentRelease → ReleaseBinding → Release—ensures complete governance while +enabling environment-specific customization. The immutable ComponentRelease supports a "create once, deploy many" +workflow, where the same release can be safely promoted across environments (dev → staging → prod) without drift. + +## Network Relationships + +Network relationships in OpenChoreo define how components communicate and expose functionality. These relationships +translate into concrete network policies, routing rules, and security configurations. + +### Endpoint Exposure + +**Endpoints** establish relationships between components and their network interfaces. A component can expose multiple +endpoints with different visibility scopes and protocols. These relationships define how the component can be accessed +and by whom. + +The endpoint relationship includes more than just network configuration. It establishes contracts about protocols, +expected behavior, and API compatibility. Other components can depend on these contracts, with the platform ensuring +that communication follows the declared patterns. + +### Connection Dependencies + +**Connections** create explicit relationships between components and their dependencies. When a component declares a +connection to another service, it establishes a formal dependency that the platform can track, secure, and monitor. + +Connection relationships make dependencies between components explicit. This relationship model helps teams understand +their application architecture and service dependencies. + + +## Environment Progression + +Environment relationships define how applications move through the delivery pipeline from development to production. +These relationships ensure consistent progression while maintaining appropriate governance. + +### Pipeline Definition + +**DeploymentPipelines** establish relationships between environments, defining allowed transitions and promotion rules. +These relationships create a directed graph of environment progression, potentially with multiple paths for different +scenarios. + +Pipeline relationships include more than just ordering. They define approval requirements and testing gates. These +relationships ensure that applications follow organizational processes while enabling automation where appropriate. + + + +## Lifecycle Dependencies + +Resource relationships in OpenChoreo include lifecycle dependencies that ensure proper initialization, updates, and +cleanup. + +### Creation Order + +Some resources must be created before others can exist. DataPlanes must be registered before environments can target +them. Projects must exist before components can be created within them. These relationships ensure that the platform +maintains consistency during resource creation. + +### Update Propagation + +When resources are updated, changes propagate through relationships to dependent resources. Updating a ComponentType +triggers reconciliation of all components that reference it, regenerating their deployments and releases with the new +template. These relationships ensure that changes are consistently applied throughout the system. + +### Deletion Cascades + +Resource relationships define deletion behavior. When a project is deleted, all its components are removed. When a +component is deleted, its WorkflowRuns, ComponentReleases, ReleaseBindings, and Releases are cleaned up. These +cascading relationships ensure that resources are properly cleaned up without leaving orphaned objects. diff --git a/versioned_docs/version-v0.11.x/concepts/runtime-model.md b/versioned_docs/version-v0.11.x/concepts/runtime-model.md new file mode 100644 index 0000000..6f2ab3e --- /dev/null +++ b/versioned_docs/version-v0.11.x/concepts/runtime-model.md @@ -0,0 +1,120 @@ +--- +title: Runtime Model +description: Runtime execution and deployment model +--- + +# Runtime Model + +The runtime model describes how OpenChoreo's abstractions transform into running systems. When developers declare +projects and components, the platform orchestrates a sophisticated runtime environment that provides isolation, +security, and observability. Understanding this transformation from declaration to execution helps teams design better +applications and troubleshoot issues effectively. + +## Cell Architecture + +At runtime, each **Project** transforms into a **Cell** - a secure, isolated runtime boundary that encapsulates all +components of an application domain. This transformation represents a fundamental principle of OpenChoreo: +organizational boundaries in code become physical boundaries in infrastructure. + +Cells provide complete isolation between different application domains. Each cell operates as an independent unit with +its own namespace, network policies, and security boundaries. Components within a cell can communicate freely using +cluster-local networking, but all communication across cell boundaries must flow through well-defined gateways. This +architecture ensures that failures, security breaches, or performance issues in one cell cannot directly impact others. + +The cell model aligns with microservices best practices and Domain-Driven Design principles. By mapping bounded contexts +to isolated runtime units, OpenChoreo ensures that architectural boundaries are enforced by infrastructure. This +alignment reduces the cognitive load on developers - the same mental model used for designing applications applies to +their runtime behavior. + +## Traffic Flow Patterns + +OpenChoreo implements a structured approach to network traffic through directional gateways, each serving a specific +purpose in the overall communication architecture. These patterns provide clarity about how data flows through the +system while enabling sophisticated security and routing policies. + +### Northbound Ingress + +Northbound ingress handles traffic entering cells from the public internet. This gateway serves as the entry point for +external users, customers, and third-party integrations accessing public APIs and web applications. The platform +automatically configures load balancing and TLS termination at this boundary. + +The northbound gateway translates friendly DNS names into internal service endpoints, handles HTTP routing based on +hostnames and paths, and enforces public-facing API policies. This abstraction means developers can focus on application +logic while the platform manages the complexities of internet-facing services. + +### Southbound Egress + +Southbound egress manages traffic leaving cells to reach external services on the internet. This gateway provides +controlled access to third-party APIs, cloud services, and external databases. By channeling all outbound traffic +through a managed gateway, the platform can enforce security policies, manage credentials, and provide observability for +external dependencies. + +The southbound gateway enables capabilities like egress filtering to prevent data exfiltration, credential injection for +authenticated external services, and circuit breaking for unreliable external dependencies. This controlled approach to +external communication reduces security risks while improving reliability. + +### Westbound Ingress + +Westbound ingress handles traffic from other parts of the organization entering the cell. This gateway manages internal +API consumption, service-to-service communication across projects, and administrative access. Unlike public northbound +traffic, westbound traffic comes from trusted sources within the organization but still requires authentication and +authorization. + +The westbound gateway enables internal service discovery, allowing components in other cells to locate and communicate +with services using logical names. It enforces organization-wide policies while allowing more permissive communication +than public interfaces. This balance enables productive development while maintaining security boundaries. + +### Eastbound Egress + +Eastbound egress manages traffic leaving the cell to reach other cells or internal services within the organization. +This gateway handles inter-project dependencies, shared service consumption, and platform service integration. By +managing internal outbound traffic, the platform can track dependencies, enforce quotas, and provide circuit breaking +between internal services. + +The eastbound gateway makes internal service dependencies explicit and observable. Teams can understand which other +projects they depend on, platform engineers can track usage patterns across the organization, and the system can prevent +cascading failures through circuit breaking and retry policies. + +## Network Security + +OpenChoreo manages network security through the cell architecture and gateway pattern. Communication within a cell is +allowed between components of the same project, while all cross-cell communication must flow through the defined +gateways. This provides security boundaries between different application domains. + +The platform uses Cilium for network policy enforcement and Kgateway for ingress traffic management. Developers +declare their components' endpoints and connections in the workload specification, and the platform handles the +underlying network configuration. + +## Workload Execution + +When components deploy to a runtime environment, OpenChoreo orchestrates a complex series of transformations. The +abstract component definition combines with workload specifications, environment configurations, and platform policies +to produce concrete Kubernetes resources. + +The platform manages the complete lifecycle of these resources. It creates deployments with appropriate resource limits +and scaling parameters, configures services for network access and load balancing, injects configuration and secrets +from secure stores, and establishes health checks and readiness probes. This orchestration happens transparently - +developers see their components running while the platform manages the underlying complexity. + +Workload execution is environment-aware. The same component might run with different resource allocations, replica +counts, or configuration values in different environments. The platform manages these variations through the binding +system, where environment-specific bindings override default values from classes and workload specifications. + +## Service Discovery and Load Balancing + +Service discovery uses standard Kubernetes DNS, allowing services to communicate using service names. Within a cell, +components can discover each other using simple service names. Across cells, services require routing through the +appropriate gateways. + +## Observability + +The runtime model includes centralized logging through the Observability Plane. Logs from all containers flow through +the platform's collection pipeline using Fluentbit, enriched with metadata about the source component, project, and +environment. This enrichment enables queries across the entire platform while maintaining clear attribution of log +entries to their sources. + +The Observer API provides access to these logs, allowing developers to search and analyze application behavior across +environments. This centralized logging approach ensures that debugging information is always available without requiring +additional configuration from developers. + + diff --git a/versioned_docs/version-v0.11.x/getting-started/deploy-first-component.mdx b/versioned_docs/version-v0.11.x/getting-started/deploy-first-component.mdx new file mode 100644 index 0000000..6d22fcc --- /dev/null +++ b/versioned_docs/version-v0.11.x/getting-started/deploy-first-component.mdx @@ -0,0 +1,159 @@ +--- +title: Deploy Your First Component +--- + +import CodeBlock from '@theme/CodeBlock'; +import {versions} from '../_constants.mdx'; + +# Deploy Your First Component + +This guide walks you through deploying your first component on OpenChoreo. By the end of this tutorial, you'll have a running web service accessible through the platform, complete with monitoring and security configured automatically. + +## Prerequisites + +Before you begin, ensure you have: + +- **OpenChoreo installed** in your Kubernetes cluster (see [On Self-Hosted Kubernetes](./try-it-out/on-self-hosted-kubernetes.mdx) or the [Operations Guide](../operations/deployment-topology.mdx) for production setup) +- **kubectl** configured to access your cluster +- **kubectl context** set to your cluster (should be `k3d-openchoreo` if following the k3d setup) + +## Step 1: Verify Your Setup + +First, make sure you have set up OpenChoreo on your cluster following one of the installation guides. + +You should see all OpenChoreo components running with the control plane and data plane pods in `Running` status. + +## Step 2: Deploy the Go Greeter Service + +For this tutorial, we'll use the Go Greeter Service sample that comes with OpenChoreo. This is a simple web service that demonstrates OpenChoreo's core capabilities. + + +{`kubectl apply -f https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/samples/from-image/go-greeter-service/greeter-service.yaml`} + + +This single command creates: +- **Component**: Defines the application and its requirements (references the `deployment/service` ComponentType) +- **Workload**: Specifies the container image and runtime configuration +- **ReleaseBinding**: Deploys the component to the development environment +- **SecretReference**: Manages external secrets for the component + +## Step 3: Monitor the Deployment + +Check that all resources are created: + +```bash +kubectl get component,workload,releasebinding -A +``` + +Check the component status: + +```bash +kubectl get component greeter-service +``` + +Monitor the component deployment: + +```bash +kubectl get releasebinding greeter-service-development +``` + +## Step 4: Verify the Deployment + +Wait for the service to be ready (this may take 1-2 minutes). + +Check the actual Kubernetes deployment: + +```bash +kubectl get deployment -A | grep greeter +``` + +Verify pods are running: + +```bash +kubectl get pods -A | grep greeter +``` + +Check HTTP routes are configured: + +```bash +kubectl get httproute -A -o wide +``` + +## Step 5: Test Your Application + +Test the greeter service endpoint: + +```bash +curl http://development.openchoreoapis.localhost:19080/greeter-service/greeter/greet +``` + +You should receive a successful response: +```text +Hello, Stranger! +``` + +You can also test with a name parameter: +```bash +curl http://development.openchoreoapis.localhost:19080/greeter-service/greeter/greet?name=OpenChoreo +``` + +Expected output: +```text +Hello, OpenChoreo! +``` + +This confirms that: +- Your component is deployed and running +- The API gateway is properly configured +- Network routing is working correctly +- Security policies are applied automatically + +## Step 6: Explore What OpenChoreo Created + +Let's examine what OpenChoreo automatically created for your component. + +View the OpenChoreo resources: + +```bash +kubectl get component,workload,releasebinding -n default +``` + +Check the underlying Kubernetes resources: + +```bash +kubectl get deployment,pod,svc -A | grep greeter +``` + +View the HTTP routing configuration: + +```bash +kubectl describe httproute -A | grep -A 20 greeter +``` + +OpenChoreo automatically created: +- **Component** - High-level application definition (using the `deployment/service` ComponentType) +- **Workload** - Container deployment specification +- **ReleaseBinding** - Environment-specific deployment configuration +- **Deployment** - Kubernetes deployment managing pods +- **Service** - Kubernetes service for networking +- **HTTPRoute** - Gateway API routing configuration +- **Secret** - External secrets synchronized from the secret store + +## Summary + +You've successfully: +- Deployed your first OpenChoreo component from a container image +- Tested API access through the OpenChoreo gateway +- Explored the resources OpenChoreo created automatically + +Your application is now running in a production-ready environment with enterprise-grade security, networking, and observability—all configured automatically by OpenChoreo! + +**Ready for more?** Try deploying additional samples or start building your own components using OpenChoreo's powerful abstractions. + +## Clean Up + +To remove the sample application: + + +{`kubectl delete -f https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/samples/from-image/go-greeter-service/greeter-service.yaml`} + diff --git a/versioned_docs/version-v0.11.x/getting-started/qsg-backstage-ui.png b/versioned_docs/version-v0.11.x/getting-started/qsg-backstage-ui.png new file mode 100644 index 0000000000000000000000000000000000000000..8d4a1c573dd533ae70be958c1af48d24cb4d84f8 GIT binary patch literal 619762 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