builder

package
v2.8.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 26, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Option added in v2.3.1 

type Option func(*WorkflowBuilder)

Option is a functional option for configuring WorkflowBuilder.

func WithActiveDeadlineSeconds 

func WithActiveDeadlineSeconds(seconds int64) Option

WithActiveDeadlineSeconds sets the maximum duration for the workflow. If the workflow runs longer than this, it will be terminated.

Example: 

builder := NewWorkflowBuilder("my-workflow", "argo",
    WithActiveDeadlineSeconds(3600)) // 1 hour max

func WithAnnotations 

func WithAnnotations(annotations map[string]string) Option

WithAnnotations adds annotations to the workflow metadata. Annotations can store arbitrary non-identifying metadata.

Example: 

annotations := map[string]string{
    "description": "Daily backup workflow",
    "owner": "platform-team",
}
builder := NewWorkflowBuilder("my-workflow", "argo",
    WithAnnotations(annotations))

func WithArchiveLogs 

func WithArchiveLogs(archive bool) Option

WithArchiveLogs enables or disables log archiving for the workflow. When enabled, workflow logs are persisted after the workflow completes.

Example: 

builder := NewWorkflowBuilder("my-workflow", "argo",
    WithArchiveLogs(true))

func WithLabels 

func WithLabels(labels map[string]string) Option

WithLabels adds labels to the workflow metadata. Labels can be used for filtering, organizing, and identifying workflows.

Example: 

labels := map[string]string{
    "app": "myapp",
    "env": "production",
}
builder := NewWorkflowBuilder("my-workflow", "argo",
    WithLabels(labels))

func WithOTelConfig 

func WithOTelConfig(cfg *otel.Config) Option

WithOTelConfig enables OpenTelemetry instrumentation for the workflow builder. This adds distributed tracing, metrics collection, and structured logging to workflow build operations.

Example: 

otelConfig := otel.NewConfig("workflow-service").
    WithTracerProvider(tp).
    WithMeterProvider(mp)
builder := NewWorkflowBuilder("my-workflow", "argo",
    WithOTelConfig(otelConfig))

func WithPodGC 

func WithPodGC(podGC *v1alpha1.PodGC) Option

WithPodGC sets the pod garbage collection strategy for the workflow. This determines when workflow pods are cleaned up after completion.

Example: 

podGC := &v1alpha1.PodGC{
    Strategy: v1alpha1.PodGCOnWorkflowSuccess,
}
builder := NewWorkflowBuilder("my-workflow", "argo",
    WithPodGC(podGC))

func WithRetryStrategy 

func WithRetryStrategy(retry *v1alpha1.RetryStrategy) Option

WithRetryStrategy sets a default retry strategy for all workflow steps. Individual steps can override this with their own retry configuration.

Example: 

retryStrategy := &v1alpha1.RetryStrategy{
    Limit: intstr.FromInt(3),
    RetryPolicy: "Always",
    Backoff: &v1alpha1.Backoff{
        Duration: "1m",
        Factor:   intstr.FromInt(2),
        MaxDuration: "10m",
    },
}
builder := NewWorkflowBuilder("my-workflow", "argo",
    WithRetryStrategy(retryStrategy))

func WithServiceAccount 

func WithServiceAccount(sa string) Option

WithServiceAccount sets the Kubernetes service account name for the workflow. The service account determines what permissions the workflow has in the cluster.

Example: 

builder := NewWorkflowBuilder("my-workflow", "argo",
    WithServiceAccount("argo-workflow"))

func WithTTL 

func WithTTL(ttl *v1alpha1.TTLStrategy) Option

WithTTL sets the time-to-live for the workflow after completion. After this duration, the workflow will be automatically deleted.

Example: 

ttl := &v1alpha1.TTLStrategy{
    SecondsAfterCompletion: int32Ptr(3600), // 1 hour
}
builder := NewWorkflowBuilder("my-workflow", "argo",
    WithTTL(ttl))

func WithVolume 

func WithVolume(volume corev1.Volume) Option

WithVolume adds a volume to the workflow. Volumes can be mounted in workflow steps for persistent storage or configuration.

Example: 

volume := corev1.Volume{
    Name: "config",
    VolumeSource: corev1.VolumeSource{
        ConfigMap: &corev1.ConfigMapVolumeSource{
            LocalObjectReference: corev1.LocalObjectReference{
                Name: "my-config",
            },
        },
    },
}
builder := NewWorkflowBuilder("my-workflow", "argo",
    WithVolume(volume))

type WorkflowBuilder 

type WorkflowBuilder struct {
	// contains filtered or unexported fields
}

WorkflowBuilder provides a fluent API for constructing Argo Workflows. It allows composing workflows from reusable WorkflowSource components, with full OpenTelemetry instrumentation for observability.

Example usage: 

// Create sources
deploy := template.NewContainer("deploy", "myapp:v1",
    template.WithCommand("deploy.sh"))

healthcheck := template.NewHTTP("healthcheck",
    template.WithURL("https://myapp/health"))

cleanup := template.NewScript("cleanup", "bash",
    template.WithScript("echo 'Cleaning up...'"))

// Build workflow
wf, err := NewWorkflowBuilder("deployment", "argo",
    WithOTelConfig(otelConfig),
    WithServiceAccount("argo-workflow"),
).
    Add(deploy).
    Add(healthcheck).
    AddExitHandler(cleanup).
    Build()

func NewWorkflowBuilder 

func NewWorkflowBuilder(name, namespace string, opts ...Option) *WorkflowBuilder

NewWorkflowBuilder creates a new workflow builder with the specified name and namespace. Additional configuration can be provided through functional options.

Parameters:

  • name: Base name for the workflow (will be used as GenerateName with a trailing dash)
  • namespace: Kubernetes namespace where the workflow will be created
  • opts: Optional configuration options (WithOTelConfig, WithServiceAccount, etc.)

Example: 

builder := NewWorkflowBuilder("hello-world", "argo",
    WithOTelConfig(otelConfig),
    WithServiceAccount("argo-workflow"),
    WithArchiveLogs(true))

func (*WorkflowBuilder) Add 

func (b *WorkflowBuilder) Add(source WorkflowSource) *WorkflowBuilder

Add adds a WorkflowSource to the workflow. The source's steps will be added sequentially to the workflow's entrypoint. Templates will be deduplicated by name.

Example: 

deploy := template.NewContainer("deploy", "myapp:v1")
builder.Add(deploy)

func (*WorkflowBuilder) AddExitHandler 

func (b *WorkflowBuilder) AddExitHandler(source WorkflowSource) *WorkflowBuilder

AddExitHandler adds a WorkflowSource as an exit handler. Exit handlers always run when the workflow completes, regardless of success or failure. They are useful for cleanup operations and callbacks.

Example: 

cleanup := template.NewScript("cleanup", "bash",
    template.WithScript("echo 'Cleaning up resources...'"))
builder.AddExitHandler(cleanup)

AddExitHandler adds an exit handler from a WorkflowSource. Exit handlers run after the main workflow completes (regardless of success or failure).

Steps whose name contains "destroy" or "cleanup" are automatically prioritized and inserted at the beginning of the exit handler list, ensuring resource cleanup runs before other exit steps.

func (*WorkflowBuilder) AddParallel 

func (b *WorkflowBuilder) AddParallel(source WorkflowSourceV2) *WorkflowBuilder

AddParallel adds a WorkflowSourceV2 that supports parallel step execution. Use this when you need steps to run in parallel rather than sequentially.

Example: 

parallelSource := &MyParallelSource{}
builder.AddParallel(parallelSource)

func (*WorkflowBuilder) AddTemplate 

func (b *WorkflowBuilder) AddTemplate(template v1alpha1.Template) *WorkflowBuilder

AddTemplate adds a template directly to the workflow builder. This is useful for advanced use cases where you need to manually construct templates. Templates are automatically deduplicated by name.

Example: 

template := v1alpha1.Template{
    Name: "custom-step",
    Container: &corev1.Container{...},
}
builder.AddTemplate(template)

func (*WorkflowBuilder) Build 

func (b *WorkflowBuilder) Build() (*v1alpha1.Workflow, error)

Build constructs the final Workflow object. Returns an error if any errors occurred during workflow construction.

The build process: 1. Validates that at least one step exists (adds a no-op if empty) 2. Creates the entrypoint template from collected steps 3. Creates exit handler template if any exit handlers were added 4. Assembles the complete workflow specification

Example: 

wf, err := builder.
    Add(deploy).
    Add(healthcheck).
    AddExitHandler(cleanup).
    Build()
if err != nil {
    log.Fatal(err)
}

func (*WorkflowBuilder) BuildWithEntrypoint 

func (b *WorkflowBuilder) BuildWithEntrypoint(entrypointName string) (*v1alpha1.Workflow, error)

BuildWithEntrypoint builds the workflow with a custom entrypoint template name. This is useful when you need to manually construct templates and specify which one should be the entry point.

Example: 

// Manually create templates
entryTemplate := v1alpha1.Template{
    Name: "custom-main",
    Steps: [][]v1alpha1.WorkflowStep{...},
}
builder.AddTemplate(entryTemplate)
wf, err := builder.BuildWithEntrypoint("custom-main")

func (*WorkflowBuilder) WithMetrics 

func (b *WorkflowBuilder) WithMetrics(provider WorkflowMetricsProvider) *WorkflowBuilder

WithMetrics sets custom Prometheus metrics for the workflow. These metrics will be exposed when the workflow executes.

Example: 

metricsProvider := &MyMetricsProvider{}
builder.WithMetrics(metricsProvider)

type WorkflowMetricsProvider 

type WorkflowMetricsProvider interface {
	// Metrics returns workflow metrics configuration.
	// These metrics will be exposed by the workflow when it executes.
	Metrics() (*v1alpha1.Metrics, error)
}

WorkflowMetricsProvider is an optional interface that workflow sources can implement to provide custom Prometheus metrics for the workflow.

Example: 

func (m *MySource) Metrics() (*v1alpha1.Metrics, error) {
    return &v1alpha1.Metrics{
        Prometheus: []*v1alpha1.Prometheus{
            {
                Name: "my_workflow_count",
                Help: "Number of workflow executions",
                Counter: &v1alpha1.Counter{Value: "1"},
            },
        },
    }, nil
}

type WorkflowSource 

type WorkflowSource interface {
	// Steps returns the workflow steps to execute.
	// These steps will be added to the workflow's entrypoint in the order they are returned.
	Steps() ([]v1alpha1.WorkflowStep, error)

	// Templates returns all templates required by the steps.
	// The WorkflowBuilder will automatically deduplicate templates with the same name.
	Templates() ([]v1alpha1.Template, error)
}

WorkflowSource is the core interface that workflow components implement. It provides a composable way to build workflows by defining the steps and templates required for a workflow operation.

This interface allows you to create reusable workflow building blocks that can be combined using WorkflowBuilder.Add() to construct complex workflows.

Example implementation: 

type MyWorkflowSource struct {
    name string
}

func (m *MyWorkflowSource) Steps() ([]v1alpha1.WorkflowStep, error) {
    return []v1alpha1.WorkflowStep{{
        Name:     "my-step",
        Template: "my-template",
    }}, nil
}

func (m *MyWorkflowSource) Templates() ([]v1alpha1.Template, error) {
    return []v1alpha1.Template{{
        Name: "my-template",
        Container: &corev1.Container{
            Image: "alpine:latest",
            Command: []string{"echo", "hello"},
        },
    }}, nil
}

type WorkflowSourceV2 

type WorkflowSourceV2 interface {
	// ParallelSteps returns workflow steps organized for parallel execution.
	// Each ParallelSteps group contains steps that run in parallel.
	// Groups execute sequentially - the next group waits for all steps in the previous group to complete.
	ParallelSteps() ([]v1alpha1.ParallelSteps, error)

	// Templates returns all templates required by the parallel steps.
	Templates() ([]v1alpha1.Template, error)
}

WorkflowSourceV2 is an extended interface that supports parallel step execution. Use this interface when you need to define steps that should run in parallel.

Example: 

func (m *MyParallelSource) ParallelSteps() ([]v1alpha1.ParallelSteps, error) {
    return []v1alpha1.ParallelSteps{
        {
            Steps: []v1alpha1.WorkflowStep{
                {Name: "step-1", Template: "template-1"},
                {Name: "step-2", Template: "template-2"}, // runs in parallel with step-1
            },
        },
        {
            Steps: []v1alpha1.WorkflowStep{
                {Name: "step-3", Template: "template-3"}, // runs after step-1 and step-2 complete
            },
        },
    }, nil
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.