# ibm/operator-collection-sdk architecture

> Architecture diagram of the GitHub repository ibm/operator-collection-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/operator-collection-sdk
- Repository: https://github.com/ibm/operator-collection-sdk

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Lanes
    subgraph "Development Environment" 
        direction TB
        DevHost["Developer Host\nAnsible CLI + SDK Collection"]:::dev
        subgraph "SDK Core"
            direction TB
            Playbooks(["Playbooks"]):::process
            Roles(["Roles"]):::process
            Plugins(["Custom Modules"]):::process
            Templates(["Jinja2 Templates"]):::process
            Tests(["Molecule Tests"]):::process
            Docs(["Documentation Snippets"]):::process
            Meta(["Metadata & Config"]):::process
        end
        ExampleOp["Example: racf-operator"]:::process
    end

    subgraph "CI/CD Pipeline"
        direction TB
        GitHub["GitHub Repo"]:::ci
        TestWF["Test Workflow"]:::ci
        ReleaseWF["Release Workflow"]:::ci
    end

    subgraph "Deployment Environment"
        direction TB
        OpenShift["OpenShift Cluster"]:::deploy
        Broker["IBM z/OS Cloud Broker"]:::deploy
        KubeAPI["Kubernetes API"]:::deploy
    end

    subgraph "External Services"
        direction TB
        Galaxy["Ansible Galaxy"]:::external
        DockerReg["Docker Registry"]:::external
        ZosAPI["z/OS Cloud Broker API"]:::external
    end

    %% Connections
    DevHost -->|invokes| Playbooks
    Playbooks -->|use| Roles
    Playbooks -->|invoke| Plugins
    Playbooks -->|render| Templates
    Playbooks -->|run tests| Tests
    Playbooks -->|generate CRDs| KubeAPI
    DevHost -->|uses example| ExampleOp

    DevHost -->|git push/tag| GitHub
    GitHub -->|triggers| TestWF
    GitHub -->|triggers| ReleaseWF
    TestWF -->|lint & test| Playbooks
    ReleaseWF -->|publish| Galaxy
    ReleaseWF -->|push images| DockerReg

    KubeAPI -->|reconcile CRs| Broker
    Broker -->|calls| ZosAPI

    %% Click Events
    click DevHost "https://github.com/ibm/operator-collection-sdk/tree/develop/ibm/operator_collection_sdk/"
    click Playbooks "https://github.com/ibm/operator-collection-sdk/tree/develop/ibm/operator_collection_sdk/playbooks/"
    click Roles "https://github.com/ibm/operator-collection-sdk/tree/develop/ibm/operator_collection_sdk/playbooks/roles/"
    click Plugins "https://github.com/ibm/operator-collection-sdk/tree/develop/ibm/operator_collection_sdk/plugins/modules/"
    click Templates "https://github.com/ibm/operator-collection-sdk/blob/develop/ibm/operator_collection_sdk/playbooks/templates/operatorcollection.yml"
    click Tests "https://github.com/ibm/operator-collection-sdk/tree/develop/ibm/operator_collection_sdk/playbooks/molecule/"
    click Docs "https://github.com/ibm/operator-collection-sdk/blob/develop/ibm/operator_collection_sdk/plugins/doc_fragments/documentation.py"
    click Meta "https://github.com/ibm/operator-collection-sdk/blob/develop/ibm/operator_collection_sdk/galaxy.yml"
    click Meta "https://github.com/ibm/operator-collection-sdk/blob/develop/ibm/operator_collection_sdk/ansible.cfg"
    click Meta "https://github.com/ibm/operator-collection-sdk/blob/develop/ibm/operator_collection_sdk/meta/runtime.yml"
    click TestWF "https://github.com/ibm/operator-collection-sdk/blob/develop/.github/workflows/test.yml"
    click ReleaseWF "https://github.com/ibm/operator-collection-sdk/blob/develop/.github/workflows/release.yml"
    click ExampleOp "https://github.com/ibm/operator-collection-sdk/tree/develop/examples/racf-operator/"
    click Galaxy "https://github.com/ibm/operator-collection-sdk/blob/develop/examples/racf-operator/collections/requirements.txt"
    click Galaxy "https://github.com/ibm/operator-collection-sdk/blob/develop/examples/racf-operator/galaxy.yml"

    %% Styles
    classDef dev fill:#dae8fc,stroke:#6c8ebf,color:#1f3c88;
    classDef ci fill:#d5ead1,stroke:#82b366,color:#395306;
    classDef deploy fill:#ffe0b2,stroke:#e69138,color:#7f6000;
    classDef external fill:#eeeeee,stroke:#bbbbbb,color:#333333;
    classDef process fill:#ffffff,stroke:#888888,color:#000000;
```
