The Private Cloud Gateway (PCG) enables support for private cloud or data center environments. You can set up the cloud gateway as a single-node or three-node cluster based on your requirements for high availability (HA).

Palette provides an installer in the form of a Docker container that is temporarily deployed on your laptop, workstation, or jump box. You can use the installer on any Linux x86-64 system with a Docker daemon installed and connectivity to Palette and the MAAS identity endpoint.

The installer does not currently work on MacOS running on Apple Silicon.


  • 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.
  • Private cloud gateway IP requirements:

    • For a single-node gateway, one IP address available in the MaaS subnet for the PCG, or three available IP addresses for a three-node gateway.

    • One IP address 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.

By default, the MAAS Kubernetes pack uses a pod classless inter-domain routing (CIDR) range of Ensure that the pod CIDR range for any clusters you deploy after setting up the PCG do 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:

    • 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 which can be generated in the MAAS web console under My Preferences > API keys. The following is an example key:


    For details, refer to the MAAS document on how to add an API key.

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

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.

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

Understand the Gateway Installation Process

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.

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.

  1. You obtain a pairing code in Palette that you will use later.
  1. Use the Docker image to start the installation on the installer host.
  1. The installer prompts you for information, including the pairing code you obtained in step 1.
  1. The installer generates the PCG configuration file from information you provide in step 3.

    The installer needs access to your Palette account and to one (no HA) or three (HA) machines in your MAAS cluster. If you select one machine in Palette, then you need one in MAAS. Likewise, if you select three machines in Palette, you need three in MAAS. The MAAS machines must have internet access and be in a ready state.

  2. The installer installs to the MAAS machine(s) and uses the configuration file to build a new cluster to host the PCG application.

Install the Gateway

The following steps will guide you to install the PCG.

  1. Log in to Palette as a tenant admin.
  1. 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.

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.

  1. Navigate to the Main Menu and select Tenant Settings > Private Cloud Gateway.
  1. Click the Create Private Cloud Gateway button and select MAAS. Private Gateway installation instructions are displayed.
  1. Note the pairing code displayed in the Instructions section of the page. You will input this code when you use the installer.
  1. To invoke the installer, copy the following code snippet to your terminal.

    docker run -it --rm \
    --net=host \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume /tmp:/opt/spectrocloud \
  2. When prompted, enter the pairing code and information listed in each of the following tables. The installer will generate the gateway configuration file.

Palette Parameters

Install TypeChoose Private Cloud Gateway.
You can change your selection with the up or down keys.
Cloud TypeChoose MAAS.
NameEnter a custom name for the PCG. Example: maas-pcg-1.
EndpointEnter 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.
UsernameEnter your Palette username. This is your sign-in email address. Example: user1@company.com.
PasswordEnter your Palette Password. This is your sign-in password.
Pairing CodeEnter the pairing code you noted from the instructions page in step 5.

Environment Configuration

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 subsequent 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 subsequent 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,
Pod CIDR (--pod_cidr)Enter the CIDR pool that will be used to assign IP addresses to pods in the cluster. The pod IP addresses should be unique and should 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 Kubernetes clusters. The service IP addresses should be unique and not overlap with any virtual machine IPs in the environment.

MAAS Account Information

API EndpointEnter the MAAS API endpoint. This can be a domain or IP address. Example:
API KeyEnter an active MAAS API key to use for authentication.

  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:

    • Availability Zone
    • Domain
    • Resource Pool
    • One node (no HA) or three nodes (HA)
  2. 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:


The /opt/spectrocloud folder is volume mapped to the /tmp folder on the host machine.

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


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.

Update and Manage the MAAS Gateway

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.

Review the changes in the update notification, and apply the update when you are ready.

Updating the cloud gateway does not result in any downtime for the tenant clusters. During the update process, new cluster provisioning is unavailable. New cluster requests are queued and processed when the gateway update is complete.

Delete the MAAS Gateway

Follow these steps to delete a MAAS gateway.

  1. Log in to Palette as a tenant admin.
  1. Navigate to the Main menu and select Tenant Settings > Private Cloud Gateways.
  1. Click the three-dot Menu for the gateway instance you want to delete and choose Delete.

    Palette checks for running tenant clusters associated with the gateway instance and displays an error message if it detects any.

  2. If there are running clusters, delete them and retry deleting the gateway instance.

Resize the MAAS Gateway

You can set up a PCG as a single-node (no HA) or three-node (HA) cluster. You can set up a PCG initially with one node and resize it to three nodes at a later time.

For production environments, we recommend setting up three nodes.


  • Each PCG node requires the following:

    • 4 CPUs
    • 8192 MiB memory
    • 60 GiB storage

Follow these steps to resize a single-node gateway to three nodes.

  1. Log in to Palette as a tenant admin.
  1. Navigate to the Main Menu and select Tenant Settings > Private Cloud Gateways.
  1. Click the three-dot Menu for the gateway instance you want to resize and choose Set number of nodes.
  1. Change the number of nodes to 3.

Two new nodes will be created in the cluster.


You can validate your your PCG has been resized by navigating to the Private Cloud Gateways page. Select the resized gateway instance and click the Nodes tab. You will see two additional nodes being deployed along with their health status. Three nodes in total will be listed.

Next Steps

You can now create tenant clusters in the auto-created cloud account. To get started, check out Create and Manage MAAS Clusters.

You can also create additional cloud accounts if you need them. Refer to Register and Manage MAAS Cloud Accounts.