Helm Chart

Helm Chart installations deploy Helm Chart services to environments. Configure service-specific settings, secrets, and resources for your Kubernetes applications.

# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: ServiceInstallation
metadata:
  name: workers-production
spec:
  service: workers
  environment: production
  config: |
    replicaCount: 2
    resources:
      requests:
        memory: 2Gi
    db:
      password:
        secretKeyRef:
          name: '{{ k8sSecretName "db-credentials" }}'
          key: password

Properties

`service`

string — required Name of the Helm Chart service to install.

service: postgresql

`environment`

string — required Target environment for this installation.

environment: production

`name`

string — optional Custom name for this installation. If not specified, uses the service name.

name: postgres-primary

`namespace`

string — optional Kubernetes namespace to install into. If not provided, uses the environment’s default namespace, which has the same name as the environment. Cannot be changed after install. See Namespaces.

namespace: databases

`releaseChannel`

string — optional Release channel to follow for this installation. If not specified, uses the environment’s channel.

releaseChannel: stable

`dependencies`

array — optional Installations that must be ready before this installation installs for the first time. Ryvn holds the first install until every entry is satisfied. After that, dependencies hold nothing: upgrades, configuration changes, and secret rotations deploy even while a dependency is being reinstalled. Each entry sets exactly one key:

Property	Type	Description
`serviceInstallation`	`string`	Name of an installation in the same environment. It must be `UP_TO_DATE`.
`service`	`string`	Name of a service. Any `UP_TO_DATE` installation of it in the environment satisfies the entry.

Dependencies have no version bounds; version requirements belong in the service’s release dependencies. When this installation’s release depends on a service and dependencies names installations of that service, the release’s range is checked against the named installations only. See Installation dependencies. You can name several installations of the same service. An entry can’t name this installation, name its own service with service, repeat another entry, sit beside a serviceInstallation entry of the same service, or form a cycle with other installations’ dependencies. Installations created by a blueprint take their dependencies from the blueprint; to set them directly, exclude the installation from blueprint updates first. See Installation Dependencies.

dependencies:
  - serviceInstallation: cert-manager
  - service: external-dns  # any ready external-dns installation

Variable Groups

All variable groups in the environment are automatically available to Helm Chart installations as Kubernetes secrets — no explicit linking required. Use the k8sSecretName template function to get the Kubernetes secret name for a variable group, then reference individual keys within it:

config: |
  db:
    password:
      secretKeyRef:
        name: '{{ k8sSecretName "db-credentials" }}'
        key: password

The k8sSecretName function returns a deterministic Kubernetes secret name derived from the variable group name. Each key in the variable group becomes a key in the Kubernetes secret. Reference them in your Helm chart templates using standard secretKeyRef or envFrom.secretRef syntax.

Avoid k8sSecretValue in Helm values — it copies the secret value into the release and can leak sensitive data. Use k8sSecretName whenever the chart supports a secret reference.

Wiring secret refs in your own chart

Give your chart a value for the secret name, then reference it from the pod spec:

# installation config
config: |
  dbCredentialsSecret: '{{ k8sSecretName "db-credentials" }}'

# your chart's deployment template
env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: {{ .Values.dbCredentialsSecret }}
        key: password
# or pull in every key at once
envFrom:
  - secretRef:
      name: {{ .Values.dbCredentialsSecret }}

If the app reads a config file instead of the environment, mount the secret:

# your chart's deployment template
volumes:
  - name: db-credentials
    secret:
      secretName: {{ .Values.dbCredentialsSecret }}
volumeMounts:
  - name: db-credentials
    mountPath: /etc/secrets
    readOnly: true

For connection strings, put the whole URL in the variable group as its own key (for example database-url) and reference that key — nothing has to be assembled from a secret in the values:

# your chart's deployment template
env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: {{ .Values.dbCredentialsSecret }}
        key: database-url

If the URL has to be built from separate pieces, let Kubernetes substitute the secret at container start — $(VAR) is expanded automatically, as long as VAR comes from envFrom or is declared earlier in the same env list (a later entry is left as literal $(VAR)):

# your chart's deployment template
env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: {{ .Values.dbCredentialsSecret }}
        key: password
  - name: DATABASE_URL
    value: postgres://app:$(DB_PASSWORD)@{{ .Values.dbHost }}:5432/app

Third-party and OSS charts

Most upstream charts already accept an existing secret instead of a literal password — look for existingSecret, secretKeyRef, or *SecretName values in the chart’s values.yaml, along with the value that names the key inside it:

config: |
  auth:
    existingSecret: '{{ k8sSecretName "db-credentials" }}'
    secretKeys:
      adminPasswordKey: postgres-password

Many charts also expose a pass-through for extra pod environment — commonly extraEnvFrom, envFrom, or extraEnvVarsSecret — which loads every key in the secret as an environment variable:

config: |
  extraEnvFrom:
    - secretRef:
        name: '{{ k8sSecretName "app-secrets" }}'

Where a chart takes a raw list of environment variables (extraEnv, env, extraEnvVars), pass a secret reference instead of a literal value:

config: |
  extraEnv:
    - name: API_KEY
      valueFrom:
        secretKeyRef:
          name: '{{ k8sSecretName "app-secrets" }}'
          key: api-key

If a chart has no way to consume an existing secret, prefer generating the secret with the chart itself over inlining a value.

Unlike server and job installations, Helm Chart installations do not use the variableGroups field. Any variable group created in the environment is automatically accessible as a Kubernetes secret.

`config`

string or array — optional Service configuration. For Helm charts, this is the values.yaml content passed to the chart.

# As string
config: |
  replicaCount: 3
  persistence:
    enabled: true
    size: 100Gi
  resources:
    limits:
      cpu: 2000m
      memory: 4Gi

# As array with file path
config:
  - path: config/production.yaml

`secrets`

array — optional Secrets to be passed to the Helm chart. Each secret can be generated or get values from blueprint inputs. To share values across installations, use variable groups: all environment variable groups are available to Helm Chart installations as Kubernetes secrets and can be referenced in config via k8sSecretName.

secrets:
  - name: db-credentials
    values:
      - key: password
        valueFromInput:
          name: dbPassword

`secrets[].name`

string — required Name of the secret.

secrets:
  - name: db-credentials

`secrets[].generated`

object — optional Configuration for generating a secret automatically. Cannot be used with values.

secrets:
  - name: api-key
    generated:
      type: random-string
      length: 32

`secrets[].generated.type`

string — required Type of secret to generate. Valid values: random-string, random-bytes, rsa-key, ec-key.

generated:
  type: random-string

`secrets[].generated.length`

integer — optional Length of the random string or bytes to generate. Only valid for random-string and random-bytes types.

generated:
  type: random-string
  length: 64

`secrets[].values`

array — optional Key-value pairs for the secret. Cannot be used with generated.

secrets:
  - name: credentials
    values:
      - key: username
        valueFromInput:
          name: dbUser
      - key: password
        valueFromInput:
          name: dbPassword

`secrets[].values[].key`

string — required Secret key name.

values:
  - key: password

`secrets[].values[].valueFromInput`

object — optional Reference to a blueprint input for the value. If the referenced input has a condition that evaluates to false, this secret key is automatically omitted.

values:
  - key: password
    valueFromInput:
      name: dbPassword

`secrets[].values[].valueFromInput.name`

string — required Name of the blueprint input to get the value from.

valueFromInput:
  name: dbPassword

Examples

kind: ServiceInstallation
metadata:
  name: postgresql-production
spec:
  service: postgresql
  environment: production
  namespace: databases
  releaseChannel: stable
  config: |
    replicaCount: 2
    persistence:
      enabled: true
      size: 100Gi
    resources:
      limits:
        cpu: 2000m
        memory: 4Gi
      requests:
        cpu: 1000m
        memory: 2Gi
  secrets:
    - name: postgres-credentials
      values:
        - key: postgres-password
          valueFromInput:
            name: dbPassword

With generated secrets:

kind: ServiceInstallation
metadata:
  name: redis-production
spec:
  service: redis
  environment: production
  config: |
    auth:
      enabled: true
    replica:
      replicaCount: 3
  secrets:
    - name: redis-password
      generated:
        type: random-string
        length: 32

With variable groups (automatically available, no explicit linking needed):

kind: ServiceInstallation
metadata:
  name: vault-production
spec:
  service: vault
  environment: production
  config: |
    seal:
      key:
        secretKeyRef:
          # All environment variable groups are available as K8s secrets
          name: '{{ k8sSecretName "prod-vault-keys" }}'
          key: seal-key

Multiple secrets:

kind: ServiceInstallation
metadata:
  name: app-production
spec:
  service: app
  environment: production
  secrets:
    - name: database
      values:
        - key: host
          valueFromInput:
            name: dbHost
        - key: password
          valueFromInput:
            name: dbPassword
    - name: api-keys
      generated:
        type: random-string
        length: 64

Services

Environments

Installations

Blueprints

Releases

Properties

`service`

`environment`

`name`

`namespace`

`releaseChannel`

`dependencies`

Variable Groups

Wiring secret refs in your own chart

Third-party and OSS charts

`config`

`secrets`

`secrets[].name`

`secrets[].generated`

`secrets[].generated.type`

`secrets[].generated.length`

`secrets[].values`

`secrets[].values[].key`

`secrets[].values[].valueFromInput`

`secrets[].values[].valueFromInput.name`

Examples

​Properties

​service

​environment

​name

​namespace

​releaseChannel

​dependencies

​Variable Groups

​Wiring secret refs in your own chart

​Third-party and OSS charts

​config

​secrets

​secrets[].name

​secrets[].generated

​secrets[].generated.type

​secrets[].generated.length

​secrets[].values

​secrets[].values[].key

​secrets[].values[].valueFromInput

​secrets[].values[].valueFromInput.name

​Examples

Properties

`service`

`environment`

`name`

`namespace`

`releaseChannel`

`dependencies`

Variable Groups

Wiring secret refs in your own chart

Third-party and OSS charts

`config`

`secrets`

`secrets[].name`

`secrets[].generated`

`secrets[].generated.type`

`secrets[].generated.length`

`secrets[].values`

`secrets[].values[].key`

`secrets[].values[].valueFromInput`

`secrets[].values[].valueFromInput.name`

Examples