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.
|
||||
---
|
||||
|
||||
## Installation
|
||||
# INFCTL CLI API Reference
|
||||
|
||||
Install `infctl` command line tool:
|
||||
|
||||
```bash
|
||||
curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/install.sh | bash
|
||||
# API Reference
|
||||
|
||||
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",
|
||||
"function": "k8sNamespaceExists",
|
||||
"params": ["infctl"],
|
||||
"retryCount": 0,
|
||||
"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",
|
||||
"params": ["./scripts/create_php_configmap_ctl.sh"],
|
||||
"retryCount": 0,
|
||||
"shouldAbort": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "say hello",
|
||||
"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
|
||||
## Notes
|
||||
- Only functions defined in the codebase are available for use in pipelines.
|
||||
- The API does not expose any HTTP endpoints; all orchestration is via CLI and pipeline JSON.
|
||||
|
|
|
|||
|
|
@ -3,10 +3,45 @@ title: Configuration Schema
|
|||
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
|
||||
[
|
||||
{
|
||||
|
|
@ -15,122 +50,10 @@ A pipeline is a JSON array of task objects. Each task represents a single operat
|
|||
"params": ["infctl"],
|
||||
"retryCount": 0,
|
||||
"shouldAbort": true
|
||||
},
|
||||
{
|
||||
"name": "create php configmap",
|
||||
"function": "RunCommand",
|
||||
"params": ["./scripts/create_php_configmap_ctl.sh"],
|
||||
"retryCount": 0,
|
||||
"shouldAbort": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Task Object Schema
|
||||
|
||||
### Required Properties
|
||||
|
||||
#### `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
|
||||
## Notes
|
||||
- Example configuration files are provided as `.example` files in the repository.
|
||||
- All configuration fields must match those defined in the codebase; do not add undocumented fields.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue