Skip to content

Commit

Permalink
docs: PEM-4236 (#1926)
Browse files Browse the repository at this point in the history 
* docs: PEM-4236

* docs: vale feedback

* Update docs/docs-content/clusters/data-center/maas/install-manage-maas-pcg.md

Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com>

---------

Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com>
(cherry picked from commit d0216fe)
  • Loading branch information
@karl-cardenas-coding
karl-cardenas-coding committed Dec 20, 2023
1 parent edfed7c commit 6a3fe04
Show file tree
Hide file tree
Showing 4 changed files with 21 additions and 589 deletions.
311 changes: 2 additions & 309 deletions docs/docs-content/clusters/data-center/maas/install-manage-maas-pcg.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,6 @@ The PCG is a Kubernetes cluster that supports Palette in a private network envir

At a high level, the following occurs during a successful MAAS PCG installation:

<br />

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


Expand All @@ -41,12 +39,6 @@ As the following diagram shows, Palette provides an installer in the form of a D

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.


<Tabs queryString="pgc-install-method">

<TabItem label="Palette CLI" value="palette-cli">


### Prerequisites


Expand All @@ -56,7 +48,8 @@ Use the following steps to install a PCG cluster in your MAAS environment. You c
- 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.md#palette-cli) page and install the CLI. Refer to the [Palette CLI Install](../../../palette-cli/install-palette-cli.md) guide to learn more.
- Download the Palette CLI from the [Downloads](../../../spectro-downloads.md#palette-cli) page and install it. Refer to the [Palette CLI Install](../../../palette-cli/install-palette-cli.md) guide to learn more. Use the latest version of the Palette CLI that matches the version of your Palette or Palette VerteX instance.



- A Palette API key. Refer to the [Create API Key](../../../user-management/authentication/api-key/create-api-key.md) page for guidance.
Expand Down Expand Up @@ -129,8 +122,6 @@ The following steps will guide you on how to install a PCG cluster.

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

<br />

```shell
palette login
```
Expand Down Expand Up @@ -279,304 +270,6 @@ To change the PCG install values, restart the installation process using the `pa
palette pcg install --config-file /home/demo/.palette/pcg/pcg-20230706150945/pcg.yaml
```


<br />

</TabItem>

<TabItem label="PCG Installer Image" value="pcg-installer-image">

## 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.


- A Linux environment with a Docker daemon installed and a connection to Palette and the MAAS endpoint. The installer 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.

:::caution

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.

:::

- 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 run out of 60 GiB 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) which 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.

:::caution

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.

:::

<br />

The installer first requests machines from MAAS and then must connect to them. To connect, the installer 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)


### Understand the Gateway Installation Process

The following steps outline the overall process to install 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** section below.

<br />

1. You obtain a pairing code in Palette that you will use later.


2. Use the Docker image to start the installation on the installer host.


3. The installer prompts you for information, including the pairing code you obtained in step **1**.


4. The installer generates the PCG configuration file from information you provide in step **3**.

<br />

The installer needs access to your Palette account and to your MAAS environment. Additionally, one (no HA) or three (HA) machines must be in ready state and have internet access in MAAS. If you select one machine in step 3, then you need one in MAAS. Likewise, if you select three machines in step 3, you need three in MAAS.
<br />

5. The installer installs the MAAS machines and uses the configuration file to build a new cluster to host the PCG application.

<br />




### Install the PCG

The following steps will guide you to install the PCG.
<br />

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


2. If you have Single or Social Sign-On (SSO) enabled, you will need to use or create a local non-SSO tenant admin account in Palette and use the credentials for that account in step **7**.

:::caution

The installer does not work with SSO or Social sign on credentials. You must use a username and password 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.

:::


3. Navigate to the **Main Menu** and select **Tenant Settings > Private Cloud Gateway**.


4. Click the **Create Private Cloud Gateway** button and select **MAAS**. Private Gateway installation instructions are displayed.


5. Note the pairing code displayed in the Instructions section of the page. You will input this code when you use the installer. This pairing code is valid for 24 hours.


6. To invoke the installer, copy the following code snippet to your terminal.
<br />

```bash
docker run -it --rm \
--net=host \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume /tmp:/opt/spectrocloud \
gcr.io/spectro-images-public/release/spectro-installer:v1.0.12
```

7. When prompted, enter the pairing code and information listed in each of the following tables. The installer will generate the gateway configuration file.
<br />


#### Palette Parameters

|**Parameter** | **Description**|
|:-----------------------------|---------------|
|**Install Type**| Choose **Private Cloud Gateway**. <br />You can change your selection with the up or down keys.|
|**Cloud Type**| Choose MAAS.|
|**Name** | Enter a custom name for the PCG. Example: ``maas-pcg-1``.|
|**Endpoint** |Enter the Palette endpoint URL. When using the Palette SaaS service, enter ``https://console.spectrocloud.com``. When using a dedicated instance of Palette, enter the URL for that instance. |
|**Username** |Enter your Palette username. This is your sign-in email address. Example: ``user1@company.com``. |
|**Password** |Enter your Palette Password. This is your sign-in password.|
|**Pairing Code** |Enter the pairing code you noted from the instructions page in step **5**. |

<br />

#### Environment Configuration


|**Parameter**| **Description**|
|:-------------|----------------|
|**HTTPS Proxy (--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(--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(--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``.|
| **Pod CIDR (--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 (--svc_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 />


#### MAAS Account Information

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

<br />

1. When the installer prompts you, 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:

- Domain
- Availability Zone
- Resource Pool
- One node (no HA) or three nodes (HA)

<br />

:::caution

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

:::

When you have entered all the configuration values, the installer saves the gateway configuration file to disk and prints its location before proceeding with the installation. For example:

``/tmp/install-user-defined-MaaS-Gateway_Name-20210805155034/pcg.yaml``

<br />

:::info

The **/opt/spectrocloud** folder is volume mapped to the installer's **/tmp** folder.
:::
The installer then requests available bare metal machines in your MAAS environment on which to install the gateway. The ``password`` and ``API key`` values in the ``pcg.yaml`` are encrypted and cannot be manually updated. To change these values, copy the code snippet in step **6** to rerun the installer.
If the deployment fails due to misconfiguration, update the gateway configuration file and rerun the installer. Refer to the **Edit PCG Config** tab above.
If you need assistance, please visit our [Customer Support](https://spectrocloud.atlassian.net/servicedesk/customer/portals) portal.
<br />
### Validate
Once installed, the gateway registers itself with Palette. To verify the gateway is registered, navigate to **Tenant Settings > Private Cloud Gateways** and ensure the gateway is listed on the **Manage Private Cloud Gateways** page.
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.
### Edit PCG Configuration File
Use the following steps if you want to edit the PCG configuration file directly.
<br />
1. Copy the ``pcg.yaml`` file out of ``/tmp/install-user-defined-MaaS-Gateway_Name-20210805155034/pcg.yaml`` and into ``/tmp`` as follows.
```bash
cp /tmp/install-User-define-MaaS-Gateway-Name-20210805155034/pcg.yaml /tmp
```
2. Make the necessary changes to the configuration file.
3. Before you redeploy the gateway, do the following:
<br />
- Ensure the pairing code in the configuration file is the same as the pairing code displayed in the installation instructions in Palette. To verify the pairing code, click the **Create Private Cloud Gateway** button and select **MAAS**. Note the pairing code and verify it is the same code in the configuration file.
<br />
- If the codes do not match, modify the code in the configuration file so it matches the code displayed in Palette.
<br />
:::caution
Issues can occur with the PCG installation if the pairing code in Palette changes during the time it takes to modify the configuration file. Ensure pairing codes in Palette and the configuration file match before you redeploy the gateway.
If you stop the installation or it fails due to mismatched pairing codes, the gateway might display as **Pending (unnamed)** on the **Private Cloud Gateways** page. If this happens, delete the gateway and ensure pairing codes in Palette and the configuration file match before redeploying the gateway.
:::
<br />
4. To redeploy the gateway, copy the following code snippet to your terminal and provide the gateway configuration file as input.
```bash
docker run -it –rm \
–net-host \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp:/opt/spectrocloud \
gcr.io/spectro-images-public/release/spectro-installer:1.0.12 \
-s true \
-c /opt/spectrocloud/pcg.yaml
```
The installer requests available bare metal machines in your MAAS environment on which to install the gateway.
If you need assistance, please visit our [Customer Support](https://spectrocloud.atlassian.net/servicedesk/customer/portals) portal.
<br />
</TabItem>
</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 6a3fe04

Please sign in to comment.