Guides/Configuration File Structure

6 min read

Beginner

Understanding Configuration File Structure

Learn how to read, understand, and modify production configuration files. This guide covers the anatomy of different configuration formats and best practices for organizing your configuration files.

Common Configuration File Types

YAML

.yml, .yaml

Human-readable data serialization standard

Commonly used in:

KubernetesDocker ComposeGitHub ActionsAnsible

Example: docker-compose.yml

JSON

.json

Lightweight data-interchange format

Commonly used in:

Package managersAPI configsTerraformVS Code

Example: package.json

Dockerfile

Instructions for building Docker images

Commonly used in:

DockerContainer registriesCI/CD pipelines

Example: Dockerfile

Environment

.env

Environment variables and secrets

Commonly used in:

Application configsSecret managementDeployment

Example: .env.production

Configuration File Anatomy

Docker Compose Structure

A typical docker-compose.yml file defines services, networks, and volumes:

# Docker Compose file structure
version: '3.8'                    # Compose file format version

services:                         # Define your application services
  web:                           # Service name
    build: .                     # Build context (Dockerfile location)
    ports:                       # Port mapping (host:container)
      - "3000:3000"
    environment:                 # Environment variables
      - NODE_ENV=production
    depends_on:                  # Service dependencies
      - database
    
  database:                      # Database service
    image: postgres:14           # Docker image to use
    environment:                 # Database configuration
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:                     # Persistent data storage
      - postgres_data:/var/lib/postgresql/data

volumes:                         # Named volumes definition
  postgres_data:

Key Sections

• version: Compose file format
• services: Application components
• volumes: Data persistence
• networks: Service communication

Best Practices

• Use specific image tags
• Define health checks
• Set resource limits
• Use named volumes

Kubernetes YAML Structure

Kubernetes manifests follow a standard structure with metadata, spec, and status:

# Kubernetes Deployment manifest
apiVersion: apps/v1              # API version
kind: Deployment                 # Resource type

metadata:                        # Resource metadata
  name: web-app                  # Resource name
  namespace: production          # Namespace (optional)
  labels:                        # Key-value pairs for organization
    app: web-app
    version: v1.0.0

spec:                           # Desired state specification
  replicas: 3                   # Number of pod instances
  selector:                     # Pod selection criteria
    matchLabels:
      app: web-app
  template:                     # Pod template
    metadata:
      labels:
        app: web-app
    spec:                       # Pod specification
      containers:               # Container definitions
      - name: web-app
        image: myapp:v1.0.0     # Container image
        ports:                  # Container ports
        - containerPort: 3000
        env:                    # Environment variables
        - name: NODE_ENV
          value: production
        resources:              # Resource limits/requests
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi

Required Fields

• apiVersion: API group and version
• kind: Resource type
• metadata: Name, labels, annotations
• spec: Desired state

Key Concepts

• Resources define desired state
• Labels organize and select objects
• Namespaces provide isolation
• Specs are declarative

File Organization Best Practices

Directory Structure

Organize your configuration files in a logical directory structure:

project-root/
├── docker/                     # Docker-related files
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── docker-compose.prod.yml
├── kubernetes/                 # Kubernetes manifests
│   ├── namespace.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── ingress.yaml
├── configs/                    # Application configs
│   ├── nginx.conf
│   ├── database.yml
│   └── logging.json
├── environments/               # Environment-specific configs
│   ├── .env.development
│   ├── .env.staging
│   └── .env.production
└── scripts/                    # Deployment scripts
    ├── deploy.sh
    └── backup.sh

Organization Tips

• Group files by technology or environment
• Use clear, descriptive file names
• Keep environment-specific configs separate
• Include README files for complex setups

Naming Conventions

Environment Suffixes

• .dev - Development
• .staging - Staging
• .prod - Production

Service Prefixes

• web- - Frontend services
• api- - Backend APIs
• db- - Database services

Version Control

Include in Git

• Configuration templates
• Docker files
• Kubernetes manifests
• Documentation

Exclude from Git

• .env files with secrets
• Local development overrides
• Temporary configuration files
• Build artifacts

Common Configuration Patterns

Environment Variables

Use environment variables for configuration that changes between deployments

Examples:

DATABASE_URL, API_KEY, NODE_ENV

Config Files

Use configuration files for complex settings and application logic

Examples:

nginx.conf, webpack.config.js, jest.config.js

Secret Management

Use dedicated secret management for sensitive information

Examples:

AWS Secrets Manager, Kubernetes Secrets, HashiCorp Vault

File Type Quick Reference

YAML.yml, .yaml

JSON.json

Environment.env

DockerDockerfile

Terraform.tf

Example Configurations

Next.js Production Docker PostgreSQL Kubernetes Microservices

Next Steps

Security Best Practices Deployment Checklist

Previous: Getting Started Next: Security Best Practices