Configuration Schema

This document describes all configuration files and their schemas for infctl-cli.

Configuration Files Overview

infctl-cli uses two main configuration files:

1. base.json - Base configuration for retry behavior
2. config.json - Project-specific configuration for logging and deployment

Both files are auto-generated with defaults if they don’t exist.

---

Base Configuration (base.json)

Controls retry behavior for failed pipeline steps.

Location

• Default: ./base.json (current working directory)
• Override: --base-config=<path>

Schema

{
  "retry_delay_seconds": 3
}

Fields

Field	Type	Required	Default	Description
retry_delay_seconds	integer	Yes	3	Number of seconds to wait before retrying a failed step

Example

{
  "retry_delay_seconds": 5
}

Auto-Generation

If base.json does not exist when the application starts, it will be automatically created with default values:

{
  "retry_delay_seconds": 3
}

---

Project Configuration (config.json)

Controls logging, deployment mode, and pipeline file location.

Location

• Default: ./config.json (current working directory)
• Override: --project-config=<path>

Schema

{
  "log_format": "full",
  "deployment_file": "infra/pipelines/dev/pipeline.json",
  "deployment_type": "development",
  "deployment_mode": "json"
}

Fields

Field	Type	Required	Default	Valid Values	Description
log_format	string	Yes	”full”	full, basic, none	Structured logging format
deployment_file	string	Yes	(from -f flag)	Any valid file path	Path to pipeline JSON file
deployment_type	string	Yes	”development”	development, pre-production, production	Deployment environment type
deployment_mode	string	Yes	”json”	json, api	Pipeline execution mode (api not yet implemented)

Field Details

log_format

Controls the verbosity and format of log output:

• full: Detailed structured logs with timestamps, levels, and all metadata
• basic: Simplified log output with essential information
• none: Minimal output, only critical messages

Can be overridden by LOG_FORMAT environment variable.

deployment_file

Path to the JSON file containing pipeline steps. Must be a valid, existing file path.

• Required via -f or --deployment-file flag
• Validated on startup to ensure file exists

deployment_type

Identifies the deployment environment:

• development: Local or dev environment
• pre-production: Staging/pre-prod environment
• production: Production environment

Used for validation and logging context.

deployment_mode

Determines how pipelines are executed:

• json: Load and execute pipeline from JSON file (currently supported)
• api: Execute pipeline via API endpoints (not yet implemented)

Can be overridden by DEPLOYMENT_MODE environment variable.

Example Configurations

Development Configuration

{
  "log_format": "full",
  "deployment_file": "infra/pipelines/dev/k3d/pipeline.json",
  "deployment_type": "development",
  "deployment_mode": "json"
}

Production Configuration

{
  "log_format": "basic",
  "deployment_file": "infra/pipelines/prod/deploy.json",
  "deployment_type": "production",
  "deployment_mode": "json"
}

Minimal Logging Configuration

{
  "log_format": "none",
  "deployment_file": "pipeline.json",
  "deployment_type": "development",
  "deployment_mode": "json"
}

Auto-Generation

If config.json does not exist when the application starts, it will be automatically created with the deployment file from the -f flag:

{
  "log_format": "full",
  "deployment_file": "<value-from-f-flag>",
  "deployment_type": "development",
  "deployment_mode": "json"
}

Validation

The application validates the project configuration on startup:

1. log_format: Must be one of full, basic, or none
2. deployment_file: Must exist and be accessible
3. deployment_mode: Must be json or api
4. deployment_type: Must be development, pre-production, or production

If validation fails, the application exits with an error message.

---

Pipeline Configuration (Pipeline JSON Files)

Pipeline files define the sequence of steps to execute.

Location

• Specified via -f or --deployment-file flag
• Common locations:
  • infra/pipelines/dev/
  • infra/pipelines/prod/

Schema

Pipeline files are JSON arrays of step objects:

[
  {
    "name": "step description",
    "function": "functionName",
    "params": ["param1", "param2"],
    "retryCount": 0,
    "shouldAbort": true
  }
]

Step Fields

Field	Type	Required	Description
name	string	Yes	Human-readable description of what the step does
function	string	Yes	Name of the function to execute (must be in functionMap)
params	array of strings	Yes	Parameters to pass to the function
retryCount	integer	Yes	Number of times to retry step on failure (0 = no retry)
shouldAbort	boolean	Yes	If true, abort entire pipeline on step failure; if false, continue

Example Pipeline Files

Simple Single-Step Pipeline

[
  {
    "name": "run a successful job",
    "function": "RunCommand",
    "params": ["./scripts/success.sh"],
    "retryCount": 0,
    "shouldAbort": true
  }
]

Multi-Step Pipeline with Retry

[
  {
    "name": "ensure namespace exists",
    "function": "k8sNamespaceExists",
    "params": ["infctl"],
    "retryCount": 3,
    "shouldAbort": true
  },
  {
    "name": "create php configmap",
    "function": "RunCommand",
    "params": ["./scripts/create_php_configmap_ctl.sh"],
    "retryCount": 2,
    "shouldAbort": true
  },
  {
    "name": "apply kubernetes manifests",
    "function": "RunCommand",
    "params": ["kubectl apply -f manifests/"],
    "retryCount": 1,
    "shouldAbort": true
  }
]

Pipeline with Non-Critical Steps

[
  {
    "name": "deploy application",
    "function": "RunCommand",
    "params": ["kubectl apply -f deploy.yaml"],
    "retryCount": 2,
    "shouldAbort": true
  },
  {
    "name": "run smoke tests",
    "function": "RunCommand",
    "params": ["./tests/smoke.sh"],
    "retryCount": 0,
    "shouldAbort": false
  },
  {
    "name": "send notification",
    "function": "RunCommand",
    "params": ["./notify.sh deployment-complete"],
    "retryCount": 0,
    "shouldAbort": false
  }
]

---

Environment Variables

Environment variables can override configuration file values:

Variable	Overrides	Valid Values	Description
DEPLOYMENT_MODE	deployment_mode in config.json	json, api	Pipeline execution mode
LOG_FORMAT	log_format in config.json	full, basic, none	Log output format
LOG_FILE	N/A	Any valid file path	Path to write logs to (default: stdout)
DEBUG	N/A	1	Enable debug output including app state JSON dump

Example Usage

# Override log format to none
LOG_FORMAT=none infctl-cli -f pipeline.json

# Enable debug mode and log to file
DEBUG=1 LOG_FILE=/tmp/infctl.log infctl-cli -f pipeline.json

# Override deployment mode
DEPLOYMENT_MODE=json infctl-cli -f pipeline.json

---

Configuration Priority

Configuration values are resolved in the following order (highest priority first):

1. Environment Variables (e.g., LOG_FORMAT, DEPLOYMENT_MODE)
2. Command Line Flags (e.g., --deployment-file)
3. Configuration Files (config.json, base.json)
4. Auto-Generated Defaults

---

Example: Complete Setup

Directory Structure

project/
├── base.json
├── config.json
└── infra/
    └── pipelines/
        └── dev/
            └── pipeline.json

base.json

{
  "retry_delay_seconds": 5
}

config.json

{
  "log_format": "full",
  "deployment_file": "infra/pipelines/dev/pipeline.json",
  "deployment_type": "development",
  "deployment_mode": "json"
}

infra/pipelines/dev/pipeline.json

[
  {
    "name": "ensure namespace",
    "function": "k8sNamespaceExists",
    "params": ["my-app"],
    "retryCount": 2,
    "shouldAbort": true
  },
  {
    "name": "deploy app",
    "function": "RunCommand",
    "params": ["kubectl apply -f k8s/"],
    "retryCount": 1,
    "shouldAbort": true
  }
]

Run Command

infctl-cli -f infra/pipelines/dev/pipeline.json

---

Notes

• All configuration files use JSON format with strict validation
• Configuration files are auto-generated with sensible defaults if missing
• Pipeline files must exist; they are not auto-generated
• Invalid configurations cause immediate application exit with error messages
• See API_REFERENCE.md for available pipeline functions