Deploy to CloudStack

tech preview

This is a Tech Preview feature and is subject to change. Do not use this feature in production workloads. This feature is supported in self-hosted Palette only.

This guide provides you with the steps to deploy a Palette Cloud Gateway (PCG) cluster to an Apache CloudStack environment using KVM as the hypervisor. Before you begin the installation, carefully review the Prerequisites section.

Prerequisites

• The ApacheCloudStack feature flag is enabled.

• A Palette API key. Refer to the Create API Key page for guidance.

  warning

  The installation does not support 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 deactivate the account if desired.

• Download and install the Palette CLI from the Downloads page. Refer to the Palette CLI Install guide to learn more.

  • You will need to provide the Palette CLI an encryption passphrase to secure sensitive data. The passphrase must be between 8 to 32 characters long and contain a capital letter, a lowercase letter, a digit, and a special character. Refer to the Palette CLI Encryption section for more information.

• PCG IP address requirements:

  • For a single-node deployment, one IP address must be available for the PCG, or three available IP addresses for a three-node deployment. Refer to the PCG Sizing section for more information on sizing.
  • For three-node deployments, one IP address must be available for the Kubernetes API-server endpoint.
  • One IP address reserved for cluster repave operations.
  • One IP address for the Virtual IP (VIP).
  • DNS can resolve the domain api.spectrocloud.com.

• The PCG nodes must be deployed on an x86 Linux environment with a Docker daemon installed and a connection to Palette and the CloudStack endpoint. The Palette CLI installation must be invoked on an up-to-date Linux system with the x86-64 architecture.

• The CloudStack environment must have the following resources available:

  • A CloudStack project to host the PCG cluster.
  • A CloudStack zone to deploy the PCG cluster into.
  • A CloudStack network within the zone to host the PCG cluster.
  • A CloudStack service offering to define the compute resources for the PCG nodes. Refer to the PCG Sizing section for more information on sizing.

• A CloudStack user account with the required permissions to deploy the PCG in the CloudStack environment. Review Required Permissions to learn more about the required permissions.

  • A CloudStack API key and Secret key for the user account used to deploy the PCG. Refer to the Using API Key and Secret Key based Authentication guide about API and Secret keys.

• CloudStack SSH keys generated and available to the user account used to deploy the PCG. Refer to the Using SSH Keys for Authentication guide to learn how to create an SSH key pair.

• The CloudStack API endpoint URL. For example, https://cloudstack.example.com:8443/client/api or https://management-server-ip:8080/client/api.

• DNS must be able to resolve api.spectrocloud.com when using SaaS PCG.

• A CloudStack template imported.

  Importing a template

  In CloudStack console, navigate to Images. Select Templates and click on Register Template from URL.

  Provide values for the fields below.

  Field	Description
  URL	Provide the following image template URL. The URL must end with qcow2 when using KVM as the hypervisor.
  Name	Must follow the format u-2404-0-k-13210-0.
  Description	Optional.
  Zone	Specify the zone from the dropdown.
  Domain	Specify the domain from the dropdown.
  Hypervisor	Select KVM from the dropdown.
  Format	Select QCOW2 from the dropdown.
  OS type	Select Ubuntu 24.04 (64-bit) from the dropdown.
  Template type	Select USER from the dropdown.
  Extractable	Leave default.
  Dynamically scalable	Leave default.
  Public	Select the checkbox.
  Password enabled	Leave default.
  HVM	Leave default.

  Click OK.

  Note: Image name must follow the required format, must be set Public, and only one template with that name may exist per user. Duplicate names can cause CloudStack functional issues and deployment failures.

  For example, user A imports an image named u-2404-0-k-13210-0 and sets it to Public availability. User B creates another template with the same name but does not mark it Public. User A will have one template named u-2404-0-k-13210-0 and user B will have two templates named u-2404-0-k-13210-0. When user B deploys a cluster using u-2404-0-k-13210-0, the deployment will fail with a duplicate template error: Reconciler error: expected 1 Template with name u-2404-0-k-13210-0, but got 2.

Deploy PCG

1. On your Linux host with the Palette CLI installed, open a terminal session.

2. Create a Palette CLI encryption passphrase and set it as an environment variable. Replace <palette-cli-encryption-passphrase> with your passphrase.

   export PALETTE_ENCRYPTION_PASSWORD=<palette-cli-encryption-passphrase>

3. Issue the following command to authenticate your Palette CLI installation with Palette. When prompted, enter the required information. Refer to the table below for information about each parameter.

   palette login

   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	Bypass x509 server Certificate Authority (CA) verification. Enter y if you are using a self-hosted Palette or Palette VerteX instance with self-signed TLS certificates and need to provide a file path to the instance CA. Otherwise, enter n.
   Spectro Cloud API Key	Enter your Palette API Key. Refer to the Create API Key guide for more information.
   Spectro Cloud Organization	Select your Palette organization name.
   Spectro Cloud Project	Select the Palette project you want to register your account in.
   Acknowledge	Accept the login banner message. Login banner messages are only displayed if the tenant admin enabled a login banner.

   info

   After completing the palette pcg install steps, the configuration details are saved to a file named pcg.yaml in the ~/.palette/pcg/pcg-<date-time> directory. The CloudAccount.apiKey and Mgmt.apiKey values in the pcg.yaml file are encrypted and cannot be manually updated. To change these values, use the palette pcg install --update-passwords command. Refer to the

   PCG command reference page for more information.

4. Once you have authenticated your Palette CLI installation, start the PCG installer by issuing the following command. Refer to the table below for information about each parameter.

   palette pcg install

   Parameter	Description
   Management Plane Type	Select Palette or VerteX.
   Enable Ubuntu Pro (required for production)	Enter y if you want to use Ubuntu Pro and provide an Ubuntu Pro token. Otherwise, enter n.
   Select an image registry type	For a non-airgap installation, choose Default to pull images from public image registries. This requires an internet connection. For airgapped installations, select Custom and point to your airgap support VM or a custom internal registry that contains the required images.
   Cloud Type	Select CloudStack.
   Private Cloud Gateway Name	Enter a custom name for the PCG.
   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.

5. If you want to configure your PCG to use a proxy network, complete the following fields, as appropriate.

   info

   By default, proxy environment variables (HTTPS_PROXY, HTTP_PROXY, and NO_PROXY) configured during PCG installation are propagated to all PCG cluster nodes, as well as the nodes of all tenant workload clusters deployed with the PCG. However, proxy CA certificates are only propagated to PCG cluster nodes; they are not propagated the nodes of tenant workload clusters.

   Parameter	Description
   HTTPS Proxy	Leave this blank unless you are using an HTTPS Proxy. This setting will be propagated to all PCG nodes in the cluster, as well as all tenant clusters using the PCG. 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 in the cluster, as well as all tenant clusters using the PCG. Example: http://USERNAME:PASSWORD@PROXYIP:PROXYPORT.

6. Enter the following network details.

   Parameter	Description
   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.

7. If you selected Custom for the image registry type, you are prompted to provide the following information.

   Parameter	Description
   Registry Name	Assign a name to the custom registry.
   Registry Endpoint	Enter the endpoint or IP address for the custom registry. Example: https://palette.example.com or https://10.10.1.0.
   Registry Base Content Path	Enter the base content path for the custom registry. Example: spectro-images.
   Configure Registry Mirror	Customize the default mirror registry settings. Your system default text editor, such as Vi, will open and allow you to make any desired changes. When finished, save and exit the file.
   Allow Insecure Connection (Bypass x509 Verification)	Bypass x509 CA verification. Enter n if using a custom registry with self-signed SSL certificates. Otherwise, enter y. If you enter y, you receive a follow-up prompt asking you to provide the file path to the CA certificate.
   Registry CA certificate Filepath	(Optional) Enter the CA certificate for the custom registry. Provide the file path of the CA certificate on the installer host. Example: /usr/local/share/ca-certificates/ca.crt.
   Registry Username	Enter the username for the custom registry.
   Password	Enter the password for the custom registry.

8. Provide the CloudStack account information when prompted by the Palette CLI.

   Field	Description
   CloudStack URL	Enter the CloudStack API endpoint URL. For example, https://cloudstack.example.com:8443/client/api or https://management-server-ip:8080/client/api.
   CloudStack ApiKey	Enter the CloudStack API key for the user account that has permissions to deploy the PCG.
   CloudStack SecretKey	Enter the CloudStack Secret key for the user account that has permissions to deploy the PCG.
   CloudStack Domain (optional)	If applicable, enter the CloudStack domain name for the user account that has permissions to deploy the PCG. Otherwise, leave blank.

9. Provide the CloudStack cluster configuration information when prompted by the Palette CLI.

Parameter	Description
Project	Enter the name of the CloudStack project to deploy the PCG into.
Zone	Enter the name of the CloudStack zone to deploy the PCG into.
Network	Enter the name of the CloudStack network to host the PCG cluster.
SSH KeyPair	Enter the name of the CloudStack service offering that defines the compute resources for the PCG nodes. Refer to the PCG Sizing section for more information on sizing.
Sync with CKS(CloudStack Kubernetes Service)	Enter y to synchronize the PCG with CloudStack Kubernetes Service (CKS) if it is available in your CloudStack environment. Enter n if CKS is not available or you do not want to synchronize with it.
Static Control Plane IP Address (optional)	Enter the static IP address for the control plane node of the PCG if you want to assign a fixed IP. Otherwise, leave blank.
Patch OS on boot	Enter y to enable automatic OS patching when the PCG nodes boot. Enter n to disable automatic OS patching.
Offering	Select the CloudStack service offering that defines the compute resources for the PCG nodes. Refer to the PCG Sizing section for more information on sizing.
Disk Offering	Select the CloudStack disk service offering that defines the disk resources for the PCG nodes. Refer to the PCG Sizing section for more information on sizing. This option will be available based on the Compute Offering template selected, and available Disk offerings in CloudStack.

10. Provide the PCG cluster size information when prompted by the Palette CLI.

    Parameter	Description
    Number of nodes	Select 1 for a single-node deployment or 3 for a high-availability (HA) deployment.
    Enable control plane node affinity?	Enter y to enable control plane node affinity or n to disable it. If enabled, all Palette related pods (those in the cluster-<uid> namespace) will be deployed to control plane nodes only on all workload clusters created through this PCG.

11. A new PCG configuration file is generated, and its location is displayed on the console.

    Example output

    ==== PCG config saved ====
    Location: :/home/demo/.palette/pcg/pcg-20230706150945/pcg.yaml

    The Palette CLI begins provisioning a PCG cluster in your CloudStack environment. Take the following steps to monitor the progress of the PCG deployment.

    1. Log in to Palette as a tenant admin.

    2. From the left main menu, select Tenant Settings.

    3. From the Tenant Settings Menu, below Infrastructure, select Private Cloud Gateways.

    4. Select the PCG cluster being deployed. Use the Events tab to monitor the deployment progress of your PCG cluster.

    If you encounter issues during the installation, refer to our PCG Troubleshooting guide. For additional assistance, reach out to our Customer Support team.

    warning

    You cannot modify a deployed PCG cluster. If you need to make changes to your PCG cluster, you must delete the existing PCG cluster and redeploy it with your updated configurations. For this reason, we recommend you save your PCG configuration file for future use. Use the Palette CLI --config-only flag to save the PCG configuration file without deploying the PCG cluster. Refer to our Generate a Configuration File guide.

12. To avoid potential vulnerabilities, once your PCG cluster is deployed, remove the kind images that were installed in the environment where you initiated the installation.

    Issue the following command to list all instances of kind that exist in the environment.

    docker images
    Example output

    REPOSITORY     TAG        IMAGE ID       CREATED        SIZE
    kindest/node   v1.26.13   131ad18222cc   5 months ago   910MB

    Then, use the following command template to remove all instances of kind. Replace <tag> with your kind image tag.

    docker image rm kindest/node:<tag>

    Consider the following example for reference.

    Example command

    docker image rm kindest/node:v1.26.13
    Example output

    Untagged: kindest/node:v1.26.13
    Untagged: kindest/node@sha256:15ae92d507b7d4aec6e8920d358fc63d3b980493db191d7327541fbaaed1f789
    Deleted: sha256:131ad18222ccb05561b73e86bb09ac3cd6475bb6c36a7f14501067cba2eec785
    Deleted: sha256:85a1a4dfc468cfeca99e359b74231e47aedb007a206d0e2cae2f8290e7290cfd

Validate

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

1. Log in to Palette as a tenant admin.

2. From the left main menu, select Tenant Settings.

3. From the Tenant Settings Menu, below Infrastructure, select Private Cloud Gateways.

4. Verify your PCG cluster is displayed and that it has a green check mark for its Health.

5. Next, from the Tenant Settings Menu, below Infrastructure, select Cloud Accounts.

6. Verify a new CloudStack cloud account is displayed.

Next Steps

Learn how to create and manage CloudStack clusters using the deployed PCG by following the steps in the Create and Manage CloudStack Clusters guide.