Merge branch 'stable' into at.rbac

Author: Aneri Thakkar

.github/workflows/docs.yml

@@ -49,5 +49,3 @@ jobs:
         with:
           branch: gh-pages
           folder: site
-
-# Made with Bob

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2025-12-25T19:13:06Z",
+  "generated_at": "2026-01-14T11:35:47Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -143,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-create-initial-users-for-saas

@@ -34,6 +34,7 @@ if __name__ == "__main__":
     parser.add_argument("--coreapi-port", required=False, default=443)
     parser.add_argument("--admin-dashboard-port", required=False, default=443)
     parser.add_argument("--manage-api-port", required=False, default=443)
+    parser.add_argument("--mas-version", required=False, default="9.0")
 
     group = parser.add_mutually_exclusive_group(required=True)
     group.add_argument("--initial-users-yaml-file")
@@ -56,6 +57,7 @@ if __name__ == "__main__":
 
     mas_instance_id = args.mas_instance_id
     mas_workspace_id = args.mas_workspace_id
+    mas_version = args.mas_version
     initial_users_yaml_file = args.initial_users_yaml_file
     initial_users_secret_name = args.initial_users_secret_name
     coreapi_port = args.coreapi_port
@@ -66,6 +68,7 @@ if __name__ == "__main__":
     logger.info("--------------")
     logger.info(f"mas_instance_id:           {mas_instance_id}")
     logger.info(f"mas_workspace_id:          {mas_workspace_id}")
+    logger.info(f"mas_version:               {mas_version}")
     logger.info(f"initial_users_yaml_file:   {initial_users_yaml_file}")
     logger.info(f"initial_users_secret_name: {initial_users_secret_name}")
     logger.info(f"log_level:                 {log_level}")
@@ -83,7 +86,7 @@ if __name__ == "__main__":
         config.load_kube_config()
         logger.debug("Loaded kubeconfig file")
 
-    user_utils = MASUserUtils(mas_instance_id, mas_workspace_id, client.api_client.ApiClient(), coreapi_port=coreapi_port, admin_dashboard_port=admin_dashboard_port, manage_api_port=manage_api_port)
+    user_utils = MASUserUtils(mas_instance_id, mas_workspace_id, client.api_client.ApiClient(), mas_version, coreapi_port=coreapi_port, admin_dashboard_port=admin_dashboard_port, manage_api_port=manage_api_port)
 
     if initial_users_secret_name is not None:
 

mkdocs.yml

@@ -112,5 +112,3 @@ extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/ibm-mas/python-devops
-
-# Made with Bob

setup.py

@@ -64,6 +64,7 @@ def get_version(rel_path):
         'semver',                  # BSD License
         'boto3',                   # Apache Software License
         'slack_sdk',               # MIT License
+        "packaging",               # Apache Software License
     ],
     extras_require={
         'dev': [