Skip to main content

Export Cluster Definition

You can export cluster definitions from a cluster in Palette and use the definition to provision or update a cluster in an Edge host. A cluster definition contains one or more cluster profiles, including the profile variables used in the profiles.

info

If you create a new cluster or update an existing one with a cluster definition and content bundle built on a Palette instance, your Palette agent will be updated to match the version of that Palette instance. This may result in an upgrade if the instance is newer than your Palette agent, or a downgrade if it is older.

You can export the cluster definition using the Palette CLI, Palette Edge CLI, or Palette API. The CLI offers a more user-friendly interface but requires a machine with X86_64 architecture. If you are using an ARM64 machine, such as Apple Silicon, use the API approach instead.

Export Cluster Definition Using the CLI​

You can export cluster definitions using either the Palette and Palette Edge CLI. This approach also allows you to create a content bundle at the same time with a single command.

Limitations​

  • If your cluster uses the legacy Harbor Edge-Native Config pack, you cannot use the Palette CLI to build content bundles or export cluster definitions. You must use the Palette Edge CLI.

    Refer to Migrate From Harbor Edge-Native Config Pack to learn how to migrate off the legacy pack to Registry Connect pack.

Prerequisites​

  • At least one cluster profile in Palette.

  • A Palette API key. For more information on how to create a Palette API key, refer to Create API Key.

  • A physical or virtual Linux machine with AMD64 (also known as x86_64) processor architecture. You can issue the following command in the terminal to check your processor architecture.

    uname -m

Enablement​

  1. Download the Palette CLI. Refer to the Palette CLI Compatibility Matrix to find a compatible CLI version and replace <palette-cli-version> with the selected version.

    VERSION=<palette-cli-version>
    wget https://software.spectrocloud.com/palette-cli/v$VERSION/linux/cli/palette
    chmod +x palette

  2. Use the following command to move the palette binary to the /usr/local/bin directory to make the binary available in your system $PATH. This will allow you to issue the palette command from any directory in your development environment.

    mv palette /usr/local/bin

  3. Verify that the Palette CLI is part of your system path by issuing the Palette CLI version command.

    palette version
    Palette CLI version: [version number]

  4. Authenticate with Palette using the login command. Replace <your-api-key> with your Palette API key.

    palette login --api-key <your-api-key> --console-url https://console.spectrocloud.com/

  5. Log in to the Palette console.

  6. Select the project you want to deploy the Edge host to.

  7. On the Project Overview page, copy the Project ID, located in the top-right below the User Menu.

    tip

    You can also retrieve your project ID from the URL: https://console.spectrocloud.com/projects/<project-id>.

  8. Navigate to the left main menu and select Profiles.

  9. Use the Cloud Types drop-down menu and select Edge Native.

  10. Select the cluster profile you want to include in the cluster definition and copy the Profile ID. Repeat this step for all cluster profiles whose images you want to include in the cluster definition.

    Copying cluster profile ID

    tip

    You can also retrieve the cluster profile ID from the URL: https://console.spectrocloud.com/projects/<project-id>/profiles/cluster/<profile-id>.

    Make sure the combination of profiles you choose to export can be used to provision a cluster together. This means that you cannot include more than one profile that has infrastructure layers and cannot have duplicate packs between the profiles.

  11. Issue the following command to export the cluster definition, replacing the placeholder values with your actual values. The build command will generate the .tgz cluster definition file in the <current-directory>/output/ folder by default. Refer to the content build CLI command page for a complete list of available flags.

    palette content build --arch <bundle-architecture> \
    --project-id <project-id> \
    --cluster-definition-name <definition-name> \
    --cluster-definition-profile-ids <cluster-profile-id1,cluster-profile-id2...>

  12. (Optional) You can also build a content bundle along with your cluster definition in a single command by adding the profiles and name flags to the command. By default, the content bundle will be generated in the <current-directory>/output/content-bundle/ folder. Content bundles are archives of all the container images required for one or more cluster profiles. You can upload a content bundle to your Edge host through Local UI or the Palette CLI, and use the resources in the content bundle to provision clusters without a connection to external networks. For more information, refer to Build Content Bundles.

    palette content build --arch <bundle-architecture> \
    --project-id <project-id> \
    --profiles <cluster-profile-id1,cluster-profile-id2...> \
    --cluster-definition-name <cluster-definition-name> \
    --cluster-definition-profile-ids <cluster-definition-profile-ids> \
    --name <bundle-name>

Validate​

  1. Log in to Local UI.

  2. From the left main menu, click on Cluster.

  3. Try creating a cluster with the exported cluster definition. For more information, refer to Create a Local Cluster.

  4. A successful cluster definition export will display the correct profile layers from the cluster creation view.

Export Cluster Definition with Palette API​

If you do not have an AMD64 machine, or you do not want to download and use the Palette Edge CLI, you can still export cluster definitions using the Palette API.

Prerequisites​

  • At least one cluster profile in Palette.

  • A Palette API key. For more information on how to create a Palette API key, refer to Create API Key.

  • curl is installed on your machine. You can also use API management tools such as Postman. This document uses curl as an example.

Enablement​

  1. Log in to Palette.

  2. Select the project you want to deploy the Edge host to.

  3. On the Project Overview page, copy the Project ID, located in the top-right below the User Menu.

    tip

    You can also retrieve your project ID from the URL: https://console.spectrocloud.com/projects/<project-id>.

  4. From the left main menu, select Profiles.

  5. Select the cluster profile you want to include in the cluster definition and copy the Profile ID. Repeat this step for all cluster profiles whose images you want to include in the cluster definition.

    Copying cluster profile ID

    tip

    You can also retrieve the cluster profile ID from the URL: https://console.spectrocloud.com/projects/<project-id>/profiles/cluster/<profile-id>.

    All profiles must be in the same project. Make sure the selected profiles can be used together to provision a cluster. Only one profile may include infrastructure layers, and no packs can be duplicated across the profiles.

  6. Use the Palette Download Cluster Definition API to download the cluster definition. The endpoint location is POST https://api.spectrocloud.com/v1/spectroclusters/spc/download. If you are using a self-hosted Palette instance, replace the base URL api.spectrocloud.com with API endpoint address of your Palette instance.

    The endpoint takes a few header arguments and a request body.

    Header ParameterDescription
    ProjectUidThe unique ID of the project where the profiles are located.
    Content-TypeYou must set the value of this header to application/json to indicate that your payload is in the JSON format.
    ApiKeyThe value of your Palette API key.

    In the request body, you must provide the ID of the cluster profiles to include in the cluster definition.

    ParameterDescription
    metadataYou must set the value of this field to {"name":"cluster-profiles"}.
    spec.cloudTypeYou must set the value of this field to edge-native.
    spec.profilesProvide the exact list of cluster profiles to include in the cluster definition. Inside the list are objects representing the cluster profiles. Each object must have the required key uid, which is the ID of the cluster profile.

    The following curl command is an example.

    curl --location 'https://api.spectrocloud.com/v1/spectroclusters/spc/download' \
    --header 'ProjectUid: 5fbbf0XXXXX' \
    --header 'Content-Type: application/json' \
    --header 'ApiKey: XXXXXXXX' \
    --output ~/Downloads/demo/cluster-definition.tgz \
    --data-raw '{
    "metadata": { "name": "cluster-profiles" },
    "spec":
        {
            "cloudType": "edge-native",
            "profiles":
                [
                    {
                        "uid": "65c90XXXXX770dae35"
                    },
                    {
                        "uid": "65c91XXXXa9fe4f51c"
                    }
                ]
        }
    }'

Validate​

  1. Log in to Local UI.

  2. From the left main menu, click on Cluster.

  3. Try creating a cluster with the exported cluster definition. For more information, refer to Create a Local Cluster.

  4. A successful cluster definition export will display the correct profile layers from the cluster creation view.

Next Steps​

You can build the cluster definition into the Edge Installer ISO, or upload the cluster definition to an existing Edge deployment using Local UI during cluster creation.