Update documentation

vmware-tanzu · Apr 18, 2024 · c1b34e2 · c1b34e2
1 parent 6250573
commit c1b34e2
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 31 deletions.
diff --git a/docs/full/context-scoped-plugins.md → docs/full/context-recommended-plugins.md b/docs/full/context-scoped-plugins.md → docs/full/context-recommended-plugins.md
@@ -1,4 +1,4 @@
-# Context-Scope Plugin Installation
+# Context Recommended Plugin Installation
 
 ## Abstract
 
@@ -42,23 +42,12 @@ Plugin availability is solely dependent on the configured discovery sources in t
 tanzu configuration file. Each discovery source points to a plugin repository
 which can contain one or more plugins.
 
-## Standalone Plugins
-
-The scope of a plugin depends on how the plugin is getting installed on the user's machine.
-Users can run the `tanzu plugin search` command to see all available plugins from
-the configured discovery sources.
-
-If the user wants to install a plugin that is not dependent on any active context and
-wants to use it with the Tanzu CLI, the user can run `tanzu plugin install <plugin-name>`
-to install the required plugin. Installing the plugin this way will make the
-plugin a standalone plugin and it will not be associated with any contexts.
-
-## Context-scoped Plugins
+## Context Recommended Plugins
 
 As mentioned above in the abstract section, there might be a scenario when a user
 is working with multiple contexts at a time and wants to automatically select the
 right set of plugins and plugin versions based on the currently active context.
-The context-scoped plugin implementation is useful in this scenario.
+The context-recommended plugin implementation is useful in this scenario.
 
 When the CLI user creates a new context for the Tanzu CLI using the
 `tanzu context create` command, the CLI adds a context in the tanzu configuration file
@@ -75,12 +64,14 @@ is the workflow of context-scoped plugin installation:
 - The Tanzu CLI finds the plugins and their metadata in the available list of plugins generated from the configured discovery sources
 - The Tanzu CLI fetches the plugin binary for these plugins from the specified location and installs the plugin
 
-Users should understand that these plugins (installed based on a context) are
-only available when said context is active. If a user deletes the context the plugins
-installed based on the deleted context are no longer available to use with the CLI.
 If the user switches the context to a different context using the `tanzu context use` command,
 the CLI will automatically install/update the recommended plugins based on the new context.
 
+Note: Users should understand that these plugins (installed based on a recommendation from a context) are
+installed as normal plugins and will not be automatically deleted when a user deletes the context or switches
+the context to a different context. Commands associated with those plugins will remain available
+to be used but will likely throw an error if those plugins do not work with the active context.
+
 ## Plugin Recommendations from a Context
 
 This section provides more details on how a context can provide

diff --git a/docs/quickstart/quickstart.md b/docs/quickstart/quickstart.md
@@ -324,24 +324,36 @@ Switching to another context:
 [i] Successfully installed all required plugins
 
 > tanzu plugin list
-Standalone Plugins
-  NAME                DESCRIPTION                                                        TARGET      VERSION  STATUS
-  isolated-cluster    Prepopulating images/bundle for internet-restricted environments   global      v0.28.0  installed
-  pinniped-auth       Pinniped authentication operations (usually not directly invoked)  global      v0.28.0  installed
-  management-cluster  Kubernetes management cluster operations                           kubernetes  v0.28.0  installed
-  package             Tanzu package management                                           kubernetes  v0.28.0  installed
-  secret              Tanzu secret management                                            kubernetes  v0.28.0  installed
-  telemetry           configure cluster-wide settings for vmware tanzu telemetry         kubernetes  v0.28.0  installed
+  NAME                DESCRIPTION                                                        TARGET      INSTALLED  RECOMMENDED  STATUS
+  cluster             Kubernetes cluster operations                                      kubernetes  v0.28.0    v0.28.0      installed
+  feature             Operate on features and featuregates                               kubernetes  v0.28.0    v0.28.0      installed
+  kubernetes-release  Kubernetes release operations                                      kubernetes  v0.28.0    v0.28.0      installed
+  isolated-cluster    Prepopulating images/bundle for internet-restricted environments   global      v0.28.0                 installed
+  pinniped-auth       Pinniped authentication operations (usually not directly invoked)  global      v0.28.0                 installed
+  management-cluster  Kubernetes management cluster operations                           kubernetes  v0.28.0                 installed
+  package             Tanzu package management                                           kubernetes  v0.28.0                 installed
+  secret              Tanzu secret management                                            kubernetes  v0.28.0                 installed
+  telemetry           configure cluster-wide settings for vmware tanzu telemetry         kubernetes  v0.28.0                 installed
 
-Plugins from Context:  tkg-mgmt-vc
-  NAME                DESCRIPTION                           TARGET      VERSION  STATUS
-  cluster             Kubernetes cluster operations         kubernetes  v0.28.0  installed
-  feature             Operate on features and featuregates  kubernetes  v0.28.0  installed
-  kubernetes-release  Kubernetes release operations         kubernetes  v0.28.0  installed
 ```
 
+The way this type of plugin installation works is that The context you
+create or activate can recommend a list of plugins and their versions.
+When you create or activate a context, the Tanzu CLI fetches the list of
+recommended plugins and automatically tries to install these plugins to
+your machine. A `RECOMMENDED` column is shown as part of the
+`tanzu plugin list` output that specifies which plugins are recommended
+by the active context.
+
+For some reason, the auto-installation of the recommended plugins fails while
+creating or activating a context or an existing active context start recommending
+some newer versions of the plugins, you can check that with the `tanzu plugin list`
+output with the `STATUS` field mentioning `update needed` and a newer version in
+the `RECOMMENDED` column. You can run the `tanzu plugin sync` command
+to automatically install the recommended version of the plugins.
+
 To learn more about the plugins installed from context, please refer to
-[context-scoped plugin installation](../full/context-scoped-plugins.md).
+[context recommended plugin installation](../full/context-recommended-plugins.md).
 
 ## Notes to users of previous versions of the Tanzu CLI