Skip to main content

Add a Custom Pack

You can add a custom pack to Palette to add new integrations or applications to your cluster profiles.

further guidance

Check out the tutorial Deploy a Custom Pack to learn how to deploy a custom pack to a custom registry.

Prerequisites​

The following items are required to create a custom pack.

JSON Schema​

Each pack contains a metadata file named pack.json. The table below explains in greater detail the JSON schema attributes.

Property NameData typeRequiredDescription
nameStringTrueName of the pack
displayNameStringTrueName of the pack as it is to be displayed on the Palette UI.
layerStringTrueRelevant layer that this pack should be part of; such as os, k8s, cni, csi, addon.
addonTypeStringFalseThe addon type must be set for packs that have the layer set to addon. The value must be one of the following: logging, monitoring, load balancer, authentication, ingress, security, ai, app services, network, storage, registry, servicemesh, or system app. Setting a relevant correct addon type ensures packs are organized correctly in the Palette UI.
versionStringTrueA Semantic version for the pack. It is recommended that the pack version be the same as the underlying integration it is being created for. For example, the version for the pack that will install Prometheus 2.3.4, should set to 2.3.4.
cloudTypesArrayTrueYou can provide one or more types for a pack. Supported values are as follows: all, aws, azure, gcp, vsphere, openstack, baremetal, maas, aks, eks, edge, edge-native, and coxedge.
groupStringFalseOptional categorization of packs. For example, LTS can be set for Ubuntu OS packs.
annotationsArrayFalseOptional key-value pairs required during pack installation. Typically, custom packs do not need to set annotations. Some packs like the ones for OS require annotations that need to be set with an image id.
eolStringFalseEnd of life date for integration.
KubeManifestsArrayFalseRelative path to Kubernetes manifest YAML files.
chartsArrayFalseRelative path to the helm chart archives.

The following is the JSON schema for packs. Review the schema to ensure your JSON configuration is defined correctly.

{
  "type": "object",
  "required": ["name", "displayName", "version", "layer"],
  "properties": {
    "name": {
      "$ref": "#/definitions/nonEmptyString"
    },
    "displayName": {
      "$ref": "#/definitions/nonEmptyString"
    },
    "version": {
      "$ref": "#/definitions/nonEmptyString"
    },
    "layer": {
      "$ref": "#/definitions/layer"
    },
    "group": {
      "type": "string"
    },
    "cloudTypes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "all",
          "aws",
          "azure",
          "gcp",
          "vsphere",
          "openstack",
          "baremetal",
          "maas",
          "aks",
          "eks",
          "edge",
          "edge-native",
          "coxedge"
        ]
      }
    },
    "cloudType": {
      "type": "string",
      "enum": [
        "all",
        "aws",
        "azure",
        "gcp",
        "vsphere",
        "openstack",
        "baremetal",
        "maas",
        "aks",
        "eks",
        "edge",
        "edge-native",
        "coxedge"
      ]
    },
    "eol": {
      "type": "string"
    },
    "addonType": {
      "type": "string"
    },
    "addonSubType": {
      "type": "string"
    },
    "charts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "kubeManifests": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "annotations": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "constraints": {
      "$ref": "#/definitions/constraints"
    }
  },
  "definitions": {
    "nonEmptyString": {
      "type": "string",
      "minLength": 1
    },
    "layer": {
      "type": "string",
      "enum": ["kernel", "os", "k8s", "cni", "csi", "addon"]
    },
    "constraints": {
      "type": "object",
      "properties": {
        "dependencies": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/dependency"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/resource"
          }
        }
      }
    },
    "dependency": {
      "type": "object",
      "required": ["packName", "layer", "type"],
      "properties": {
        "packName": {
          "$ref": "#/definitions/nonEmptyString"
        },
        "layer": {
          "$ref": "#/definitions/layer"
        },
        "minVersion": {
          "type": "string"
        },
        "maxVersion": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": ["required", "optional", "notSupported", "upgrade"]
        }
      }
    },
    "resource": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["cpu", "memory", "diskSize"]
        },
        "minLimit": {
          "type": "number"
        },
        "components": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/component"
          }
        }
      }
    },
    "component": {
      "type": "object",
      "required": ["scheduleType"],
      "properties": {
        "scheduleType": {
          "type": "string",
          "enum": ["all", "control-plane", "worker"]
        },
        "resourceRequestParamRef": {
          "type": "string"
        },
        "replicaCountParamRef": {
          "type": "string"
        }
      }
    }
  }
}

Create a Custom Pack​

Follow the steps below to create a custom pack.

  1. Create a directory with a suitable name for all the pack contents.

    Example: prometheus_1_0

  2. Create a metadata file named pack.json to describe the pack.

    Example:

    {
      "annotations": {
        "name": "value"
      },
      "displayName": "<PACK_DISPLAY_NAME>",
      "eol": "2028-04-30",
      "group": "<PACK_GROUP>",
      "kubeManifests": ["manifests/deployment.yaml"],
      "layer": "<LAYER>",
      "name": "<PACK_NAME>",
      "version": "<PACK_VERSION>"
    }

  3. Create a file named values.yaml. This file consists of configurable parameters that need to be exposed to the end-users during the creation of a cluster profile.

    info

    A values.yaml file is mandatory for every pack. For an OS pack, there are typically no configurable parameters, but an empty file still needs to be added to the OS pack.

    Parameters for all charts and manifests defined in the pack are defined in the values.yaml file. Helm charts natively support values override. Any values defined are merged with those defined within a chart. Manifests need to be explicitly configured to use parameters if desired.

    pack:
       namespace : <default namespace for charts and manifests>
    charts:
       chart1:
       <configurable chart1 parameters>
       chart2:
       <configurable chart2 parameters>
    manifests:
       manifest1:
           <manifest1 parameters>
       manifest2:
           <manifest2 parameters>

  4. (Optional) If you are designing a pack that can be used in Edge cluster profiles in the local management mode, ensure you include all images that are referenced in the pack in the pack.content.images section of the values.yaml file. For more information about local deployments with primary registries, refer to Deploy with a Primary Registry.

    pack:
      content:
        images:
          - docker.io/example-image:latest
          - gcr.io/example-image-two:latest

    If you do not specify the images in the pack.content.images field and your cluster is a local cluster with an in-cluster primary registry, the images will not be loaded and deployment of the application will fail.

  5. A pack must have the logo file named logo.png and must be copied into the pack directory.

  6. Log in to the pack registry using the following command.

     spectro registry login [REGISTRY_SERVER]

  7. Push the newly defined pack to the pack registry using the following command.

     spectro pack push [PACK_DIR_LOCATION] --registry-server [REGISTRY_SERVER]

  8. To overwrite contents of a previously deployed pack, use the force option as follows.

     spectro pack push [PACK_DIR_LOCATION] -f --registry-server [REGISTRY_SERVER]

Adding an OS Pack​

The OS is one of the Core Layers in a cluster profile. An OS pack can be built to use a custom OS image for cluster nodes. This might be desirable if an organization wants to use an approved hardened OS image for their infrastructure. There are typically the following two scenarios for the OS image:

  1. Pre-Installed Kubernetes - The OS image has the desired version of Kubernetes components like kubelet, kubectl, etc installed.

  2. Vanilla OS Image - Kubernetes components are not installed.

Additionally, for both scenarios, additional components or packages may need to be installed at runtime to prepare the final OS image. The following are a few examples of building custom OS packs to cover some of these scenarios.

A few sample pack manifests for building a custom OS pack are shown in the following examples. These are examples for images that do not have Kubernetes components pre-installed. Palette installs these components at the time of provisioning. The version of Kubernetes that gets installed depends on the Kubernetes pack configuration in the cluster profile. If Kubernetes is pre-installed in the image, set the flag skipK8sInstall to true.

Examples​

AWS Custom-OS Pack​

{
  "annotations":
    {
      "cloudRegion": "us-east-1",
      "imageId": "ami-071f6fc516c53fca1",
      "imageOwner": "421085264799",
      "osName": "centos",
      "os_spectro_version": "0",
      "sshUsername": "centos",
      "skipK8sInstall": "false",
    },
  "cloudTypes": ["aws"],
  "displayName": "CentOS",
  "eol": "2024-06-30",
  "group": "",
  "kubeManifests": [],
  "layer": "os",
  "name": "golden-centos-aws",
  "version": "7.7.1908",
}