From e1c54306401b5a0bb2d00859058d791ce81bb19a Mon Sep 17 00:00:00 2001 From: Karl Cardenas <29551334+karl-cardenas-coding@users.noreply.github.com> Date: Fri, 28 Jun 2024 09:37:37 -0700 Subject: [PATCH] docs: PLT-1267 EC Install Validate Flag (#3176) --- .../automation/palette-cli/commands/ec.md | 314 ++++++++++++++---- .../install-on-vmware/install.md | 79 +---- .../install-on-vmware/install.md | 16 + 3 files changed, 279 insertions(+), 130 deletions(-) diff --git a/docs/docs-content/automation/palette-cli/commands/ec.md b/docs/docs-content/automation/palette-cli/commands/ec.md index ce817a67a8..1e188fbfb9 100644 --- a/docs/docs-content/automation/palette-cli/commands/ec.md +++ b/docs/docs-content/automation/palette-cli/commands/ec.md @@ -40,52 +40,48 @@ you for required values. Alternatively, you can use flags to generate a configur | Short Flag | Long Flag | Description | Type | | ---------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `-f` | `--config-file` | Install using a configuration file (optional). Use `-config-only` to generate a configuration file. | string | +| `-d` | `--skip-teardown` | Skip tear down of the kind cluster in case of errors. | boolean | | `-o` | `--config-only` | Generate configuration file only. This command will not proceed with installation. | boolean | | `-v` | `--custom-values-file` | Enterprise Cluster custom values.yaml configuration file (optional). Use this to customize the cluster profile of the Enterprise Cluster. Refer to the [custom value file](#custom-value-file) section for more information. | string | | `-p` | `--update-passwords` | Update passwords only. Do not proceed with installation. The `--config-file` flag must also be provided. | string | +| `-t` | `--update-tokens` | Update authentication tokens only. Do not proceed with installation. The `--config-file` flag must be provided. | boolean | +| - | `--validate` | Scan the environment and conduct validation before the enterprise cluster is installed. | boolean | ### Examples Install an Enterprise Cluster in interactive mode. -
- ```shell palette ec install ``` -
- Create a configuration file for the Enterprise Cluster installation. -
- ```shell palette ec install --config-only ``` -
- Install an Enterprise Cluster using a configuration file. The configuration file is generated using the `--config-only` flag. -
- ```shell hideCliboard palette ec install --config-file ~/.palette/ec/ec-20230807143205/ec.yaml ``` -
- Update the passwords of an Enterprise Cluster using a configuration file. The configuration file is generated using the `--config-only` flag. -
- ```shell hideCliboard palette ec install --config-file ~/.palette/ec/ec-20230807143205/ec.yaml --update-passwords ``` +Install an Enterprise Cluster and validate the environment before installation. Check out the +[Validate Environment](#validate-environment) section for more information. + +```shell +palette ec install --validate +``` + ## Custom Value File You can customize the [Cluster Profile](../../../glossary-all.md#cluster-profile) that makes up the Enterprise Cluster @@ -95,8 +91,6 @@ This is an advanced feature and should only be used by advanced users or when ex The **values.yaml** file is made up of the following components: -
- - `os` The operating system layer of the Enterprise Cluster. This layer contains the values for the operating system that will be used to install the Enterprise Cluster. @@ -117,56 +111,250 @@ The **values.yaml** file is made up of the following components: file that contains the `os` layer, it will replace the default operating system configuration. The Enterprise Cluster profile as follows The **values.yaml** must use the following format: -
- -```yaml hideClipboard -os: |- - # ... values.yaml for OS layer go here. -k8s: |- - # ... values.yaml for K8s layer go here. -csi: |- - # ... values.yaml for CSI layer go here. -cni: |- - # ... values.yaml for CNI layer go here. -mgmt: |- - # ... values.yaml for spectro-mgmt layer go here. -``` + ```yaml hideClipboard + os: |- + # ... values.yaml for OS layer go here. + k8s: |- + # ... values.yaml for K8s layer go here. + csi: |- + # ... values.yaml for CSI layer go here. + cni: |- + # ... values.yaml for CNI layer go here. + mgmt: |- + # ... values.yaml for spectro-mgmt layer go here. + ``` The following example shows a custom **values.yaml** file that contains the `os` layer. The `os` layer contains the configuration for the operating system that will be used to install the Enterprise Cluster. -
+ ```yaml hideClipboard + os: |- + kubeadmconfig: + preKubeadmCommands: + - echo "Executing pre kube admin config commands" + - update-ca-certificates + - "systemctl restart containerd; sleep 3" + - 'while [ ! -S /var/run/containerd/containerd.sock ]; do echo "Waiting for containerd..."; sleep 1; done' + postKubeadmCommands: + - echo "Executing post kube admin config commands" + files: + - targetPath: /usr/local/share/ca-certificates/mycom.crt + targetOwner: "root:root" + targetPermissions: "0644" + content: | + -----BEGIN CERTIFICATE----- + MIICyzCCAbOgAwIBAgIBADANBgkqhkiG9w0BAQsFADAVMRMwEQYDVQQDEwprdWJl + cm5ldGVzMB4XDTIwMDkyMjIzNDMyM1oXDTMwMDkyMDIzNDgyM1owFTETMBEGA1UE + AxMKa3ViZXJuZXRlczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMdA + nZYs1el/6f9PgV/aO9mzy7MvqaZoFnqO7Qi4LZfYzixLYmMUzi+h8/RLPFIoYLiz + qiDn+P8c9I1uxB6UqGrBt7dkXfjrUZPs0JXEOX9U/6GFXL5C+n3AUlAxNCS5jobN + fbLt7DH3WoT6tLcQefTta2K+9S7zJKcIgLmBlPNDijwcQsbenSwDSlSLkGz8v6N2 + 7SEYNCV542lbYwn42kbcEq2pzzAaCqa5uEPsR9y+uzUiJpv5tDHUdjbFT8tme3vL + 9EdCPODkqtMJtCvz0hqd5SxkfeC2L+ypaiHIxbwbWe7GtliROvz9bClIeGY7gFBK + jZqpLdbBVjo0NZBTJFUCAwEAAaMmMCQwDgYDVR0PAQH/BAQDAgKkMBIGA1UdEwEB + /wQIMAYBAf8CAQAwDQYJKoZIhvcNAQELBQADggEBADIKoE0P+aVJGV9LWGLiOhki + HFv/vPPAQ2MPk02rLjWzCaNrXD7aPPgT/1uDMYMHD36u8rYyf4qPtB8S5REWBM/Y + g8uhnpa/tGsaqO8LOFj6zsInKrsXSbE6YMY6+A8qvv5lPWpJfrcCVEo2zOj7WGoJ + ixi4B3fFNI+wih8/+p4xW+n3fvgqVYHJ3zo8aRLXbXwztp00lXurXUyR8EZxyR+6 + b+IDLmHPEGsY9KOZ9VLLPcPhx5FR9njFyXvDKmjUMJJgUpRkmsuU1mCFC+OHhj56 + IkLaSJf6z/p2a3YjTxvHNCqFMLbJ2FvJwYCRzsoT2wm2oulnUAMWPI10vdVM+Nc= + -----END CERTIFICATE----- + ``` + +## Validate Environment + +You can use the `--validate` flag to scan the environment and conduct validation before the Enterprise Cluster is +installed. The validation uses the open-source project [Validator](https://github.com/validator-labs/validator) to check +for the following prerequisites: + +- The required vSphere permissions and privileges are available for the provided user. +- At least five IP addresses are available in the provided IP range. +- Ensure vSphere tags for Kubernetes regions and zones are available. +- The provided vSphere Datacenter is accessible and has the required compute resources available. + +:::info + +The `--validate` is only available in environments that have internet access to download the Helm charts required by the +Validator. If you are in an environment without internet access, the validation will not be able to execute and will +return an error. + +::: + +When you use the `--validate` flag, the standard installation wizard will proceed unless the `--config-file` flag is +provided. Once all user inputs are provided, the validation will begin. A kind cluster will be created that contains the +necessary components to conduct the validation checks. The Validator plugins will trigger the validation checks. The +validation results will be displayed in the terminal. Below is an example of the validation results. -```yaml hideClipboard -os: |- -kubeadmconfig: - preKubeadmCommands: - - echo "Executing pre kube admin config commands" - - update-ca-certificates - - "systemctl restart containerd; sleep 3" - - 'while [ ! -S /var/run/containerd/containerd.sock ]; do echo "Waiting for containerd..."; sleep 1; done' - postKubeadmCommands: - - echo "Executing post kube admin config commands" - files: - - targetPath: /usr/local/share/ca-certificates/mycom.crt - targetOwner: "root:root" - targetPermissions: "0644" - content: | - -----BEGIN CERTIFICATE----- - MIICyzCCAbOgAwIBAgIBADANBgkqhkiG9w0BAQsFADAVMRMwEQYDVQQDEwprdWJl - cm5ldGVzMB4XDTIwMDkyMjIzNDMyM1oXDTMwMDkyMDIzNDgyM1owFTETMBEGA1UE - AxMKa3ViZXJuZXRlczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMdA - nZYs1el/6f9PgV/aO9mzy7MvqaZoFnqO7Qi4LZfYzixLYmMUzi+h8/RLPFIoYLiz - qiDn+P8c9I1uxB6UqGrBt7dkXfjrUZPs0JXEOX9U/6GFXL5C+n3AUlAxNCS5jobN - fbLt7DH3WoT6tLcQefTta2K+9S7zJKcIgLmBlPNDijwcQsbenSwDSlSLkGz8v6N2 - 7SEYNCV542lbYwn42kbcEq2pzzAaCqa5uEPsR9y+uzUiJpv5tDHUdjbFT8tme3vL - 9EdCPODkqtMJtCvz0hqd5SxkfeC2L+ypaiHIxbwbWe7GtliROvz9bClIeGY7gFBK - jZqpLdbBVjo0NZBTJFUCAwEAAaMmMCQwDgYDVR0PAQH/BAQDAgKkMBIGA1UdEwEB - /wQIMAYBAf8CAQAwDQYJKoZIhvcNAQELBQADggEBADIKoE0P+aVJGV9LWGLiOhki - HFv/vPPAQ2MPk02rLjWzCaNrXD7aPPgT/1uDMYMHD36u8rYyf4qPtB8S5REWBM/Y - g8uhnpa/tGsaqO8LOFj6zsInKrsXSbE6YMY6+A8qvv5lPWpJfrcCVEo2zOj7WGoJ - ixi4B3fFNI+wih8/+p4xW+n3fvgqVYHJ3zo8aRLXbXwztp00lXurXUyR8EZxyR+6 - b+IDLmHPEGsY9KOZ9VLLPcPhx5FR9njFyXvDKmjUMJJgUpRkmsuU1mCFC+OHhj56 - IkLaSJf6z/p2a3YjTxvHNCqFMLbJ2FvJwYCRzsoT2wm2oulnUAMWPI10vdVM+Nc= - -----END CERTIFICATE----- +```shell hideCliboard +Plugins will now execute validation checks. + +You can list validation results via the following command: +kubectl -n validator get validationresults --kubeconfig /home/ubuntu/.palette/ec/ec-20240627215351/kind-cluster.kubeconfig + +And you can view all validation result details via the following command: +kubectl -n validator describe validationresults --kubeconfig /home/ubuntu/.palette/ec/ec-20240627215351/kind-cluster.kubeconfig + +Watching validation results, waiting for all to succeed +Using kubeconfig from validator configuration file: /home/ubuntu/.palette/ec/ec-20240627215351/kind-cluster.kubeconfig + +Validation result for validator-plugin-vsphere-rules updated: + +================= +Validation Result +================= + +Plugin: vSphere +Name: validator-plugin-vsphere-rules +Namespace: validator +State: Succeeded + +------------ +Rule Results +------------ + +Validation Rule: validation-folder-/Datacenter/vm/spectro-templates +Validation Type: vsphere-entity-privileges +Status: True +Last Validated: 2024-06-27T21:57:04Z +Message: All required vsphere-entity-privileges permissions were found for account: demo@vsphere.local + +Validation Rule: validation-demo@vsphere.local +Validation Type: vsphere-role-privileges +Status: True +Last Validated: 2024-06-27T21:57:04Z +Message: All required vsphere-role-privileges permissions were found + +Validation Rule: validation-tag-cluster-k8s-zone +Validation Type: vsphere-tags +Status: True +Last Validated: 2024-06-27T21:57:04Z +Message: Required entity tags were found + +Validation Rule: validation-tag-datacenter-k8s-region +Validation Type: vsphere-tags +Status: True +Last Validated: 2024-06-27T21:57:04Z +Message: Required entity tags were found + +Validation Rule: validation-cluster-Cluster2 +Validation Type: vsphere-compute-resources +Status: True +Last Validated: 2024-06-27T21:57:04Z +Message: All required compute resources were satisfied + +Watching for updates to validation results for [validator-plugin-network-rules]... + +Validation result for validator-plugin-network-rules updated: + +================= +Validation Result +================= + +Plugin: Network +Name: validator-plugin-network-rules +Namespace: validator +State: Succeeded + +------------ +Rule Results +------------ + +Validation Rule: IP range rule 1, start IP 10.10.189.10 with length 5 +Validation Type: network-ip-range +Status: True +Last Validated: 2024-06-27T21:57:04Z +Message: All network-ip-range checks passed + +------- +Details +------- +- Ensuring that 10.10.189.10 and 5 subsequent IPs are all unallocated +- ping [-c 3 -W 3 10.10.189.10] failed; err: exit status 1, stderr: +- ping [-c 3 -W 3 10.10.189.11] failed; err: exit status 1, stderr: +- ping [-c 3 -W 3 10.10.189.12] failed; err: exit status 1, stderr: +- ping [-c 3 -W 3 10.10.189.13] failed; err: exit status 1, stderr: +- ping [-c 3 -W 3 10.10.189.14] failed; err: exit status 1, stderr: + +Validation Rule: VSphere TCP Connection +Validation Type: network-tcp-conn +Status: True +Last Validated: 2024-06-27T21:57:19Z +Message: + +------- +Details +------- +- Ensuring that TCP connection(s) can be established to vcenter.spectrocloud.dev on port(s) [443] +- nc [-w 3 vcenter.spectrocloud.dev 443] succeeded + +All validations have completed. +``` + +After the validation checks are complete, the kind cluster is removed. If any of the validation checks fail, the +installation will not proceed. The example below displays a failed network validation check. + +```shell hideCliboard +Validation result for validator-plugin-network-rules updated: + +================= +Validation Result +================= + +Plugin: Network +Name: validator-plugin-network-rules +Namespace: validator +State: Failed + +------------ +Rule Results +------------ + +Validation Rule: IP range rule 1, start IP 10.10.189.1 with length 4 +Validation Type: network-ip-range +Status: False +Last Validated: 2024-06-27T22:36:03Z +Message: IP range check failed: one or more IPs in the provided range was allocated + +------- +Details +------- +- Ensuring that 10.10.189.1 and 4 subsequent IPs are all unallocated +- ping [-c 3 -W 3 10.10.189.1] succeeded +- ping [-c 3 -W 3 10.10.189.2] failed; err: exit status 1, stderr: +- ping [-c 3 -W 3 10.10.189.3] failed; err: exit status 1, stderr: +- ping [-c 3 -W 3 10.10.189.4] failed; err: exit status 1, stderr: + +-------- +Failures +-------- +- stdout: PING 10.10.189.1 (10.10.189.1) 56(84) bytes of data. +64 bytes from 10.10.189.1: icmp_seq=1 ttl=63 time=0.338 ms +64 bytes from 10.10.189.1: icmp_seq=2 ttl=63 time=0.065 ms +64 bytes from 10.10.189.1: icmp_seq=3 ttl=63 time=0.145 ms + +--- 10.10.189.1 ping statistics --- +3 packets transmitted, 3 received, 0%!p(MISSING)acket loss, time 2052ms +rtt min/avg/max/mdev = 0.065/0.182/0.338/0.114 ms + + +Validation Rule: VSphere TCP Connection +Validation Type: network-tcp-conn +Status: True +Last Validated: 2024-06-27T22:36:14Z +Message: + +------- +Details +------- +- Ensuring that TCP connection(s) can be established to vcenter.spectrocloud.dev on port(s) [443] +- nc [-w 3 vcenter.spectrocloud.dev 443] succeeded + +All validations have completed. + +helm delete validator --namespace validator --kubeconfig /tmp/1406656575 + +Uninstalled validator and validator plugin(s) successfully +Deleting cluster "validator-kind-cluster" ... +Deleted local Kind cluster: validator-kind-cluster +Error: failed to install Enterprise Cluster: environment validation failed ``` diff --git a/docs/docs-content/enterprise-version/install-palette/install-on-vmware/install.md b/docs/docs-content/enterprise-version/install-palette/install-on-vmware/install.md index ee4bbdf7be..0f53f88f76 100644 --- a/docs/docs-content/enterprise-version/install-palette/install-on-vmware/install.md +++ b/docs/docs-content/enterprise-version/install-palette/install-on-vmware/install.md @@ -15,11 +15,10 @@ Refer to [Access Palette](../../enterprise-version.md#access-palette) for instru ## Prerequisites -:::warning +:::tip -If you are installing Palette in an airgap environment, ensure you complete all the airgap pre-install steps before -proceeding with the installation. Refer to the -[VMware vSphere Airgap Instructions](../install-on-vmware//airgap-install/vmware-vsphere-airgap-instructions.md) guide +We recommend using the `--validate` flag with the `ec install` command to validate the installation. Check out the +[Validate Environment](../../../automation/palette-cli/commands/ec.md#validate-environment) section of the EC command for more information. ::: @@ -125,6 +124,14 @@ Use the following steps to install Palette. palette ec install ``` + You can also use the `--validate` flag to validate the installation prior to deployment. Refer to the + [Validate Environment](../../../automation/palette-cli/commands/ec.md#validate-environment) section of the EC + command for more information. + + ```bash + palette ec install --validate + ``` + 6. At the **Enterprise Cluster Type** prompt, choose **Palette**. 7. Type `y` if you want to use Ubuntu Pro. Otherwise, type `n`. If you choose to use Ubuntu Pro, you will be prompted @@ -168,69 +175,7 @@ Use the following steps to install Palette. | **Pod CIDR** | Enter the CIDR pool IP that will be used to assign IP addresses to pods in the EC cluster. The pod IP addresses should be unique and not overlap with any machine IPs in the environment. | | **Service IP Range** | Enter the IP address range that will be used to assign IP addresses to services in the EC cluster. The service IP addresses should be unique and not overlap with any machine IPs in the environment. | -13. Select the tab below that matches your installation type for further guidance. - - - - - - Select `y` to use the Spectro Cloud repository and proceed to the next step. - - - - - - :::info - - If you are using the Palette CLI from inside an - [airgap support VM](./airgap-install/vmware-vsphere-airgap-instructions.md), the CLI will automatically detect the - airgap environment and prompt you to **Use local, air-gapped Pack Registry?** Type `y` to use the local resources - and skip filling in the OCI registry URL and credentials. - - ::: - - Select the OCI registry type and provide the configuration values. Review the following table for more information. - - :::warning - - For self-hosted OCI registries, ensure you have the server Certificate Authority (CA) certificate file available on - the host where you are using the Palette CLI. You will be prompted to provide the file path to the OCI CA - certificate. Failure to provide the OCI CA certificate will result in self-linking errors. Refer to the - [Self-linking Error](../../../troubleshooting/enterprise-install.md#scenario---self-linking-error) troubleshooting - guide for more information. - - ::: - - #### Pack & Image Registry Configuration - - | **Parameter** | **Description** | - | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | **Registry Type** | Specify the type of registry. Allowed values are `OCI` or `OCI ECR`. Airgap users, select `OCI`. | - | **Registry Name** | Enter the name of the registry. | - | **Registry Endpoint** | Enter the registry endpoint. Airgap users, provide the **Spectro Cloud Repository** URL or hostname shared by the airgap setup script. | - | **Registry Base Path** | Enter the registry base path. | - | **Allow Insecure Connection** | Bypasses x509 verification. Type `n` to specify a certificate authority in the follow-up prompt. Airgap user, ensure you select `n`. | - | **Registry CA certificate filepath** | Specify the file path to the certificate authority. Use absolute paths. Airgap users, provide the filepath displayed by the aurgap setup script. | - | **Registry Username** or **Registry Access Key** | Enter the registry username or the access key if using `OCI ECR`. | - | **Registry Password** or **Registry Secret Key** | Enter the registry password or the secret key if using `OCI ECR`. | - | **Registry Region** | Enter the registry region. This option is only available if you are using `OCI ECR`. | - | **ECR Registry Private** | Type `y` if the registry is private. Otherwise, type `n`. | - | **Use Public Registry for Images** | Type `y` to use a public registry for images. Type `n` to a different registry for images. If you are using another registry for images, you will be prompted to enter the registry URL, base path, username, and password. Airgap users, select `n` so that you can specify the values for the OCI registry that contains all the required images. | - - When prompted to **Pull images from public registry**, type `n` and specify the OCI registry configuration values for - your image registry. If you are an airgap support VM, the CLI will automatically detect the airgap environment and prompt you to **Use local, air-gapped Image Registry?** Type `y` to use the local resources and skip filling in the OCI registry URL and credentials. - Refer to the table above for more information. - - :::info - - You will be provided with an opportunity to update the mirror registries values. To exit `vi` press the `Escape` key - and type `:wq` to save and exit. - - ::: - - - - +13. Select `y` to use the Spectro Cloud repository and proceed to the next step. 14. The next set of prompts is for the VMware vSphere account information. Enter the information listed in the following table. diff --git a/docs/docs-content/vertex/install-palette-vertex/install-on-vmware/install.md b/docs/docs-content/vertex/install-palette-vertex/install-on-vmware/install.md index 42d175562c..ad58694837 100644 --- a/docs/docs-content/vertex/install-palette-vertex/install-on-vmware/install.md +++ b/docs/docs-content/vertex/install-palette-vertex/install-on-vmware/install.md @@ -16,6 +16,14 @@ Palette VerteX will be deployed. ## Prerequisites +:::tip + +We recommend using the `--validate` flag with the `ec install` command to validate the installation. Check out the +[Validate Environment](../../../automation/palette-cli/commands/ec.md#validate-environment) section of the EC command +for more information. + +::: + - An AMD64 Linux environment with connectivity to the VMware vSphere environment. - [Docker](https://docs.docker.com/engine/install/) or equivalent container runtime installed and available on the Linux @@ -142,6 +150,14 @@ Use the following steps to install Palette VerteX. palette ec install ``` + You can also use the `--validate` flag to validate the installation prior to deployment. Refer to the + [Validate Environment](../../../automation/palette-cli/commands/ec.md#validate-environment) section of the EC + command for more information. + + ```bash + palette ec install --validate + ``` + 6. At the **Enterprise Cluster Type** prompt, choose **Palette VerteX**. 7. Select the desired OS you want to use for the installation. Review the table below for more information about each