Implementing Values Schema Validation

1. Creating values.schema.json File

Creating a values.schema.json file enables schema validation for Helm chart values, ensuring that the values provided during installation or upgrade conform to a defined structure and data types.

Property	Type	Description	Required
type	`object`	Defines the root type as an object, which is required for Helm values schema validation.	Yes
properties	`object`	Defines the structure and schema of the values object.	Yes
required	`array`	List of property names that must be present in the values object.	No

Example: Basic values.schema.json

{
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 0
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        }
      },
      "required": ["repository", "tag"]
    }
  },
  "required": ["replicaCount", "image"]
}

Note: The values.schema.json file must be placed in the root directory of your Helm chart for validation to occur during helm install or helm upgrade commands.

Warning: If validation fails, Helm will return an error and prevent the installation or upgrade from proceeding.

2. Defining Schema Properties

Property	Type	Description	Default
name	`string`	Name of the property	`""`
type	`string`	JSON type of the property (e.g., `string`, `integer`, `boolean`)	`string`
description	`string`	Description of the property for documentation	`""`
default	`any`	Default value if not provided in values file	`null`
required	`boolean`	Whether property is required in values file	`false`
format	`string`	Format constraint (e.g., `email`, `uri`)	`""`

Example: Defining Schema Properties

properties:
  database:
    type: object
    description: Database configuration
    properties:
      host:
        type: string
        description: Database host address
        default: "localhost"
      port:
        type: integer
        description: Database port number
        default: 5432
      ssl:
        type: boolean
        description: Enable SSL connection
        default: false

3. Setting Required Fields

Field	Type	Description	Required
database.host	`string`	Database host address	REQUIRED
database.port	`integer`	Database port number	REQUIRED
database.name	`string`	Database name to connect to	REQUIRED
database.username	`string`	Username for database authentication	REQUIRED
database.password	`string`	Password for database authentication	REQUIRED

Example: Required Fields in Values Schema

database:
  host: "db.example.com"
  port: 5432
  name: "myapp"
  username: "admin"
  password: "secret123"

4. Defining Value Types

Property	Type	Description	Example
string	`string`	Represents textual data	`"nginx"`
integer	`integer`	Represents whole numbers	`80`
number	`number`	Represents decimal numbers	`3.14`
boolean	`boolean`	Represents true or false values	`true`
array	`array`	Represents a list of values	`["value1", "value2"]`
object	`object`	Represents a collection of key-value pairs	`{"key": "value"}`

Example: Defining Value Types in Values Schema

name: my-app
version: 1.0.0
apiVersion: v2
appVersion: "1.0"
type: application

values:
  image:
    repository: "nginx"
    tag: "latest"
  replicas: 3
  enabled: true
  ports:
    - containerPort: 80
      name: http
  config:
    key1: "value1"
    key2: "value2"

5. Adding Property Constraints

Property	Type	Constraints	Description
replicaCount	`integer`	`minimum: 0`	Number of replicas for the deployment
image.repository	`string`	`pattern: ^[a-z0-9\-\.\/]+$`	Docker image repository URL
image.tag	`string`	`pattern: ^[a-zA-Z0-9\-\.]+$`	Docker image tag
service.type	`string`	`enum: [ClusterIP, NodePort, LoadBalancer]`	Kubernetes service type
resources.limits.cpu	`string`	`pattern: ^[0-9]+m$`	CPU limit in millicores
resources.limits.memory	`string`	`pattern: ^[0-9]+Mi$`	Memory limit in mebibytes

Example: Validating Property Constraints

replicaCount: 3
image:
  repository: nginx
  tag: v1.21.0
service:
  type: ClusterIP
resources:
  limits:
    cpu: 500m
    memory: 512Mi

Note: Property constraints in Helm values schema ensure that the values provided to a chart are valid and conform to expected formats. These constraints help prevent deployment errors due to invalid configurations.

6. Using Enum Values

Property	Values	Description
database.type	`"mysql"`, `"postgresql"`, `"mssql"`	Specifies the database type to be used in the chart
log.level	`"debug"`, `"info"`, `"warn"`, `"error"`	Defines the logging level for application logs
storage.class	`"standard"`, `"fast"`, `"slow"`	Storage class for persistent volumes

Example: Setting Enum Values in Values Schema

database:
  type: "mysql"
log:
  level: "info"
storage:
  class: "standard"

Note: Enum values in Helm charts provide type safety and reduce configuration errors by restricting input to predefined options.

7. Setting Default Values

Property	Default Value	Description
replicaCount	`1`	Number of replicas for the deployment
image.repository	`nginx`	Container image repository name
image.tag	`latest`	Container image tag
service.type	`ClusterIP`	Kubernetes service type to expose the application
service.port	`80`	Port to expose the service on

Example: Default Values in values.yaml

replicaCount: 1
image:
  repository: nginx
  tag: latest
service:
  type: ClusterIP
  port: 80

8. Adding Schema Descriptions

Property	Description	Type	Default
description	Human-readable description of the schema property	`string`	`""`
title	Short title for the property (used in UIs)	`string`	`""`
examples	Array of example values for the property	`array`	`[]`

Example: Schema with Descriptions

{
  "properties": {
    "replicaCount": {
      "type": "integer",
      "description": "Number of replicas to run",
      "title": "Replica Count",
      "examples": [
        1,
        3
      ]
    }
  }
}

9. Validating Nested Objects

Property	Type	Description	Validation
database.host	`string`	Hostname of the database server	Must be a valid hostname or IP address
database.port	`integer`	Port number for database connection	Must be between 1 and 65535
database.credentials.username	`string`	Database user name	Must not be empty
database.credentials.password	`string`	Password for database user	Must not be empty and must meet complexity requirements

Example: Nested Object Schema Validation

database:
  host: "db.example.com"
  port: 5432
  credentials:
    username: "appuser"
    password: "securePassword123"

Note: Nested object validation in Helm uses JSON Schema with properties and required keywords to ensure all nested fields are properly validated.

10. Testing Schema Validation

Example: Unit Test with Chart Testing

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
  - name: test-container
    image: alpine:latest
    command: [&#34;/bin/sh&#34;, &#34;-c&#34;, &#34;echo 'Testing schema validation'&#34;]

Test Type	Description	Command	Notes
Unit Test	Validate chart values against schema	`helm unittest my-chart`	Requires `helm-unittest` plugin
Integration Test	Deploy chart and verify values in runtime	`helm install test-release my-chart --set key=value`	Use `helm template` to inspect rendered manifests

Note: Ensure all values are validated before deployment to avoid runtime errors.

Warning: Schema validation does not catch all runtime issues; always test in a staging environment.