Skip to main content
Updated Feb 10, 2026
Version history

Library Charts and Organizational Standardization

In Lessons 1-7, you've built individual Helm charts that deploy applications with templating, hooks, and distribution strategies. But what happens when you have 10 microservices? Do you repeat the same labels, resource probes, and annotations in each chart? What if your security team requires specific SecurityContext defaults across all deployments?

This lesson introduces library charts—a Helm pattern that solves this through reusable templates. Instead of duplicating patterns across charts, you encode them once in a library chart that all application charts consume. Your organization then has a single source of truth for labels, probes, resource defaults, and organizational standards.

By the end of this lesson, you'll understand how library charts enforce consistency across your platform without forcing teams into rigid constraints.

What You'll Learn​

This lesson covers 8 concepts organized into 3 groups:

Concept GroupConceptsWhat You'll Build
Library Chart Fundamentals1-2Understand library chart type and installation restrictions
Creating Reusable Templates3-5Build organizational templates and consume them in applications
Advanced Patterns6-8Implement overrides, enterprise use cases, and template inheritance

Prerequisites:

  • Completed Lessons 1-4 (Helm basics, templating, values)
  • Understanding of include function and template helpers
  • Experience creating application charts

Time Estimate: 45 minutes

Concept 1: Library Chart Type​

Library charts declare their purpose in Chart.yaml with type: library. This tells Helm that this chart exists to be included as a dependency, not to be installed directly.

Creating a Library Chart​

Start with the basic structure:

mkdir -p org-standards/templates

Create org-standards/Chart.yaml:

apiVersion: v2
name: org-standards
description: "Organizational standards for labels, probes, and security"
type: library
version: 1.0.0

Create org-standards/values.yaml with organizational defaults:

organization:
  name: "my-company"
  team: "platform"
  environment: "dev"

commonLabels:
  managed-by: "helm"
  org: "my-company"

commonAnnotations:
  doc-link: "https://internal.docs/deployments"

securityDefaults:
  runAsNonRoot: true
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false

Output:

org-standards/
├── Chart.yaml
├── values.yaml
└── templates/

$ cat org-standards/Chart.yaml
apiVersion: v2
name: org-standards
description: "Organizational standards for labels, probes, and security"
type: library
version: 1.0.0

The type: library field distinguishes this chart from application charts (which have no type field or type: application).

Concept 2: Why Library Charts Cannot Be Installed Directly​

Helm refuses to install library charts directly. They contain only template definitions, not complete deployable resources.

Testing the Restriction​

Try installing the library chart:

cd org-standards

# Attempt to install library chart
helm install my-org . --dry-run=client

Output:

error: chart "org-standards" is a library chart. Library charts
are not installable. See https://helm.sh/docs/topics/library_charts/
for more information.

This restriction is intentional. Library charts have no .Chart.Name release—they're meant to provide helper functions that application charts use. Installing them directly would create an empty release with no resources, providing no value.

Checkpoint: Library Chart Fundamentals​

Quick Reference:

  • Library charts: type: library in Chart.yaml, cannot be installed directly
  • Purpose: Provide reusable templates consumed by application charts
  • Usage: Included as dependencies, not standalone releases

Self-Check Questions:

  1. What happens if you try to helm install a library chart?
  2. Why does Helm prevent library chart installation?
  3. Where does the library chart declaration go in Chart.yaml?

Answers:

  1. Helm returns an error: "chart is a library chart. Library charts are not installable"
  2. Library charts contain only template definitions, not complete deployable resources
  3. type: library field in Chart.yaml

Concept 3: Common Templates for Organizational Consistency​

Create reusable templates in the library chart that enforce organizational patterns.

Creating Labels Template​

Create org-standards/templates/_labels.tpl:

{{- define "org-standards.labels" -}}
app.kubernetes.io/name: {{ include "org-standards.name" . }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
org: {{ .Values.organization.name }}
team: {{ .Values.organization.team }}
env: {{ .Values.organization.environment }}
{{- end }}

{{- define "org-standards.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

Creating Common Annotations Template​

Create org-standards/templates/_annotations.tpl:

{{- define "org-standards.annotations" -}}
documentation: {{ .Values.commonAnnotations.doc-link }}
updated-at: {{ now | date "2006-01-02T15:04:05Z07:00" }}
{{- end }}

Creating Probes Template​

Create org-standards/templates/_probes.tpl:

{{- define "org-standards.livenessProbe" -}}
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3
{{- end }}

{{- define "org-standards.readinessProbe" -}}
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 2
{{- end }}

Output:

org-standards/templates/
├── _annotations.tpl
├── _labels.tpl
└── _probes.tpl

$ ls -la org-standards/templates/
total 48
-rw-r--r--  1 user  staff  285 org-standards/templates/_annotations.tpl
-rw-r--r--  1 user  staff  412 org-standards/templates/_labels.tpl
-rw-r--r--  1 user  staff  518 org-standards/templates/_probes.tpl

These templates define labels, annotations, and probes that any application chart can use without reimplementation.

Concept 4: Consuming Library Charts as Dependencies​

Application charts declare library charts as dependencies in Chart.yaml.

Create Application Chart with Library Dependency​

mkdir -p my-api/templates

Create my-api/Chart.yaml with library dependency:

apiVersion: v2
name: my-api
description: "AI agent API service"
type: application
version: 1.0.0
appVersion: "1.0"
dependencies:
  - name: org-standards
    version: "1.0.0"
    repository: "file://../org-standards"
    condition: org-standards.enabled

Create my-api/values.yaml:

appName: my-api
replicaCount: 2
image:
  repository: my-org/my-api
  tag: "1.0.0"

# Enable the library chart
org-standards:
  enabled: true
  organization:
    name: my-company
    team: platform
    environment: prod

Update Helm dependencies:

helm dependency update my-api/

Output:

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "file://../org-standards" repo
Saving 1 charts
Downloading org-standards from repo file://../org-standards
...Deleting outdated charts

$ ls -la my-api/charts/
total 32
drwxr-xr-x  4 user  staff  128 org-standards/

The helm dependency update command fetches the library chart and places it in my-api/charts/org-standards/.

Concept 5: Using include to Pull Library Templates​

Application charts use include function to reference templates from library charts.

Creating Application Deployment Using Library Templates​

Create my-api/templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Values.appName }}
  labels:
    {{- include "org-standards.labels" . | nindent 4 }}
  annotations:
    {{- include "org-standards.annotations" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Values.appName }}
  template:
    metadata:
      labels:
        app: {{ .Values.appName }}
        {{- include "org-standards.labels" . | nindent 8 }}
    spec:
      containers:
      - name: api
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        ports:
        - containerPort: 8080
        {{- include "org-standards.livenessProbe" . | nindent 8 }}
        {{- include "org-standards.readinessProbe" . | nindent 8 }}
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi

Output:

$ helm template my-api .
---
# Source: my-api/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-api
  labels:
    app.kubernetes.io/name: my-api
    app.kubernetes.io/version: "1.0"
    app.kubernetes.io/managed-by: Helm
    org: my-company
    team: platform
    env: prod
  annotations:
    documentation: https://internal.docs/deployments
    updated-at: "2025-12-23T10:15:30Z"
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-api
  template:
    metadata:
      labels:
        app: my-api
        app.kubernetes.io/name: my-api
        app.kubernetes.io/version: "1.0"
        app.kubernetes.io/managed-by: Helm
        org: my-company
        team: platform
        env: prod
    spec:
      containers:
      - name: api
        image: "my-org/my-api:1.0.0"
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 2
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi

The include function pulls templates from the library chart and injects them into the deployment, automatically inheriting organization labels and probes.

Concept 6: Override Patterns for Application-Specific Values​

Applications override library defaults through the values.yaml hierarchy while maintaining organizational standards.

Creating Multiple Application Charts with Overrides​

Application 1: Web service

mkdir -p web-service/templates

Create web-service/Chart.yaml:

apiVersion: v2
name: web-service
description: "Web frontend"
type: application
version: 1.0.0
dependencies:
  - name: org-standards
    version: "1.0.0"
    repository: "file://../org-standards"

Create web-service/values.yaml:

appName: web-service
replicaCount: 3  # More replicas for web traffic

image:
  repository: my-org/web-service
  tag: "2.1.0"

org-standards:
  enabled: true
  organization:
    name: my-company
    team: frontend  # Override team
    environment: prod

  # Override default probes for web service
  customProbes:
    livenessProbe:
      httpGet:
        path: /api/health
        port: 8080
      initialDelaySeconds: 15  # Faster startup

Application 2: Background worker

mkdir -p bg-worker/templates

Create bg-worker/Chart.yaml:

apiVersion: v2
name: bg-worker
description: "Background job processor"
type: application
version: 1.0.0
dependencies:
  - name: org-standards
    version: "1.0.0"
    repository: "file://../org-standards"

Create bg-worker/values.yaml:

appName: bg-worker
replicaCount: 2

image:
  repository: my-org/bg-worker
  tag: "1.5.0"

org-standards:
  enabled: true
  organization:
    name: my-company
    team: backend  # Override team
    environment: prod

Output:

# Web service inherits all org-standards labels/probes
$ helm template web-service . | grep -A 5 labels:
  labels:
    app.kubernetes.io/name: web-service
    org: my-company
    team: frontend  # Team overridden in values

# Background worker gets same labels
$ helm template bg-worker . | grep -A 5 labels:
  labels:
    app.kubernetes.io/name: bg-worker
    org: my-company
    team: backend  # Different team

Each application overrides organizational defaults for its context while maintaining consistency through the library chart.

Checkpoint: Creating and Consuming Library Templates​

Quick Reference:

  • Template files: Prefix with _ (e.g., _labels.tpl), define with {{- define "name" -}}
  • Dependency setup: Add to Chart.yaml dependencies, run helm dependency update
  • Template usage: {{- include "org-standards.labels" . | nindent 4 }}
  • Override values: Pass through org-standards: section in application values.yaml

Self-Check Questions:

  1. How do application charts reference library chart templates?
  2. What command fetches library chart dependencies?
  3. How can applications override library default values?

Answers:

  1. Using include function: {{- include "library-name.template-name" . }}
  2. helm dependency update <chart-directory>/
  3. Through values.yaml hierarchy under the library chart's name (e.g., org-standards:)

Concept 7: Enterprise Use Cases​

Library charts solve real organizational problems: enforcing security policies, maintaining labeling conventions, and standardizing resource defaults across hundreds of deployments.

Common Enterprise Library Chart Patterns​

Pattern 1: Security Enforcement

Create org-standards/templates/_security.tpl:

{{- define "org-standards.securityContext" -}}
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000
  capabilities:
    drop:
      - ALL
  readOnlyRootFilesystem: true
{{- end }}

All deployments automatically get security hardening without individual configuration.

Pattern 2: Compliance Labels

Add to org-standards/values.yaml:

complianceLabels:
  audit-enabled: "true"
  pci-dss: "required"
  hipaa: "not-applicable"
  gdpr-processing: "true"

Platform teams enforce compliance requirements that auditors verify through labels.

Pattern 3: Cost Attribution

Create org-standards/templates/_costAttribution.tpl:

{{- define "org-standards.costLabels" -}}
cost-center: {{ .Values.costCenter }}
project: {{ .Values.projectName }}
owning-team: {{ .Values.organization.team }}
{{- end }}

Finance teams track costs per team/project through labels injected by the library.

Concept 8: Template Inheritance and Overrides​

Templates in library charts can be extended or overridden by application charts, creating a flexible inheritance pattern.

Base Probe Template with Override Points​

Create org-standards/templates/_probes-extended.tpl:

{{- define "org-standards.livenessProbe" -}}
livenessProbe:
  {{- if .Values.probes.liveness.custom }}
  {{- toYaml .Values.probes.liveness.custom | nindent 2 }}
  {{- else }}
  httpGet:
    path: {{ .Values.probes.liveness.path | default "/health" }}
    port: {{ .Values.probes.liveness.port | default 8080 }}
  initialDelaySeconds: {{ .Values.probes.liveness.initialDelay | default 30 }}
  periodSeconds: {{ .Values.probes.liveness.period | default 10 }}
  timeoutSeconds: {{ .Values.probes.liveness.timeout | default 5 }}
  failureThreshold: {{ .Values.probes.liveness.failureThreshold | default 3 }}
  {{- end }}
{{- end }}

Application Chart Overrides Probe Behavior​

Create my-app/values.yaml:

# Standard org-standards usage
org-standards:
  enabled: true
  organization:
    name: my-company
    team: platform

# Override probe behavior for specific app
probes:
  liveness:
    path: /custom-health-check
    initialDelay: 60
    failureThreshold: 5

Output:

$ helm template my-app . | grep -A 10 "livenessProbe:"
livenessProbe:
  httpGet:
    path: /custom-health-check  # Overridden
    port: 8080
  initialDelaySeconds: 60  # Overridden
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 5  # Overridden

The library chart defines structure and defaults, but applications customize behavior through values without modifying templates.

Checkpoint: Advanced Patterns​

Quick Reference:

  • Enterprise patterns: Security enforcement, compliance labels, cost attribution
  • Template inheritance: Use default function and conditional logic for overrides
  • Flexibility: Provide escape hatches (.custom blocks) for complete overrides

Self-Check Questions:

  1. How can library charts enforce security policies across all deployments?
  2. What's the pattern for allowing applications to override library defaults?
  3. Why include compliance labels in library charts instead of application charts?

Answers:

  1. Define security templates (SecurityContext, resource limits) that all apps include automatically
  2. Use default function and conditional logic: {{ .Values.custom | default .Values.libraryDefault }}
  3. Ensures consistency across all deployments, simplifies auditing, prevents human error

Common Mistakes​

Before starting the exercises, be aware of these common pitfalls:

Mistake 1: Forgetting type: library in Chart.yaml​

Problem: Creating a library chart without declaring the type Symptom: Chart can be installed but produces empty release Fix: Add type: library to Chart.yaml

Mistake 2: Using Library Chart Name Instead of Template Name​

Problem: {{- include "org-standards" . }} instead of {{- include "org-standards.labels" . }} Symptom: Error: "template: no template "org-standards" associated with template" Fix: Reference the full template name defined in library chart

Mistake 3: Incorrect Dependency Repository Path​

Problem: repository: "../org-standards" instead of repository: "file://../org-standards" Symptom: helm dependency update fails to find chart Fix: Use file:// prefix for local file paths

Mistake 4: Not Running helm dependency update​

Problem: Adding dependency to Chart.yaml but not updating dependencies Symptom: Template errors: "template "org-standards.labels" not found" Fix: Run helm dependency update after modifying Chart.yaml dependencies

Mistake 5: Overriding in Wrong Values Section​

Problem: Putting overrides at root level instead of under library chart name Symptom: Library chart ignores custom values, uses defaults Fix: Nest overrides under library chart name:

org-standards:  # Library chart name
  organization:
    team: frontend  # Override here

Mistake 6: Hardcoding Values in Library Templates​

Problem: Defining fixed values in library templates instead of reading from values.yaml Symptom: Applications can't customize behavior without forking library Fix: Use {{ .Values.fieldName | default "fallback" }} pattern

Exercises​

Exercise 8.1: Create a Library Chart​

Create your own library chart with organizational standards.

Steps:

  1. Create directory: mkdir -p org-lib/templates
  2. Create Chart.yaml with type: library
  3. Create values.yaml with default labels and annotations
  4. Create _helpers.tpl with common label template

Validation: helm lint org-lib/ should show no errors

Expected outcome:

  • Chart.yaml contains type: library
  • values.yaml has default organization metadata
  • _helpers.tpl defines reusable label template

Exercise 8.2: Verify Library Chart Cannot Be Installed​

Attempt to install the library chart and observe Helm's protection.

Steps:

  1. Run: helm install test org-lib/ --dry-run=client
  2. Observe the error message

Expected error:

error: chart "org-lib" is a library chart. Library charts are not installable.

Exercise 8.3: Create Organizational Templates​

Add security context, resource requests, and probe templates to your library.

Steps:

  1. Create _security.tpl with SecurityContext template
  2. Create _resources.tpl with resource requests/limits
  3. Create _probes.tpl with liveness/readiness probes

Validation: helm lint org-lib/ should succeed

Exercise 8.4: Create Application Chart with Library Dependency​

Build an application chart that declares the library as a dependency.

Steps:

  1. Create app chart directory: mkdir -p my-service/templates
  2. Add library dependency in Chart.yaml
  3. Run: helm dependency update my-service/

Validation: ls my-service/charts/ should show org-lib

Exercise 8.5: Use include to Pull Library Templates​

Create a deployment that uses library templates.

Steps:

  1. Create templates/deployment.yaml in application chart
  2. Use include "org-lib.labels" . for labels
  3. Use include "org-lib.livenessProbe" . for probes
  4. Run: helm template my-service .

Validation: Template output includes labels and probes from library

Exercise 8.6: Override Library Defaults​

Modify application values to override library probe defaults.

Steps:

  1. Add probe customization to values.yaml
  2. Modify templates/deployment.yaml to use conditional overrides
  3. Run: helm template my-service . twice:
    • First with defaults
    • Then with custom values

Validation: Second template output uses custom probe paths/timings

Try With AI​

Part 1: Design Library Chart Structure

Ask AI: "I have 5 microservices that all need the same Kubernetes labels (organization, team, cost-center), security context (runAsNonRoot, readOnlyRootFilesystem), and health check probes. I want to avoid repeating this in each service's chart. How would I structure a library chart to enforce these standards across all services?"

Part 2: Evaluate the Recommendation

Review AI's response. Ask yourself:

  • Does the recommendation include type: library in Chart.yaml?
  • Does it separate reusable templates (helpers) from application logic?
  • Can all 5 services consume this single library without modification?

Part 3: Request Implementation Guidance

Tell AI: "I need the library to provide templates for common labels, security context, and probes. The application charts should be able to override the probe paths (some use /health, others use /api/health-check). Walk me through how to structure the template conditionals so apps can override without duplicating code."

Part 4: Test the Pattern

Ask AI: "Show me how an application chart would declare this library as a dependency and use the library's label template. I want to see the Chart.yaml, values.yaml, and a sample deployment.yaml that pulls in the library templates."

Part 5: Validate the Approach

Ask yourself:

  • Does the application chart dependency declaration match library chart naming?
  • Can I see which values override organizational defaults?
  • Is the include syntax correct for pulling templates from dependency charts?
  • Would this pattern scale to 10+ applications without duplication?

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​

Using my helm-chart skill, create a library chart with organizational standards.
Does my skill understand type: library and template sharing?

Identify Gaps​

Ask yourself:

  • Did my skill create a chart with type: library in Chart.yaml?
  • Did it explain why library charts cannot be installed directly?
  • Does it demonstrate creating reusable templates (_helpers.tpl patterns)?
  • Did it show how application charts consume library dependencies?

Improve Your Skill​

If you found gaps:

My helm-chart skill is missing [library chart patterns / organizational standards].
Update it to include:
- type: library declaration in Chart.yaml
- Reusable templates for labels, annotations, probes, security
- Naming convention: library-name.template-name
- Application charts declaring library dependencies
- Using include to pull library templates
- Override patterns through values hierarchy
- Enterprise use cases (security, compliance, cost attribution)