[docs] added install method

[ponkio-o]

I added install method use with aquaproj/aqua. The following PRs support installation on aqua.
aquaproj/aqua-registry#24498

aqua is a CLI tool to install CLI tools with declarative YAML configuration. It may be easier to imagine something like asdf.

[dag-andersen]

Hi @ponkio-o

I am not familiar with the Aqua project, but when I run aqua g -i dag-andersen/argocd-diff-preview, I get the following error:

FATA[0000] aqua failed        aqua_version=2.36.2 env=darwin/arm64 error="configuration file isn't found" program=aqua

What am I missing or doing wrong? :)

[ponkio-o]

Hi @dag-andersen

I am not familiar with the Aqua project, but when I run aqua g -i dag-andersen/argocd-diff-preview, I get the following error:

Maybe, you didn't create aqua.yaml or didn't set AQUA_GLOBAL_CONFIG. Could you try run aqua init before aqua g -i command?

1. Create aqua.yaml

$ aqua init
$ cat aqua.yaml
---
# aqua - Declarative CLI Version Manager
# https://aquaproj.github.io/
# checksum:
#   enabled: true
#   require_checksum: true
#   supported_envs:
#   - all
registries:
- type: standard
  ref: v4.243.0  # renovate: depName=aquaproj/aqua-registry
packages:

2. Adding package name to aqua.yaml with aqua g -i command. (-i option is to insert package name to aqua.yaml)

$ aqua g -i dag-andersen/argocd-diff-preview
$ cat aqua.yaml
---
# aqua - Declarative CLI Version Manager
# https://aquaproj.github.io/
# checksum:
#   enabled: true
#   require_checksum: true
#   supported_envs:
#   - all
registries:
- type: standard
  ref: v4.243.0  # renovate: depName=aquaproj/aqua-registry
packages:
- name: dag-andersen/argocd-diff-preview@v0.0.21

3. Install package

$ aqua i
aqua i
INFO[0000] download and unarchive the package            aqua_version=2.36.2 env=linux/arm64 package_name=aqua-proxy package_version=v1.2.8 program=aqua registry=
INFO[0001] create a symbolic link                        aqua_version=2.36.2 command=aqua-proxy env=linux/arm64 package_name=aqua-proxy package_version=v1.2.8 program=aqua registry=
INFO[0001] create a symbolic link                        aqua_version=2.36.2 command=argocd-diff-preview env=linux/arm64 program=aqua
INFO[0001] download and unarchive the package            aqua_version=2.36.2 env=linux/arm64 package_name=dag-andersen/argocd-diff-preview package_version=v0.0.21 program=aqua registry=standard

4. Run argocd-diff-preview (For some reason, didn't change the version number in --version command 😂 But installation success v0.0.21 correctly.)

$ argocd-diff-preview --version
argocd-diff-preview 0.0.20

I updated document the following commit.
2e1c46b

[ponkio-o]

By the way, if you want to change the version of argocd-diff-preview, you can use aqua update -s argocd-diff-preview command.

This command is useful when switching the version of package.
https://aquaproj.github.io/docs/tutorial/change-version-per-project
https://aquaproj.github.io/docs/guides/update-command

1. Check current version

$ cat aqua.yaml
---
# aqua - Declarative CLI Version Manager
# https://aquaproj.github.io/
# checksum:
#   enabled: true
#   require_checksum: true
#   supported_envs:
#   - all
registries:
- type: standard
  ref: v4.243.0  # renovate: depName=aquaproj/aqua-registry
packages:
- name: dag-andersen/argocd-diff-preview@v0.0.21

#  Show version number is 0.0.20, but actually version is 0.0.21. This is a bug of argocd-diff-preview.
$ argocd-diff-preview --version
argocd-diff-preview 0.0.20

2. Run aqua update command and select the version with fzf-like window.

$ aqua update -s argocd-diff-preview

  v0.0.1                                                                                                                           │                                                                                                                                  │
  v0.0.3                                                                                                                           │                                                                                                                                  │
  v0.0.5                                                                                                                           │                                                                                                                                  │
  v0.0.6                                                                                                                           │                                                                                                                                  │
  v0.0.7                                                                                                                           │                                                                                                                                  │
  v0.0.8                                                                                                                           │                                                                                                                                  │
  v0.0.9                                                                                                                           │                                                                                                                                  │
  v0.0.10                                                                                                                          │                                                                                                                                  │
  v0.0.11                                                                                                                          │                                                                                                                                  │
  v0.0.12                                                                                                                          │                                                                                                                                  │
  v0.0.13                                                                                                                          │                                                                                                                                  │
  v0.0.14                                                                                                                          │                                                                                                                                  │
  v0.0.15                                                                                                                          │                                                                                                                                  │
  v0.0.16                                                                                                                          │                                                                                                                                  │
  v0.0.17                                                                                                                          │                                                                                                                                  │
  v0.0.18                                                                                                                          │                                                                                                                                  │
> v0.0.19                                                                                                                          │                                                                                                                                  │
  v0.0.20                                                                                                                          │                                                                                                                                  │
  v0.0.21 (*)                                                                                                                      │                                                                                                                                  │
  19/19                                                                                                                            │                                                                                                                                  │

3. Check aqua.yaml

$ cat aqua.yaml | grep argocd-diff-preview
- name: dag-andersen/argocd-diff-preview@v0.0.19

4. Run argocd-diff-preview.
   (Note that no need aqua i again and install new version automatically. This feature called Lazy Install)

$ argocd-diff-preview --version
INFO[0000] download and unarchive the package            aqua_version=2.36.2 env=linux/arm64 exe_name=argocd-diff-preview package_name=dag-andersen/argocd-diff-preview package_version=v0.0.19 program=aqua registry=standard
argocd-diff-preview 0.0.19

[dag-andersen]

@ponkio-o

Should i maybe commit and push the aqua file? or is it a best practice that everyone who installs argued-diff-preview creates their own file?

[ponkio-o]

@dag-andersen

Should i maybe commit and push the aqua file? or is it a best practice that everyone who installs argued-diff-preview creates their own file?

Typically, each project or team will have its own aqua.yaml. And aqua.yaml should also be committed to git and shared with CI and team members.

This has the following advantages:

• CI is less likely to break because the version specified in aqua.yaml is always used
• Tool versions can be aligned on the local machine and CI
• Team members can install the same version of the same tool by simly running aqua i in the repo root
• Renovate allows tool versions to be updated

To show how it works, we have created a sample.
https://github.com/ponkio-o/argocd-diff-preview-sample

The following tools are intalled in aqua.yaml. This is the tool needed by argocd-diff-preview.

• dag-andersen/argocd-diff-preview
• kubernetes/kubectl
• kubernetes-sigs/kind
• argoproj/argo-cd

In aqua.yaml, the version is strictly specified. This means that these versions are alwasy used on CI.
Even if a new version of these tools is released that contains a bug, it will not be affected because we have specified the version.
https://github.com/ponkio-o/argocd-diff-preview-sample/blob/cb01ff362571c89fbc89305c072a35ae3042dc23/aqua.yaml#L12-L16

Then, when new versions of these tools are released, Renovate will update the tools. For example, below is how argocd-diff-preview will be updated to v0.0.23.
ponkio-o/argocd-diff-preview-sample#2

If there is a problem with v0.0.23, you can revert to the previous version by reverting the Renovate PR.

Did you imagine how to use it? If there is anything unclear, please let us know!