Skip to content

Commit

Permalink
Add tanzu-cli installation and move doc to install.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@anujc25
anujc25 committed May 3, 2023
1 parent b88bbbf commit 2ce583c
Show file tree
Hide file tree
Showing 3 changed files with 125 additions and 111 deletions.
111 changes: 0 additions & 111 deletions docs/full/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,114 +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.
## 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`).

```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.
123 changes: 123 additions & 0 deletions docs/quickstart/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 here 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.
2 changes: 2 additions & 0 deletions go.work.sum
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
cloud.google.com/go v0.102.1 h1:vpK6iQWv/2uUeFJth4/cBHsQAGjn1iIE6AAlxipRaA0=
github.com/apex/log v1.1.4 h1:3Zk+boorIQAAGBrHn0JUtAau4ihMamT4WdnfdnXM1zQ=
github.com/cespare/xxhash v1.1.0 h1:a6HrQnmkObjyL+Gs60czilIUGqrzKutQD6XZog3p+ko=
github.com/cpuguy83/go-md2man v1.0.10 h1:BSKMNlYxDvnunlTymqtgONjNnaRV1sTpcovwwjF22jk=
github.com/emicklei/go-restful v2.16.0+incompatible h1:rgqiKNjTnFQA6kkhFe16D8epTksy9HQ1MyrbDXSdYhM=
github.com/google/go-github v17.0.0+incompatible h1:N0LgJ1j65A7kfXrZnUDaYCs/Sf4rEjNlfyDHW9dolSY=
github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c h1:Lgl0gzECD8GnQ5QCWA8o6BtfL6mDH5rQgM4/fX3avOs=
github.com/russross/blackfriday v1.6.0 h1:KqfZb0pUVN2lYqZUYRddxF4OR8ZMURnJIG5Y3VRLtww=
github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
k8s.io/klog v1.0.0 h1:Pt+yjF5aB1xDSVbau4VsWe+dQNzA0qv1LlXdC2dF6Q8=

0 comments on commit 2ce583c

Please sign in to comment.