site: custom index docs

site/content/docs/developer-guide/custom-indexes.md

@@ -0,0 +1,54 @@
+---
+title: Hosting Custom Plugin Indexes
+slug: custom-indexes
+weight: 500
+draft: true
+---
+
+Krew comes with a plugin index named `default` that points to the
+[`krew-index` repository](https://github.com/kubernetes-sigs/krew) which allows
+centralized discovery through community curation.
+
+However, you can host your own plugin indexes (and possibly remove/replace the
+`default` index). It’s not recommended to host your own plugin index, unless you
+have a use case such as:
+
+- your plugin is not accepted to `krew-index`
+- you want full control over the distribution lifecycle of your own plugin
+- you want to run a _private_ plugin index in your organization (e.g. to be
+  installed on developer machines)
+
+Hosting your own custom index is simple:
+
+- Custom index repositories must be `git` repositories.
+- Your clients should have read access to the repository (if the repository
+  is not public, users can still authenticate to it with SSH keys or other
+  [gitremote-helpers](https://git-scm.com/docs/gitremote-helpers) installed
+  on the client machine).
+- The repository must contain a `plugins/` directory at the root, with at least
+  one plugin manifest in it. Plugin manifests should be directly in this
+  directory.
+- Ensure plugin manifests are valid YAML and passes Krew manifest validation
+  (optionally, you can use the
+  [validate-krew-manifest](https://github.com/kubernetes-sigs/krew/tree/master/cmd/validate-krew-manifest)
+  tool for static analysis).
+
+Example plugin repository layout:
+
+```text
+.
+└── plugins/
+    ├── plugin-a.yaml
+    ├── plugin-b.yaml
+    └── plugin-c.yaml
+```
+
+## Duplicate plugin names
+
+Your custom index can contain plugins that have the same name as the ones in
+`krew-index`.
+
+Users of your index will need to install your plugin using the
+explicit `<INDEX>/<PLUGIN>` syntax. See the [user guide][ug].
+
+[ug]: {{< relref "../user-guide/using-custom-indexes.md">}}

site/content/docs/developer-guide/plugin-stats.md

@@ -1,7 +1,7 @@
 ---
 title: Plugin usage analytics
 slug: plugin-stats
-weight: 500
+weight: 600
 ---
 
 Krew does not track user behavior. However, for plugins that distribute their

site/content/docs/user-guide/using-custom-indexes.md

@@ -0,0 +1,84 @@
+---
+title: Using Custom Plugin Indexes
+slug: custom-indexes
+weight: 800
+draft: true
+---
+
+Plugin indexes contain plugin manifests, which are documents that describe
+installation procedure for a plugin. For discovery purposes, Krew comes with a
+`default` plugin index,  plugins hosted in the [`krew-index`
+repository](https://github.com/kubernetes-sigs/krew-index).
+
+However, some plugin authors may choose to host their own indexes that contain
+their curation of kubectl plugins. These are called "custom plugin indexes".
+
+## Adding a custom index
+
+A custom plugin index can be added with the `kubectl krew index add` command:
+
+```sh
+{{<prompt>}}kubectl krew index add foo https://github.com/foo/custom-index.git
+```
+
+The URI you use can be any [git remote](https://git-scm.com/docs/git-remote)
+(e.g., `[email protected]:foo/custom-index.git`).
+
+## Removing a custom index
+
+You can remove a custom plugin index by passing the name it was added with to
+the remove command:
+
+```sh
+{{<prompt>}}kubectl krew index remove foo
+```
+
+## Listing indexes
+
+To see what indexes you have added you can run the list command
+
+```sh
+{{<prompt>}}kubectl krew index list
+{{<output>}}INDEX    URL
+default  https://github.com/kubernetes-sigs/krew-index.git
+foo      https://github.com/foo/custom-index.git{{</output>}}
+```
+
+## Installing plugins from custom indexes
+
+Commands for managing plugins (e.g. `install`, `upgrade`) work with custom
+indexes as well.
+
+By default, Krew prefixes plugins with a `default/` prefix. However, if you have
+a plugin installed from a custom index, you need to specify it in format
+`INDEX_NAME/PLUGIN_NAME`.
+
+For example, to install a plugin named `bar` from custom index `foo`:
+
+```sh
+{{<prompt>}}kubectl krew install foo/bar
+```
+
+Similarly:
+
+- To list all plugins (including the ones from custom indexes), run:
+
+    ```sh
+    {{<prompt>}}kubectl krew search
+    ```
+
+- To remove a plugin, you don't need to specify its index:
+
+    ```sh
+    {{<prompt>}}kubectl krew uninstall PLUGIN_NAME
+    ```
+
+- To get information about a plugin from a custom index:
+
+    ```sh
+    {{<prompt>}}kubectl krew info INDEX_NAME/PLUGIN_NAME
+    ```
+
+
+> **Caveat:** If two indexes offer a plugin with the same name, only one can
+> be installed at any time.