Include example YAML files with their matching release

[nrb]

Describe the solution you'd like
Currently, our documentation points to example YAML in git. In the cases where master is changing things such as adding/removing required CRDs, it's not immediately obvious that the user should be switching to the relevant release- branch to get the examples and prereqs for the version of Ark that's deployed in their cluster.

As an alternative, we could package the examples directory in to the release tarballs and update our documentation to refer to the files from the tarball. This was first proposed by @ncdc in Slack.

@heptio/bluesteelsquad @rosskukulinski thoughts?

[rosskukulinski]

Good idea!

This raises some questions:

• Do users tend to download a release or do they git clone?
• Does this change if they're kicking the tires or if they're using Ark in production?
• How might Add velero install command #52 impact this?

That said, I think release tarballs should have example yaml as well as matching Docker image tags.

Taking a step back, I will always advocate for the user and for first-run use (over your developer experience). Users will consistently go to github.com/heptio/ark, git clone (which gets them master), and start kubectl apply -f.

So, I think the master branch example YAML could always point to the latest tagged release. Each tagged release branch should have example YAML pointing to tagged images for that release.

I understand that this might make the Ark developer experience more challenging (you'll have to update tags yourself) as well as for folks testing master features, but I think it's worth the tradeoff.

Thoughts?

[nrb]

Do users tend to download a release or do they git clone?

I'd need to circle back on the download numbers, but the downloads on GitHub (which indicate client downloads or people building their own images) tend to be pretty low for what I'd expect.

Does this change if they're kicking the tires or if they're using Ark in production?

I'm not sure I'm clear on what you're asking here. Is it a continuation of the previous point?

How might #52 impact this?

I think ark install would manage this for us, more or less.

So, I think the master branch example YAML could always point to the latest tagged release. Each tagged release branch should have example YAML pointing to tagged images for that release.

Currently master does sit at latest. I'd be up for updating release tooling to not just collecting the YAML, but also updating the image tag to match.

Truthfully, I mostly run the Ark server locally when I'm building, so updating and changing tags hasn't been an issue, but if I do test with an image I have to update the repository it's sent to, anyway, so I don't see this as an imposition.

[rosskukulinski]

Does this change if they're kicking the tires or if they're using Ark in production?

I'm not sure I'm clear on what you're asking here. Is it a continuation of the previous point?

Yes - I was trying to ask if users new to Ark are more likely to download via a release tarball or via git clone.

[ncdc]

I assume people download our GitHub release files, at least for the ark cli tool (since that's all that's there now). Because we don't have the yaml files in the GitHub releases, they then must clone the repo and use the yaml files from the clone.

The best user & first-run experience is, imho, to download a release tarball from GitHub that contains ark and all the yaml files with the correct matching image tags. Users should not have to git clone our repo to be able to install ark.

If we do this, the yaml in the repo can point at the master tag instead of latest. If someone is developing a bug fix for a previous version, they'll have to make sure to switch to the right image versions, but that's a developer to-do. And if we do ark install and remove the yaml from the repo entirely, it makes the developer experience even easier.

[rosskukulinski]

So would it be accurate to describe the two following changes should happen?

1. Download release tarball from GitHub should have ark and the yaml files with the correct matching tags
2. Release branches (e.g. release-0.9) should have yaml that points to the image tag of that release.

[ncdc]

I think only 1 is reasonable. If we do 2, there will potentially be merge conflicts if we have to backport yaml changes.

[rosskukulinski]

I'm onboard 👍

[skriss]

This has been closed by #1045