Document auto-completion files generation

[gonzaloserrano]

I did not find the autocompletion files for istioctl, after searching I found this issue comment istio/istio#19297 (comment) and I thought could be interesting to add it to the docs.

---

And to help us figure out who should review this PR, please
put an X in all the areas that this PR affects.

• Configuration Infrastructure
• Docs
• Installation
• Networking
• Performance and Scalability
• Policies and Telemetry
• Security
• Test and Release
• User Experience
• Developer Infrastructure

[istio-policy-bot]

😊 Welcome! This is either your first contribution to the Istio documentation repo, or
it's been awhile since you've been here. A few things you should know:

• You can learn about how we write and maintain documentation, about our style guidelines,
  and about all the available web site features by visiting Contributing to the Docs.

• In the next few minutes, an automatic preview of your change will be
  built as a full copy of the istio.io website. You can find this preview by clicking on
  the Details link next to the deploy/netlify entry in the Status section of this
  page.

• We care about quality, so we've put in place a number of checks to ensure our documentation
  is top notch. We do spell checking, we sanitize the markdown, we ensure all hyperlinks point
  to valid location, and more. If your PR doesn't pass one of these checks, you'll see a red X in the
  status section of the page. Click on the Details link to get a list of the problems with your PR.
  Fix those problems and push an update to your PR. This will automatically rerun the tests and
  hopefully this time everything will be perfect.

• Once your changes are accepted and merged into the repository, they will initially show up
  on https://preliminary.istio.io. The changes will be published to https://istio.io
  the next time we do a major release (which typically happens every 3 months or so).

Thanks for contributing!

Courtesy of your friendly welcome wagon.

[istio-testing]

Hi @gonzaloserrano. Thanks for your PR.

I'm waiting for a istio member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[ericvn]

I don't think the normal way to add a completion file is to source it with .zsh. Normally it would be placed so it was found in FPATH or in a folder on FPATH..

[gonzaloserrano]

To be honest, I don't have enough ZSH knowledge to hell. These were the previous instructions.

[ericvn]

/ok-to-test

[gonzaloserrano]

@ericvn I fixed most of it I think, but the tide check is running since a lot time ago

[craigbox]

Tide is only waiting now on approval; all the tests have passed. Thanks!

[ericvn]

Another issue is that I believe these commands need to be updated for 1.11 (current master) to istioctl completion ... post istio/istio#33787. @silenceshell will have more information on this. I do note that in istio/istio master the file generation using collateral is different than the file using completion.

Pointer to some docs on enabling for bash/zsh: https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#enable-shell-autocompletion.

In the above, they simply source the generated file. The benefit of that is that any changes made will automatically happen with istioctl is updated).

[silenceshell]

As #33787 has been merged to master, we could use istioctl completion instead of istio collateral.
It's usage is quite like kubectl.
@gonzaloserrano Would you please use the new istioctl completion command to update the doc?

for bash:

To load completions for every new session, execute once:
Linux:
  $ istioctl completion bash > /etc/bash_completion.d/istioctl
MacOS:
  $ istioctl completion bash > /usr/local/etc/bash_completion.d/istioctl

for zsh:

To load completions for every new session, execute once:
# Linux:
$ istioctl completion zsh > "${fpath[1]}/_istioctl"
# macOS:
$ istioctl completion zsh > /usr/local/share/zsh/site-functions/_istioctl

[gonzaloserrano]

@silenceshell I'm running macOS Big Sur and I don't have neither /usr/local/etc/bash_completion.d/ nor /usr/local/share/zsh/site-functions/ directories. In fact:

➜  ~ ls /usr/local
bin  lib

[ericvn]

Looking at a machine with a fresh Big Sur install I only see the usr/local/bin as well. On another machine I also have brew installed and I believe it puts things in /usr/local/share/zsh/site-functions. Some quick investigation shows I have multiple versions of a few files (_istioctl included) between /usr/local/share/zsh/site-functions and /usr/local/share/zsh-completions (fpath[1]) so need some cleanup. An echo $fpath on my fresh Big Sur does show /usr/local/share/zsh/site-functions as the first entry, so the same command as on Linux on a fresh Big Sur would be the same.

What does the mean for instructions for a Mac? Do we just say to install in a directory on the fpath as I stated above? Might we say the same for Linux (removing the idea of pointing it in the first fpath entry)?

[gonzaloserrano]

What does the mean for instructions for a Mac? Do we just say to install in a directory on the fpath as I stated above? Might we say the same for Linux (removing the idea of pointing it in the first fpath entry)?

That could work, e.g tell the user to list $fpath entries and put the file in one of those?

Not sure how it works for linux though.

[ericvn]

Linux and Mac using zsh should be the same in that respect. Since old MacOS had bash and now it's zsh, you really can't default to one. I think it's bash vs zsh and ignore the OS. I might have some time over the weekend to add some more comments within the text.

[gonzaloserrano]

@ericvn any idea on how to unblock this? Thanks

[ericvn]

@gonzaloserrano There is at least one issue in that the doc uses istioctl collaboration, while the current code moved to istioctl completion. The files generated by the former does not contain all the completion logic. I have an issue for the team to remove/deprecate that command: istio/istio#34092.