Skip to main content
Version: latest

Deploy App Workloads with a PCG

Palette Private Cloud Gateway (PCG) is a crucial infrastructure support component that acts as a bridge between your private cloud environment or data center and Palette.

A PCG is required in environments lacking direct network access to Palette. For example, many infrastructure environments reside within private networks that restrict external connections, preventing internal devices and resources from reaching Palette directly.

Upon installation, the PCG initiates a connection from inside the private network to Palette, serving as an endpoint for Palette to communicate with the infrastructure environment. The PCG continuously polls Palette for instructions to either deploy or delete Kubernetes clusters within the environment. This connection uses a secure communication channel that is encrypted using the Transport Layer Security (TLS) protocol. Once a cluster is deployed, the PCG is no longer involved in the communication between Palette and the deployed cluster. The cluster then communicates directly with Palette through the Palette agent available within each cluster, which originates all network requests outbound toward Palette. Refer to the PCG Architecture section for more information.

A PCG comprises a cluster of nodes and can be deployed using two methods. The first method uses the Palette CLI to deploy a PCG in one of the three supported infrastructure environments; MAAS, OpenStack, or VMware vSphere. The other method manually deploys a PCG onto an existing Kubernetes cluster.

In this tutorial, you will deploy a VMware PCG using Palette CLI. Next, you will learn how to deploy a VMware cluster with a sample Kubernetes application called Hello Universe, utilizing either the Palette dashboard or Terraform.

The following diagram illustrates the components that will be deployed in this tutorial and how they communicate with each other.

An architecture diagram of PCG

Prerequisites

To complete this tutorial, you will need the following prerequisites in place.

  • A Palette account with tenant admin access.

  • A Palette API key. Refer to the Create API Key page for instructions on how to create an API key.

  • A VMware vSphere user account with the required permissions.

  • A Linux x86-64 machine with access to a terminal and Internet, as well as connection to both Palette and VMware vSphere.

  • An SSH key pair. Use the Create and Upload an SSH Key guide to learn how to create an SSH key and upload it to Palette.

  • The following IP address requirements must be met in your VMware vSphere environment:

    • One IP address available for the single-node PCG deployment. Refer to the PCG Sizing section for more information on sizing.
    • One IP address reserved for cluster repave operations.
    • One IP address for the Virtual IP (VIP).
    • DNS must be able to resolve the domain api.spectrocloud.com.
    • NTP server must be reachable from the PCG.
  • The following minimum resources must be available in your VMware vSphere environment:

    • CPU: 4 cores.
    • Memory: 4 GiB.
    • Storage: 60 GiB.

    info

    In production environments, we recommend deploying a three-node PCG, each node with 8 cores of CPU, 8 GiB of memory, and 100 GiB of storage.

  • Ensure the following software is installed and available on your Linux machine.

Authenticate with Palette

The initial step to deploy a PCG using Palette CLI involves authenticating with your Palette environment using the palette login command.

In your terminal, execute the following command.

palette login

Once issued, you will be prompted for several parameters to complete the authentication. The table below outlines the required parameters along with the values that will be utilized in this tutorial. If a parameter is specific to your environment and Palette account, such as your Palette API key, ensure to input the value according to your environment. Check out the Deploy a PCG to VMware vSphere guide for more information. option.

ParameterValueEnvironment-Specific
Spectro Cloud Consolehttps://console.spectrocloud.com. If using a self-hosted instance of Palette, enter the URL for that instance.No
Allow Insecure ConnectionY. Enabling this option bypasses x509 CA verification. In production environments, enter Y if you are using a self-hosted Palette or VerteX instance with self-signed TLS certificates and need to provide a file path to the instance CA. Otherwise, enter N.No
Spectro Cloud API KeyEnter your Palette API Key.Yes
Spectro Cloud OrganizationSelect your Palette Organization name.Yes
Spectro Cloud ProjectNone (TenantAdmin)No
AcknowledgeAccept the login banner message. Login banner messages are only displayed if the tenant admin enabled a login banner.Yes

After accepting the login banner message, you will receive the following output confirming you have successfully authenticated with Palette.

Welcome to Spectro Cloud Palette

The video below demonstrates Palette's authentication process. Ensure you utilize values specific to your environment, such as the correct Palette URL. Contact your Palette administrator for the correct URL if you use a self-hosted Palette or VerteX instance.

Deploy a PCG with Palette CLI

After authenticating with Palette, you can proceed with the PCG creation process. Issue the command below to start the PCG installation.

palette pcg install

The palette pcg install command will prompt you for information regarding your PCG cluster, vSphere environment, and resource configurations. The following tables display the required parameters along with the values that will be used in this tutorial. Enter the provided values when prompted. If a parameter is specific to your environment, such as your vSphere endpoint, enter the corresponding value according to your environment. For detailed information about each parameter, refer to the Deploy a PCG to VMware vSphere guide.

info

The PCG to be deployed in this tutorial is intended for educational purposes only and is not recommended for production environments.

  1. PCG General Information

    Configure the PCG general information, including the Cloud Type and Private Cloud Gateway Name, as shown in the table below.

    ParameterValueEnvironment-Specific
    Management Plane TypePaletteNo
    Enable Ubuntu Pro (required for production)NNo
    Select an image registry typeDefaultNo
    Cloud TypeVMware vSphereNo
    Private Cloud Gateway Namegateway-tutorialNo
    Share PCG Cloud Account across platform ProjectsYNo
  2. Environment Configuration

    Enter the environment configuration information, such as the Pod CIDR and Service IP Range according to the table below.

    ParameterValueEnvironment-Specific
    HTTPS ProxySkip.No
    HTTP ProxySkip.No
    Pod CIDR172.16.0.0/20. The pod IP addresses should be unique and not overlap with any machine IPs in the environment.No
    Service IP Range10.155.0.0/24. The service IP addresses should be unique and not overlap with any machine IPs in the environment.No
  3. vSphere Account Information

    Enter the information specific to your vSphere account.

    ParameterValueEnvironment-Specific
    vSphere EndpointYour vSphere endpoint. You can specify a Full Qualified Domain Name (FQDN) or an IP address. Make sure you specify the endpoint without the HTTP scheme https:// or http://. Example: vcenter.mycompany.com.Yes
    vSphere UsernameYour vSphere account username.Yes
    vSphere PasswordYour vSphere account password.Yes
    Allow Insecure Connection (Bypass x509 Verification)Y. Enabling this option bypasses x509 CA verification. In production environments, enter N if using a custom registry with self-signed SSL certificates. Otherwise, enter Y.No
  4. vSphere Cluster Configuration

    Enter the PCG cluster configuration information. For example, specify the vSphere Resource Pool to be targeted by the PCG cluster.

    ParameterValueEnvironment-Specific
    DatacenterThe vSphere data center to target when deploying the PCG cluster.Yes
    FolderThe vSphere folder to target when deploying the PCG cluster.Yes
    NetworkThe port group to which the PCG cluster will be connected.Yes
    Resource PoolThe vSphere resource pool to target when deploying the PCG cluster.Yes
    ClusterThe vSphere compute cluster to use for the PCG deployment.Yes
    Select specific Datastore or use a VM Storage PolicyDatastoreNo
    DatastoreThe vSphere datastore to use for the PCG deployment.Yes
    Add another Fault DomainNNo
    NTP ServersSkip.No
    SSH Public KeysProvide a public OpenSSH key to be used to connect to the PCG cluster.Yes
  5. PCG Cluster Size

    This tutorial will deploy a one-node PCG with dynamic IP placement (DDNS). If needed, you can convert a single-node PCG to a multi-node PCG to provide additional capacity. Refer to the Increase PCG Node Count guide for more information.

    ParameterValueEnvironment-Specific
    Number of Nodes1No
    Placement TypeDDNSNo
    Search domainsComma-separated list of DNS search domains. For example, spectrocloud.dev.Yes
  6. Cluster Settings

    Set the parameter Patch OS on boot to N, meaning the OS of the PCG hosts will not be patched on the first boot.

    ParameterValueEnvironment-Specific
    Patch OS on bootNNo
  7. vSphere Machine Configuration

    Set the size of the PCG as small (S) as this PCG will not be used in production environments.

    ParameterValueEnvironment-Specific
    S4 CPU, 4 GB of Memory, and 60 GB of StorageNo
  8. Node Affinity Configuration Information

    Set Node Affinity to N, indicating no affinity between Palette pods and control plane nodes.

    ParameterValueEnvironment-Specific
    Node AffinityNNo

After answering the prompts of the pcg install command, a new PCG configuration file is generated, and its location is displayed on the console.

==== PCG config saved ==== Location: /home/ubuntu/.palette/pcg/pcg-20240313152521/pcg.yaml

Next, Palette CLI will create a local kind cluster that will be used to bootstrap the PCG cluster deployment in your VMware environment. Once installed, the PCG registers itself with Palette and creates a VMware cloud account with the same name as the PCG.

The following recording demonstrates the pcg install command with the --config-only flag. When using this flag, a reusable configuration file named pcg.yaml is created under the path .palette/pcg. You can then utilize this file to install a PCG with predefined values using the command pcg install with the --config-file flag. Refer to the Palette CLI PCG Command page for further information about the command.



You can monitor the PCG cluster creation by logging into Palette and switching to the Tenant Admin scope. Next, click on Tenant Settings from the left Main Menu and select Private Cloud Gateways. Then, click on the PCG cluster you just created and check the deployment progress under the Events tab.

PCG Events page.

You can also track the PCG deployment progress from your terminal. Depending on the PCG size and infrastructure environment, the deployment might take up to 30 minutes. Upon completion, the local kind cluster is automatically deleted from your machine.

tip

To avoid potential vulnerabilities, once the installation is complete, remove the kind images that were installed in the environment where you initiated the installation.

Remove kind Images

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

docker images
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.

docker image rm kindest/node:<version>

Consider the following example for reference.

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

Palette CLI PCG deployment

Next, log in to Palette as a tenant admin. Navigate to the left Main Menu and select Tenant Settings. Click on Private Cloud Gateways from the Tenant Settings Menu and select the PCG you just created. Ensure that the PCG cluster status is Running and Healthy before proceeding.

PCG Overview page.

Create a Cluster Profile and Deploy a Cluster

Once you have successfully deployed the PCG, proceed to create a cluster profile with the Hello Universe application and use it to deploy a VMware cluster. You can use the Palette dashboard or Terraform.

Create a Cluster Profile

Log in to Palette and select Profiles from the left Main Menu to access the cluster profile page. Click on the Add Cluster Profile button and follow the wizard to create a new cluster profile.

Basic Information

Complete the Basic Information section with the values provided below.

FieldValue
Namepcg-tutorial-profile
Version1.0.0
DescriptionCluster profile as part of the Deploy App Workloads with a PCG tutorial.
TypeFull
Tagsspectro-cloud-education, app:hello-universe, terraform_managed:false, repository:spectrocloud:tutorials, tutorial:DEPLOY_APP_WORKLOADS_WITH_A_PCG

Click on Next to continue.

Cloud Type

In the Cloud Type section, select VMware as the infrastructure provider, then click Next to proceed.

Profile Layers

Add the following core infrastructure layers displayed to your profile.

Pack NameVersionLayer
ubuntu-vsphere LTS22.4.xOperating System
kubernetes1.28.xKubernetes
cni-calico3.26.xNetwork
csi-vsphere-csi3.0.xStorage

After adding each layer, click on the Next Layer button. Once the storage layer is added, click Confirm to complete the core infrastructure stack.

Next, click on the Add New Pack button to include add-on layers to your cluster profile.

Add the MetalLB (Helm) pack to your profile. The MetalLB pack provides a load-balancer implementation for your Kubernetes cluster, as VMware does not offer a load balancer solution natively. The load balancer is required to help the LoadBalancer service specified in the Hello Universe application manifest obtain an IP address, so that you can access the application from your browser.

Pack NameVersionLayer
lb-metallb-helm0.13.xLoad Balancer

Now, under Pack Details, click on Values and replace the predefined 192.168.10.0/24 IP CIDR listed below the addresses line with a valid IP address or IP range from your VMware environment to be assigned to your load balancer. Next, click Confirm & Create to add the MetalLB pack.

Metallb Helm-based pack.

Finally, click again on the Add New Pack button to add the Hello Universe pack.

Pack NameVersionLayer
hello-universe1.1.xApp Service

Click on the Confirm & Create button and then click Next.

Review

Review the selected cluster layers and configurations. Click on Finish Configuration to complete the cluster profile creation.

Cluster profile review page.

Deploy a VMware Cluster

Navigate to the left Main Menu and select Profiles. Locate and click on the cluster profile you previously created. Next, click on the Deploy button and confirm by clicking OK to start the cluster deployment using the selected cluster profile.

Cluster profile page.

Basic Information

Ensure the following values are set for the Basic Information section.

FieldValue
Cluster namepcg-tutorial-cluster
DescriptionCluster as part of the Deploy App Workloads with a PCG tutorial.
Tagsspectro-cloud-education, app:hello-universe, terraform_managed:false, repository:spectrocloud:tutorials, tutorial:DEPLOY_APP_WORKLOADS_WITH_A_PCG
Type of clusterDatacenter
Cloud AccountSelect the VMware cloud account that was registered with Palette during the PCG creation. The cloud account has the same name as the PCG. In this tutorial, the cloud account is called gateway-tutorial.

Parameters

The Parameters section displays all the layers in the cluster profile and allows you to modify profile configurations if needed. Proceed by clicking Next.

Cluster Configuration

In the Cluster Config section, provide specific information about your VMware vSphere environment. First, select the Datacenter and Deployment Folder where the cluster nodes will be launched. Next, select the Image Template Folder to which the Spectro templates are imported, and choose DHCP as the Network Type. Finally, provide the SSH key for accessing the cluster nodes. Proceed by clicking Next to advance to the Nodes Configuration section.

Nodes Configuration

Provide the details for the nodes of the control plane and worker pools.

FieldControl Plane PoolWorker Pool
Node pool namecontrol-plane-poolworker-pool
Number of nodes in the pool11
Allow worker capabilityNoNot applicable
Enable AutoscalerNot applicableNo
Rolling updateNot applicableExpand First

Keep the Cloud Configuration settings the same for both pools, with CPU set to 4 cores, memory allocated at 8 GB, and disk space at 60 GB. Next, populate the Compute cluster, Resource Pool, Datastore, and Network fields according to your VMware vSphere environment. Click Next to proceed.

Settings

The Settings section offers advanced options for OS patching, scheduled scans, scheduled backups, and cluster role binding. Utilize the default values, and click on the Validate button.

Review

The Review section allows you to review the cluster configuration before deploying the cluster. Click on Finish Configuration to start the cluster deployment, which may take up to 20 minutes.

Cluster review page.

Now, navigate to the left Main Menu and click on Clusters. While the deployment is in progress, Palette displays the cluster status as Provisioning. You can view detailed cluster information, including deployment status and event logs, by selecting your cluster.

Palette&#39;s Clusters page.

Validate

Once the cluster creation process has finished, log in to Palette, navigate to the left Main Menu, and click on Clusters. Select the pcg-tutorial-cluster to display the cluster's Overview page. Once the cluster status displays Running and Healthy, you can access the application through the exposed service URL along with the displayed port number.

Healthy VMware cluster

Click on the URL for port :8080 to access the Hello Universe application landing page.

Hello Universe application

Once you have completed the steps and accessed the application, you have successfully deployed your first application to a VMware cluster managed by Palette.

Clean Up

The following steps will guide you to clean up your environment after completing the tutorial. Follow the steps below to delete the PCG, the cluster profile, and the VMware cluster.

Delete the Cluster Profile and Cluster

In Palette, navigate to the left Main Menu, click on Clusters and select the pcg-tutorial-cluster to access its details page. Next, click on the Settings button to expand the drop-down Menu, then select the Delete Cluster. Confirm the deletion by entering the cluster name when prompted.

Delete Palette cluster

The cluster status will change to Deleting, and the deletion process may take up to 15 minutes.

Once the cluster is deleted, proceed to delete the cluster profile. On the left Main Menu, click on Profiles, and select the profile pcg-tutorial-profile. Next, click on the three-dot Menu, select Delete, and confirm the selection to remove the cluster profile.

Delete the PCG

After deleting your VMware cluster and cluster profile, proceed with the PCG deletion. Log in to Palette as a tenant admin, navigate to the left Main Menu and select Tenant Settings. Next, from the Tenant Settings Menu, click on Private Cloud Gateways. Identify the PCG you want to delete, click on the Three-Dot Menu at the end of the PCG row, and select Delete. Click OK to confirm the PCG deletion.

Delete PCG image

Palette will delete the PCG and the Palette services deployed on the PCG node. However, the underlying infrastructure resources, such as the virtual machine, must be removed manually from VMware vSphere.

Log in to your VMware vSphere server and select the VM representing the PCG node named gateway-tutorial-cp. Click on the Three-Dot Actions button, select Power, and Power Off to power off the machine. Once the machine is powered off, click on the Three-Dot Actions button again and select Delete from Disk to remove the machine from your VMware vSphere environment.

Delete VMware VM

Wrap-Up

In this tutorial, you learned how to deploy a VMware PCG using the Palette CLI. Then, you used the PCG to support the deployment of a Kubernetes cluster with a sample application to your VMware vSphere environment. Next, you accessed the Hello Universe application landing page through the exposed service URL.

A PCG is a powerful component that enables Palette to communicate with private clouds or data center environments residing in restricted networks that don't allow inbound connections from external sources. The PCG acts as an endpoint and continuously polls Palette for instructions. With a PCG, you can deploy Palette clusters and support their lifecycle in environments like VMware vSphere without the need to configure complex firewall rules or expose public endpoints.

We encourage you to check out the reference resources below to learn more about PCGs.