What do do with example instances of capabilities provided via an addon

[jorgemoralespou]

Feedback

We do provide some capabilities as addons (e.g. Contour operator) that let the user create specific instances of the capability (e.g. contour instance). Currently, in the 0.1.0 release, we do ship that instance by default (https://github.com/vmware-tanzu/tce/blob/main/extensions/contour/bundle/config/contour.yaml) but we should think:

• Should we provide examples as a away for the user to configure things as documentation or should we create example instances OOTB?
• Where in the new addon structure should we place this instance (overlay, upstream, static/downstream, examples,...)

This raises concerns on what type of documentation (via CLI) we should be providing the user when an addon is installed. When you look at helm, it does provide some output for the user to decide what to do next, in this case, how he can create that example instance.

Details

TCE build version: v0.1.0

[jorgemoralespou]

An idea is to use a config variable that instructs the installation of the example, (e.g. install_example: True), and then add an ytt template/overlay that does the necessary if the install_example is enabled.

[joshrosso]

@jorgemoralespou can you give us a very concrete example of this so we can ensure we're grokking it?

[jorgemoralespou]

I'll expand on my comment and then on a possible solution (partial?).

When a user installs something like Contour, there's 2 parts he needs to install to have a working environment:

• The underlying tech (in contour example, the contour operator)
• An instance (in contour example the linked instance we do provide)

Sometimes, a user might need to install one of such instances, sometimes he might need even more, so this issue is to raise 2 things:

• Is there a way that when a user installs a package he gets some feedback about next steps? Something like helm does that can show you some information after you install a chart. This could be something like, if you want to create an instance do ... (maybe even showing a yaml snippet). This is something that needs to be in the package, maybe in the description or standarizing how carvel can provide the user some output. This is not tracked by kapp-controller but there's a related issue in ytt (Provide a way to generate output as part of the ytt processing carvel-dev/ytt#213). This comment shows an example: Provide a way to generate output as part of the ytt processing carvel-dev/ytt#213 (comment)
• Is there a way to provide a default instance that can be applied as part of the installation. To this, we would need to have a sample instance that via a configuration flag would be applied (or not). It would be ideal to explore this model and maybe be able to provide different versions of the examples that could be applied by the user. An example would be for a package that relies on the infrastructure to be able to install different example if the cluster is on AES, or Azure or Docker. Knative or external-dns are some examples of technologies that will have different configuration. This is not also tracked by Carvel, AFAIK.

This would be an example of the second item:

values.yaml

install_example: True
namespace: contour

overlays\contour-example.yaml: (to replace this file: https://github.com/vmware-tanzu/tce/blob/main/addons/packages/contour-operator/bundle/config/overlays/contour.yaml)

#@ load("@ytt:data", "data")

#@ if/end data.values.install_example:
---
apiVersion: operator.projectcontour.io/v1alpha1
kind: Contour
metadata:
  name: contour-sample
spec: {}

[jorgemoralespou]

@joshrosso maybe from the above, and depending on your opinion, to add to this issue: #192