Release "dev" shows kumactl 1.5.0 in installation instructions

[slonka]

What happened?

The version should probably be the current preview version.

[jakubdyszkiewicz]

Triage: apparently there is a script called preview.sh that we should use here.

[lahabana]

preview.sh would be tricky and messy... The version is extracted from: https://github.com/kumahq/kuma-website/blob/master/docs/docs/dev/versions.json. Maybe we should just have notAvailable I guess users playing with the dev docs know what they are doing?

[kleinfreund]

After the replatform, the versions file is now located at https://github.com/kumahq/kuma-website/blob/c7d2d266ba3942362a3676cd955bfbdca3a397fc/app/_data/versions.yml.

Also, after the replatform, the dev docs use VERSION=2.0.0 in installation instructions (e.g. https://kuma.io/docs/dev/installation/kubernetes/).

@lahabana Looking at https://kuma.io/preview.sh, you say this is messy because it relies on GitHub CLI, right?

In that case, should the dev docs simply show installation instructions without VERSION being explicitly set? This would try and use the latest version as per https://kuma.io/latest_version. Right now that would be 1.8.1 instead of 2.0.0.

The next question is which direct download URLs we would use. Currently we use the URLs referencing 2.0.0 (e.g. https://download.konghq.com/mesh-alpine/kuma-2.0.0-ubuntu-amd64.tar.gz). Looking at https://download.konghq.com/mesh-alpine/, there are version-less archives (e.g. https://download.konghq.com/mesh-alpine/kuma-ubuntu-amd64.tar.gz), but they seem to contain an old version.

[lahabana]

For KM the link it should link to a kong-mesh build anyway (the script used should be https://docs.konghq.com/mesh/installer.sh).

I'm not sure latest_version is perfect either. Could we have preview as a version in versions.yml and then have a condition in installer.sh to error and say you should use preview.sh? We really don't need anything perfect here as dev is mostly used by us and we know what we're doing :)

[kleinfreund]

I'm not sure latest_version is perfect either. Could we have preview as a version in versions.yml and then have a condition in installer.sh to error and say you should use preview.sh? We really don't need anything perfect here as dev is mostly used by us and we know what we're doing :)

@lahabana I think that would work, yes. Are you proposing this to make it so that we can use the same curl -L https://kuma.io/installer.sh | VERSION=$VERSION sh - type commands across all docs (i.e. we wouldn’t have to have conditional logic in the future "one source document for version pages" style)? Because otherwise we could just use preview.sh, no?

[kleinfreund]

This is actually more tricky.

In the installation instructions for Docker, we reference the latest version variable several times, for example:

https://github.com/kumahq/kuma-website/blob/78f508ae562150a3b43e2025f7e05a630193a98a/app/docs/dev/installation/docker.md?plain=1#L19-L21

In general installation instructions, we commonly use the install_os.md snippet with the latest version variable, for example:

https://github.com/kumahq/kuma-website/blob/78f508ae562150a3b43e2025f7e05a630193a98a/app/_includes/snippets/install_os.md?plain=1#L19

We would also need to conditionally switch between the latest version number and the preview version number depending on context here:

https://github.com/kumahq/kuma-website/blob/78f508ae562150a3b43e2025f7e05a630193a98a/app/_includes/snippets/install_os.md?plain=1#L14

---

With a version marked as preview: true in the versions.yml file, we would have access to an appropriate version number.

Perhaps we can provide the version number in includes like this:

{% include snippets/install_os.md version=page.latest_version %}
<!-- or -->
{% include snippets/install_os.md version=page.preview_version %}

and use that in the snippet. I’ll play around with that approach.

[kleinfreund]

I’m stuck on this. It seems that the only reliable kind of version number we should be using for the dev docs is one of the form 0.0.0-preview.v${COMMIT} which isn’t possible with the current setup because to determine it you need git access to the repository or a GitHub CLI API call (i.e. what we do in the preview.sh script). In theory it’s probably possible to determine this version number once when building the docs website, but this version number would quickly become out-of-date.

Using a preview version keyword would work for triggering some special-cased logic in the installer.sh script, but there are many other references for which that wouldn’t work:

• Archive download URLs: https://download.konghq.com/mesh-alpine/kuma-{{ page.latest_version }}-{{ page.os }}-{{ page.arch }}.tar.gz
• Docker image URLs: docker.io/kumahq/kuma-cp:{{ page.latest_version }}

We would need to publish images and archives for the preview version keyword to make that work.

[lahabana]

Other option is to have page.latest_version set at build times by doing the github stuff then? Or doing it as nightly workflow?

[kleinfreund]

Other option is to have page.latest_version set at build times by doing the github stuff then?

That version would be out-of-date as soon as we publish a new preview version. For the dev docs, that’s perhaps tolerable?

Or doing it as nightly workflow?

As in rebuilding and redeploying the site every night? That would keep the preview version pretty up-to-date. The choice depends on how precise we want this to be.