Descriptive Metadata

kontinue supports adding human-readable display names and descriptions to Functions and Executions. This metadata is displayed in the UI and CLI to help users understand what workflows do at a glance.

Annotations

Metadata is stored as Kubernetes annotations on resources:

These annotations can be set on Functions, Executions, Suspensions, and Jobs.

Functions

Set display name and description when registering a function:

worker.RegisterFunction(w, "prod-deploy", ProdDeploy, &function.Options{
    DisplayName: "Production Deployment",
    Description: "Deploys to staging cluster, runs smoke tests, then deploys to production cluster",
})

The function metadata is published to the Function CRD and displayed in the UI’s function list and when starting new executions.

Function Arguments

Functions can declare their input arguments with descriptions, default values, and allowed values. This metadata is displayed in the UI when starting executions and enables validation.

Automatic Metadata via Struct Tags

The easiest way to define argument metadata is using Go struct tags with ArgumentMetadata:

type DeployArgs struct {
    Environment string `json:"environment" description:"Target environment" default:"staging" enum:"staging,production"`
    Version     string `json:"version" description:"Version to deploy"`
    DryRun      bool   `json:"dryRun" description:"Preview changes without applying" default:"false"`
    Replicas    int    `json:"replicas" description:"Number of replicas" default:"3"`
}

worker.RegisterFunction(w, "deploy", Deploy, &function.Options{
    DisplayName: "Deploy Application",
    Description: "Deploys the application to the specified environment",
    Arguments:   function.ArgumentMetadata(&DeployArgs{}),
})

Supported struct tags:

Default values are automatically parsed based on the field type (string, int, bool, float).

Manual Argument Definition

For more control, define arguments manually:

worker.RegisterFunction(w, "provision-cluster", ProvisionCluster, &function.Options{
    DisplayName: "Provision Cluster",
    Description: "Creates a new Kubernetes cluster",
    Arguments: []function.Argument{
        {
            Name:        "clusterName",
            Description: "Name for the new cluster",
        },
        {
            Name:        "nodeCount",
            Description: "Number of worker nodes",
            Default:     3,
        },
        {
            Name:        "machineType",
            Description: "Machine type for nodes",
            Default:     "n1-standard-4",
            Enum:        []any{"n1-standard-2", "n1-standard-4", "n1-standard-8"},
        },
    },
})

Example: Complete Function Registration

type ChildArgs struct {
    Name string `json:"name" description:"The name to include in the greeting" default:"World"`
}

type ParentArgs struct {
    Name string `json:"name" description:"The name to pass to both parent and child" default:"World"`
}

worker.RegisterFunction(w, "hello-world", helloWorld, &function.Options{
    DisplayName: "Hello World",
    Description: "Parent execution that calls a child function with suspensions",
    Arguments:   function.ArgumentMetadata(&ParentArgs{}),
})

worker.RegisterFunction(w, "hello-world-child", helloWorldChild, &function.Options{
    DisplayName: "Hello World (Child)",
    Description: "Child execution that generates a greeting with suspension",
    Arguments:   function.ArgumentMetadata(&ChildArgs{}),
})

When starting an execution via the UI, users see:

• Argument names and descriptions
• Input fields pre-filled with default values
• Dropdowns for enum fields with allowed options

Child Executions

When spawning child executions from within a workflow, use StepOptions to set metadata:

func DeployWorkflow(ktx *kontinue.ExecutionContext, args *DeployArgs) (*DeployResult, error) {
    // Child execution with descriptive metadata
    _, err := kontinue.Execute[TestResult](ktx, "run-tests", &TestArgs{
        Environment: "staging",
    }, &kontinue.ExecuteOptions{
        StepOptions: kontinue.StepOptions{
            DisplayName: "Run Integration Tests",
            Description: "Executes the full integration test suite against staging",
        },
    })
    if err != nil {
        return nil, err
    }

    _, err = kontinue.Execute[DeployResult](ktx, "deploy-app", &DeployAppArgs{
        Cluster: args.ProdCluster,
    }, &kontinue.ExecuteOptions{
        StepOptions: kontinue.StepOptions{
            DisplayName: "Deploy to Production",
            Description: "Rolls out the new version to production with canary deployment",
        },
    })
    if err != nil {
        return nil, err
    }

    return &DeployResult{}, nil
}

The display name and description appear in the execution tree view in the UI, making it easy to understand what each step does without reading code.

Other Resources

Suspensions

Add metadata to sleep and suspend operations:

kontinue.SleepNamed(ktx, &kontinue.SleepOptions{
    Duration: 5 * time.Minute,
    StepOptions: kontinue.StepOptions{
        DisplayName: "Wait for DNS Propagation",
        Description: "Allows time for DNS changes to propagate globally",
    },
})

Jobs

Add metadata to Kubernetes jobs:

kontinue.RunScript(ktx, &kontinue.ScriptOptions{
    Image:   "alpine:latest",
    Command: "echo 'Building artifacts...'",
    StepOptions: kontinue.StepOptions{
        DisplayName: "Build Release Artifacts",
        Description: "Compiles and packages release artifacts for distribution",
    },
})

Root Executions via YAML

When creating executions directly via YAML, add annotations:

apiVersion: kontinue.cloud/v1alpha1
kind: Execution
metadata:
  name: weekly-report
  annotations:
    kontinue.cloud/display-name: "Weekly Analytics Report"
    kontinue.cloud/description: "Generates and emails the weekly analytics summary"
spec:
  function: generate-report
  arguments:
    reportType: weekly

Viewing Metadata

CLI

The kontinue show command displays metadata in the execution details:

kontinue show my-execution

Display names are shown in the execution tree, and descriptions appear in the details section.

UI

The UI displays:

• Function list: Shows display names and descriptions for all registered functions
• Execution tree: Shows display names for each step in the hierarchy
• Details panel: Shows the full description when a step is selected

Best Practices

1. Use clear, action-oriented display names: “Deploy to Production” is better than “prod-deploy”
2. Keep descriptions concise but informative: Explain what the step does and any important behavior
3. Include relevant context: Mention environments, dependencies, or side effects
4. Be consistent: Use similar naming patterns across your workflow functions

Examples of Good Metadata