Environment Variables Configuration

Environment Variables Configuration

Timonel can load a small declarative environment-variable configuration and turn it into Kubernetes env entries containing literal Helm values or secretKeyRef references.

It does not fetch secret values from external secret stores.

Configuration model

interface EnvVarConfig {
  name: string;
  type: 'value' | 'secret';
  scope?: string;
  defaultValue?: string;
  secretName?: string;
}

YAML configuration

Create env-config.yaml:

- name: LOG_LEVEL
  type: value
  scope: global.env
  defaultValue: info

- name: DATABASE_PASSWORD
  type: secret
  secretName: app-database

Load it:

import { loadEnvVarsConfig } from 'timonel';

const config = loadEnvVarsConfig({
  configPath: './env-config.yaml',
});

JSON files are also supported.

Default lookup paths

When configPath is omitted, Timonel checks the current directory for:

env-config.yaml
env-config.json

If neither file can be loaded, fallbackConfig is returned.

Generate Kubernetes env entries

import { generateEnvVars } from 'timonel';

const env = generateEnvVars(config, {
  defaultScope: 'global.env',
});

A value entry becomes a Helm expression like:

- name: LOG_LEVEL
  value: {{ .Values.global.env.LOG_LEVEL | default "info" }}

A secret entry becomes a Kubernetes secret reference:

- name: DATABASE_PASSWORD
  valueFrom:
    secretKeyRef:
      name: app-database
      key: DATABASE_PASSWORD
      optional: true

Load and generate in one call

import { loadAndGenerateEnvVars } from 'timonel';

const env = loadAndGenerateEnvVars({
  configPath: './env-config.yaml',
  defaultScope: 'global.env',
  fallbackConfig: [
    {
      name: 'LOG_LEVEL',
      type: 'value',
      defaultValue: 'info',
    },
  ],
});

Use with a custom manifest fallback

For a CRD or another object-form resource:

const env = loadAndGenerateEnvVars({
  configPath: './env-config.yaml',
});

chart.addManifest(
  {
    apiVersion: 'example.io/v1',
    kind: 'Worker',
    metadata: { name: 'worker' },
    spec: {
      podTemplate: {
        containers: [
          {
            name: 'worker',
            image: 'example/worker:1.0.0',
            env,
          },
        ],
      },
    },
  },
  'Worker',
);

For standard Kubernetes workloads, prefer the corresponding cdk8s-plus environment APIs when they fit your needs.

Scope behavior

For type: value, the generated values path is:

.Values.<scope>.<name>

If an entry has no explicit scope, defaultScope is used. The default scope is global.env.

Secret behavior

For type: secret:

• secretName selects the referenced Kubernetes Secret;
• if secretName is omitted, the generated name is {{ .Values.secretName }};
• the Secret key is the environment-variable name;
• the current generated reference sets optional: true.

External secret systems

Timonel does not have built-in clients for Vault, AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault in this loader.

A common architecture is:

external secret store
        |
        v
External Secrets / CSI / platform controller
        |
        v
Kubernetes Secret
        |
        v
Timonel-generated secretKeyRef

Do not put secret values directly into values.yaml unless that exposure is explicitly acceptable for your deployment model.

Error and fallback behavior

loadEnvVarsConfig() returns the fallback configuration when loading/parsing fails. If you require configuration to exist, enforce that requirement in your application before chart synthesis.

Security notes

• configuration paths are validated through Timonel's path validation;
• generated expressions are intended for Helm serialization, not shell execution;
• the loader does not make a configuration file a secure secret store;
• keep sensitive input out of logs and committed values files.