Skip to content

Commit

Permalink
docs: added Palette CLI subcommand (#1421)
Browse files Browse the repository at this point in the history 
* docs: added Palette CLI subcommand

* docs: updated openstack and VMware

* Apply suggestions from code review

Co-authored-by: Rita Watson <117382432+ritawatson@users.noreply.github.com>

* docs: updated the CLI steps

* chore: updates

* docs: updated MAAS section to include former method

* docs: updated the VMware section

* docs: minor touches

* docs: PLT-452 updated install command

* docs: final touches

* Apply suggestions from code review

Co-authored-by: Rita Watson <117382432+ritawatson@users.noreply.github.com>

* docs: updated pr feedback

* docs: vale feedback

---------

Co-authored-by: Rita Watson <117382432+ritawatson@users.noreply.github.com>
  • Loading branch information
@karl-cardenas-coding @ritawatson
karl-cardenas-coding and ritawatson committed Jul 19, 2023
1 parent 3211399 commit 6a35139
Show file tree
Hide file tree
Showing 5 changed files with 882 additions and 57 deletions.
280 changes: 266 additions & 14 deletions content/docs/04-clusters/02-data-center/01-maas/05-install-manage-maas-pcg.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,13 @@ At a high level, the following occurs during a successful MAAS PCG installation:

<br />

- Start the PCG installer on a laptop, workstation, or Bastion host.
- Use the Palette CLI on a laptop, workstation, or Bastion host.


- Provide information to the installer so that it can connect both to a local MAAS installation and a Palette account.
- Provide information to the CLI so that it can connect to both a local MAAS installation and a Palette account.


- The installer uses MAAS to obtain machines and install a PCG on them.
- The installation process uses MAAS to obtain machines and install a PCG on them.


- The PCG then facilitates all communication between Palette and MAAS, enabling Palette to create new clusters on machines that MAAS provides.
Expand All @@ -43,18 +43,271 @@ As the following diagram shows, Palette provides an installer in the form of a D
![An architecture diagram of MaaS with PCG.](/clusters_maas_install-manage-mass-pcg_diagram-of-mass-with-pcg.png)


# Install PCG

Use the following steps to install a PCG cluster in your MAAS environment. You can use the [Palette CLI](/palette-cli) or the PCG Installer Image to deploy a PCG cluster. Review the prerequisites for each option to help you identify the correct install method.

<br />


<Tabs>

<Tabs.TabPane tab="Palette CLI" key="palette-cli">


## Prerequisites


- Palette version 4.0.X or greater.


- Canonical [MAAS installed](https://maas.io/docs/how-to-install-maas), set up, and available in your environment.


- Download the Palette CLI from the [Downloads](/spectro-downloads#palettecli) page and install the CLI. Refer to the [Palette CLI Install](/palette-cli/install-palette-cli) guide to learn more.


- A Palette API key. Refer to the [Create API Key](/user-management/user-authentication#apikey) page for guidance.

<br />

<WarningBox>

The installation does not work with Single Sign-On (SSO) credentials. You must use an API key from a local tenant admin account in Palette to deploy the PCG. After the PCG is configured and functioning, this local account is no longer used to keep the PCG connected to Palette, so you can disable the account if desired.

</WarningBox>

- A Linux environment with a Docker daemon installed and a connection to Palette and the MAAS endpoint. The installation must be invoked on an up-to-date Linux system with an x86-64 architecture. ARM architecture is currently not supported.


- PCG IP address requirements: <br /><br />

- For a single-node gateway, one IP address must be available in the MAAS subnet for the PCG, or three available IP addresses for a three-node gateway.
<br />

- One IP address must be available in the MAAS subnet for the Kubernetes API-server endpoint when deploying a three-node gateway.


- Sufficient available IPs within the configured MAAS subnets.

<WarningBox>

The installer does not work on Apple Mac operating systems with Apple silicon chips.
By default, the MAAS Kubernetes pack uses a pod classless inter-domain routing (CIDR) range of 192.168.0.0/16. Ensure that the pod CIDR range for any clusters you deploy after setting up the PCG does not overlap with the network used by the bare metal machines that MAAS manages.

</WarningBox>

- Each node in the PCG cluster requires a machine from MAAS in a ready state with the following resources:

<br />

- CPU: 4
- Memory: 8192 MiB
- Storage: 60 GiB

For production environments, we recommend using three nodes, each with 100 GiB of storage, as nodes can exhaust the 60 GiB storage with prolonged use. If you initially set up the gateway with one node, you can resize it at a later time.


- An active [MAAS API key](https://maas.io/docs/api-authentication-reference) can be generated in the MAAS web console under **My Preferences** > **API keys**. The following is an example key:

``APn53wz232ZwBMxDp5:MHZIbUp3e4DJTjZEKg:mdEv33WAG536MhNC8mIywNLtjcDTnFAQ``

For details, refer to the MAAS document on [how to add an API key](https://maas.io/docs/how-to-manage-user-accounts#heading--api-key).

<br />

- The DNS server that the PCG installer will use, must be able to resolve the DNS names of machines that MAAS deploys so it can connect to them. The default setup is to use the MAAS server as the DNS server for any bare metal servers that it deploys. The default MAAS DNS zone is ``.maas``. You can use ``.maas`` or you can use the MAAS web console to create a new DNS zone. When you deploy the PCG and clusters, you can select the desired DNS zone in which DNS name records should be created.

In the MAAS subnets configuration, you can specify which DNS servers those servers in the MAAS subnet should use.

<WarningBox>

If you configure a different DNS server than the MAAS DNS server, you must be sure to create a DNS delegation in the other DNS server, so that it can forward DNS requests for zones that are hosted by MAAS to the MAAS DNS server.

</WarningBox>

<br />

The installation process first requests machines from MAAS and then must connect to them. To connect, the install process attempts to use the fully qualified domain name (FQDN) of the server. If you used ``.maas`` as the default DNS zone, the FQDN would be ``machine-hostname.maas``.

The diagram shows an example of using an external DNS server for servers that MAAS deploys in addition to a DNS delegation. This ensures all servers in the network can resolve the DNS names of servers deployed by MAAS. Note that it is not required for the DNS records to be accessible from the internet.


![Image showing external DNS server machines that MAAS deploys in addition to a DNS delegation](/clusters_maas_maas-dns-setup.png)


## Install

The following steps will guide you on how to install a PCG cluster.
<br />

1. In an x86 Linux host, open up a terminal session.


2. Use the [Palette CLI](/palette-cli/install-palette-cli) `login` command to authenticate the CLI with Palette. When prompted, enter the information listed in the following table.

<br />

```shell
palette login
```

<br />

|**Parameter** | **Description**|
|:-----------------------------|---------------|
|**Spectro Cloud Console** |Enter the Palette endpoint URL. When using the Palette SaaS service, enter ``https://console.spectrocloud.com``. When using a self-hosted instance of Palette, enter the URL for that instance. |
|**Allow Insecure Connection** |Enabling this option bypasses x509 verification. Enter `y` if you are using a self-hosted Palette instance with self-signed TLS certificates. Otherwise, enter `n`.|
|**Spectro Cloud API Key** |Enter your Palette API Key.|
|**Spectro Cloud Organization** |Enter your Palette Organization name.|
|**Spectro Cloud Project** |Enter your desired project name within the selected Organization.|


3. Once you have authenticated successfully, invoke the PCG installer by issuing the following command. When prompted, enter the information listed in each of the following tables.

<br />

```bash
palette pcg install
```

<br />

|**Parameter** | **Description**|
|:-----------------------------|---------------|
|**Cloud Type**| Choose OpenStack.|
|**Private Cloud Gateway Name** | Enter a custom name for the PCG. Example: `openstack-pcg-1`.|
|**Share PCG Cloud Account across platform Projects** |Enter `y` if you want the Cloud Account associated with the PCG to be available from all projects within your organization. Enter `n` if you want the Cloud Account to only be available at the tenant admin scope.|



4. Next, provide environment configurations for the cluster. Refer to the following table for information about each option.

<br />

|**Parameter**| **Description**|
|:-------------|----------------|
|**HTTPS Proxy**|Leave this blank unless you are using an HTTPS Proxy. This setting will be propagated to all PCG nodes and all of its cluster nodes. Example: ``https://USERNAME:PASSWORD@PROXYIP:PROXYPORT``.|
|**HTTP Proxy**|Leave this blank unless you are using an HTTP Proxy. This setting will be propagated to all PCG nodes and all of its cluster nodes. Example: ``http://USERNAME:PASSWORD@PROXYIP:PROXYPORT``.|
|**No Proxy**|The default is blank. You can add a comma-separated list of local network CIDR addresses, hostnames, and domain names that should be excluded from being a proxy. This setting will be propagated to all the nodes to bypass the proxy server. Example if you have a self-hosted environment: ``maas.company.com,10.10.0.0/16``.|
|**Proxy CA Certificate Filepath**|The default is blank. You can provide the file path of a CA certificate on the installer host. If provided, this CA certificate will be copied to each host in the PCG cluster during deployment. The provided path will be used on the PCG cluster hosts. Example: `/usr/local/share/ca-certificates/ca.crt`.|
|**Pod CIDR**|Enter the CIDR pool that will be used to assign IP addresses to pods in the PCG 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 PCG cluster. The service IP addresses should be unique and not overlap with any machine IPs in the environment.|.|

<br />


5. After the environment options, the next set of prompts is for configuring the PCG cluster for the MAAS environment. The following table contains information about each prompt.

<br />

|**Parameter**| **Description**|
|-------------|----------------|
| **MAAS API Endpoint** |Enter the MAAS API endpoint. This can be a domain or IP address. Example: `http://10.11.12.13:5240/MAAS`.|
| **MAAS API Key** |Enter an active MAAS API key to use for authentication.|



6. Next, select the appropriate option for each of the following items to define which machines should be selected on the MAAS server for deployment as a PCG.

<br />

|**Parameter**| **Description**|
|-------------|----------------|
| **Domain** | Select the MAAS domain. |
| **Patch OS on boot** | This parameter indicates whether or not to patch the OS of the PCG hosts on the first boot.|
| **Reboot nodes once OS patch is applied** | This parameter indicates whether or not to reboot PCG nodes after OS patches are applied.|
| **Availability Zone** | Select the availability zones for the PCG cluster. |
| **Resource Pool** | Select the MAAS resource pool. |
| **Cluster Size** | The number of nodes that will make up the cluster. Available options are **1** or **3** . Use three nodes for a High Availability (HA) cluster. | |

<WarningBox>

Ensure the MAAS server has one or more machines in the **Ready** state for the chosen availability zone
and resource pool combination.

</WarningBox>


7. A new PCG configuration file is generated and its location is displayed on the console. You will receive an output similar to the following.

<br />

```bash hideClipboard
==== PCG config saved ====
Location: :/home/spectro/.palette/pcg/pcg-20230706150945/pcg.yaml
```

<InfoBox>

The ``CloudAccount.apiKey`` and ``Mgmt.apiKey`` values in the **pcg.yaml** are encrypted and cannot be manually updated. To change these values, restart the installation process using the `palette pcg install` command.

</InfoBox>


The Palette CLI will now provision a PCG cluster in your OpenStack environment.
If the deployment fails due to misconfiguration, update the PCG configuration file and restart the install process. Refer to the Edit and Redeploy PCG section below. For additional assistance, visit our [Customer Support](https://spectrocloud.atlassian.net/servicedesk/customer/portals) portal.

## Validate

Once installed, the PCG registers itself with Palette. To verify the PCG is registered, use the following steps.


1. Log in to [Palette](https://console.spectrocloud.com) as a tenant admin.


2. Navigate to the left **Main Menu** and select **Tenant Settings**


3. From the **Tenant Settings Menu** click on **Private Cloud Gateways**. Verify your PCG cluster is available from the list of PCG clusters displayed.


4. When you install the PCG, a cloud account is auto-created. To verify the cloud account is created, go to **Tenant Settings > Cloud Accounts** and locate **MAAS** in the table. Verify your MAAS account is listed.



## Edit and Redeploy PCG

To change the PCG install values, restart the installation process using the `palette pcg install` command. Use the following steps to redeploy the PCG or restart the install process.

<br />

1. Make the necessary changes to the PCG configuration file the CLI created during the installation, if needed. Use a text editor, such as Vi or Nano to update the PCG install configuration file.

<br />

```shell hideClipboard
==== Create PCG reference config ====
==== PCG config saved ====
Location: /Users/demo/.palette/pcg/pcg-20230717114807/pcg.yaml
```

```bash hideClipboard
vi /home/demo/.palette/pcg/pcg-20230706150945/pcg.yaml
```



2. To redeploy the PCG, use the `install` command with the flags `--silent` and `--config-file`. Provide the file path to the generated PCG config file that was generated and displayed in the output.

<br />

```bash hideClipboard
palette pcg install --silent --config-file /home/demo/.palette/pcg/pcg-20230706150945/pcg.yaml
```


<br />

</Tabs.TabPane>

<Tabs.TabPane tab="PCG Installer Image" key="pcg-installer-image">

## Prerequisites

- Palette version 3.4.X or older.



- Canonical [MAAS installed](https://maas.io/docs/how-to-install-maas), set up, and available in your environment.


Expand Down Expand Up @@ -120,9 +373,9 @@ The diagram shows an example of using an external DNS server for servers that MA

The following steps outline the overall process to install the PCG.

For detailed steps, refer to the **Install PCG** tab below, which describes a single-step installation that creates the PCG configuration file and installs the PCG.
For detailed steps, refer to the **Install PCG** section below, which describes a single-step installation that creates the PCG configuration file and installs the PCG.

If you have already installed the PCG and are experiencing issues that you want to fix by editing the PCG configuration file directly, refer to the **Edit PCG Config** tab.
If you have already installed the PCG and are experiencing issues that you want to fix by editing the PCG configuration file directly, refer to the **Edit PCG Config** section below.

<br />

Expand All @@ -147,9 +400,6 @@ If you have already installed the PCG and are experiencing issues that you want
<br />


<Tabs>

<Tabs.TabPane tab="Install PCG" key="install_pcg">


## Install the PCG
Expand Down Expand Up @@ -272,9 +522,7 @@ Once installed, the gateway registers itself with Palette. To verify the gateway

When you install the gateway, a cloud account is auto-created. To verify the cloud account is created, go to **Tenant Settings > Cloud Accounts** and locate **MAAS** in the table. Verify your MAAS account is listed.

</Tabs.TabPane>

<Tabs.TabPane tab="Edit PCG Config" key="edit_pcg_config">


## Edit PCG Configuration File
Expand Down Expand Up @@ -333,13 +581,17 @@ The installer requests available bare metal machines in your MAAS environment on

If you need assistance, please visit our [Customer Support](https://spectrocloud.atlassian.net/servicedesk/customer/portals) portal.

</Tabs.TabPane>

</Tabs>

<br />

# Update and Manage the MAAS Gateway
</Tabs.TabPane>
</Tabs>




# Update and Manage the PCG

Palette maintains the Operating System (OS) image and all configurations for the PCG. Periodically, the OS images, configurations, and other components need to be updated to resolve security or functionality issues. Palette releases updates when required, and informs you with an update notification when you click on the gateway in the **Manage Cloud Gateways** page.

Expand Down
Loading

0 comments on commit 6a35139

Please sign in to comment.