Skip to main content

Deploy to OpenStack

This guide provides you with the steps to deploy a PCG cluster to an OpenStack environment. Before you begin the installation, carefully review the Prerequisites section.

Prerequisites​

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

    warning

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

The following system requirements must be met to install a PCG in OpenStack:

  • PCG IP address requirements:

    • One IP address for a single-node PCG or three IP addresses for a three-node PCG. 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 can resolve the domain api.spectrocloud.com.

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

  • An Open Stack SSH Key Pair. Refer to the Configure access and security for instances guide to learn how to create an SSH key pair.

  • An OpenStack user account with the required permissions to deploy the PCG. Review the OpenStack Cloud Account Permissions section to learn more about the required permissions.

OpenStack Cloud Account Permissions​

The following permissions are required to deploy a PCG to OpenStack and for Palette to register an OpenStack account.

"volume:attachment_update": "rule:admin_or_owner"
"volume:attachment_delete": "rule:admin_or_owner"
"volume:attachment_complete": "rule:admin_or_owner"
"volume:multiattach_bootable_volume": "rule:admin_or_owner"
"message:get_all": "rule:admin_or_owner"
"message:get": "rule:admin_or_owner"
"message:delete": "rule:admin_or_owner"
"volume:get_snapshot_metadata": "rule:admin_or_owner"
"volume:update_snapshot_metadata": "rule:admin_or_owner"
"volume:delete_snapshot_metadata": "rule:admin_or_owner"
"volume:get_all_snapshots": "rule:admin_or_owner"
"volume_extension:extended_snapshot_attributes": "rule:admin_or_owner"
"volume:create_snapshot": "rule:admin_or_owner"
"volume:get_snapshot": "rule:admin_or_owner"
"volume:update_snapshot": "rule:admin_or_owner"
"volume:delete_snapshot": "rule:admin_or_owner"
"backup:get_all": "rule:admin_or_owner"
"backup:get": "rule:admin_or_owner"
"backup:update": "rule:admin_or_owner"
"backup:delete": "rule:admin_or_owner"
"backup:restore": "rule:admin_or_owner"
"group:get_all": "rule:admin_or_owner"
"group:get": "rule:admin_or_owner"
"group:update": "rule:admin_or_owner"
"group:get_all_group_snapshots": "rule:admin_or_owner"
"group:get_group_snapshot": "rule:admin_or_owner"
"group:delete_group_snapshot": "rule:admin_or_owner"
"group:update_group_snapshot": "rule:admin_or_owner"
"group:reset_group_snapshot_status": "rule:admin_or_owner"
"group:delete": "rule:admin_or_owner"
"group:enable_replication": "rule:admin_or_owner"
"group:disable_replication": "rule:admin_or_owner"
"group:failover_replication": "rule:admin_or_owner"
"group:list_replication_targets": "rule:admin_or_owner"
"volume_extension:quotas:show": "rule:admin_or_owner"
"limits_extension:used_limits": "rule:admin_or_owner"
"volume_extension:volume_type_access": "rule:admin_or_owner"
"volume:extend": "rule:admin_or_owner"
"volume:extend_attached_volume": "rule:admin_or_owner"
"volume:revert_to_snapshot": "rule:admin_or_owner"
"volume:retype": "rule:admin_or_owner"
"volume:update_readonly_flag": "rule:admin_or_owner"
"volume_extension:volume_actions:upload_image": "rule:admin_or_owner"
"volume_extension:volume_actions:initialize_connection": "rule:admin_or_owner"
"volume_extension:volume_actions:terminate_connection": "rule:admin_or_owner"
"volume_extension:volume_actions:roll_detaching": "rule:admin_or_owner"
"volume_extension:volume_actions:reserve": "rule:admin_or_owner"
"volume_extension:volume_actions:unreserve": "rule:admin_or_owner"
"volume_extension:volume_actions:begin_detaching": "rule:admin_or_owner"
"volume_extension:volume_actions:attach": "rule:admin_or_owner"
"volume_extension:volume_actions:detach": "rule:admin_or_owner"
"volume:get_all_transfers": "rule:admin_or_owner"
"volume:create_transfer": "rule:admin_or_owner"
"volume:get_transfer": "rule:admin_or_owner"
"volume:delete_transfer": "rule:admin_or_owner"
"volume:get_volume_metadata": "rule:admin_or_owner"
"volume:create_volume_metadata": "rule:admin_or_owner"
"volume:update_volume_metadata": "rule:admin_or_owner"
"volume:delete_volume_metadata": "rule:admin_or_owner"
"volume_extension:volume_image_metadata": "rule:admin_or_owner"
"volume:get": "rule:admin_or_owner"
"volume:get_all": "rule:admin_or_owner"
"volume:update": "rule:admin_or_owner"
"volume:delete": "rule:admin_or_owner"
"volume_extension:volume_tenant_attribute": "rule:admin_or_owner"
"volume_extension:volume_encryption_metadata": "rule:admin_or_owner"
"volume:multiattach": "rule:admin_or_owner"

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
    ParameterDescription
    Spectro Cloud ConsoleEnter 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 ConnectionBypass 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 KeyEnter your Palette API Key. Refer to the Create API Key guide for more information.
    Spectro Cloud OrganizationSelect your Palette organization name.
    Spectro Cloud ProjectSelect the project you want to register your OpenStack account in.
    AcknowledgeAccept the login banner message. Login banner messages are only displayed if the tenant admin enabled a login banner.
    info

    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
    ParameterDescription
    Management Plane TypeSelect 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 typeFor 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.
    Share PCG Cloud Account across platform ProjectsEnter 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.
    Cloud TypeSelect OpenStack.
    Private Cloud Gateway NameEnter a custom name for the PCG.

  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.

    ParameterDescription
    HTTPS ProxyLeave 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 ProxyLeave 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.
    No ProxyProvide a 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, as well as all tenant clusters using the PCG. Example for a self-hosted environment: my.company.com,10.10.0.0/16.
    Proxy CA Certificate Filepath(Optional) Provide the file path of a CA certificate on the installer host. If provided, this CA certificate will be copied to each PCG node when deploying the PCG cluster, and the provided path will be used on the PCG cluster nodes. Example: /usr/local/share/ca-certificates/ca.crt.

    Note that proxy CA certificates are not automatically propagated to tenant clusters using the PCG; these certificates must be added at either the tenant level or cluster profile level in the OS layer.
    Configure Proxy CA Certificate for Workload Clusters

    If you are configuring proxy CA certificates for your PCG, they must also be added to workload clusters at the tenant level or cluster profile level in the OS layer.

    • If configured at the tenant level, all workload clusters provisioned from the tenant, with the exception of managed Kubernetes clusters (EKS, AKS, and GKE) and Edge clusters, will have the CA certificate injected into their cluster nodes.

    • If configured at the cluster profile level, only workload clusters deployed using the cluster profile will be injected with the CA certificate.


    To configure your proxy CA certificate for your workload clusters, use one of the following methods.

    Take the following approach to propagate your proxy server CA certificate to all workload cluster nodes provisioned from the tenant, with the exception of managed Kubernetes clusters (EKS, AKS, and GKE) and Edge clusters.

    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 Platform, select Certificates.

    4. Select Add A New Certificate.

    5. In the Add Certificate dialog, enter the Certificate Name and Certificate value.

    6. Confirm your changes.

  6. Enter the following network details.

    ParameterDescription
    Pod CIDREnter 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 RangeEnter 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.

    ParameterDescription
    Registry NameAssign a name to the custom registry.
    Registry EndpointEnter the endpoint or IP address for the custom registry. Example: https://palette.example.com or https://10.10.1.0.
    Registry Base Content PathEnter the base content path for the custom registry. Example: spectro-images.
    Configure Registry MirrorCustomize 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 UsernameEnter the username for the custom registry.
    PasswordEnter the password for the custom registry.

  1. Next, provide the OpenStack environment configurations.

    ParameterDescription
    OpenStack Identity EndpointEnter the OpenStack Identity endpoint. Domain or IP address. Example: https://openstack.mycompany.com/identity.
    OpenStack Account UsernameEnter your OpenStack account username.
    OpenStack Account PasswordEnter your OpenStack account password.
    Allow Insecure ConnectionBypass x509 verification. Enter y if you are using an OpenStack instance with self-signed TLS certificates. Otherwise, enter n.
    CA certificate Filepath(Optional) Enter the CA certificate for the OpenStack environment. Provide the file path of the CA certificate on the installer host. Example: /usr/local/share/ca-certificates/ca.crt.
    Default DomainEnter the default domain for the OpenStack environment.
    Default RegionEnter the default region for the OpenStack environment.
    Default ProjectEnter the default project for the OpenStack environment.

    After providing the OpenStack environment configurations and credentials, the Palette CLI will query the OpenStack environment to validate the credentials. If the credentials are valid, the installation process continues; otherwise, you are prompted to re-enter the credentials.

  2. After the OpenStack environment configurations are validated, you are prompted to enter additional OpenStack configuration values.

    ParameterDescription
    DomainSelect the domain you want to target for the PCG deployment. Example: Default.
    RegionSelect a region for the PCG deployment.
    ProjectSpecify an OpenStack project to place the PCG cluster in.
    Placement TypeSelect a Static or Dynamic placement type. For static placement, cluster nodes are placed into existing networks. For dynamic placement, a new network is created.
    Network(Static placement only) Select an existing network.
    Subnet(Static placement only) Select an existing subnet.
    DNS Server(s)(Dynamic placement only) Enter a comma-separated list of DNS server IPs.
    Node CIDR(Dynamic placement only) Enter a node CIDR. Example: 10.55.0.0/24.
    SSH Public KeyProvide the public OpenSSH key for the PCG cluster. Use this key when establishing an SSH connection with the PCG cluster. Your system default text editor, such as Vi, will open and prompt you to enter the SSH key. Save and exit the file when finished.
    Patch OS on bootIndicate whether to patch the OS of the PCG hosts on the first boot.
    Reboot nodes once OS patch is appliedIndicate whether to reboot PCG nodes after OS patches are complete. This applies only if Patch OS on boot is enabled.
    AZsSelect the availability zones for the PCG cluster.
    FlavorSpecify the OpenStack Flavor for the PCG nodes.
    Number of NodesSpecify the number of nodes for the PCG cluster. Available options are 1 or 3. We recommend three nodes for a High Availability (HA) cluster in a production environment.
    Node AffinityEnter y to schedule all Palette pods on the control plane node.

  3. 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 OpenStack 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.

  4. 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 OpenStack cloud account is displayed.

Next Steps​

After you have successfully deployed the PCG into your OpenStack environment, you can deploy Kubernetes clusters in your OpenStack environment through Palette. Check out the Deploying an OpenStack Cluster guide to learn how to deploy a Kubernetes cluster in OpenStack that is managed by Palette.