Skip to content

exit-codes.md

Latest commit

 

History

History
396 lines (304 loc) · 8.43 KB

exit-codes.md

File metadata and controls

396 lines (304 loc) · 8.43 KB
id exit-codes
title Exit Codes
sidebar_label Exit Codes
description Complete reference of CLI exit codes for error handling in scripts and CI/CD pipelines.
doc_type reference
audience developers, devops engineers
tags
exit-codes
errors
automation
ci-cd

Exit Codes

Purpose: For automation users, provides complete reference of CLI exit codes for error handling in scripts and CI/CD pipelines.

This reference documents all exit codes returned by openCenter CLI commands.

Overview

openCenter CLI uses standard Unix exit codes to indicate command success or failure. Exit codes enable automated error handling in scripts and CI/CD pipelines.

Convention:

  • 0: Success
  • 1-255: Error (specific error indicated by code)

Usage in scripts:

#!/bin/bash
opencenter cluster validate my-cluster
if [ $? -eq 0 ]; then
    echo "Validation passed"
else
    echo "Validation failed with exit code $?"
    exit 1
fi

Standard Exit Codes

0 - Success

Command completed successfully.

Example:

opencenter cluster validate my-cluster
echo $?  # Output: 0

When returned:

  • Configuration validation passed
  • Cluster operation completed successfully
  • Command executed without errors

1 - General Error

General error or unspecified failure. This is the catch-all exit code for any error condition.

Example:

opencenter cluster validate invalid-cluster
echo $?  # Output: 1

When returned:

  • Configuration validation failed
  • Provider authentication failed
  • Network connectivity error
  • Missing dependencies
  • Invalid command syntax
  • Missing required arguments
  • Any unclassified error

Note: Most error conditions currently return exit code 1. Use --output json on supported commands to get structured error details for programmatic handling.

3 - Configuration Not Found

The specified cluster configuration does not exist.

Example:

opencenter cluster validate nonexistent-cluster
echo $?  # Output: 3
# stderr: Check available clusters with: opencenter cluster list
#         Initialize a new cluster with: opencenter cluster init nonexistent-cluster

When returned:

  • Cluster name does not match any configuration file
  • Organization/cluster path does not exist

Recovery:

# List available clusters
opencenter cluster list

# Initialize the missing cluster
opencenter cluster init <name> --org <org>

Exit Code Summary

Code Meaning Typical Cause
0 Success Command completed without error
1 General error Validation failure, provider error, network error, any unclassified error
3 Config not found Cluster configuration file does not exist

Basic Error Handling

#!/bin/bash
set -e  # Exit on any error

opencenter cluster validate my-cluster
opencenter cluster generate my-cluster
opencenter cluster deploy my-cluster

echo "Cluster deployed successfully"

Specific Error Handling

#!/bin/bash

opencenter cluster validate my-cluster
EXIT_CODE=$?

case $EXIT_CODE in
    0)
        echo "Validation passed"
        ;;
    3)
        echo "Cluster not found - run 'opencenter cluster init' first"
        exit 1
        ;;
    *)
        echo "Error (exit code: $EXIT_CODE)"
        exit 1
        ;;
esac

Structured Error Output

For programmatic error handling, use --output json to get structured error details:

#!/bin/bash

OUTPUT=$(opencenter cluster validate my-cluster --output json 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
    echo "$OUTPUT" | jq '.errors[]?.message' 2>/dev/null
    exit $EXIT_CODE
fi

Retry Logic

#!/bin/bash

MAX_RETRIES=3
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
    opencenter cluster deploy my-cluster
    EXIT_CODE=$?
    
    if [ $EXIT_CODE -eq 0 ]; then
        echo "Cluster deployed successfully"
        exit 0
    elif [ $EXIT_CODE -eq 1 ]; then
        echo "Error - retrying ($((RETRY_COUNT + 1))/$MAX_RETRIES)"
        RETRY_COUNT=$((RETRY_COUNT + 1))
        sleep 30
    else
        echo "Non-retryable error (exit code: $EXIT_CODE)"
        exit $EXIT_CODE
    fi
done

echo "Failed after $MAX_RETRIES retries"
exit 1

CI/CD Integration

GitHub Actions:

- name: Validate cluster
  run: opencenter cluster validate my-cluster
  continue-on-error: false

- name: Deploy cluster
  run: opencenter cluster deploy my-cluster
  if: success()

GitLab CI:

validate:
  script:
    - opencenter cluster validate my-cluster
  allow_failure: false

deploy:
  script:
    - opencenter cluster deploy my-cluster
  needs: [validate]
  when: on_success

Jenkins:

stage('Validate') {
    steps {
        script {
            def exitCode = sh(
                script: 'opencenter cluster validate my-cluster',
                returnStatus: true
            )
            if (exitCode != 0) {
                error("Validation failed with exit code ${exitCode}")
            }
        }
    }
}

Exit Code Checking

Check Last Exit Code

# Run command
opencenter cluster validate my-cluster

# Check exit code
echo $?

# Or save to variable
EXIT_CODE=$?
echo "Exit code: $EXIT_CODE"

Check Exit Code in Conditional

# If statement
if opencenter cluster validate my-cluster; then
    echo "Validation passed"
else
    echo "Validation failed"
fi

# Or with explicit check
opencenter cluster validate my-cluster
if [ $? -eq 0 ]; then
    echo "Validation passed"
fi

Check Multiple Commands

# Run multiple commands, check each
opencenter cluster validate my-cluster
VALIDATE_EXIT=$?

opencenter cluster generate my-cluster
SETUP_EXIT=$?

if [ $VALIDATE_EXIT -eq 0 ] && [ $SETUP_EXIT -eq 0 ]; then
    echo "All commands succeeded"
else
    echo "One or more commands failed"
    echo "Validate exit code: $VALIDATE_EXIT"
    echo "Setup exit code: $SETUP_EXIT"
    exit 1
fi

Error Messages

Exit codes are accompanied by error messages on stderr:

# Redirect stderr to file
opencenter cluster validate my-cluster 2> error.log

# Check exit code and error message
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
    echo "Command failed with exit code $EXIT_CODE"
    echo "Error message:"
    cat error.log
fi

Best Practices

  1. Always check exit codes: Don't assume commands succeed
  2. Use set -e in scripts: Exit on first error
  3. Handle specific errors: Different actions for different exit codes
  4. Log exit codes: Record exit codes for debugging
  5. Retry transient errors: Network errors (exit code 4) can be retried
  6. Don't retry permanent errors: Configuration errors (exit code 2) need fixing
  7. Document expected exit codes: In scripts and CI/CD pipelines
  8. Test error paths: Verify error handling works correctly

Troubleshooting

Exit Code Not as Expected

Symptom: Command returns unexpected exit code

Diagnosis:

# Run command with verbose output
opencenter cluster validate my-cluster --verbose

# Check error message
opencenter cluster validate my-cluster 2>&1 | tee error.log

# Check exit code
echo $?

Solution:

  • Read error message carefully
  • Check command syntax
  • Verify configuration file
  • Check provider credentials

Exit Code 0 But Command Failed

Symptom: Command returns 0 but didn't complete successfully

Diagnosis:

# Check command output
opencenter cluster validate my-cluster | tee output.log

# Verify expected output
grep "Configuration is valid" output.log

Solution:

  • Check command output for warnings
  • Verify expected behavior
  • Report bug if exit code incorrect

Script Exits Unexpectedly

Symptom: Script exits without completing

Diagnosis:

# Run script with set -x for debugging
bash -x script.sh

# Check which command failed
echo $?

Solution:

# Use set -e to exit on error
set -e

# Or handle errors explicitly
opencenter cluster validate my-cluster || {
    echo "Validation failed"
    exit 1
}

Related Topics

Evidence

This reference is based on:

  • Exit code conventions: Unix/Linux standards
  • CLI error handling: cmd/ directory structure
  • Error types: internal/config/validator.go, internal/cloud/
  • CI/CD integration: Session 7 integrate-ci-cd.md