🚀 iapetus: Your Ultimate Go Workflow Orchestration Solution

16.05.2025 — go — 3 min read

Welcome to the future of workflow automation in Go! iapetus is not just another package - it's your powerful ally in managing complex workflows with elegance and efficiency. Whether you're building CI/CD pipelines, automating system tests, or orchestrating infrastructure deployments, iapetus has got you covered.

🎯 What Makes iapetus Special?

iapetus is more than just a Go package - it's a complete solution for workflow orchestration. Here's what sets it apart:

📦 Structured workflow execution with sequential steps
✅ Built-in and custom assertions for validating outputs
🔄 Retry mechanisms for handling flaky operations
💪 Fluent builder pattern for readable workflow construction
🚀 Lightning-fast performance with minimal overhead
🔒 Secure execution environment with proper isolation
📊 Comprehensive logging and error handling

Key Features

1. Structured Workflows

iapetus allows you to define complex workflows with multiple steps that execute in sequence. Here's a real-world example of a Kubernetes workflow:

// Create a Kubernetes namespace and deployment
workflow := iapetus.NewWorkflow("k8s-deployment", &logLevel).
    AddTask(iapetus.Task{
        Name:    "Create Namespace",
        Command: "kubectl",
        Args:    []string{"create", "ns", "test"},
        Expected: iapetus.Output{
            ExitCode: 0,
        },
        Asserts: []func(*iapetus.Task) error{
            iapetus.AssertByExitCode,
        },
    }).
    AddTask(iapetus.Task{
        Name:    "Create Deployment",
        Command: "kubectl",
        Args:    []string{"create", "deployment", "test", "--image", "nginx", "--replicas", "30", "-n", "test"},
        Expected: iapetus.Output{
            ExitCode: 0,
        },
        Asserts: []func(*iapetus.Task) error{
            iapetus.AssertByExitCode,
        },
    })

2. Robust Task Execution

Each task in iapetus is a configurable command execution unit that can:

Execute commands with arguments
Set environment variables
Configure timeouts
Define retry mechanisms
Validate outputs

task := iapetus.NewTask("verify-service", 5*time.Second, &logLevel).
    AddCommand("curl").
    AddArgs("-v", "https://api.example.com").
    AddEnv("API_KEY=secret").
    AddContains("200 OK")

3. Comprehensive Assertions

iapetus provides a powerful assertion system to validate your workflows. Here are some practical examples:

Built-in Assertions

// Validate command exit code
task.AddAssertion(iapetus.AssertByExitCode)

// Validate JSON output with node skipping
task.AddAssertion(iapetus.AssertByOutputJson)

// Check for specific strings in output
task.AddAssertion(iapetus.AssertByContains)

// Validate using regular expressions
task.AddAssertion(iapetus.AssertByRegexp)

Custom Assertions

You can create custom assertions for specific use cases. Here's a real-world example from our Kubernetes tests:

// Custom assertion to validate deployment status
func AssertByCustomDeploymentCheck(s *iapetus.Task) error {
    deployment := &appsv1.DeploymentList{}
    err := json.Unmarshal([]byte(s.Actual.Output), &deployment)
    if err != nil {
        return fmt.Errorf("failed to unmarshal deployment specs: %w", err)
    }
    if len(deployment.Items) != 1 {
        return fmt.Errorf("expected exactly one deployment")
    }
    return nil
}

// Add custom assertion to task
task.AddAssertion(AssertByCustomDeploymentCheck)

Combining Assertions

You can combine multiple assertions for comprehensive validation:

task.AddAssertion(iapetus.AssertByExitCode)
// Validate JSON structure
task.AddAssertion(iapetus.AssertByOutputJson)
// Check for specific strings
task.AddContains("deployment created")
// Add custom validation
task.AddAssertion(AssertByCustomDeploymentCheck)

4. Retry Mechanisms

iapetus handles transient failures gracefully with configurable retry mechanisms:

// Configure task with 3 retries
iapetus.NewTask("flaky-task", 10*time.Second, &logLevel).
    AddCommand("curl").
    AddArgs("-v", "https://unstable-api.com").
    AddRetries(3)

Getting Started

To get started with iapetus, simply install it using:

go get github.com/yindia/iapetus

Then you can create your first workflow:

workflow := iapetus.NewWorkflow("my-workflow", &logLevel).
    AddTask(
        iapetus.NewTask("verify-service", 5*time.Second, &logLevel).
            AddCommand("curl").
            AddArgs("-v", "https://api.example.com").
            AddContains("200 OK")
    ).
    AddTask(
        iapetus.NewTask("process-data", 10*time.Second, &logLevel).
            AddCommand("python").
            AddArgs("process.py", "--input", "data.json").
            AddExpected(iapetus.Output{
                ExitCode: 0,
                Contains: []string{"processed", "success"},
            })
    )

if err := workflow.Run(); err != nil {
    log.Fatalf("Failed to run workflow: %v", err)
}

Use Cases

iapetus is particularly useful for:

CI/CD pipeline orchestration
System testing and validation
Automated deployments
Infrastructure automation
API testing
Integration testing

Conclusion

iapetus provides a powerful yet simple way to orchestrate complex workflows in Go. With its fluent builder pattern, comprehensive assertions, and robust retry mechanisms, it's an excellent choice for any Go project that needs to execute and validate command-line workflows.

Happy coding!