Add documentation for installing plugins in air-gapped environments (#254)

Author: Anuj Chaudhari

docs/full/README.md

@@ -206,35 +206,3 @@ Signature verification could fail in the scenarios below:
    that signature verification is skipped for the repository. Users can choose to
    suppress this warning by setting the environment variable `TANZU_CLI_SUPPRESS_SKIP_SIGNATURE_VERIFICATION_WARNING`
    to `true`.
-
-## Interacting with a central repository hosted on a registry with self-signed CA or with expired CA
-
-If a user has configured a central repository on a custom registry (e.g. air-gaped environment) with a self-signed CA or
-if the
-registry CA
-certificate is expired, the user can execute the `tanzu config cert` family of commands to configure the certificate for
-the registry host.
-
-```shell
-
-    # If the registry host is self-signed add CA certificate for the registry
-    tanzu config cert add --host test.registry.com --ca-certificate path/to/ca/cert
-
-    # If the registry is self-signed and is serving on non-default port add CA certificate for the registry
-    tanzu config cert add --host test.registry.com:8443 --ca-certificate path/to/ca/cert
-
-    # If the registry is self-signed or CA cert is expired, add cert configuration for the registry host with
-    # skip-cert-verify option
-    tanzu config cert add --host test.registry.com  --skip-cert-verify true
-
-    # Set to allow insecure (http) connection while interacting with host
-    tanzu config cert add --host test.registry.com  --insecure true
-
-```
-
-The CLI uses the certificate configuration added for the registry host (using `tanzu config cert add` command ) while
-interacting with the registry.
-
-Users can update or delete the certificate configuration using the `tanzu config cert update`
-and `tanzu config cert delete` commands.
-Also, users can list the certificate configuration using the `tanzu config cert list` command.

docs/quickstart/install.md

@@ -91,3 +91,126 @@ The Tanzu CLI prompts the user for CEIP participation on their first use of any
 except for `tanzu version`, `tanzu ceip-participation set` and `tanzu config set` commands.
 Users installing/using the CLI through CI or by any automation means should be able to skip the prompt by
 calling `tanzu ceip-participation set <true/false>` as their first command to set the CEIP participation status.
+
+## Installing and using the Tanzu CLI in internet-restricted environments
+
+### Installing the Tanzu CLI
+
+You can install the Tanzu CLI in the internet-restricted environments by downloading the Tanzu CLI Binary
+from Github Release and copy it to the internet-restricted environment. Once copied follow the steps
+mentioned [here](#from-the-binary-releases-in-the-github-project) to install the Tanzu CLI.
+
+### Installing Tanzu CLI plugins in internet-restricted environments
+
+The Tanzu CLI allows users to install and run CLI plugins in internet-restricted
+environments (which means air-gapped environments, with no physical connection
+to the Internet). To run the Tanzu CLI in internet-restricted environments a
+private Docker-compatible container registry such as
+[Harbor](https://goharbor.io/), [Docker](https://docs.docker.com/registry/), or
+[Artifactory](https://jfrog.com/artifactory/) is required.
+
+Once the private registry is set up, the operator of the private registry can
+migrate plugins from the publicly available registry to the private registry
+using the below-mentioned steps:
+
+1. Download the plugin-inventory image along with all selected plugin images
+as a `tar.gz` file on the local disk of a machine which has internet access
+using the `tanzu plugin download-bundle` command.
+2. Copy this `tar.gz` file to the air-gapped network (using a USB drive or
+other mechanism).
+3. Upload the plugin bundle `tar.gz` to the air-gapped private registry using
+the `tanzu plugin upload-bundle` command.
+
+#### Downloading plugin bundle
+
+You can download all plugins within the default central repository by running
+the following command:
+
+```sh
+tanzu plugin download-bundle --to-tar /tmp/plugin_bundle_complete.tar.gz
+```
+
+However, If you want to just migrate plugins within specific plugin groups
+(e.g. `vmware-tkg/default:v2.1.0`) you can run the below command to download
+the plugin bundle containing only plugins from specified groups:
+
+```sh
+tanzu plugin download-bundle --group vmware-tkg/default:v2.1.0 --to-tar /tmp/plugin_bundle_tkg_v2_1_0.tar.gz
+```
+
+To migrate plugins from the specific plugin repository and not use the default
+plugin repository you can provide a `--image` flag with the above command. Example:
+
+```sh
+tanzu plugin download-bundle
+                  --image custom.repo.example.com/tanzu-cli/plugins/plugin-inventory:latest
+                  --group vmware-tkg/default:v2.1.0
+                  --to-tar /tmp/plugin_bundle_tkg_v2_1_0.tar.gz
+```
+
+#### Uploading plugin bundle to the private registry
+
+Once you download the plugin bundle as a `tar.gz` file and copy the file to the
+air-gapped network, you can run the following command to migrate plugins to the
+private registry (e.g. `registry.example.com/tanzu-cli/plugin`).
+
+Note: If you private registry is using self-signed certificates please configure
+certs for the registry as mentioned [here](#interacting-with-a-central-repository-hosted-on-a-registry-with-self-signed-ca-or-with-expired-ca).
+
+```sh
+tanzu plugin upload-bundle --tar /tmp/plugin_bundle_complete.tar.gz --to-repo `registry.example.com/tanzu-cli/plugin`
+```
+
+The above-mentioned command uploads the plugin bundle to the provided private
+repository location with the image name `plugin-inventory:latest`. So for the
+above example, the plugin inventory image will be published to
+`registry.example.com/tanzu-cli/plugin/plugin-inventory:latest`.
+
+Please note that `tanzu plugin upload-bundle` uploads the plugins by adding them
+to any plugin-inventory already present in the private registry. That means if you have already uploaded
+any plugins to the specified private repository, it will keep the existing
+plugins and append new plugins from the plugin bundle provided.
+
+You can use this image and configure the default discovery source to point to
+this image by running the following command:
+
+```sh
+tanzu plugin source update default --uri registry.example.com/tanzu-cli/plugin/plugin-inventory:latest
+```
+
+Now, the Tanzu CLI should be able to discover plugins from this newly configured
+private plugin discovery source. Verify that plugins are discoverable by
+running the `tanzu plugin search`, `tanzu plugin group search`, and
+`tanzu plugin install` commands.
+
+### Interacting with a central repository hosted on a registry with self-signed CA or with expired CA
+
+If a user has configured a central repository on a custom registry (e.g. air-gaped environment) with a self-signed CA or
+if the
+registry CA
+certificate is expired, the user can execute the `tanzu config cert` family of commands to configure the certificate for
+the registry host.
+
+```shell
+
+    # If the registry host is self-signed add CA certificate for the registry
+    tanzu config cert add --host test.registry.com --ca-certificate path/to/ca/cert
+
+    # If the registry is self-signed and is serving on non-default port add CA certificate for the registry
+    tanzu config cert add --host test.registry.com:8443 --ca-certificate path/to/ca/cert
+
+    # If the registry is self-signed or CA cert is expired, add cert configuration for the registry host with
+    # skip-cert-verify option
+    tanzu config cert add --host test.registry.com  --skip-cert-verify true
+
+    # Set to allow insecure (http) connection while interacting with host
+    tanzu config cert add --host test.registry.com  --insecure true
+
+```
+
+The CLI uses the certificate configuration added for the registry host (using `tanzu config cert add` command ) while
+interacting with the registry.
+
+Users can update or delete the certificate configuration using the `tanzu config cert update`
+and `tanzu config cert delete` commands.
+Also, users can list the certificate configuration using the `tanzu config cert list` command.