diff --git a/proposals/xxxx_carvel-package/README.md b/proposals/xxxx_carvel-package/README.md new file mode 100644 index 00000000..91d4747f --- /dev/null +++ b/proposals/xxxx_carvel-package/README.md @@ -0,0 +1,169 @@ +--- +title: "Carvel Package Management for Pinniped" +authors: [ "@benjaminapetersen" ] +status: "in-review" +sponsor: [ "@cfryanr", "@joshuatcasey" ] +approval_date: "" +--- + +*Disclaimer*: Proposals are point-in-time designs and decisions. +Once approved and implemented, they become historical documents. +If you are reading an old proposal, please be aware that the +features described herein might have continued to evolve since. + +# Carvel Package Management for Pinniped + +## Problem Statement + +There are a number of tools available to the Kubernetes ecosystem for deploying complex software +to a Kubernetes cluster. The Carvel toolchain provides a set of APIs, Custom Resources and CLI tools +that can aid a user in the configuration and lifecycle management of software deployed to a cluster. +We should enhance our deployment options by providing Carvel Packages that may be installed on a cluster +configured with `kapp-controller` to manage the software on the cluster. + +## How Pinniped Works Today (as of version v0.25.0) + +The `./deploy` directory in the root of the Pinniped repository contains a set of `ytt` templates +that: +- Are pre-rendered into installable templates listed with each Pinniped relese: + - [v0.25.0](https://github.com/vmware-tanzu/pinniped/releases/tag/v0.25.0) +- Can optionally be customized and rendered by a consumer of the Pinniped project by cloning down + the github repository, making changes to the `values.yaml` file and then rendered via `ytt`. + +## Terminology / Concepts + +- `Carvel` is an open-source project that provides tools for managing software build, configuration + and deployment on a Kubernetes cluster. For more information [read the Carvel docs](https://carvel.dev/). +- `kapp` is a Carvel provided CLI tool for deploying software onto a Kubernetes cluster. See + [the docs](https://carvel.dev/kapp/) for more information. +- `imgpkg` is a Carvel provided CLI tool that provides a mechanism for collecting configuration and + OCI images into a bundle that can be deployed on a cluster. +- `kapp-controller` is a server side component managing software in the form of Carvel `App`s delivered + via Carvel `Package`s. See [the docs](https://carvel.dev/kapp-controller/) for more information. +- `PackageRepository` is a custom resource that configures `kapp-controller` with a set of + `Package`s on a cluster. See [the docs](https://carvel.dev/kapp-controller/docs/v0.47.x/packaging/#package-repository) + for more information. +- `Package` is a custom resource that represents configuration in the form of metadata and OCI images + that may be used to deliver software onto a Kuberentes cluster. See [the docs](https://carvel.dev/kapp-controller/docs/v0.47.x/packaging/#package) + for more information. +- `PackageMetadata` is a custom resource describing attributes for a `Package`. See [the docs](https://carvel.dev/kapp-controller/docs/v0.47.x/packaging/#package-metadata) + for more information. + +## Proposal + +Allow Pinniped to be deployed onto a Kuberentes cluster through the mechanism of two Carvel `Packages`, +a Supervisor and a Concierge package. These may be delivered via a `PackageRepository` resource. + +### Goals and Non-goals + +Goals +- Provide an additional deployment option to deliver Pinniped software to a Kubernetes cluster + in the form of the `Package` apis provided by the Carvel toolchain. + +Non-Goals +- Provide additional deployment alternatives, such as official Helm charts + +#### API Changes + +No changes or additions to Pinniped APIs, this proposal represents a second, alternative +method for deployment utilising Carvel APIs. + +#### Upgrades + +Upgrading Pinniped via the Carvel Package mechanism will look something like this: + +- We deliver a `PackageRepository` that lists: + - Pinniped `Supervisor` package at a number of versions (ex: 0.23.0,0.24.0,0.25.0, etc) + - Pinniped `Concierge` package at a number of versions (ex: 0.23.0,0.24.0,0.25.0, etc) +- The user installs the Pinniped `PackageRepository`. +- The user creates: + - A `Supervisor` and `Concierge` `PackageInstall` Custom Resource (and `Secret`) with the following: +```yaml +spec: + packageRef: + refName: "supervisor.pinniped.dev" + versionSelection: + # - Constraints control the version and upgrades of the package + # if the constraint is pinned to a specific version, then only + # that version is installed on the cluster + # - If the PackageResource no longer serves a version that matches + # the constraint, then the PackageInstall will enter an error state + # until the constraint is updated + constraints: "0.25.0" + # - Alternatively, a constraint can be based on a semver range and can + # control automatic updates. + constraints: ">0.25.0" +``` + +#### Tests + +Our current integration test suite uses the `./deploy` directory to deploy Pinniped onto a +variety of clusters. We should continue to test this for the majority of users who do not +integrate with Carvel. In addition, we should update at least 1 of our tests to make use of +the new `Package` mechanism to ensure it functions correctly. + +Optionally we can: + +- Change a single test to deploy via the `Package` mechanism +- Change several tests to deploy via the `Package` mechanism +- Provide a flag to our `./prepare-for-integration-test.sh` and cycle all of our tests, + perhaps randomly back and forth between the simple deploy and the Package deploy. + +#### New Dependencies + +The Carvel toolset is not strickly a dependency for Pinniped itself. This proposal is an +optional method for delivering the Pinniped software to a kubernetes cluster. Therefore, `kapp`, +`kapp-controller`, and the custom resources such as `PackageRepository`, `Package`, `PackageMetadata`, +`PackageInstall` as well as `imgpkg`, `vendir` and `ytt` are all optional dependencies for a +consumer of Pinniped. + +#### Performance Considerations + +None. It is up to the user to determine if the adoption of the Carvel toolset is the +correct decision for their application lifecycle needs. + +#### Observability Considerations + +`Package`, `App` and `PackageInstall` custom resources contain a `status` field like many +Kubernetes resources. These are thoroughly detailed with relevant bits of information that may +aid the user in understanding the state of their applications. For example, a Carvel `App` Custom Resource +(disambiguation, a Carvel `app` (lowercase) from `kapp` vs an `App` (uppercase) from `kapp-controller` are +entirely different resources) contains a detailed status referencing all resources owned by the `App`. This +is very helpful when attempting to understand the state of a complex multi-component application. + +#### Security Considerations + +Carvel is a toolset separate from Pinniped. This feature is optional, users who choose to use +Carvel should assess Carvel for its risks and treadeoffs. + +#### Usability Considerations + +As of today the `./deploy` directory of Pinniped is implemented via the use of a subset of the +Carvel toolchain, namely, `ytt`. However, it is implemented in such a way that consumers of Pinniped +have choice, they may opt-in to the use of the Carvel toolchain, or simply `kubectl apply -f` our +pre-rendered yaml files, there is no requirement to use the Carvel toolchain. + +This feature serves the community users who have deeply adopted Carvel into their management, such that +`kapp-controller` is installed on their cluster and used to manage software lifecycle. + +#### Documentation Considerations + +This design doc serves as an announcement that the feature will be implemented. +It would be helpful to provide a blog post describing how the feature was validated. +Also include in release notes. + +#### Other Approaches Considered + +None. + +## Open Questions + +A list of questions that need to be answered. + +## Answered Questions + +## Implementation Plan + +## Implementation PRs + +* TBD