Configuration

Field Ordering Rules

kfix applies Kubernetes-aware field ordering to make manifests more readable and consistent. Fields are ordered according to their importance and common usage patterns.

Top-Level Fields

Resource-level fields are ordered:

1. apiVersion - API version of the resource

2. kind - Type of Kubernetes resource

3. metadata - Resource metadata

4. spec - Resource specification

5. data - ConfigMap/Secret data

6. status - Resource status (typically read-only)

Example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
status:
  availableReplicas: 3

Metadata Fields

Within metadata, fields are ordered:

1. name - Resource name (required)

2. namespace - Namespace location

3. labels - Label selectors

4. annotations - Additional metadata

5. Other fields (alphabetically)

Example:

metadata:
  name: myapp
  namespace: production
  labels:
    app: myapp
    version: v1.0.0
  annotations:
    description: "My application"

Container Spec Fields

Within container specifications, fields are ordered:

1. name - Container name

2. image - Container image

3. imagePullPolicy - Image pull strategy

4. command - Entrypoint override

5. args - Arguments to command

6. workingDir - Working directory

7. ports - Exposed ports

8. env - Environment variables

9. resources - Resource requests/limits

10. volumeMounts - Volume mount points

11. livenessProbe - Liveness health check

12. readinessProbe - Readiness health check

13. startupProbe - Startup health check

14. lifecycle - Lifecycle hooks

15. securityContext - Security settings

Example:

containers:
- name: app
  image: myapp:1.0.0
  command: ["/app"]
  args: ["--config=/etc/app/config.yaml"]
  ports:
  - containerPort: 8080
  env:
  - name: LOG_LEVEL
    value: info
  resources:
    limits:
      memory: 512Mi
      cpu: 500m
    requests:
      memory: 256Mi
      cpu: 250m
  volumeMounts:
  - name: config
    mountPath: /etc/app
  livenessProbe:
    httpGet:
      path: /healthz
      port: 8080

Pod Spec Fields

Within pod specifications, fields are ordered:

1. replicas - Number of replicas (for Deployments/StatefulSets)

2. selector - Label selector

3. template - Pod template

4. serviceName - Service name (for StatefulSets)

5. serviceAccountName - Service account

6. serviceAccount - Legacy service account

7. automountServiceAccountToken - Token mounting

8. nodeSelector - Node selection

9. affinity - Pod affinity rules

10. tolerations - Node tolerations

11. initContainers - Init containers

12. containers - Main containers

13. volumes - Volume definitions

14. restartPolicy - Restart behavior

15. terminationGracePeriodSeconds - Graceful shutdown time

Example:

spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      serviceAccountName: myapp
      containers:
      - name: app
        image: myapp:1.0.0
      volumes:
      - name: config
        configMap:
          name: myapp-config
      restartPolicy: Always

Indentation Settings

Default: 2 Spaces

kfix uses 2-space indentation by default, which is the Kubernetes standard:

apiVersion: v1
kind: Pod
metadata:
  name: myapp
spec:
  containers:
  - name: app
    image: myapp:1.0.0

Custom Indentation

Use the --indent flag to customize:

kfix format --indent 4 deployment.yaml

Output with 4 spaces:

apiVersion: v1
kind: Pod
metadata:
    name: myapp
spec:
    containers:
    - name: app
      image: myapp:1.0.0

Formatting Behavior

What kfix Does

✓ Reorders fields according to K8s conventions

✓ Applies consistent indentation

✓ Formats nested structures (containers, volumes, etc.)

✓ Handles multi-document YAML files

✓ Preserves comments (where possible)

✓ Maintains data types (strings, numbers, booleans)

What kfix Does NOT Do

✗ Fix malformed YAML syntax

✗ Validate resource schema

✗ Add missing required fields

✗ Modify resource logic or behavior

✗ Convert between API versions

✗ Apply cluster-specific policies

Limitations

Valid YAML Required

kfix requires syntactically valid YAML. It will reject:

# Invalid indentation
metadata:
  name: test
   namespace: default  # Incorrect indent

# Missing colons
metadata
  name: test

# Unclosed quotes
metadata:
  name: "test

Kubernetes Resources Only

kfix only formats files with apiVersion and kind fields:

# Will be formatted
apiVersion: v1
kind: ConfigMap
data:
  key: value

# Will be rejected (no apiVersion/kind)
data:
  key: value

Future Configuration

Configuration File Support

Planned support for .kfix.yaml or .kfix.yml configuration files.

Future configuration options:

• Custom field ordering preferences

• Field exclusion rules

• Resource-type-specific formatting

• Indentation per resource type

• Comment preservation strategies

Example future config:

# .kfix.yaml
indent: 2

fieldOrder:
  container:
    - name
    - image
    - ports
    - env

excludeFields:
  - status
  - managedFields

Stay tuned for updates at: https://github.com/amaanx86/kfix