# Package Version Constraints in kapp-controller

## Problem: Not all Packages work equally with all versions of Kubernetes and/or kapp-controller
### Supporting context:
* For Fork 1:
* https://github.com/vmware-tanzu/carvel-kapp-controller/issues/484
* https://github.com/vmware-tanzu/carvel-kapp-controller/issues/577
* For Fork 2:
* https://github.com/vmware-tanzu/carvel-kapp-controller/issues/781
* Additionally (no issue), we've heard the use-case that while a package may be compatible with a given version of k8s, it might need to conditionally enable/disable some things (e.g. k8s-provided CRs or even specific Packaging API features)

### Additionally:
We may eventually implement other package management features around version requirements. For example we could interpret version range constraints in a PackageInstall in combination with Package level compatibility constraints to select "the largest version in the specified range that is still compatible with the cluster's version of kubernetes."

## Proposal :rocket:
:::success
**A Two Pronged Solution**
:fork_and_knife: 1.) Add to Package spec fields: range selection for kubernetes and kapp-controller version
:fork_and_knife: 2.) Expose current versions of kapp-controller and kubernetes to the templating phase via Downward API
:::

### Proposal Part 1: New fields in Package spec

---
apiVersion: data.packaging.carvel.dev/v1alpha1
kind: Package
metadata:
  [...]
spec:
  kubernetesVersionSelection:
    constraints: ">v1.19.3"
  kappControllerVersionSelection:
    constraints: ">v1.23.99"
[...]

##### Package Install Override Annotation

packaging.carvel.dev/ignore-kubernetes-version-selection: "" 
packaging.carvel.dev/ignore-kapp-controller-version-selection: "" 

these annotations allow package consumers to override any version constraints specified in the package at their discretion.
#### Description
- all range fields are optional, and if unspecified you're just good indefinitely
- a PackageInstall referencing a package will fail to reconcile if the cluster k8s version or kc version is outside your specified requirements

#### Questions
- ~~would you rather specify a range similar to how we do version constraints?~~
- ~~Are there other things you would want to constrain at this level?~~

### Concerns
~~- version range will be more flexible in terms of allowing someone to exclude a specific version~~
- ~~if we shut down an installation based on version will we be locking somebody out of installing a package that would actually work based on feature gates / specific config. Where's the override?~~
- ~~should we even allow packages to exist on a system where they are marked incompatible? Who is wiser: the package author or the package consumer?~~

### Proposal Part 2: New Data in Downward API

downwardAPI
  items:
  - name: myK8sVersionName
    kubernetesVersion: {}
  - name: myNameForkcVersion
    kappControllerVersion: {}
  - name: myNameForAPICapabilities
    clusterAPIs: {}

in particular, clusterAPIs should be compatible with how Helm presents that data currently, ([]string{"group/version", "group/version", ...}) see e.g. https://github.com/helm/helm/blob/d84655a9c527e090d2f50ed097beebf3aeed0421/pkg/chartutil/capabilities.go#L103

template specific examples:

helmTemplate:
  valuesFrom:   # type Values.AsPaths()  helm template  -f  .... --kube-version ... --api-versions x
  - secretRef: ...
  - configMapRef: ...
  kubernetesVersion: {}
  kubernetesAPIs: {}


ytt:
  valuesFrom:   # ytt [-f ...]
  - downwardAPI:
      items:
      - name: foo
        fieldPath: ...
      - name: kube_version
        kubernetesVersion: {} # default will pull from network but could also be user-provided e.g. {1.2.3}
	  - name: kube_apis
	    kubernetesAPIs: {}

#### Description
kapp-controller's downward API was recently introduced into develop (not yet in any release) and works similar to the k8s downward API: We make available certain information from the metadata of the AppCR to the template step. ([see develop branch App CR docs](https://carvel.dev/kapp-controller/docs/develop/app-spec/) for more).

Here we add two new pieces of information: the current version of kapp-controller and of kubernetes itself, and allow the user to specify a name to bind that data to which can then be used during templating. This would allow users to create conditionals during templating that are sensitive to e.g. the current kubernetes version.

##### Implementation details
For helm, expose `kubernetesVersion: {}` and `kubernetesAPIs:{}` bc those correspond to flags we'll pass in to the helm template.

Then we'll have the items still in the downwardsAPIs for the other templaters (and technically helm though wouldn't expect anyone to ever use)

#### Questions
- ~~The k8s downward API uses two values on the left-hand side: "fieldpath" and "resource." Here we present two options for discussion/feedback:~~
- ~~a pseudo value "source" on LHS with the magic value "carvel.kubernetesVersion" on the RHS, or~~
- ~~the magic string "carvel.kubernetesVersion" on the LHS and a dummy "true" value on the RHS.~~
- ~~are there other similar data points you think we should make available via this mechanism? (A: yes, helm capabilities / APIs)~~

#### discussion / concerns
- ~~eventually we could make other info available re APIs on the cluster (see e.g. helm built in capabilities)~~
- ~~for helm template could we _always_ pass in the k8s version as this value? (pass it in via helm capabilities) (ytt & cue would be data value)~~
- so then should it still be in items part of downward API or some additional section that allows you to inject things into the helm capabilities
- (see also: https://github.com/helm/helm/pull/5392)
- ~~do we pull this out every time we reconcile? that comes with a cost bc we're goign to pull it from the server API, and not all helm templates will use it. So keeping it opt-in is an optimization. user has to explicitly request. helm template has kube-version and api-versions flags that we can leverage.~~
---
## Additional Concerns
- Ensure we get multi-cluster scenarios right: if there is a version mismatch between the management cluster and the destination workload cluster, we'd want to take the workload cluster's k8s version. (h/t Graham)
## Timeline
this work is hopefully not controversial and might be started as early as July 11, pending feedback and discussion.