From 274de811da9a9ce4b5a0d40b2d4f3b09d0eb1c7e Mon Sep 17 00:00:00 2001
From: Tomas Aschan <1550920+tomasaschan@users.noreply.github.com>
Date: Sun, 1 Oct 2023 00:43:10 +0200
Subject: [PATCH] :book: Clarify plugin executable locations (#3643)

Clarify plugin executable locations

This was confusing to me, so I tried to make it less confusing.

See https://kubernetes.slack.com/archives/CAR30FCJZ/p1695820734815719
---
 docs/book/src/plugins/external-plugins.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/book/src/plugins/external-plugins.md b/docs/book/src/plugins/external-plugins.md
index 0539fa1c19a..c8a545ae706 100644
--- a/docs/book/src/plugins/external-plugins.md
+++ b/docs/book/src/plugins/external-plugins.md
@@ -84,11 +84,17 @@ If you need to include logs or debug messages while developing your plugin, cons
   This can be done by setting the `${EXTERNAL_PLUGINS_PATH}` environment variable, or by placing the plugin in a path that follows a `group-like name and version` scheme:
 ```sh
 # for Linux
-$HOME/.config/kubebuilder/plugins/${name}/${version}
+$HOME/.config/kubebuilder/plugins/${name}/${version}/${name}
 
 # for OSX
-~/Library/Application Support/kubebuilder/plugins/${name}/${version}
+~/Library/Application Support/kubebuilder/plugins/${name}/${version}/${name}
 ```
+As an example, if you're on Linux and you want to use `v2` of an external plugin called `foo.acme.io`, you'd place the executable in the folder `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/` with a file name that also matches the plugin name up to an (optional) file extension.
+In other words, passing the flag `--plugins=foo.acme.io/v2` to `kubebuilder` would find the plugin at either of these locations
+* `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io`
+* `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io.sh`
+* `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io.py`
+* etc...
 
 ### Subcommands: