diff --git a/docs/full/README.md b/docs/full/README.md index b10c53369..5ab1fe4d5 100644 --- a/docs/full/README.md +++ b/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. diff --git a/docs/quickstart/install.md b/docs/quickstart/install.md index a866d79f1..ee9828978 100644 --- a/docs/quickstart/install.md +++ b/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 ` 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.