|
| 1 | +--- |
| 2 | +title: Developer Abstractions |
| 3 | +description: Developer abstractions for building and running applications |
| 4 | +--- |
| 5 | + |
| 6 | +# Developer Abstractions |
| 7 | + |
| 8 | +Developer abstractions in OpenChoreo enable teams to build, deploy, and operate cloud-native applications without |
| 9 | +managing infrastructure complexity. These abstractions provide a declarative model for expressing application |
| 10 | +architecture, dependencies, and operational requirements while the platform handles the underlying Kubernetes resources, |
| 11 | +networking, and security configurations automatically. |
| 12 | + |
| 13 | +## Project |
| 14 | + |
| 15 | +A **Project** represents a bounded context in Domain-Driven Design terms - a cohesive collection of components that |
| 16 | +together implement a specific business capability or application domain. It serves as the primary organizational unit |
| 17 | +for developers, defining clear boundaries for code ownership, deployment coordination, and operational responsibility. |
| 18 | + |
| 19 | +Projects establish both logical and physical boundaries in the platform. Logically, they group related components that |
| 20 | +share common business logic, data models, and team ownership. Physically, they translate into isolated deployment units |
| 21 | +with dedicated namespaces, network boundaries, and security policies. This alignment between organizational structure |
| 22 | +and technical architecture enables teams to work autonomously while maintaining clear integration points with other |
| 23 | +projects. |
| 24 | + |
| 25 | +The project boundary also defines the scope for internal communication and shared resources. Components within a project |
| 26 | +can communicate freely with each other. This locality principle reduces complexity for |
| 27 | +developers while maintaining security and isolation between different application domains. |
| 28 | + |
| 29 | +## Component |
| 30 | + |
| 31 | +A **Component** represents a deployable unit of software - the fundamental building block of applications in OpenChoreo. |
| 32 | +Each component encapsulates a specific piece of functionality, whether it's a microservice handling business logic, a |
| 33 | +web application serving user interfaces, or a background job processing data. |
| 34 | + |
| 35 | +Components use a **ComponentType** reference to determine their deployment characteristics. This reference follows the |
| 36 | +format `{workloadType}/{componentTypeName}`, such as `deployment/web-service` or `cronjob/data-processor`. This explicit |
| 37 | +typing allows platform engineers to define multiple variations of deployment patterns for the same workload type, each |
| 38 | +tuned for different use cases. |
| 39 | + |
| 40 | +The Component resource connects four essential elements: |
| 41 | + |
| 42 | +**ComponentType Reference** specifies which platform-defined template governs this component's deployment. The |
| 43 | +ComponentType defines the available configuration schema, resource templates, and allowed workflows. This separation |
| 44 | +of concerns means developers work with a simplified interface while platform engineers maintain control over |
| 45 | +infrastructure patterns. |
| 46 | + |
| 47 | +**Parameters** provide the component-specific configuration values that conform to the schema defined in the |
| 48 | +ComponentType. When a ComponentRelease is created, these parameter values are captured in the release snapshot. The |
| 49 | +same values then apply wherever that release is deployed—if you deploy the same ComponentRelease to dev, staging, and |
| 50 | +prod, the parameters are identical across all environments. To change parameter values, you update the Component and |
| 51 | +create a new ComponentRelease. Environment-specific values (like resource limits or storage sizes) are handled |
| 52 | +separately through `envOverrides` in ReleaseBinding resources. |
| 53 | + |
| 54 | +**Traits** enable composition of additional capabilities into the component. Each trait instance adds specific |
| 55 | +functionality like persistent storage, caching, or monitoring. Traits can be instantiated multiple times with |
| 56 | +different configurations using unique instance names. For example, a component might attach multiple persistent volume |
| 57 | +traits for different storage needs, each with its own size, storage class, and mount configuration. Traits use the |
| 58 | +same schema-driven approach as ComponentTypes, with parameters set in the Component and environment-specific overrides |
| 59 | +applied through ReleaseBinding resources. |
| 60 | + |
| 61 | +**Workflow Configuration** optionally specifies how to build the component from source code. This references a |
| 62 | +Workflow and provides the developer-configured schema values needed to execute builds. The workflow integration |
| 63 | +enables automated container image creation triggered by code changes or manual developer actions. |
| 64 | + |
| 65 | +The component abstraction thus becomes a declarative specification that combines: |
| 66 | +- A ComponentType that defines *how* to deploy |
| 67 | +- Parameters that configure *what* to deploy |
| 68 | +- Traits that compose *additional capabilities* |
| 69 | +- A Workflow that defines *how to build* |
| 70 | + |
| 71 | +This composition-based approach enables developers to assemble complex applications from reusable building blocks |
| 72 | +while the platform ensures consistency, governance, and operational best practices through the underlying ComponentType |
| 73 | +and Trait templates. |
| 74 | + |
| 75 | +## Workload |
| 76 | + |
| 77 | +A **Workload** defines the runtime contract of a component - specifying what the component needs to run. The workload |
| 78 | +focuses on application requirements rather than infrastructure details, which are handled by the platform through Classes. |
| 79 | + |
| 80 | +Each component has one workload that describes its runtime needs through several key specifications: |
| 81 | + |
| 82 | +**Containers** define the container images to deploy, along with their commands, arguments, and environment variables. |
| 83 | +This tells the platform what code to run and how to configure it. |
| 84 | + |
| 85 | +**Endpoints** specify the network interfaces that the component exposes - the ports and protocols it listens on. Each |
| 86 | +endpoint declares its type (HTTP, gRPC, TCP, etc.) and port number. These definitions tell the platform what network |
| 87 | +services the component provides, enabling automatic service creation and network policy generation. |
| 88 | + |
| 89 | +**Connections** declare the component's dependencies on other services, whether internal to the platform or external |
| 90 | +third-party services. Each connection specifies how to inject service information into the component through environment |
| 91 | +variables. This enables the platform to manage service discovery, configure network policies, and track dependencies. |
| 92 | + |
| 93 | +This declarative specification can be generated from configuration files in the source repository or applied directly |
| 94 | +to the cluster. The separation between workload (what the application needs) and classes (how the platform provides it) |
| 95 | +enables platform teams to control infrastructure policies while developers focus on application requirements. Resource |
| 96 | +limits, scaling parameters, and operational policies come from the ServiceClass or WebApplicationClass, while the |
| 97 | +workload simply declares what the application needs to function. |
| 98 | + |
| 99 | +## ComponentWorkflowRun |
| 100 | + |
| 101 | +A **ComponentWorkflowRun** represents a runtime execution instance of a ComponentWorkflow - a specialized workflow type |
| 102 | +designed specifically for building components. While ComponentWorkflows define the build template and schema, |
| 103 | +ComponentWorkflowRuns represent actual build executions with specific parameter values and ownership tracking. |
| 104 | + |
| 105 | +ComponentWorkflowRuns bridge the gap between developer intent and CI/CD execution for component builds. Developers |
| 106 | +create ComponentWorkflowRun resources to trigger builds, providing component ownership information, repository details, |
| 107 | +and build parameters. The platform handles all the complexity of rendering the final workflow specification, |
| 108 | +synchronizing secrets, and managing execution in the build plane. |
| 109 | + |
| 110 | +Each ComponentWorkflowRun captures three essential pieces of information: |
| 111 | + |
| 112 | +**Ownership Tracking** links the build execution to a specific component and project. This enables traceability, |
| 113 | +allowing the platform to track which builds belong to which components and maintain build history per component. The |
| 114 | +ownership information includes both project name and component name, ensuring proper audit trails and enabling |
| 115 | +component-specific build operations. |
| 116 | + |
| 117 | +**System Parameters** provide the structured repository information required for build-specific platform features. These |
| 118 | +parameters follow a fixed structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, |
| 119 | +and `repository.appPath` fields. This predictable structure enables the platform to support auto-builds triggered by |
| 120 | +webhooks, manual build actions in the UI, build traceability linking images to source commits, and monorepo support by |
| 121 | +identifying specific application paths within repositories. |
| 122 | + |
| 123 | +**Developer Parameters** provide values for the flexible configuration schema defined by the platform engineer in the |
| 124 | +ComponentWorkflow. These might include build version numbers, test modes, resource allocations, timeout settings, |
| 125 | +caching configurations, and retry limits. The schema validation ensures type correctness and constraint satisfaction |
| 126 | +automatically. |
| 127 | + |
| 128 | +This abstraction provides a specialized interface for component builds, where developers interact with curated schemas |
| 129 | +rather than complex CI/CD pipeline definitions. The separation of concerns allows platform engineers to control build |
| 130 | +implementation and security policies through ComponentWorkflow templates while developers manage repository information |
| 131 | +and build parameters through ComponentWorkflowRun instances. ComponentWorkflowRuns can be created manually for ad-hoc |
| 132 | +builds or automatically by platform controllers in response to code changes, supporting both interactive development and |
| 133 | +fully automated CI/CD pipelines while maintaining consistent execution patterns and governance specifically tailored for |
| 134 | +component build operations. |
0 commit comments