Warning
This repository has been archived in August 2024. The community is excited to be working on a new design for OLM (v1). As part of that effort, RukPak's functionality has been moved to v1's primary repository: operator controller.
If you have any questions, please engage with us:
RukPak runs in a Kubernetes cluster and defines APIs for installing cloud native content.
RukPak is a pluggable solution for the packaging and distribution of cloud-native content and supports advanced strategies for installation, updates, and policy. The project provides a content ecosystem for installing a variety of artifacts, such as Git repositories, Helm charts, OLM bundles, and more onto a Kubernetes cluster. These artifacts can then be managed, scaled, and upgraded in a safe way to enable powerful cluster extensions.
At its core, RukPak is a small set of APIs, packaged as Kubernetes CustomResourceDefinitions, and controllers that watch for those APIs. These APIs express what content is being installed on-cluster and how to create a running deployment of the content.
The RukPak project is community driven and is part of the broader Kubernetes ecosystem. New contributors are welcome and highly encouraged. See the contributing guidelines to get started.
This project uses GitHub issues and milestones to prioritize and keep track of ongoing work. To see the current state of the project, checkout the open issues and recent milestones.
The RukPak project currently houses all of its documentation directly in this repository. There are several sources of documentation. The below section of this README contains a high-level overview of the primary APIs and how to get started using RukPak.
The recommended way of installing RukPak is via a tagged release from
the releases page. There are detailed instructions provided in
the release notes on how to install a particular release. The only requirement is to have a kubectl client available
that is configured to target the cluster to install to.
Note: RukPak depends on cert-manager for creating and managing certificates for its webhooks. cert-manager should be installed prior to installing RukPak. See the cert-manager installation docs for more information on how to install cert-manager.
It is recommended to install the latest release to access the latest features and new bugfixes. RukPak releases target the linux operating system and support amd64, arm64, ppc64le, and s390x architectures via multi-arch images.
To install the latest release of RukPak, simply run:
kubectl apply -f https://github.com/operator-framework/rukpak/releases/latest/download/rukpak.yamlAnother installation option for developers interested in running RukPak locally is to clone the source code and deploy RukPak to a local kind cluster.
git clone https://github.com/operator-framework/rukpak && cd rukpak
make runNote: RukPak may take some time to become fully operational while its controllers and webhooks are spinning up during installation. As a result, please allow a few moments before creating Bundles/BundleDeployments if you are noticing unexpected failures.
The following make target is also available to developers that wish to debug the container remotely through dlv. Once completed, a remote debugging session may be attached through any preferred IDE on localhost:40000 :
make debugAs an example, the following launch.json file may be used to connect to the debugging session with vscode:
{
"version": "0.2.0",
"configurations": [
{
"name": "Remote Debugging",
"type": "go",
"request": "attach",
"mode": "remote",
"remotePath": "",
"port":40000,
"host":"127.0.0.1",
"showLog": true,
"trace": "log",
"logOutput": "rpc"
}
]
}There are currently no other supported ways of installing RukPak, although there are plans to add support for other popular packaging formats such as a Helm chart or an OLM bundle.
The RukPak project consists of a series of controllers, known as provisioners, that install and manage content on a Kubernetes cluster. See below for a more detailed look into the APIs that RukPak provides.
The provisioner currently implemented and bundled with RukPak is known as the plain provisioner. To get started with this provisioner on a local kind cluster, see the quickstart section of the plain provisioner README. To install the latest version of the provisioner on an existing cluster, see the installation guide. There will be other provisioners added to the RukPak project that support different content types.
The plain provisioner is able to source and unpack plain bundles. To learn more about the plain bundle format, see the plain bundle spec.
RukPak is composed of two primary APIs, Bundle and BundleDeployment, as well as the concept of a Provisioner. These components work together to bring content onto the cluster and install it, generating resources within the cluster. Below is a high level diagram depicting the interaction of the RukPak components.
graph TD
C[Provisioner]
C -->|Unpacks| D[Bundle]
C -->|Reconciles| E[BundleDeployment]
D ---|References| F((Content))
E -->|Creates/Manages| G([Cluster Resources])
A provisioner places a watch on both Bundles and BundleDeployments that refer to it explicitly. For a given bundle, the provisioner unpacks the contents of the Bundle onto the cluster. Then, given a BundleDeployment referring to that Bundle, the provisioner then installs the bundle contents and is responsible for managing the lifecycle of those resources.
A Bundle represents content that needs to be made available to other consumers in the cluster. Much like the contents
of a container image need to be pulled and unpacked in order for Pods to start using them,
Bundles are used to reference content that may need to be pulled and should be unpacked. In this sense, Bundle is a
generalization of the image concept, and can be used to represent any type of content.
Bundles do nothing on their own - they require a Provisioner to unpack and make their content available in-cluster.
They can be unpacked to any arbitrary storage medium such as a tar.gz file in a directory mounted into the provisioner
pods. Each Bundle has an associated spec.provisionerClassName field which indicates the Provisioner that should be
watching and unpacking that particular bundle type.
Example Bundle configured to work with the plain provisioner.
apiVersion: core.rukpak.io/v1alpha1
kind: Bundle
metadata:
name: my-bundle
spec:
source:
type: image
image:
ref: my-bundle@sha256:xyz123
provisionerClassName: core-rukpak-io-plainNote: Bundles are considered immutable once they are created. See the bundle immutability doc for more information.
⚠️ A BundleDeployment changes the state of the Kubernetes cluster by installing and removing objects. It's important to verify and trust the content that is being installed, and limit access (via RBAC) to the BundleDeployment API to only those who require those permissions.
The BundleDeployment API points to a Bundle and indicates that it should be “active”. This includes pivoting from
older versions of an active bundle.BundleDeployment may also include an embedded spec for a desired Bundle.
Much like Pods stamp out instances of container images, BundleDeployments stamp out a deployed version of
Bundles. BundleDeployment can be seen as a generalization of the Pod concept.
The specifics of how an BundleDeployment makes changes to a cluster based on a referenced Bundle is defined by the
Provisioner that is configured to watch that BundleDeployment.
Example BundleDeployment configured to work with the plain provisioner.
apiVersion: core.rukpak.io/v1alpha1
kind: BundleDeployment
metadata:
name: my-bundle-deployment
spec:
provisionerClassName: core-rukpak-io-plain
template:
metadata:
labels:
app: my-bundle
spec:
source:
type: image
image:
ref: my-bundle@sha256:xyz123
provisionerClassName: core-rukpak-io-plainA Provisioner is a controller that understands BundleDeployment and Bundle APIs and can take action.
Each Provisioner is assigned a unique ID, and is responsible for reconciling a Bundle and BundleDeployment with
a spec.provisionerClassName that matches that particular ID.
For example, in this repository the plain provisioner is implemented.
The plain provisioner is able to unpack a given plain+v0 bundle onto a cluster and then instantiate it, making the
content of the bundle available in the cluster.
If you are interested in implementing your own provisioner, please see the Provisioner Overview [DRAFT], which describes the expectations of provisioner implementations.
RukPak comes with a webhook for validating the upgrade of CRDs from Bundles. If a CRD does potentially destructive
actions to the cluster, it will not allow it to be applied. In the context of RukPak, this will result in a failed
BundleDeployment resolution.
To read more about this webhook, and learn how to disable this default behavior, view
the crdvalidator documentation. The plain provisioner is able to unpack a
given plain+v0 bundle onto a cluster and then instantiate it, making the content of the bundle available in the
cluster.