API Reference

This document describes the pipeline functions and architecture available in infctl-cli.

Overview

infctl-cli is a pipeline orchestration tool that executes deployment steps defined in JSON pipeline files. It supports retry logic, error handling, and structured logging.

Command Line Interface

Usage

infctl-cli --deployment-file=<path_to_pipeline.json> [options]
# or short form
infctl-cli -f <path_to_pipeline.json> [options]

Flags

• -f, --deployment-file: Path to pipeline JSON file (required)
• --base-config: Path to base config file (optional, defaults to base.json)
• --project-config: Path to project config file (optional, defaults to config.json)
• -v, --version: Show version information
• --help: Show help information

Environment Variables

• DEPLOYMENT_MODE: Override deployment mode from config (json or api)
• LOG_FORMAT: Override log format from config (full, basic, or none)
• LOG_FILE: Path to log file (optional, logs to stdout by default)
• DEBUG: Set to 1 to enable debug output including app state

Pipeline Structure

PipelineStep Schema

Each pipeline step is a JSON object with the following structure:

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

Fields:

• name (string, required): Human-readable description of the step
• function (string, required): Function name to execute (must be registered in functionMap)
• params (array of strings, required): Parameters to pass to the function
• retryCount (integer, required): Number of times to retry on failure (0 = no retries)
• shouldAbort (boolean, required): Whether to abort entire pipeline if step fails after retries

Available Functions

k8sNamespaceExists

Checks if a Kubernetes namespace exists, and creates it if not found.

Parameters:

• params[0]: Namespace name (string)

Behavior:

• Executes kubectl get ns <namespace>
• If namespace not found, automatically creates it with kubectl create ns <namespace>
• Returns error if kubectl command fails for reasons other than “not found”

Example:

{
  "name": "ensure infctl namespace exists",
  "function": "k8sNamespaceExists",
  "params": ["infctl"],
  "retryCount": 0,
  "shouldAbort": true
}

RunCommand

Executes a shell command with real-time output streaming.

Parameters:

• params[0]: Shell command to execute (string)

Behavior:

• Executes command via sh -c
• Streams stdout and stderr in real-time through structured logging
• Returns error if command exits with non-zero status

Example:

{
  "name": "create php configmap",
  "function": "RunCommand",
  "params": ["./scripts/create_php_configmap_ctl.sh"],
  "retryCount": 2,
  "shouldAbort": true
}

Pipeline Execution Flow

1. Initialization: Load base and project configs
2. Logger Setup: Configure structured logging based on config/env vars
3. App State Creation: Initialize AppState with configs
4. Pipeline Loading: Parse JSON pipeline file
5. Step Execution: For each step:
   • Log step start
   • Look up function in functionMap
   • Execute function with provided params
   • On failure:
     • If retryCount > 0: Retry with delay (from retry_delay_seconds)
     • If shouldAbort == true: Stop pipeline and exit with error
     • If shouldAbort == false: Log error and continue to next step
   • On success: Log completion and proceed
6. Completion: Exit with status code (0 = success, 1 = failure)

Example Pipeline Files

Simple 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": ["my-app"],
    "retryCount": 3,
    "shouldAbort": true
  },
  {
    "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
  }
]

Error Handling

• Step Failure: When a step fails, behavior depends on shouldAbort and retryCount
• Retry Logic: Failed steps are retried after a delay (configured via retry_delay_seconds in base config)
• Critical Failures: Steps with shouldAbort: true will halt the entire pipeline on failure
• Non-Critical Failures: Steps with shouldAbort: false log errors but allow pipeline to continue
• Function Not Found: If a function name is not registered, step is skipped with error log

Logging

The application uses structured logging (slog) with configurable formats:

• full: Detailed logs with timestamps and levels
• basic: Simplified log output
• none: Minimal output

Log levels:

• Info: Step execution, completion messages
• Error: Failed steps, critical errors
• Debug: Command details, internal state (when DEBUG=1)

Architecture Notes

• Function Map: All pipeline functions must be registered in functionMap in app.go
• No HTTP API: Current implementation only supports JSON-based pipelines (CLI orchestration)
• Stateless: Each pipeline run is independent, no persistent state between runs
• Shell Integration: Commands executed via sh -c for maximum flexibility
• Real-time Output: Command output streams to logs as it’s generated

Extending with New Functions

To add a new function:

1. Implement the function in app.go or k8s.go with signature func(params []string) error
2. Register it in functionMap with parameter validation
3. Document it in this reference

Example:

var functionMap = map[string]func([]string) error{
    "myNewFunction": func(params []string) error {
        if len(params) != 2 {
            return fmt.Errorf("myNewFunction requires 2 parameters")
        }
        // Implementation here
        return nil
    },
}