Layered Chart Values¶

What is a Layered Chart Values¶

Omnistrate supports layered chart values for Helm chart configuration, providing conditional deployment customization across different environments, cloud providers, and deployment contexts. This feature replaces traditional static chartValues with a flexible, hierarchical system that applies configuration layers based on runtime conditions.

Info

Layered Chart Values and traditional chartValues are mutually exclusive. You must choose one approach per resource.

Basic example for Layered Chart Values¶

layeredChartValues:
  - # Base layer - applies to all deployments
    values:
      global:
        environment: "production"
        monitoring:
          enabled: true

  - # Conditional layer - applies only to AWS
    scope:
      "{{ $sys.deploymentCell.cloudProviderName }}": "aws"
    values:
      aws:
        storageClass: "gp3"
        loadBalancer:
          type: "nlb"

  - # External configuration layer
    scope:
      "{{ $sys.deploymentCell.region }}": "us-west-2"
    valuesFile:
      gitConfiguration:
        repositoryUrl: "https://github.com/your-org/helm-configs.git"
        reference: "refs/heads/main"
        accessToken: "{{ $secret.GH_ACCESS_TOKEN }}"
      path: "regions/us-west-2/values.yaml"

How Layered Chart Values work¶

Layers are processed in definition order. Each layer's scope conditions are evaluated against deployment context, and only matching layers are applied. Configuration values are deep merged, with later layers overriding earlier ones.

Template variables available:

System variables ($sys.*): Platform parameters like cloud provider, region, network config. See System Parameters
API parameters ($var.*): User-defined API parameters from your service specification
Output variables ($out.*): Infrastructure outputs from Terraform resources and other resource outputs
Secrets ($secret.*): Secure access to secrets managed by Omnistrate

Layered Chart Values Types¶

Inline values layer¶

Defines configuration directly in the service specification:

- values:
    app:
      name: "my-service"
      replicas: 3
      image:
        tag: "v1.2.3"

Git-referenced layer¶

References external configuration files:

- valuesFile:
    gitConfiguration:
      repositoryUrl: "https://github.com/your-org/configs.git"
      reference: "refs/heads/main"
      accessToken: "{{ $secret.GITHUB_TOKEN }}"
    path: "services/my-service/values.yaml"

Scoped layer¶

Applies only when conditions are met:

- scope:
    "{{ $sys.deploymentCell.cloudProviderName }}": "gcp"
    "{{ $sys.deploymentCell.region }}": "us-central1"
  values:
    gcp:
      workloadIdentity:
        enabled: true

Advanced examples of Layered Chart Values¶

Multi-cloud deployment¶

layeredChartValues:
  # Base configuration for all clouds
  - values:
      app:
        name: "multi-cloud-service"
        replicas: 3
        monitoring:
          enabled: true

  # AWS-specific configuration
  - scope:
      "{{ $sys.deploymentCell.cloudProviderName }}": "aws"
    values:
      serviceAccount:
        annotations:
          eks.amazonaws.com/role-arn: "{{ $out.iam.role.arn }}"
      storage:
        class: "gp3"
        provisioner: "ebs.csi.aws.com"

  # GCP-specific configuration
  - scope:
      "{{ $sys.deploymentCell.cloudProviderName }}": "gcp"
    values:
      serviceAccount:
        annotations:
          iam.gke.io/gcp-service-account: "{{ $out.iam.serviceAccount.email }}"
      storage:
        class: "ssd"
        provisioner: "pd.csi.storage.gke.io"

  # Azure-specific configuration
  - scope:
      "{{ $sys.deploymentCell.cloudProviderName }}": "azure"
    values:
      serviceAccount:
        annotations:
          azure.workload.identity/client-id: "{{ $out.iam.identity.clientId }}"
      storage:
        class: "managed-csi"
        provisioner: "disk.csi.azure.com"

Environment-based configuration¶

layeredChartValues:
  # Production defaults
  - values:
      app:
        replicas: 5
        resources:
          cpu: "1000m"
          memory: "2Gi"
        monitoring:
          level: "standard"

  # Development overrides
  - scope:
      "{{ $var.environment }}": "development"
    values:
      app:
        replicas: 1
        resources:
          cpu: "100m"
          memory: "256Mi"
        monitoring:
          level: "debug"

  # Staging configuration from Git
  - scope:
      "{{ $var.environment }}": "staging"
    valuesFile:
      gitConfiguration:
        repositoryUrl: "https://github.com/your-org/staging-configs.git"
        reference: "refs/heads/main"
        accessToken: "{{ $secret.GH_ACCESS_TOKEN }}"
      path: "common/staging-values.yaml"

Large customer-specific override blocks¶

When the number of customer-specific Helm overrides is too large to model as individual API parameters, define a single json API parameter and merge it as a layered values block.

services:
  - name: MyApp
    apiParameters:
      - key: customChartValues
        name: Custom Chart Values
        description: Customer-specific Helm overrides for advanced cases
        type: json
        modifiable: true
        required: false
        export: true
        defaultValue: |
          metrics:
            serviceMonitor:
              enabled: true
    helmChartConfiguration:
      chartName: my-app
      chartVersion: 1.0.0
      chartRepoName: my-charts
      chartRepoURL: https://charts.example.com
      layeredChartValues:
        - values:
            global:
              environment: production
        - name: customer-overrides
          values: $var.customChartValues

This pattern is useful when:

You need a flexible escape hatch for advanced customer overrides
The override surface is too large to register field-by-field as API parameters
You want a stable base layer with a single customer-provided override layer on top

Note

The json parameter should resolve to an object-shaped YAML or JSON document that matches the Helm values structure you want to merge. Use this for maps of values, not for arbitrary free-form text.

Git integration for Layered Chart Values¶

Repository authentication¶

Public repositories¶

For publicly accessible repositories, only specify the repository URL:

valuesFile:
  gitConfiguration:
    repositoryUrl: "https://github.com/your-org/public-helm-configs.git"
    reference: "refs/heads/main"
  path: "shared/base-values.yaml"

Private repositories¶

For private repositories, provide an access token via Omnistrate secrets:

valuesFile:
  gitConfiguration:
    repositoryUrl: "https://github.com/your-org/private-helm-configs.git"
    reference: "refs/heads/main"
    accessToken: "{{ $secret.GITHUB_TOKEN }}"
  path: "secure/production-values.yaml"

Reference types¶

Omnistrate supports standard Git reference formats for specifying which version of your configuration to use:

Branch references¶

# Latest commit on main branch
reference: "refs/heads/main"

# Latest commit on develop branch
reference: "refs/heads/develop"

# Latest commit on feature branch
reference: "refs/heads/feature/new-config"

Tag references¶

# Specific release tag
reference: "refs/tags/v1.2.3"

# Latest stable release
reference: "refs/tags/stable"

Commit references¶

For referencing specific commits, use the commitSHA field instead of reference:

valuesFile:
  gitConfiguration:
    repositoryUrl: "https://github.com/your-org/helm-configs.git"
    reference: "refs/heads/main"
    commitSHA: "a1b2c3d4e5f67890xxxxxxxxxxx34567890abcd"
    accessToken: "{{ $secret.GH_ACCESS_TOKEN }}"
  path: "values.yaml"