Skip to main content

Pack Constraints

Pack constraints are a set of rules defined at the pack level to validate the packs for a Profile or a Cluster before it gets created or updated. Packs must be validated before the cluster is submitted to ensure a successful deployment.


info

You can find information about the JSON schema for the pack metadata file in the JSON schema section of the documentation.

Pack Values Constraints​

A Spectro Pack currently supports various configurations through a configuration file called values.yaml. The values defined in the config file are applied while deploying the Kubernetes cluster. The values defined in the pack are default values and can be overridden in the Cluster Profile or during the Cluster deployment.

Since the default pack values can be overridden, users may inadvertently set incorrect values leading to cluster deployment failure. These failures can occur at any point during the cluster deployment process. If the system is capable of detecting invalid pack values before the cluster is submitted for deployment, then deployment failures can be overcome to some extent.

Pack value constraints are additional information provided through a template file called schema.yaml in the pack. They define the schema format of the pack values. The pack constraints framework auto-checks for any schema constraints defined in the pack and validates the pack values. This checking occurs while creating or updating Cluster Profiles and Clusters.

Schema Constraints​

Every schema constraint consists of a key name and the schema template. The key name must be the complete path of the parameter which is defined in the config file.

Required

Defines whether the pack value is optional or required.

registry.hostname:
 schema: '{{ required }}'

Readonly

The pack value is not editable if marked as readonly.

registry.hostname:
 schema: '{{ readonly }}'

Format

Defines the pack value format: the value is valid only when the value format matches the format defined in the pack.

Format Syntax

A format template consists of one or more format types along with the optional regex and number range values.

registry.hostname:
  schema: '{{ required | format "${FORMAT_TYPE:/REGEX/ OR [NUMBER RANGE] OR [LIST_OPTIONS]}" }}'
warning

The syntax of the regex accepted is the same general syntax used by Perl, Python, and other languages. More precisely, it is the syntax accepted by RE2 and described here.

Format Types

The string format type checks if the input value is a string and supports the regex in the template. If regex is specified in the template then the input value must match the regex.

registry.hostname:
  schema: '{{ format "${string}" }}'
registry.hostname:
  schema: '{{ format "${string:/^([a-z0-9].*)$/}" }}'

Examples

Schema constraints can be combined to support multiple validations using a single template.

registry.addresses.$[]:
 schema: '{{ required | format "${ipv4} - ${ipv4}" | hints "ip pool range"}}'

registry.addresses.$[] is an array data type in the config file. The schema template defines that the value is required and the format must match - ${ipv4} - ${ipv4}

Examples:

10.10.10.10 - 10.10.10.255 → valid

10.10.10.10 → invalid

10.10.10.10-10.10.10.255 → invalid

Pack Dependency Constraints​

Spectro Cloud provides the flexibility to choose any pack of any version in the profile. Clusters are deployed based on the packs selected in the profile. While this works for most of the cases, it is sometimes required to select a minimum or maximum pack version, or to have dependencies between the packs to ensure the Kubernetes cluster is deployed successfully as desired.

Pack dependency constraints are the rules defined in the pack metadata file pack.json. They are used to define the minimum and maximum supported versions, and also to specify which pack is required or not supported. The pack constraints framework auto-checks for any schema constraints defined in the pack and validates the pack values. This checking occurs while creating or updating Cluster Profiles and Clusters.

Pack metadata JSON​

Pack dependency constraints must be defined in the pack.json file. The sample pack metadata shown below defines the dependencies under constraints key.

{
  "addonType": "system app",
  "cloudTypes": ["all"],
  "displayName": "Test Pack",
  "kubeManifests": [],
  "layer": "addon",
  "name": "pack-constraints-test",
  "version": "1.0.0",
  "constraints": {
    "dependencies": [
      {
        "packName": "vault",
        "layer": "addon",
        "minVersion": "0.6.0",
        "maxVersion": "",
        "type": "optional"
      },
      {
        "packName": "csi-vsphere-volume",
        "layer": "csi",
        "minVersion": "1.0.0",
        "maxVersion": "",
        "type": "notSupported"
      },
      {
        "packName": "kubernetes",
        "layer": "k8s",
        "minVersion": "1.17.0",
        "maxVersion": "1.18.6",
        "type": "required"
      }
    ]
  }
}
warning

If the minimum and maximum versions are not mentioned, the validation is skipped.

Pack Dependency Attributes​

A pack can have one or more dependencies defined in the dependencies array. Each dependency consists of the following attributes.

AttributeDescription
packNameName of the dependent pack.
layerThe layer type of the dependent pack. Refer to the Layer Types section to learn more.
minVersionMinimum supported dependent pack version, any version below the minimum version is not valid.
maxVersionMaximum supported dependent pack version, any version above the maximum version is not valid.
typeThe defined type for the dependency. Refer to the Dependency Types section to learn more.

In the example code snippet from earlier, the three dependent packs are identified by unique pack names such as vault, csi-vsphere-volume, and kubernetes. A minVersion, maxVersion, and type are defined for each dependent pack.

"dependencies": [
    {
      "packName": "vault",
      "layer": "addon",
      "minVersion": "0.6.0",
      "maxVersion": "",
      "type": "optional"
    },
    {
      "packName": "csi-vsphere-volume",
      "layer": "csi",
      "minVersion": "1.0.0",
      "maxVersion": "",
      "type": "notSupported"
    },
    {
      "packName": "kubernetes",
      "layer": "k8s",
      "minVersion": "1.17.0",
      "maxVersion": "1.18.6",
      "type": "required"
    }
  ]

Layer Types​

The layer attribute defines the layer where the dependent pack can be found in the Cluster Profile. The following table lists the different layer types.

LayerDescription
osThe dependent pack can only be found in the operating system layer of the Cluster Profile. The os layer contains packs such as Ubuntu, CentOS or Bring Your Own OS (BYOOS).
k8sThe dependent pack can only be found in the Kubernetes layer of the Cluster Profile. The k8s layer contains packs such as Palette eXtended Kubernetes, RKE2, k3s or MicroK8s.
cniThe dependent pack can only be found in the network layer of the Cluster Profile. The cni layer contains packs such as Calico, Cilium, Flannel and Antrea.
csiThe dependent pack can only be found in the storage layer of the Cluster Profile. The csi layer contains packs such as vSphere CSI, Amazon EBS CSI, Amazon EFS, Azure Disk and Portworx.
addonThe dependent pack can only be found in the add-on layers of the Cluster Profile. The addon layer contains packs such as ArgoCD, Vault, Nginx, and many more.

Dependency Types​

The type attribute defines the type of dependency. The following table lists the different dependency types.

TypeDescription
optionalThe dependent pack is optional but validates minimum or maximum versions if the pack is selected. In the example, the vault pack is optional.
requiredThe dependent pack is mandatory and must contain a version within the minimum or maximum supported versions, if defined. In the example, the kubernetes pack is required with a minimum version of 1.17.0 and a max version of 1.18.6. Any Kubernetes version below 1.17.0 and above 1.18.6 is not valid.
notSupportedThe pack versions within the range of the mentioned minimum and maximum are not supported. The csi-vsphere-volume pack is not supported if the version selected falls within the min and max versions.

Pack Resource Constraints​

A successful Kubernetes Cluster deployment is possible only when the cluster has sufficient hardware requirements. We consider the CPU, Memory, and Disk size as the hardware requirements. The minimum resource requests can be varied depending on the workload to be deployed in the cluster. Spectro Cloud users are allowed to select the desired instance type, and the disk size while configuring the machine pool in the Cluster deployment procedure. If the user selects the instance type which does not satisfy the minimum CPU or Memory or Disk size requirements, then there is a high probability that the cluster deployment may not succeed due to insufficient CPU or Memory or Disk size.

Pack Resource Constraints are a set of rules defined in the pack metadata pack.json to specify the minimum CPU, Memory, and Disk size requirements. The pack constraints framework auto-checks the resource constraints and validates the user-selected instance type specifications before the cluster is submitted for deployment. The total input resource capacity is evaluated against the machine pool size with the actual hardware specifications of a selected instance type.

Pack metadata JSON​

Pack resource constraints must be defined in the pack.json file. The sample pack metadata is shown below to define the resources under constraints key.

{
  "addonType": "system app",
  "cloudTypes": ["all"],
  "displayName": "Test Pack",
  "kubeManifests": [],
  "layer": "addon",
  "name": "pack-constraints-test",
  "version": "1.0.0",
  "constraints": {
    "resources": [
      {
        "type": "cpu",
        "minLimit": 2000,
        "components": [
          {
            "resourceRequestParamRef": "requests.cpu",
            "replicaCountParamRef": "replicas",
            "scheduleType": "all"
          }
        ]
      },
      {
        "type": "memory",
        "minLimit": 2048,
        "components": [
          {
            "resourceRequestParamRef": "requests.memory",
            "replicaCountParamRef": "replicas",
            "scheduleType": "worker"
          }
        ]
      },
      {
        "type": "diskSize",
        "minLimit": 10
      }
    ]
  }
}

Pack Resources Attributes​

The type of resource

  • cpu
  • memory
  • diskSize

Pack Presets​

Pack Presets are the predefined values in a file called presets.yaml in the pack. It contains an array of the presets for the pack, and is visible in the pack parameters of the Cluster profile and the Cluster. Users can select any preset from the available pack presets, and the predefined values of a selected preset are applied automatically by the Spectro Cloud UI. Presets make pack configuration much easier as multiple pack values are updated at a time and the user does not need to understand all the configuration parameters which get changed depending on various factors.

Presets Metadata YAML​

This presets.yaml shows two presets

  • privatePackRegistry
  • publicPackRegistry

with a different set of pre-defined values.

presets:
- name: "privatePackRegistry"
  displayName: "Private Registry"
  group: "registry"
  remove: ["registry.ingress.host"]
  add: |
    registry:
      private: true
      type: "PACK"
      host:
       ip: "127.0.0.1"
       port: 5000
- name: "publicPackRegistry"
  displayName: "Public Registry"
  group: "registry"
  remove: ["registry.ingress.host"]
  add: |
    registry:
      private: false
      type: "PACK"
      host:
       ip: "13.233.2.255"
       port: 80

Preset Attributes​

Name of the preset. It must be unique.

Pack Macros​

Pack macros are the variables defined in the Cluster profile or in Cluster pack values, and these variables are resolved only at the cluster deployment time.

Types of Macros​

System macros are variables defined by the system. Users are allowed to use these variables and the system is capable of resolving all the variables to values at the time of cluster deployment.

user:
 name: "{{ .spectro.system.[VARIABLE_NAME] }}"

Supported Variables​

MacroDescription
{{.spectro.system.user.name}}The name of the user currently logged in.
{{.spectro.system.user.uid}}The unique identifier of the user currently logged in.
{{.spectro.system.user.email}}The email address of the user currently logged in.
{{.spectro.system.tenant.uid}}The unique identifier of the current tenant.
{{.spectro.system.project.name}}The name of the project.
{{.spectro.system.project.uid}}The unique identifier of the project.
{{.spectro.system.clusterprofile.name}}The name of the cluster profile associated with the current project.
{{.spectro.system.clusterprofile.uid}}The unique identifier of the cluster profile the pack is part of.
{{.spectro.system.clusterprofile.version}}The current version of the cluster profile the pack is part of.
{{.spectro.system.cluster.name}}The name of the cluster.
{{.spectro.system.cluster.uid}}The unique identifier of the cluster.
{{.spectro.system.cloudaccount.name}}The name of the cloud account associated with the current project.
{{.spectro.system.cloudaccount.uid}}The unique identifier of the cloud account associated with the current project.
{{.spectro.system.kubernetes.version}}The version of Kubernetes currently running on the cluster.
{{.spectro.system.reverseproxy.server}}The hostname of the reverse proxy server.
{{.spectro.system.reverseproxy.port}}The port number of the reverse proxy server.
{{.spectro.system.reverseproxy.protocol}}The protocol used by the reverse proxy server, either HTTP or HTTPS.
{{.spectro.system.reverseproxy.vhostport}}The port number used by the virtual host on the reverse proxy server.
{{.spectro.system.cloud.type }}The type of cloud provider being used, such as AWS, GCP, Azure or other providers.
{{.spectro.system.cloud.region }}The region where the cloud resources are located.
{{.spectro.system.clusterprofile.infra.name}}The name of the cluster profile.
{{.spectro.system.clusterprofile.infra.uid}}The unique identifier of the cluster profile.
{{.spectro.system.clusterprofile.infra.version}}The version of the cluster profile.
{{.spectro.system.cluster.kubevip}}The IP address of the virtual IP (VIP) assigned to the cluster and load balancer for the control plane. This macro is only available for Edge and vSphere cluster deployments.

Additional Capabilities​

Sprig Template Functions​

Users are allowed to use the sprig template functions to modify the resolved variable value.

Examples

user:
 name: "{{ .spectro.system.user.name | upper }}"

upper - sprig template function which converts resolved user name to upper case

How to set the default value?​

k8s:
 version: "{{ .spectro.pack.kubernetes.version | default \"1.19.0\"}}"
info

If the variable version is not defined in the pack kubernetes, then the default value 1.19.0 will be applied at deployment. In case the default value is not specified then the empty value will be applied.