bluexport_api.sh: Native REST Automation for PowerVS IBM i Operations

Repo: https://github.com/rqmartins73/bluexport_api

Abstract

bluexport_api.sh is a Bash automation framework that uses IBM Cloud PowerVS native REST APIs to manage VSI lifecycle operations, snapshots, captured images, volume clones, tier changes, and Global Replication Services. Designed for enterprise IBM i environments, it eliminates dependency on the IBM Cloud CLI while simplifying hybrid cloud operations across HA/DR and multi-region deployments.

Introduction

Running IBM i workloads on PowerVS without automation is not just inefficient, it introduces operational risk.
The IBM Cloud CLI is not available on IBM i, and while REST APIs provide full control, they are not designed for day-to-day operations.
bluexport_api.sh exists to close that gap. In most enterprise IBM i setups, administrators need to coordinate virtual server operations, storage workflows, replication, and recovery steps while keeping everything consistent, auditable, and repeatable.

bluexport_api.sh was built for exactly that challenge. Instead of depending on the IBM Cloud CLI, it talks directly to the native PowerVS REST APIs, giving IBM i operations teams a lightweight but powerful Bash toolset for daily tasks and advanced lifecycle management. bluexport_api.sh can run on IBM i and other supported Bash environments, making it especially useful for PowerVS teams that manage IBM i workloads.

The Problem It Solves

In real PowerVS environments, operations are not complex because of individual tasks, they are complex because of repetition, scale, and risk.
Manual execution across multiple workspaces and regions increases the likelihood of human error, inconsistent results, and failed recovery scenarios.

bluexport_api.sh centralizes these operations into one command-line framework, reducing manual effort while maintaining transparency for enterprise operations teams to understand, trust, and extend.

Core Capabilities

The framework provides a single Bash interface for essential PowerVS administration tasks, organized around a JSON secrets/configuration file that maps human-friendly names to IBM Cloud resources.

Key operations supported:

• VSI lifecycle management (start, stop, monitor)

• Snapshot create/update/delete/restore workflows

• Captured image listing and cleanup

• Volume clone creation, management, and deletion

• Volume tier optimization

• Global Replication Services (GRS) orchestration

• IBM i-specific boot modes, operating modes, and SRC monitoring

Configuration Architecture

The repository includes bluexscrt_config_api.sh, an interactive configuration generator that creates the JSON secrets file consumed by the main framework. This file contains:

• IBM Cloud API key

• PowerVS workspace definitions (CRN, ID, human-readable names)

• Region-specific API endpoints

• VSI metadata and IP mappings

• Cloud Object Storage (COS) credentials

• SSH parameters for IBM i operations

This separation keeps environment-specific data isolated from operational logic, enabling dynamic resolution of regions, CRNs, and instance IDs at runtime.

IBM i Operational Intelligence

The framework's IBM i awareness sets it apart from generic PowerVS automation. Key capabilities include:

• VSI start with monitoring until ACTIVE + SRC 00000000

• Boot/operating mode management (a/b/c/d, normal/manual)

• IBM i task execution (iopreset, retrydump, console operations)

• Independent SRC monitoring to stable states

• ASP/iASP detection and management

These features address the operational realities of IBM i workloads in hybrid cloud environments.

Production Logging

Every operation generates detailed audit logs including:

• Timestamped API calls and responses

• Polling/monitoring events

• Error conditions and abort sequences

• Configurable log destinations

This makes bluexport_api.sh suitable for production operations, DR rehearsals, and customer support scenarios where traceability matters.

Operational Advisory ⚠️

Important: The script uses CHGASPACT OPTION(*FRCWRT) instead of CHGASPACT OPTION(*SUSPEND) for snapshot creation, volume cloning, and image capture operations. Users should schedule these operations during low system activity periods to avoid damaged objects on the snapshots, volume clones, or image captures.

Quick Start

bash

# Generate configuration (interactive)

./bluexscrt_config_api.sh -createconfig

# View usage

./bluexport_api.sh -h

# Common operations

./bluexport_api.sh -vsistart VSI_NAME

./bluexport_api.sh -snaplsall

./bluexport_api.sh -creategrs SRC_VSI TGT_VSI VG_NAME VOL_PREFIX

Runtime Requirements

• Bash 5.x+

• curl 

• jq 1.6+

• IBM Cloud PowerVS API access

• Generated secrets JSON file

Tested Environment

• IBM i PASE | SSH and Linux environments
• curl 8.12.0
• jq 1.6 | 1.7 | 1.8

Why It Matters for IBM i Teams

For IBM Power administrators, bluexport_api.sh delivers consistency across complex multi-region environments. It standardizes operations that would otherwise require manual coordination across CLI tools, portal navigation, and custom scripting.

The native REST approach eliminates CLI dependencies while maintaining full API feature coverage, making it ideal for controlled enterprise environments where governance and repeatability matter most.

Typical Use Cases

- Automated DR testing using GRS failover and failback workflows  
- Snapshot orchestration before PTF or application changes  
- Rapid provisioning of QA environments using clones and images  
- Cross-region operational consistency for multi-workspace deployments  
- Backup export and recovery workflows integrated with COS  

Get Involved

bluexport_api.sh demonstrates practical enterprise Bash automation built around native platform capabilities. The project welcomes feedback, contributions, and suggestions from the IBM Power community.

Repository: https://github.com/rqmartins73/bluexport_api
License: MIT

Ricardo Martins
IBM Power Technical Leader @ Blue Chip Portugal
IBM Champion 2025 | IBM Champion 2026