{"id":18510696,"url":"https://github.com/operator-framework/rukpak","last_synced_at":"2025-04-09T04:33:20.841Z","repository":{"id":37078339,"uuid":"372874538","full_name":"operator-framework/rukpak","owner":"operator-framework","description":"RukPak runs in a Kubernetes cluster and defines APIs for installing cloud native content","archived":true,"fork":false,"pushed_at":"2024-08-12T16:41:39.000Z","size":2545,"stargazers_count":51,"open_issues_count":79,"forks_count":50,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-25T05:03:10.515Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/operator-framework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-01T15:17:55.000Z","updated_at":"2025-03-18T17:31:02.000Z","dependencies_parsed_at":"2023-11-10T22:22:06.989Z","dependency_job_id":"455e3378-3f03-4fd4-8858-0b133d07a437","html_url":"https://github.com/operator-framework/rukpak","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operator-framework%2Frukpak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operator-framework%2Frukpak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operator-framework%2Frukpak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operator-framework%2Frukpak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/operator-framework","download_url":"https://codeload.github.com/operator-framework/rukpak/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980833,"owners_count":21027803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T15:24:28.957Z","updated_at":"2025-04-09T04:33:18.888Z","avatar_url":"https://github.com/operator-framework.png","language":"Go","readme":"# RukPak\n\n---\n\u003e [!WARNING]\n\u003e This repository has been archived in August 2024.\n\u003e 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](https://www.github.com/operator-framework/operator-controller).\n\nIf you have any questions, please engage with us: [![Slack Channel](https://img.shields.io/badge/chat-4A154B?logo=slack\u0026logoColor=white \"Slack Channel\")](https://kubernetes.slack.com/archives/C0181L6JYQ2)\n\n---\n\n[![GitHub Actions](https://github.com/operator-framework/rukpak/workflows/e2e/badge.svg)](https://github.com/operator-framework/rukpak/actions)\n[![License](http://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)\n[![Go Report Card](https://goreportcard.com/badge/github.com/operator-framework/rukpak)](https://goreportcard.com/report/github.com/operator-framework/rukpak)\n[![Slack Channel](https://img.shields.io/badge/chat-4A154B?logo=slack\u0026logoColor=white \"Slack Channel\")](https://kubernetes.slack.com/archives/C038B7MF75M)\n\nRukPak runs in a Kubernetes cluster and defines APIs for installing cloud native content.\n\n## Introduction\n\nRukPak is a pluggable solution for the packaging and distribution of cloud-native content and supports advanced\nstrategies for installation, updates, and policy. The project provides a content ecosystem for installing a variety of\nartifacts, such as Git repositories, Helm charts, OLM bundles, and more onto a Kubernetes cluster. These artifacts can\nthen be managed, scaled, and upgraded in a safe way to enable powerful cluster extensions.\n\nAt its core, RukPak is a small set of APIs, packaged as Kubernetes CustomResourceDefinitions, and controllers that watch\nfor those APIs. These APIs express what content is being installed on-cluster and how to create a running deployment of\nthe content.\n\n## Contributing\n\nThe RukPak project is community driven and is part of the broader Kubernetes ecosystem. New contributors are welcome and\nhighly encouraged. See the [contributing guidelines](CONTRIBUTING.md) to get started.\n\nThis project uses GitHub issues and milestones to prioritize and keep track of ongoing work. To see the current state of\nthe project, checkout the [open issues](https://github.com/operator-framework/rukpak/issues) and\n[recent milestones](https://github.com/operator-framework/rukpak/milestones).\n\n## Documentation\n\nThe RukPak project currently houses all of its documentation [directly in this repository](docs). There are several sources of\ndocumentation. The below section of this README contains a high-level overview of the primary APIs and how to get started using RukPak.\n\n## Getting Started\n\n### Installation\n\nThe recommended way of installing RukPak is via a tagged release from\nthe [releases](https://github.com/operator-framework/rukpak/releases) page. There are detailed instructions provided in\nthe release notes on how to install a particular release. The only requirement is to have a `kubectl` client available\nthat is configured to target the cluster to install to.\n\n\u003e Note: RukPak depends on [cert-manager](https://cert-manager.io/) for creating and managing certificates for its webhooks. cert-manager should be installed prior to installing RukPak. See the cert-manager [installation docs](https://cert-manager.io/docs/installation/)\nfor more information on how to install cert-manager.\n\nIt is recommended to install the latest release to access the latest features and new bugfixes. RukPak releases target\nthe linux operating system and support amd64, arm64, ppc64le, and s390x architectures via multi-arch images.\n\nTo install the latest release of RukPak, simply run:\n\n```bash\nkubectl apply -f https://github.com/operator-framework/rukpak/releases/latest/download/rukpak.yaml\n```\n\nAnother installation option for developers interested in running RukPak locally is to clone the source code and deploy\nRukPak to a local [kind](https://kind.sigs.k8s.io/) cluster.\n\n```bash\ngit clone https://github.com/operator-framework/rukpak \u0026\u0026 cd rukpak\nmake run\n```\n\n\u003e Note: 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.\n\n### Debugging\n\nThe 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` :\n\n```bash\nmake debug\n```\n\nAs an example, the following `launch.json` file may be used to connect to the debugging session with vscode:\n```json\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    {\n      \"name\": \"Remote Debugging\",\n      \"type\": \"go\",\n      \"request\": \"attach\",\n      \"mode\": \"remote\",\n      \"remotePath\": \"\",\n      \"port\":40000,\n      \"host\":\"127.0.0.1\",\n      \"showLog\": true,\n      \"trace\": \"log\",\n      \"logOutput\": \"rpc\"\n    }\n  ]\n}\n```\n\nThere are currently no other supported ways of installing RukPak, although there are plans to add support for other\npopular packaging formats such as a Helm chart or an OLM bundle.\n\n### Quickstart\n\nThe RukPak project consists of a series of controllers, known as [provisioners](#provisioner), that install and manage\ncontent on a Kubernetes cluster. See [below](#components) for a more detailed look into the APIs that RukPak provides.\n\nThe provisioner currently implemented and bundled with RukPak is known as the plain provisioner. To get started with\nthis provisioner on a local kind cluster,\nsee [the quickstart section](docs/provisioners/plain.md##Running-locally) of the plain provisioner README. To\ninstall the latest version of the provisioner on an existing cluster, see the [installation guide](#installation). There will\nbe other provisioners added to the RukPak project that support different content types.\n\nThe plain provisioner is able to source and unpack plain bundles. To learn more about the plain bundle format,\nsee [the plain bundle spec](docs/bundles/plain.md).\n\n## Components\n\nRukPak is composed of two primary APIs, [Bundle](#bundle) and [BundleDeployment](#bundledeployment), as well as the\nconcept of a [Provisioner](#provisioner). These components work together to bring content onto the cluster and install\nit, generating resources within the cluster. Below is a high level diagram depicting the interaction of the RukPak\ncomponents.\n\n```mermaid\ngraph TD\n    C[Provisioner]\n    C --\u003e|Unpacks| D[Bundle]\n    C --\u003e|Reconciles| E[BundleDeployment]\n    D ---|References| F((Content))\n    E --\u003e|Creates/Manages| G([Cluster Resources])\n```\n\nA provisioner places a watch on both Bundles and BundleDeployments that refer to it explicitly. For a given bundle, the\nprovisioner unpacks the contents of the Bundle onto the cluster. Then, given a BundleDeployment referring to that\nBundle, the provisioner then installs the bundle contents and is responsible for managing the lifecycle of those\nresources.\n\n### Bundle\n\nA `Bundle` represents content that needs to be made available to other consumers in the cluster. Much like the contents\nof a container image need to be pulled and unpacked in order for Pods to start using them,\n`Bundles` are used to reference content that may need to be pulled and should be unpacked. In this sense, Bundle is a\ngeneralization of the image concept, and can be used to represent any type of content.\n\n`Bundles` do nothing on their own - they require a `Provisioner` to unpack and make their content available in-cluster.\nThey can be unpacked to any arbitrary storage medium such as a tar.gz file in a directory mounted into the provisioner\npods. Each `Bundle` has an associated `spec.provisionerClassName` field which indicates the `Provisioner` that should be\nwatching and unpacking that particular bundle type.\n\nExample Bundle configured to work with the [plain provisioner](docs/bundles/plain.md##Example).\n\n```yaml\napiVersion: core.rukpak.io/v1alpha1\nkind: Bundle\nmetadata:\n  name: my-bundle\nspec:\n  source:\n    type: image\n    image:\n      ref: my-bundle@sha256:xyz123\n  provisionerClassName: core-rukpak-io-plain\n```\n\n\u003e Note: Bundles are considered immutable once they are created. See the [bundle immutability doc](docs/concepts/bundle-immutability.md)\n\u003e for more information.\n\n### BundleDeployment\n\n\u003e :warning: A BundleDeployment changes the state of the Kubernetes cluster by installing and removing objects. It's important\n\u003e to verify and trust the content that is being installed, and limit access (via RBAC) to the BundleDeployment API to only those\n\u003e who require those permissions.\n\nThe `BundleDeployment` API points to a Bundle and indicates that it should be “active”. This includes pivoting from\nolder versions of an active bundle.`BundleDeployment` may also include an embedded spec for a desired Bundle.\n\nMuch like Pods stamp out instances of container images, `BundleDeployments` stamp out a deployed version of\nBundles. `BundleDeployment` can be seen as a generalization of the Pod concept.\n\nThe specifics of how an `BundleDeployment` makes changes to a cluster based on a referenced `Bundle` is defined by the\n`Provisioner` that is configured to watch that `BundleDeployment`.\n\nExample BundleDeployment configured to work with the [plain provisioner](docs/provisioners/plain.md###-Installing-the-Combo-Operator).\n\n```yaml\napiVersion: core.rukpak.io/v1alpha1\nkind: BundleDeployment\nmetadata:\n  name: my-bundle-deployment\nspec:\n  provisionerClassName: core-rukpak-io-plain\n  template:\n    metadata:\n      labels:\n        app: my-bundle\n    spec:\n      source:\n        type: image\n        image:\n          ref: my-bundle@sha256:xyz123\n      provisionerClassName: core-rukpak-io-plain\n```\n\n### Provisioner\n\nA Provisioner is a controller that understands `BundleDeployment` and `Bundle` APIs and can take action.\nEach `Provisioner` is assigned a unique ID, and is responsible for reconciling a `Bundle` and `BundleDeployment` with\na `spec.provisionerClassName` that matches that particular ID.\n\nFor example, in this repository the [plain](docs/provisioners/plain.md) provisioner is implemented.\nThe `plain` provisioner is able to unpack a given `plain+v0` bundle onto a cluster and then instantiate it, making the\ncontent of the bundle available in the cluster.\n\nIf you are interested in implementing your own provisioner, please see the\n[Provisioner Overview [DRAFT]](docs/provisioners/overview.md), which describes the expectations of provisioner implementations.\n\n### CustomResourceDefinition (CRD) Validator\n\nRukPak comes with a webhook for validating the upgrade of CRDs from `Bundle`s. If a CRD does potentially destructive\nactions to the cluster, it will not allow it to be applied. In the context of RukPak, this will result in a failed\n`BundleDeployment` resolution.\n\nTo read more about this webhook, and learn how to disable this default behavior, view\nthe `crdvalidator` [documentation](cmd/crdvalidator/README.md). The `plain` provisioner is able to unpack a\ngiven `plain+v0` bundle onto a cluster and then instantiate it, making the content of the bundle available in the\ncluster.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperator-framework%2Frukpak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foperator-framework%2Frukpak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperator-framework%2Frukpak/lists"}