How ibm/operator-collection-sdk works
Project Type and Purpose
• This is an open-source CLI/toolkit (written as an Ansible Collection) designed to scaffold, develop, test, and publish “Operator Collections” for the IBM® z/OS® Cloud Broker on OpenShift.
• Key purpose: provide playbooks, roles, and custom modules to automate creation and management of Ansible-based Kubernetes Operators.
File Structure Highlights
• Top-level:
• .github/ : CI workflows for “test” and “release” on GitHub Actions
• docs/ : design specs, tutorial, lifecycle, ansible-mod docs
• examples/ : sample “racf-operator” Collection with playbooks, roles, inventories
• ibm/operator_collection_sdk/ : the main SDK collection
– playbooks/ : idempotent tasks (create_operator, build_collection, etc.)
– roles/ : reusable task logic (build_collection, cluster_setup, etc.)
– plugins/modules/ : custom Ansible modules (oc_operatorcollection, oc_zosendpoint, etc.)
– plugins/doc_fragments/ : documentation snippets for modules
– meta/**, galaxy.yml, ansible.cfg : collection metadata & configuration
– tests/ : sanity checks
a. Developer Local Environment
• Ansible CLI + “ibm.operator_collection_sdk” Collection
• Playbooks invoke Roles & Plugins → generate Kubernetes CRDs & Operator resources
• Local Docker container build (for local operator debugging)
b. Version Control & CI/CD
• GitHub Repo hosts code
• GitHub Actions “test.yml” runs ansible-lint, molecule, sanity tests
• GitHub Actions “release.yml” publishes Collection to Ansible Galaxy or container registries
c. OpenShift Cluster
• IBM z/OS Cloud Broker installed
• OperaterCollections CRs created by playbooks → dynamically converted to Operators
• SubOperatorConfig & ZosEndpoint CRs injected
d. External Services & Artifact Stores
• Git/Galaxy (artifact repository for Ansible Collections)
• Docker Registry (optional: built operator images)
• z/OS Cloud Broker API
Interactions & Data Flows
• Developer → (ansible-playbook) → SDK Playbooks/Roles/Plugins → OpenShift APIs
• Playbooks → create YAML CRDs (operatorcollection.yml, suboperatorconfig.yml, etc.) via Jinja templates
• CI/CD pipeline → on push/tag → run tests (molecule, lint) → publish artifacts
• Collection publish → Ansible Galaxy & optionally Docker image registry
• OpenShift & z/OS Cloud Broker → reconcile CRs to actual running operator pods
Architectural Patterns & Principles
• Plugin-based: custom modules extend Ansible (oc_*.py)
• Role-based decomposition: each functional area (build, cluster_setup, upload) is a role
• Template-driven CR generation: Jinja2 templates in playbooks → consistent operator manifests
• Declarative infrastructure: leveraging Kubernetes CustomResourceDefinitions
Execution Steps
1. Sketch high-level lanes: Development, CI/CD, Deployment
2. Components in respective lanes
4. Technologies at each boundary (Ansible CLI, GitHub Actions, Kubernetes API, z/OS Cloud Broker API)
5. Iterate with team to ensure coverage of all playbooks, roles, and plugins modules