Values Deep Dive

You learned that values.yaml contains default configuration and environment-specific files override those defaults. That was enough to deploy basic agents across environments.

But production deployments require more: clarity about which override takes precedence when multiple are specified, validation that required fields are present before rendering, and organizational patterns that keep complex values readable as your chart grows. This lesson teaches the complete values architecture that production charts depend on.

---

What You'll Learn

This lesson covers 8 concepts in 4 groups:

Prerequisites: You should be comfortable with:

• Basic Helm chart structure (Lesson 1)
• Template rendering with {{ .Values }} (Lesson 2)
• YAML syntax (nested objects, lists, strings)
• JSON Schema basics (types, required fields, enums)

Time estimate: 45-60 minutes

---

The Values Override Precedence Hierarchy

When you deploy a Helm chart, values come from multiple sources. Understanding the order matters—if you override something and it doesn't work, you're probably at the wrong level of the hierarchy.

The Hierarchy (Lowest to Highest Priority)

Here's what happens in order, with later sources overriding earlier ones:

1. Chart defaults (values.yaml)
2. Parent chart values (if this is a subchart)
3. Values from -f file.yaml flags (environment-specific files)
4. Command-line --set overrides (highest priority)

Understanding Each Level

Level 1: Chart Defaults (values.yaml)

This is the baseline. Every configuration option your chart supports should have a sensible default here:

Output: This values.yaml is used when you run helm install task-api ./task-api-chart with no overrides.

When Helm renders templates, it replaces {{ .Values.replicaCount }} with 3, {{ .Values.image.tag }} with v1.0.0, etc.

---

Level 2: Environment-Specific Files (-f values-prod.yaml)

When deploying to production, you don't modify values.yaml (it's version-controlled and shared). Instead, you create environment-specific files that override only the values that differ:

Output: When you run:

Helm merges these two YAML files. The result:

Key principle: Only specify values you're changing in environment files. Keep defaults in values.yaml.

---

Level 3: Command-Line --set Overrides

For one-off changes (emergency fixes, testing), you can override values directly via CLI:

This runs at the highest priority. The effective values would have:

• image.tag: v1.0.1 (from --set, overrides both values.yaml and values-prod.yaml)
• agent.logLevel: DEBUG (from --set, overrides values-prod.yaml's WARN)
• Everything else merged as normal

Output: Same structure as before, but with CLI overrides applied last.

---

Practical: Demonstrating the Precedence Hierarchy

Let's verify the precedence with a real example:

Output (Test 1: Defaults):

Output (Test 2: With -f values-prod.yaml):

Output (Test 3: With -f + --set replicas=10):

The pattern is clear: --set beats -f, which beats values.yaml defaults.

---

Checkpoint: Precedence Hierarchy

You've learned how Helm merges values from multiple sources. Quick reference:

Self-check:

1. If you run helm install my-app ./chart -f values-prod.yaml --set replicas=7, and values-prod.yaml has replicas: 5, what's the final replica count?

   Answer7 (--set has highest priority)

2. Which values source should contain passwords and API keys?

   AnswerNone—use Kubernetes Secrets or --set with external secret managers

3. When would you use --set instead of creating a new environment file?

   AnswerEmergency hotfixes, testing new values, or one-off debugging (not for permanent config)

Common mistakes:

• Putting all config in --set (hard to reproduce, not version-controlled)
• Repeating unchanged defaults in environment files (creates maintenance burden)
• Storing secrets in values files (security risk)

---

Designing values.yaml Structure: Flat vs Nested

As your chart grows, values.yaml can become unwieldy. Should you organize values hierarchically or keep them flat? The answer depends on cognitive load and reusability.

The Flat Approach (Simple, Limited)

Advantages:

• Easy to understand (all values visible at once)
• No nested nesting to navigate

Disadvantages:

• Names become verbose (agentName, agentReplicas, agentImage)
• Hard to group related configuration (where does agent logging belong?)
• CLI overrides become tedious: --set agentLogLevel=DEBUG

---

The Nested Approach (Organized, Scalable)

Advantages:

• Clear organization (all agent settings grouped, all database settings grouped)

• Template access is intuitive: {{ .Values.agent.replicas }}

• Environment overrides are cleaner:

  Specification

  WrapCopy

  # values-prod.yamlagent: replicas: 5 config: log

Level: WARN

Not like this (organized by location in template):

The first approach is maintainable. The second scatters related values across different top-level keys.

---

Checkpoint: Values Organization

You've learned how to structure values.yaml for maintainability. Quick reference:

Self-check:

1. Which structure is better for a chart with agent, database, redis, and monitoring configuration?

   AnswerNested—group by concept (agent., database., redis., monitoring.)

2. How do you access agent.config.logLevel in a template?

   Answer {{ .Values.agent.config.logLevel }}

3. What's wrong with organizing values by template file (deployment., service., configMap.*)?

   AnswerScatters related configuration—database password separated from database host just because they're in different templates

Common mistakes:

• Over-nesting (5+ levels deep makes templates hard to read)
• Mixing organizational strategies (some values flat, others nested with no pattern)
• Organizing by template location instead of by concept

---

Environment-Specific Files: The Three-Tier Pattern

Production deployments typically use three environments: development (for testing), staging (for pre-production), and production. Each has different configurations—resource limits, replica counts, security settings, and external dependencies.

The Three Files

File 1: values.yaml (Development Defaults)

This is the baseline—what most developers use locally. Minimal resources, one replica, verbose logging:

Output: When you run helm install task-api ./task-api-chart, you get:

• 1 replica
• Light resource requests
• Verbose logging (DEBUG)
• Development database

---

File 2: values-staging.yaml

Staging mirrors production more closely—multiple replicas, tighter resources, and real external services:

Output: When you run helm install task-api ./task-api-chart -f values-staging.yaml, you get:

• 2 replicas
• Realistic resource limits
• Production-like logging (INFO)
• Staging external services (separate DB, Redis enabled)

---

File 3: values-prod.yaml

Production maximizes availability and performance:

Output: When you run helm install task-api ./task-api-chart -f values-prod.yaml, you get:

• 5 replicas for high availability
• Production-grade resource limits
• Minimal logging (WARN)
• Production external services
• External LoadBalancer access

---

Using Environment Files in Practice

Each command uses the same chart with different configurations. The chart stays in source control, environment files stay in source control, and Helm handles the merging.

---

Checkpoint: Environment-Specific Files

You've learned the three-tier environment pattern. Quick reference:

Self-check:

1. Should values-prod.yaml repeat all values from values.yaml?

   AnswerNo—only override what differs from defaults (replicas, resources, logging, external services)

2. Where should production database passwords be stored?

   AnswerKubernetes Secrets, referenced in templates via secretKeyRef or --set at deploy time

3. What's the advantage of the three-tier pattern over a single values.yaml?

   AnswerSame chart deploys to all environments with appropriate config; changes tracked in version control; minimal duplication

Common mistakes:

• Duplicating all values in environment files (makes updates error-prone)
• Hardcoding secrets in values-prod.yaml (security risk)
• Using different chart versions per environment (defeats purpose of single source)

---

Command-Line --set Overrides

While environment files are preferred (they're version-controlled and documented), --set overrides are useful for debugging, quick tests, and emergency patches. Understanding the syntax is essential.

Basic --set Syntax

Each --set takes the path to the value (using dot notation) and the new value. The chart is installed with those overrides applied.

Output: The effective values have:

• agent.name: custom-agent
• agent.replicas: 10
• agent.config.logLevel: DEBUG
• All other values from values.yaml unchanged

---

--set-string (for String Values)

By default, --set tries to infer the type (number vs string). For values that look like numbers but should be strings, use --set-string:

Why it matters: If your template stores {{ .Values.agent.apiKey }} in an environment variable, it needs to be a string, not a number.

---

--set-file (for Loading from Files)

When you have multi-line values (TLS certificates, JSON configs), loading from a file is cleaner:

The file's contents become the value of agent.customConfig. In your template, you can access it as:

Output: The environment variable contains the entire JSON config from the file.

---

Checkpoint: Command-Line Overrides

You've learned three --set variants for different value types. Quick reference:

Self-check:

1. When would --set agent.port=8000 fail but --set-string agent.port=8000 succeed?

   AnswerWhen template expects string but --set infers number (environment variables need strings)

2. Why use --set-file instead of --set for TLS certificates?

   AnswerCertificates are multi-line and contain special characters; loading from file avoids escaping issues

3. Should you use --set for permanent configuration changes?

   AnswerNo—use environment files (version-controlled, documented). Use --set for temporary/emergency changes only

Common mistakes:

• Using --set for secrets (visible in shell history)
• Not using --set-string for numeric-looking strings (API keys, ports as env vars)
• Forgetting that --set overrides are lost on next deployment (not persisted)

---

Values Schema Validation: values.schema.json

As your chart grows, it's easy to make mistakes: typos in value names, wrong types (string vs number), missing required fields. The chart installs but doesn't work as expected, leading to debugging nightmares.

values.schema.json is a JSON Schema file that validates values before rendering. Helm refuses to render if required fields are missing or types don't match.

Creating a Basic Schema

Place this in task-api-chart/values.schema.json.

---

Schema Validation in Action

Now when you run helm with invalid values, it catches the error:

---

Nested Values and Access Patterns

As your chart grows, accessing deeply nested values in templates becomes essential. Understanding the dot notation and when to use bracket notation saves time.

Dot Notation (Most Common)

This is readable and works for most cases. The template engine navigates the YAML structure using dots.

---

Accessing Values in Loops

When iterating over values, use the correct scope:

In your template:

Output:

---

With Blocks for Scope Management

When accessing nested values repeatedly, with simplifies templates:

Instead of:

The with block sets . to the nested object, reducing repetition.

Output: Same result, but cleaner template code.

---

Checkpoint: Schema Validation and Template Patterns

Template access patterns:

Self-check:

1. What happens if you deploy with --set agent.logLevel=TRACE when schema only allows DEBUG/INFO/WARN/ERROR?

   AnswerHelm rejects with validation error: "Unsupported value" (prevents invalid deployment)

2. When should you use with instead of repeated dot notation?

   AnswerWhen accessing multiple fields from the same nested object (cleaner, less repetition)

3. What's the benefit of schema validation over template-based checks?

   AnswerFails fast before rendering (better error messages), validates types/formats (catches typos), documents valid options

Common mistakes:

• Skipping schema validation (allows invalid values to reach production)
• Making all fields required (prevents environment-specific overrides)
• Using with when you need to access other parts of .Values (changes scope)

---

Best Practices for values.yaml Design

1. Sensible Defaults

Every value should have a default that allows the chart to deploy and function, even if suboptimally:

Not like this (missing defaults):

---

2. Documentation Comments

Use YAML comments in values.yaml to explain what each value does and valid options:

Output: Developers know what each value does, valid options, and environment-specific recommendations without reading the chart code.

---

3. Grouping Related Values

Group values by concept and function:

---

4. No Secrets in values.yaml

Never put passwords, API keys, or tokens in values.yaml. These should come from Kubernetes Secrets or external secret management:

Instead:

Or use --set with Secret values at deploy time:

---

Common Mistakes

Before moving to exercises, review these frequent errors when working with Helm values:

Quick validation checklist before deploying:

---

Exercises

Exercise 3.1: Create values.yaml with Realistic AI Agent Defaults

Create a values.yaml for an AI agent chart with:

• Agent configuration (name, replicas, image)
• Model settings (model name, temperature, max tokens)
• Resource limits (reasonable for a CPU-constrained environment)
• Database connection (PostgreSQL)
• Logging configuration

Solution:

---

Exercise 3.2: Create Environment-Specific Files

Create values-staging.yaml and values-prod.yaml that override the development defaults:

Staging Requirements:

• 2 replicas
• Real production database (postgres-staging.production.svc)
• INFO logging
• gpt-4 model

Production Requirements:

• 5 replicas
• Production database (postgres-prod.production.svc)
• WARN logging
• gpt-4-turbo model
• Higher resource limits

Solution:

---

Exercise 3.3: Verify Override Precedence with helm template

Create a Helm chart and verify that values override in the correct order.

Steps:

Output:

Verify that:

• Default: replicas: "1", logLevel: "DEBUG"
• With -f: replicas: "5", logLevel: "WARN", name unchanged
• With --set: replicas: "10", logLevel: "WARN"

---

Exercise 3.4: Create values.schema.json

Create a JSON Schema that validates:

• agent.replicas is a number between 1-100
• agent.config.logLevel is one of: DEBUG, INFO, WARN, ERROR
• agent.config.modelName is a string (required)
• database.host is a string (required)

Solution:

Save as task-api-chart/values.schema.json.

---

Exercise 3.5: Validate Invalid Values Against Schema

Test that Helm rejects invalid values according to schema:

---

Try With AI

Now it's time to use your understanding of values hierarchy and override precedence to refine a real deployment scenario.

Part 1: Initial Challenge

You're deploying your AI agent to three environments, but the current values setup has issues:

1. Environment files override too much (they repeat defaults they don't change)
2. Production database password is in values-prod.yaml (security issue)
3. No schema validation (invalid log levels are accepted)
4. Developers don't know which values control what (missing documentation)

Ask AI: "Help me redesign our Helm chart values files. We're deploying an AI agent to dev, staging, and production. Create a values.yaml with sensible defaults, values-staging.yaml and values-prod.yaml that only override what differs, and values.schema.json that validates the required fields. Include comments documenting each value."

Part 2: Evaluate AI's Response

Review the AI's suggestions:

• Does values.yaml have sensible defaults for all fields?
• Do environment files only override what differs (not repeat everything)?
• Is values.schema.json complete (required fields, valid enums)?
• Are comments clear about what each value does and valid options?

Part 3: Refine for Your Context

Tell AI: "I missed something in my requirements. The agent needs to support custom API endpoints for different providers (OpenAI, Anthropic, Ollama). Add that to the values structure and schema. Also, the staging environment should use the same replicas as production (for realistic load testing), so only the database connection differs."

Part 4: Validate Your Understanding

Ask AI: "Walk me through the precedence hierarchy. If I run: helm install task-api ./task-api-chart -f values-prod.yaml --set agent.replicas=3, what will the final replica count be? Why?"

AI's answer should explain that --set has highest priority, so replicas will be 3 (not 5 from values-prod.yaml).

Part 5: Final Check

Compare your final values structure to your learning objectives:

• Can you explain the override precedence hierarchy?
• Can you create environment-specific files that only override necessary values?
• Can you write --set overrides for one-off changes?
• Can you create a values.schema.json that prevents invalid deployments?
• Can you design a values.yaml structure that's maintainable as the chart grows?

If all are "yes," you're ready for Lesson 5 (Chart Dependencies). If any are "no," ask AI to clarify that specific concept.

---

Reflect on Your Skill

You built a helm-chart skill in Lesson 0. Test and improve it based on what you learned.

Test Your Skill

Identify Gaps

Ask yourself:

• Did my skill demonstrate the precedence hierarchy (values.yaml < -f file < --set)?
• Did it create environment files that only override what differs?
• Does it include values.schema.json with required fields and type validation?
• Did it organize values by concept (agent., database.) not by template file?

Improve Your Skill

If you found gaps: