MOBB RULES

Managed OpenShift Black Belts - ReUsable Library for Expert Systems

A comprehensive knowledge base of best practices, standards, and guidelines for infrastructure and platform engineering. This repository serves as both a source of truth for AI coding agents and browsable documentation for engineers.

What is MOBB RULES?

MOBB RULES captures the expertise of Red Hat's Managed OpenShift Black Belts (MOBB)—experts specializing in managed OpenShift platforms (ROSA, ARO, OSD). It provides:

• Best practices for cloud providers (AWS, Azure, GCP)
• Platform-specific standards for OpenShift deployments
• Language guidelines for Terraform, Ansible, and Bash
• Security and governance rules
• Testing and documentation standards

Quick Start

For Human Users

Browse the Documentation:

• Visit the published Hugo site (when deployed)
• Or run locally: make preview and open http://localhost:1313

Find Rules:

• Navigate by category: Clouds → Platforms → Languages → Tools
• Use Hugo's built-in search (if enabled)
• Read Markdown files directly in content/ directory

For AI Agents

Read the Knowledge Base:

1. Traverse the content/ directory structure
2. Read raw Markdown files (ignore YAML frontmatter)
3. Apply rules hierarchically (platform inherits cloud, cloud inherits language)
4. See README_AGENTS.md for detailed instructions

Create Project-Specific Rules:

1. Read MOBB RULES from this repository
2. Analyze your project's stack and requirements
3. Compile relevant rules into a project-specific AGENTS.md
4. Create a .cursorrules file referencing your AGENTS.md

See README_AGENTS.md for complete instructions on creating customized best practices.

Repository Structure

.
├── content/              # All rules and best practices live here
│   ├── _index.md        # Homepage - project overview and philosophy
│   ├── global/          # Global best practices (testing, docs, CI/CD, etc.)
│   ├── clouds/          # Cloud provider rules (AWS, Azure, GCP)
│   ├── platforms/       # Platform rules (ROSA, ARO, OSD, OpenShift)
│   ├── languages/       # Language standards (Terraform, Ansible, Bash)
│   └── tools/           # Tool standards (Hugo)
├── layouts/              # Custom Hugo layouts
├── themes/rhds/         # Red Hat Design System theme
├── config.toml          # Hugo configuration
├── Makefile             # Build and preview commands
├── AGENTS.md            # Project-specific best practices
├── README_AGENTS.md     # Instructions for AI agents
├── DESIGN.md            # Project design and architecture
└── README.md            # This file

Using the Knowledge Base

Understanding Rule Inheritance

Rules follow a hierarchical inheritance model:

1. Platform-specific rules (highest priority, most specific)
   • Example: ROSA rules inherit from OpenShift + AWS
2. OpenShift general practices (middle layer)
   • Applies to all OpenShift platforms
3. Cloud-specific rules (foundation layer)
   • AWS, Azure, or GCP standards
4. Language-specific rules (base layer)
   • Terraform, Ansible, Bash standards
5. Global best practices (foundational)
   • Testing, documentation, CI/CD, Git, Makefile patterns

Example: When working on a ROSA project with Terraform:

• Read content/global/_index.md (global best practices - testing, documentation, CI/CD, etc.)
• Read content/platforms/rosa/_index.md (includes ROSA-specific rules)
• Also read content/platforms/openshift/_index.md (general OpenShift practices)
• Also read content/clouds/aws/_index.md (AWS standards)
• Also read content/languages/terraform/_index.md (Terraform best practices)

Example: When working on a Hugo site:

• Read content/tools/hugo/_index.md (Hugo best practices)

Context-Aware Application

Rules should be applied with consideration for the project's purpose:

• Examples/Demos: Prioritize usability and learning; security can be relaxed but documented
• Development: Balance security with developer productivity
• Staging: Apply production-like standards with some flexibility
• Production: Enforce all security best practices strictly

See the Philosophy section for more details.

Building and Previewing

Prerequisites

• Hugo (extended version recommended)
• Make (optional, for using Makefile)

Local Development

Preview the site:

make preview
# or
hugo server -D --bind 0.0.0.0

Then open http://localhost:1313 in your browser.

Build for production:

make build
# or
hugo --minify --gc --environment production

Clean generated files:

make clean

Validate configuration:

make check

Available Make Targets

• make preview or make server - Launch Hugo preview server
• make build - Build the Hugo site for production
• make clean - Remove generated files (public/, resources/)
• make check - Validate Hugo configuration
• make help - Show all available targets

Note: Hugo doesn't include built-in link checking. To check for broken links, use external tools like htmltest, lychee, or linkchecker after building the site.

Contributing

Adding or Updating Rules

1. Edit Markdown files in the content/ directory
2. Follow existing structure and naming conventions
3. Document inheritance - If your section inherits from another, explicitly state it
4. Test locally - Run make preview to verify changes render correctly
5. Submit a PR - Include a clear description of changes

Content Guidelines

• Use Markdown with YAML frontmatter (see archetypes/default.md for template)
• Be specific - Include examples and rationale for rules
• Document inheritance - Clearly state what rules you inherit from
• Keep it maintainable - Follow WET over DRY philosophy (duplication is okay for clarity)

File Organization

• Section roots: Use _index.md for section landing pages
• Naming: Use lowercase with hyphens for directories (osd-aws/, not osd_aws/)
• Structure: Group related rules together logically

Example: Adding a New Cloud Provider Rule

1. Create content/clouds/newcloud/_index.md
2. Follow the structure of existing cloud files (see content/clouds/aws/_index.md)
3. Include sections: Style & Naming, Security & Governance, Testing
4. Update content/clouds/_index.md to reference the new section

Key Documents

• README_AGENTS.md - Instructions for AI agents on using this knowledge base
• AGENTS.md - Project-specific best practices (this project's compiled rules)
• DESIGN.md - Project design, architecture, and design decisions
• content/_index.md - Global manifesto and philosophy
• .cursorrules - Cursor IDE agent instructions

Philosophy

MOBB RULES follows three core principles:

1. Simplicity over Complexity - Favor straightforward, maintainable solutions
2. WET over DRY - Write Everything Twice before abstracting; duplication improves clarity
3. Context-Aware Application - Apply rules based on project purpose and environment

See the manifesto for details.

Deployment

The site is automatically deployed to GitHub Pages via GitHub Actions when changes are pushed to the main branch. See .github/workflows/gh-pages.yaml for the deployment configuration.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE file for the full license text.

Support

For questions or issues:

• Open an issue in this repository
• Contact the MOBB team
• Review DESIGN.md for architectural questions

---

Remember: This knowledge base is a living document. Rules evolve as best practices are refined. Always check the latest content for the most current standards.