Refactor API and configuration schema documentation for clarity; streamline content and improve structure.
This commit is contained in:
jon brookes
parent
454e911dc7
commit
0240a32266
2 changed files with 89 additions and 192 deletions
|
|
@ -3,82 +3,56 @@ title: API Reference
|
||||||
description: Reference for infctl commands and functions.
|
description: Reference for infctl commands and functions.
|
||||||
---
|
---
|
||||||
|
|
||||||
## Installation
|
# INFCTL CLI API Reference
|
||||||
|
|
||||||
Install `infctl` command line tool:
|
|
||||||
|
|
||||||
```bash
|
# API Reference
|
||||||
curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/install.sh | bash
|
|
||||||
|
This document provides a reference for the API and CLI usage of the [INFCTL CLI](https://codeberg.org/headshed/infctl-cli) tool
|
||||||
|
|
||||||
|
## PipelineStep Structure
|
||||||
|
|
||||||
|
Each pipeline step is defined as:
|
||||||
|
|
||||||
|
- `name`: Step name (string)
|
||||||
|
- `function`: Function to call (string)
|
||||||
|
- `params`: List of parameters (array of strings)
|
||||||
|
- `retryCount`: Number of retries (integer)
|
||||||
|
- `shouldAbort`: Whether to abort on failure (boolean)
|
||||||
|
|
||||||
|
## Available Functions
|
||||||
|
|
||||||
|
### k8sNamespaceExists
|
||||||
|
Checks if a Kubernetes namespace exists.
|
||||||
|
- Params: `[namespace]` (string)
|
||||||
|
- Returns: error if namespace does not exist
|
||||||
|
|
||||||
|
### RunCommand
|
||||||
|
Runs a shell command.
|
||||||
|
- Params: `[command]` (string)
|
||||||
|
- Returns: error if command fails
|
||||||
|
|
||||||
|
## Example Pipeline JSON
|
||||||
|
|
||||||
```
|
```
|
||||||
|
[
|
||||||
Or download from [Releases](https://codeberg.org/headshed/infctl-cli/releases) and place in your `PATH`.
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
`infctl` uses JSON files for configuration and is designed around pipelines that perform a series of steps.
|
|
||||||
|
|
||||||
## Functions
|
|
||||||
|
|
||||||
### `k8sNamespaceExists`
|
|
||||||
Ensures a Kubernetes namespace exists.
|
|
||||||
|
|
||||||
**Parameters:**
|
|
||||||
- `namespace` (string) - Name of the namespace
|
|
||||||
|
|
||||||
**Example:**
|
|
||||||
```json
|
|
||||||
{
|
{
|
||||||
"name": "ensure inf namespace exists",
|
"name": "ensure inf namespace exists",
|
||||||
"function": "k8sNamespaceExists",
|
"function": "k8sNamespaceExists",
|
||||||
"params": ["infctl"],
|
"params": ["infctl"],
|
||||||
"retryCount": 0,
|
"retryCount": 0,
|
||||||
"shouldAbort": true
|
"shouldAbort": true
|
||||||
}
|
},
|
||||||
```
|
|
||||||
|
|
||||||
### `RunCommand`
|
|
||||||
Executes a shell command, script, or executable.
|
|
||||||
|
|
||||||
**Parameters:**
|
|
||||||
- `command` (string) - Command, script path, or executable to run
|
|
||||||
|
|
||||||
**Examples:**
|
|
||||||
```json
|
|
||||||
{
|
{
|
||||||
"name": "run setup script",
|
"name": "create php configmap",
|
||||||
"function": "RunCommand",
|
"function": "RunCommand",
|
||||||
"params": ["./scripts/create_php_configmap_ctl.sh"],
|
"params": ["./scripts/create_php_configmap_ctl.sh"],
|
||||||
"retryCount": 0,
|
"retryCount": 0,
|
||||||
"shouldAbort": true
|
"shouldAbort": true
|
||||||
}
|
}
|
||||||
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
```json
|
## Notes
|
||||||
{
|
- Only functions defined in the codebase are available for use in pipelines.
|
||||||
"name": "say hello",
|
- The API does not expose any HTTP endpoints; all orchestration is via CLI and pipeline JSON.
|
||||||
"function": "RunCommand",
|
|
||||||
"params": ["echo 'hello world'"],
|
|
||||||
"retryCount": 0,
|
|
||||||
"shouldAbort": true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Task Properties
|
|
||||||
|
|
||||||
### Required
|
|
||||||
- `name` - Human-readable description displayed in logs
|
|
||||||
- `function` - Name of function registered within infctl
|
|
||||||
- `params` - Array of string parameters passed to the function
|
|
||||||
|
|
||||||
### Optional
|
|
||||||
- `retryCount` - Number of times to retry if task fails (default: 0)
|
|
||||||
- `shouldAbort` - Whether to stop pipeline if task fails (default: true)
|
|
||||||
|
|
||||||
## Execution Behavior
|
|
||||||
|
|
||||||
- Tasks execute in sequence
|
|
||||||
- Task fails if script/command returns non-zero exit code
|
|
||||||
- Failed tasks retry up to `retryCount` times
|
|
||||||
- If `shouldAbort` is `true` and task fails, pipeline stops
|
|
||||||
- If `shouldAbort` is `false`, pipeline continues to next task
|
|
||||||
- Unlimited flexibility through `RunCommand` for any automation
|
|
||||||
|
|
|
||||||
|
|
@ -3,10 +3,45 @@ title: Configuration Schema
|
||||||
description: JSON schema reference for infctl pipeline configurations.
|
description: JSON schema reference for infctl pipeline configurations.
|
||||||
---
|
---
|
||||||
|
|
||||||
## Pipeline Structure
|
# INFCTL CLI Configuration Schema
|
||||||
|
|
||||||
A pipeline is a JSON array of task objects. Each task represents a single operation to be executed in sequence.
|
|
||||||
|
|
||||||
|
# Configuration Schema
|
||||||
|
|
||||||
|
This document describes the configuration schema for the [INFCTL CLI](https://codeberg.org/headshed/infctl-cli) tool
|
||||||
|
|
||||||
|
## Base Configuration (`base.json`)
|
||||||
|
|
||||||
|
Example:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"retry_delay_seconds": 3
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `retry_delay_seconds` (integer): Delay in seconds before retrying failed steps.
|
||||||
|
|
||||||
|
## Project Configuration (`config.json`)
|
||||||
|
|
||||||
|
Project configuration fields are defined in the code and may include:
|
||||||
|
- Project name
|
||||||
|
- Directory paths
|
||||||
|
- URLs
|
||||||
|
- Port numbers
|
||||||
|
- Log format
|
||||||
|
|
||||||
|
Refer to the code for exact field names and types.
|
||||||
|
|
||||||
|
## Pipeline Configuration (`pipeline.json`)
|
||||||
|
|
||||||
|
Pipeline configuration is an array of steps. Each step:
|
||||||
|
- `name`: Step name (string)
|
||||||
|
- `function`: Function to call (string)
|
||||||
|
- `params`: List of parameters (array of strings)
|
||||||
|
- `retryCount`: Number of retries (integer)
|
||||||
|
- `shouldAbort`: Whether to abort on failure (boolean)
|
||||||
|
|
||||||
|
Example:
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
|
|
@ -15,122 +50,10 @@ A pipeline is a JSON array of task objects. Each task represents a single operat
|
||||||
"params": ["infctl"],
|
"params": ["infctl"],
|
||||||
"retryCount": 0,
|
"retryCount": 0,
|
||||||
"shouldAbort": true
|
"shouldAbort": true
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "create php configmap",
|
|
||||||
"function": "RunCommand",
|
|
||||||
"params": ["./scripts/create_php_configmap_ctl.sh"],
|
|
||||||
"retryCount": 0,
|
|
||||||
"shouldAbort": true
|
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
## Task Object Schema
|
## Notes
|
||||||
|
- Example configuration files are provided as `.example` files in the repository.
|
||||||
### Required Properties
|
- All configuration fields must match those defined in the codebase; do not add undocumented fields.
|
||||||
|
|
||||||
#### `name`
|
|
||||||
- **Type:** `string`
|
|
||||||
- **Description:** Human-readable description displayed in logs
|
|
||||||
- **Example:** `"ensure inf namespace exists"`
|
|
||||||
|
|
||||||
#### `function`
|
|
||||||
- **Type:** `string`
|
|
||||||
- **Description:** Name of the function registered within infctl
|
|
||||||
- **Known Functions:** `k8sNamespaceExists`, `RunCommand`
|
|
||||||
- **Example:** `"RunCommand"`
|
|
||||||
|
|
||||||
#### `params`
|
|
||||||
- **Type:** `array`
|
|
||||||
- **Description:** Array of string parameters passed to the function
|
|
||||||
- **Example:** `["./scripts/create_php_configmap_ctl.sh"]`
|
|
||||||
|
|
||||||
### Optional Properties
|
|
||||||
|
|
||||||
#### `retryCount`
|
|
||||||
- **Type:** `number`
|
|
||||||
- **Default:** `0`
|
|
||||||
- **Description:** Number of times to retry the task if it fails (script returns non-zero)
|
|
||||||
- **Example:** `3`
|
|
||||||
|
|
||||||
#### `shouldAbort`
|
|
||||||
- **Type:** `boolean`
|
|
||||||
- **Default:** `true`
|
|
||||||
- **Description:** Whether to stop the pipeline if this task fails. If `false`, pipeline continues to next task
|
|
||||||
- **Example:** `true`
|
|
||||||
|
|
||||||
## Known Functions
|
|
||||||
|
|
||||||
Based on the documented examples:
|
|
||||||
|
|
||||||
#### `k8sNamespaceExists`
|
|
||||||
- **Parameters:** `[namespace: string]`
|
|
||||||
- **Description:** Ensures a Kubernetes namespace exists
|
|
||||||
|
|
||||||
#### `RunCommand`
|
|
||||||
- **Parameters:** `[command: string]`
|
|
||||||
- **Description:** Executes a shell command, script, or executable
|
|
||||||
- **Notes:** Can be any command, script path, or executable. Task fails if command returns non-zero exit code
|
|
||||||
|
|
||||||
## Example Configurations
|
|
||||||
|
|
||||||
### Basic Two-Step Pipeline
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"name": "ensure inf namespace exists",
|
|
||||||
"function": "k8sNamespaceExists",
|
|
||||||
"params": ["infctl"],
|
|
||||||
"retryCount": 0,
|
|
||||||
"shouldAbort": true
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "create php configmap",
|
|
||||||
"function": "RunCommand",
|
|
||||||
"params": ["./scripts/create_php_configmap_ctl.sh"],
|
|
||||||
"retryCount": 0,
|
|
||||||
"shouldAbort": true
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Simple Script Execution
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"name": "say hello",
|
|
||||||
"function": "RunCommand",
|
|
||||||
"params": ["echo 'hello world'"],
|
|
||||||
"retryCount": 0,
|
|
||||||
"shouldAbort": true
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Continue on Failure
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"name": "optional cleanup",
|
|
||||||
"function": "RunCommand",
|
|
||||||
"params": ["rm -f /tmp/tempfile"],
|
|
||||||
"retryCount": 0,
|
|
||||||
"shouldAbort": false
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "main deployment",
|
|
||||||
"function": "RunCommand",
|
|
||||||
"params": ["./deploy.sh"],
|
|
||||||
"retryCount": 2,
|
|
||||||
"shouldAbort": true
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Execution Rules
|
|
||||||
|
|
||||||
1. **Tasks execute in sequence** - Each task in the array runs one after another
|
|
||||||
2. **Failure handling** - If a task fails (returns non-zero), it may be retried up to `retryCount` times
|
|
||||||
3. **Pipeline stopping** - If `shouldAbort` is `true` and task fails, pipeline stops. If `false`, pipeline continues
|
|
||||||
4. **Unlimited flexibility** - `RunCommand` can execute any script, command, or executable for complete automation flexibility
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue