Caution
This project is in early development and not yet ready for production use.
The OCM K8s Toolkit
- supports the deployment of an OCM component and its resources, like Helm charts or other manifests, into a Kubernetes cluster with the help of kro and a deployer, e.g. FluxCD.
- provides a controller to transfer OCM components.
You should be familiar with the following concepts:
- Open Component Model
- Kubernetes ecosystem
- kro
- Kubernetes resource deployer such as FluxCD.
Note
The following section provides a high-level overview of the OCM K8s Toolkit and its components regarding the deployment of an OCM resource in a very basic scenario. To learn more about the transfer of OCM component versions, please take a look at its architecture document.
The primary purpose of OCM K8s Toolkit is simple: Deploy an OCM resource from an OCM component version into a Kubernetes cluster.
The implementation, however, is a bit more complex as deployments must be secure and configurable. Additionally, an OCM Resource can, in theory, contain any form of deployable resource, for instance a Helm chart, a Kustomization, or plain Kubernetes manifests. Each of these resources has its own way of being deployed or configured. So, instead of creating a generic deployer that offers all these functionalities, we decided to use existing tools that are already available in the Kubernetes ecosystem.
The following diagram describes a basic scenario in which an OCM resource containing a Helm chart is deployed into a Kubernetes cluster using the OCM K8s Toolkit as well as kro and FluxCD. kro is used to orchestrate the deployment and to transport information about the location of the OCM resource to FluxCD. FluxCD takes the location of the OCM resource, downloads the chart, configures it if necessary, and deploys it into the Kubernetes cluster.
flowchart TB
classDef cluster fill:white,color:black,stroke:black;
classDef reconciledBy fill:#dedede,stroke:black,stroke-dasharray: 5,color:black;
classDef k8sObject fill:#b3b3b3,color:black,stroke:black;
classDef information fill:#b3b3b3,color:black,stroke:black,stroke-dasharray: 2;
classDef ocm fill:white,stroke:black,color:black;
classDef legendStyle fill:white,stroke:black,color:black,stroke-dasharray: 2;
classDef legendStartEnd height:0px;
classDef legendItems fill:#b3b3b3,stroke:none,color:black;
subgraph legend[Legend]
start1[ ] ---references[referenced by] --> end1[ ]
start2[ ] -.-creates -.-> end2[ ]
start3[ ] ---instanceOf[instance of] --> end3[ ]
start4[ ] ~~~reconciledBy[reconciled by] ~~~ end4[ ]
start5[ ] ~~~k8sObject[k8s object] ~~~ end5[ ]
start6[ ] ~~~templateOf[template of] ~~~ end6[ ]
end
subgraph background[ ]
direction TB
subgraph ocmRepo[OCM Repository]
subgraph ocmCV[OCM Component Version]
subgraph ocmResource[OCM Resource: HelmChart]
end
end
end
subgraph k8sCluster[Kubernetes Cluster]
subgraph kroRGD[kro]
subgraph rgd[RGD: Simple]
direction LR
rgdRepository[Repository]
rgdComponent[Component]
rgdResourceHelm[Resource: HelmChart]
rgdSource[FluxCD: OCI Repository]
rgdHelmRelease[FluxCD: HelmRelease]
end
end
subgraph kroInstance[kro]
subgraph instanceSimple[Instance: Simple]
subgraph ocmK8sToolkit[OCM K8s Toolkit]
k8sRepo[Repository] --> k8sComponent[Component] --> k8sResource[Resource: HelmChart]
end
subgraph fluxCD[FluxCD]
source[OCI Repository] --> helmRelease[HelmRelease]
end
k8sResource --> source
end
end
kroRGD & instanceSimple --> crdSimple[CRD: Simple]
helmRelease --> deployment[Deployment: Helm chart]
end
ocmRepo --> k8sRepo
end
linkStyle default fill:none,stroke:black;
linkStyle 2,3,16,18 stroke:black,stroke-dasharray: 10;
linkStyle 4,5,17 stroke:black,stroke-dasharray: 4;
class start1,end1,start2,end2,start3,end3,start4,end4,start5,end5,start6,end6 legendStartEnd;
class references,creates,instanceOf legendItems;
class templateOf,rgdRepository,rgdComponent,rgdResourceHelm,rgdSource,rgdHelmRelease information;
class reconciledBy,ocmK8sToolkit,fluxCD,kroRGD,kroInstance reconciledBy;
class k8sObject,rgd,k8sRepo,k8sComponent,k8sResource,source,helmRelease,deployment,crdSimple,instanceSimple k8sObject;
class ocmRepo,ocmCV,ocmResource ocm;
class k8sCluster cluster;
class legend legendStyle;
The above diagram shows an OCM resource of type helmChart. This resource is part of an OCM component version,
which is located in an OCM repository.
In the Kubernetes Cluster we can see several Kubernetes (custom) resources. The ResourceGraphDefintion
(RGD: Simple) contains the template of all the resources for deploying the Helm chart into the Kubernetes cluster.
kro creates a Custom Resource Definition (CRD) Simple based on that ResourceGraphDefinition. By creating an instance
of this CRD (Instance: Simple), the resources are created and reconciled by the respective controllers:
Repository: Points to the OCM repository and checks if it is reachable by pinging it.Component: Refers to theRepositoryand downloads and verifies the OCM component version descriptor.Resource: Points to theComponent, downloads the OCM component version descriptor from which it gets the location of the OCM resource. It then downloads the resource to verify its signature (optional) and publishes the location of the resource in its status.
Important
With FluxCD, this only works if the OCM resource has an access for which FluxCD has a corresponding Source type (e.g. an OCI or a GitHub repository)
As a result, FluxCD can now consume the information of the Resource and deploy the Helm chart:
OCIRepository: Watches and downloads the resource from the location provided by theResourcestatus.HelmRelease: Refers to theOCIRepository, lets you configure the Helm chart, and creates the deployment into the Kubernetes cluster.
A more detailed architecture description of the OCM K8s Toolkit can be found here.
Currently, the OCM K8s Toolkit is available as image and Kustomization. A Helm chart is planned for the future.
To install the OCM K8s Toolkit into your running Kubernetes cluster, you can use the following commands:
# In the ocm-k8s-toolkit/ repository
make deployor
kubectl apply -k https://github.com/open-component-model/ocm-k8s-toolkit/config/default?ref=mainImportant
While the OCM K8s Toolkit technically can be used standalone, it requires kro and a deployer, e.g. FluxCD, to deploy an OCM resource into a Kubernetes cluster. The OCM K8s Toolkit deployment, however, does not contain kro or any deployer. Please refer to the respective installation guides for these tools:
- Setup your (test) environment with kind, kro, and FluxCD
- Deploying a Helm chart using a
ResourceGraphDefinitionwith FluxCD - Deploying a Helm chart using a
ResourceGraphDefinitioninside the OCM component version (bootstrap) with FluxCD - Configuring credentials for OCM K8s Toolkit resources to access private OCM repositories
Code contributions, feature requests, bug reports, and help requests are very welcome. Please refer to our Contributing Guide for more information on how to contribute to OCM.
OCM K8s Toolkit follows the CNCF Code of Conduct.
Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.