Merge branch 'stable' into isc

Author: HariPalleti

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - '**'
+    tags-ignore:
+      - '**'
+  release:
+    types: [ published ]
+
+# Ensure only one build at a time for any branch, cancelling any in-progress builds
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py', '**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install package and doc build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: |
+          mkdocs build
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@4.1.7
+        if: ${{ github.event_name == 'release' || contains(github.event.head_commit.message, '[doc]') }}
+        with:
+          branch: gh-pages
+          folder: site

.gitignore

@@ -19,3 +19,5 @@ venv/
 # Other
 kubectl.exe
 /build
+/.vscode
+/site

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2025-12-15T15:57:18Z",
+  "generated_at": "2026-01-14T11:35:47Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -95,6 +95,44 @@
         "verified_result": null
       }
     ],
+    "docs/cli/create-initial-users.md": [
+      {
+        "hashed_secret": "33f220dd67f717cc949db63e21c90e130a6137da",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 126,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/cli/index.md": [
+      {
+        "hashed_secret": "33f220dd67f717cc949db63e21c90e130a6137da",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 56,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/cli/notify-slack.md": [
+      {
+        "hashed_secret": "1572c8dd915cf3bdecae817b1cb65847b4e94037",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 61,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "2d8b1074eb78b85690ced3d2cc0aed0466f6f652",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 207,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
     "src/mas/devops/templates/ibm-entitlement-dockerconfig.json.j2": [
       {
         "hashed_secret": "d2e2ab0f407e4ee3cf2ab87d61c31b25a74085e5",
@@ -105,6 +143,16 @@
         "verified_result": null
       }
     ],
+    "test/src/test_backup.py": [
+      {
+        "hashed_secret": "4dfd3a58b4820476afe7efa2e2c52b267eec876a",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 753,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
     "test/src/test_db2.py": [
       {
         "hashed_secret": "a4b48a81cdab1e1a5dd37907d6c85ca1c61ddc7c",

AGENT_INSTRUCTIONS.md

@@ -0,0 +1,84 @@
+# python-devops AI Coding Instructions
+
+## Project Overview
+Python package for IBM Maximo DevOps utilities. Provides command-line tools for deployment automation, database validation, Slack notifications, and user management. Distributed as installable package with `setup.py`/`pyproject.toml` and standalone scripts in `bin/`.
+
+## Architecture
+- **bin/**: Executable CLI scripts (entry points)
+  - `mas-devops-*`: Command-line tools for specific operations
+  - Scripts import from `src/` package for implementation
+  - Each script typically wraps a single operational task
+- **src/**: Main package source code
+  - Organized by module/function (import path: `from mas_devops import ...`)
+  - Core utilities: configuration management, API clients, database handlers
+- **test/**: Test suite (pytest structure)
+  - Mirror `src/` structure in test files
+  - Run with `pytest` or `make test`
+- **build/**: Generated artifacts (don't edit)
+  - `*.egg-info/`: Package metadata
+  - `dist/`, `*.whl`: Distribution packages
+- **setup.py** / **pyproject.toml**: Package definition
+  - Entry points defined in setup.py pointing to `bin/` scripts
+  - Dependencies in both files (must keep in sync)
+  - Version defined once (check both files)
+
+## Key Patterns
+- **CLI Tool Pattern**: `bin/mas-devops-*` scripts are thin wrappers
+  - Import main logic from `src/mas_devops/`
+  - Handle argument parsing and error reporting
+  - Example: `mas-devops-notify-slack` → calls slack notification module
+- **Dependency Management**:
+  - Core dependencies in `setup.py` `install_requires`
+  - Dev dependencies in `setup.py` `extras_require['dev']`
+  - `requirements.txt` for pinned versions (reproducible installs)
+  - Keep all three in sync
+- **Entry Points**: `setup.py` defines CLI commands
+  - Format: `'mas-devops-task-name = mas_devops.module:main_function'`
+  - Creates executable scripts in `bin/` when package installed
+- **Module Organization**: Import directly from package
+  - `from mas_devops.db2_validator import validate_config`
+  - Avoid deep nesting; keep public API clear
+
+## Development Workflow
+```bash
+make install           # Install package in dev mode (pip install -e .)
+make test              # Run pytest suite
+make test-verbose      # Pytest with verbose output
+make build             # Build distribution (wheel/tarball)
+make clean             # Remove build artifacts
+make all               # Clean, test, build
+```
+
+## Important Conventions
+- **Python Version**: Check `setup.py` for `python_requires` (e.g., `>=3.8`)
+- **Entry Points**: Adding new CLI tool requires editing `setup.py` entry_points section
+- **Error Handling**: CLI scripts should catch exceptions and exit with meaningful error messages
+- **Logging**: Use Python logging module; configure in main module
+- **Testing**: Test structure mirrors source; test file for `src/module.py` is `test/test_module.py`
+- **Documentation**: Docstrings in functions should describe parameters, return, exceptions
+- **Imports**: Use absolute imports from package (`from mas_devops import ...`), not relative
+
+## Common CLI Tools (Reference)
+- `mas-devops-create-initial-users-for-saas`: User provisioning (SaaS)
+- `mas-devops-db2-validate-config`: Validate DB2 configuration
+- `mas-devops-notify-slack`: Send notifications
+- `mas-devops-saas-job-cleaner`: Cleanup SaaS jobs
+
+## Integration Points
+- **ansible-devops**: Playbooks call these Python utilities for infrastructure setup
+- **playbook**: Runbooks document procedures; Python tools automate them
+- **Standalone Usage**: Scripts can be called independently or from other tools via entry points
+- **Distribution**: Package installed via pip; entry points register CLI commands globally
+
+## When Adding New CLI Tool
+1. Create implementation module in `src/mas_devops/`
+2. Create script in `bin/mas-devops-tool-name` or update `setup.py` entry_points
+3. Add entry to `setup.py` entry_points section
+4. Add tests in `test/` matching module structure
+5. Update `requirements.txt` if adding dependencies
+6. Test with `make install` then run `mas-devops-tool-name --help`
+
+## Packaging & Distribution
+- Build: `python -m build` or `make build`
+- Outputs: wheel file in `dist/` ready for pip install
+- Version managed in `setup.py` (check both setup.py and pyproject.toml)

MANIFEST.in

@@ -1,3 +1,4 @@
 include src/mas/devops/templates/*.json.j2
 include src/mas/devops/templates/*.yml.j2
 include src/mas/devops/data/catalogs/*.yaml
+include src/mas/devops/data/*.yaml

README.md

@@ -88,5 +88,4 @@ mas-devops-create-initial-users-for-saas \
 Example of initial_users secret:
 ```json
 {"john.smith1@example.com":"primary,john1,smith1","john.smith2@example.com":"primary,john2,smith2","john.smith3@example.com":"secondary,john3,smith3"}
-```
-
+```

bin/mas-devops-notify-slack

@@ -33,7 +33,7 @@ def _getToolchainLink() -> str:
     return ""
 
 
-def notifyProvisionFyre(channels: list[str], rc: int, additionalMsg: str = None) -> bool:
+def notifyProvisionFyre(channels: list[str], rc: int, additionalMsg: str | None = None) -> bool:
     """Send Slack notification about Fyre OCP cluster provisioning status."""
     name = _getClusterName()
     toolchainLink = _getToolchainLink()
@@ -67,7 +67,7 @@ def notifyProvisionFyre(channels: list[str], rc: int, additionalMsg: str = None)
     return response.data.get("ok", False)
 
 
-def notifyProvisionRoks(channels: list[str], rc: int, additionalMsg: str = None) -> bool:
+def notifyProvisionRoks(channels: list[str], rc: int, additionalMsg: str | None = None) -> bool:
     """Send Slack notification about ROKS cluster provisioning status."""
     name = _getClusterName()
     toolchainLink = _getToolchainLink()
@@ -81,14 +81,14 @@ def notifyProvisionRoks(channels: list[str], rc: int, additionalMsg: str = None)
         message = [
             SlackUtil.buildHeader(f":glyph-ok: Your IBM Cloud ROKS cluster ({name}) is ready"),
             SlackUtil.buildSection(f"{url}"),
-            SlackUtil.buildSection(f"<https://cloud.ibm.com/kubernetes/clusters|IBM Cloud Dashboard>{toolchainLink}")
+            SlackUtil.buildSection(f"<https://cloud.ibm.com/kubernetes/clusters|IBM Cloud Dashboard> | {toolchainLink}")
         ]
         if additionalMsg is not None:
             message.append(SlackUtil.buildSection(additionalMsg))
     else:
         message = [
             SlackUtil.buildHeader(f":glyph-fail: Your IBM Cloud ROKS cluster ({name}) failed to deploy"),
-            SlackUtil.buildSection(f"<https://cloud.ibm.com/kubernetes/clusters|IBM Cloud Dashboard>{toolchainLink}")
+            SlackUtil.buildSection(f"<https://cloud.ibm.com/kubernetes/clusters|IBM Cloud Dashboard> | {toolchainLink}")
         ]
 
     response = SlackUtil.postMessageBlocks(channels, message)

docs/api/aiservice.md

@@ -0,0 +1,5 @@
+# AI Service Module
+
+The `aiservice` module provides functions for AI/ML service management and configuration.
+
+::: mas.devops.aiservice

docs/api/db2.md

@@ -0,0 +1,5 @@
+# DB2 Module
+
+The `db2` module provides functions for DB2 database configuration and validation.
+
+::: mas.devops.db2

docs/api/index.md

@@ -0,0 +1,98 @@
+# API Reference
+
+Welcome to the MAS DevOps API reference documentation. This section provides detailed documentation for all modules, classes, and functions in the `mas-devops` package.
+
+## Core Modules
+
+These modules provide fundamental operations for working with OpenShift/Kubernetes and related technologies:
+
+- **[OCP](ocp.md)**: OpenShift/Kubernetes cluster operations including namespace management, resource creation, and cluster interactions
+- **[Tekton](tekton.md)**: Pipeline management, installation, and execution of Tekton pipelines for MAS automation
+- **[OLM](olm.md)**: Operator Lifecycle Manager operations for installing and managing operators
+- **[Utils](utils.md)**: Common utility functions and helper methods used throughout the library
+
+## MAS Modules
+
+Modules specifically designed for managing Maximo Application Suite:
+
+- **[Suite](mas/suite.md)**: Core MAS suite management including installation, configuration, and lifecycle operations
+- **[Apps](mas/apps.md)**: MAS application management for deploying and configuring MAS applications like Manage, Monitor, etc.
+
+## Service Integration Modules
+
+Modules for integrating with various services and dependencies:
+
+- **[DB2](db2.md)**: Database operations including DB2 configuration validation and management
+- **[SLS](sls.md)**: Suite License Service integration for license management
+- **[AI Service](aiservice.md)**: AI/ML service management and configuration
+- **[Slack](slack.md)**: Slack notification and alerting integration
+
+## SaaS Modules
+
+Modules for SaaS-specific operations:
+
+- **[Job Cleaner](saas/job_cleaner.md)**: Utilities for cleaning up completed jobs in SaaS environments
+
+## User Management
+
+- **[Users](users.md)**: User creation and management for MAS deployments
+
+## Module Overview
+
+### Core Operations
+
+The core modules provide the foundation for all MAS DevOps operations:
+
+```python
+from mas.devops.ocp import createNamespace, getResource
+from mas.devops.tekton import installOpenShiftPipelines
+from mas.devops.olm import installOperator
+from mas.devops.utils import waitForResource
+```
+
+### MAS Management
+
+Work with MAS suite and applications:
+
+```python
+from mas.devops.mas.suite import installMAS, configureMAS
+from mas.devops.mas.apps import installApp, configureApp
+```
+
+### Service Integration
+
+Integrate with external services:
+
+```python
+from mas.devops.db2 import validateDB2Config
+from mas.devops.sls import configureSLS
+from mas.devops.slack import sendSlackNotification
+```
+
+## Navigation
+
+Use the navigation menu on the left to browse through the API documentation for each module. Each module page includes:
+
+- Module overview and purpose
+- Class and function documentation with parameters and return types
+- Usage examples
+- Related modules and cross-references
+
+## Conventions
+
+Throughout the API documentation:
+
+- **Required parameters** are clearly marked
+- **Optional parameters** include default values
+- **Return types** are specified for all functions
+- **Exceptions** that may be raised are documented
+- **Examples** demonstrate common usage patterns
+
+## Getting Help
+
+If you need help using the API:
+
+1. Check the [Quick Start Guide](../getting-started/quickstart.md) for common usage patterns
+2. Review the specific module documentation for detailed information
+3. Look at the [CLI Tools](../cli/index.md) for command-line usage examples
+4. Visit the [GitHub repository](https://github.com/ibm-mas/python-devops) to report issues or ask questions