{"id":46775873,"url":"https://github.com/stacklok/toolhive-operator-metadata","last_synced_at":"2026-03-09T23:43:59.033Z","repository":{"id":322260989,"uuid":"1086023765","full_name":"stacklok/toolhive-operator-metadata","owner":"stacklok","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-05T18:39:29.000Z","size":1058,"stargazers_count":0,"open_issues_count":5,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-09T07:12:19.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacklok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-29T20:51:53.000Z","updated_at":"2025-12-05T18:39:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stacklok/toolhive-operator-metadata","commit_stats":null,"previous_names":["stacklok/toolhive-operator-metadata"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stacklok/toolhive-operator-metadata","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-operator-metadata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-operator-metadata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-operator-metadata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-operator-metadata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacklok","download_url":"https://codeload.github.com/stacklok/toolhive-operator-metadata/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-operator-metadata/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30316783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T20:05:46.299Z","status":"ssl_error","status_checked_at":"2026-03-09T19:57:04.425Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-09T23:43:58.268Z","updated_at":"2026-03-09T23:43:59.021Z","avatar_url":"https://github.com/stacklok.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ToolHive Operator Metadata\n\nKubernetes/OpenShift manifest metadata and OLM bundle for the [ToolHive Operator](https://github.com/stacklok/toolhive), which manages MCP (Model Context Protocol) servers and registries.\n\n## Overview\n\nThis repository contains:\n- **Kustomize manifests** for deploying the ToolHive Operator\n- **OLMv1 File-Based Catalog (FBC)** for operator distribution via Operator Lifecycle Manager\n- **Bundle metadata** following Operator Framework standards\n\n## GitHub Actions Workflows\n\nAutomated container image builds are available via GitHub Actions for bundle, index, and catalog images. All workflows publish to `ghcr.io/{owner}/{repo}/{type}` with repository-based naming.\n\n**Available Workflows**:\n- **Bundle Build** - Generates and publishes OLM bundle image (required for all OLM versions)\n- **Index Build (OLMv0)** - Publishes SQLite-based index for legacy OpenShift 4.15-4.18\n- **Catalog Build (OLMv1)** - Publishes File-Based Catalog for modern OpenShift 4.19+\n\n**Manual Trigger**:\n1. Go to [Actions tab](../../actions)\n2. Select the desired workflow\n3. Click \"Run workflow\" → Choose branch → Run\n\n**Published Images**:\n- Bundle: `ghcr.io/stacklok/toolhive-operator-metadata/bundle:v0.6.11`\n- Index: `ghcr.io/stacklok/toolhive-operator-metadata/index:v0.6.11`\n- Catalog: `ghcr.io/stacklok/toolhive-operator-metadata/catalog:v0.6.11`\n\nFor detailed workflow usage and troubleshooting, see [specs/014-github-build-actions/quickstart.md](specs/014-github-build-actions/quickstart.md).\n\n## Quick Start\n\n### Prerequisites\n\n- `kustomize` (v5.0.0+)\n- `podman` or `docker`\n- `opm` (Operator Package Manager) - for catalog operations\n- `yq` (v4+) - for YAML processing\n- `imagemagick` - for icon validation (optional, for custom icons)\n- Kubernetes 1.24+ or OpenShift 4.12+\n\n**OpenShift Compatibility**: The operator is fully compatible with OpenShift's `restricted-v2` Security Context Constraint (SCC). The manifests in `config/base/` are specifically configured to run under OpenShift's restrictive security policies without requiring custom SCCs or elevated privileges.\n\n### Building Manifests\n\nBuild kustomize manifests:\n\n```shell\n# Standard Kubernetes deployment\nkustomize build config/default\n\n# OpenShift-specific deployment (includes security context patches)\nkustomize build config/base\n```\n\n**Security Context Configuration**: The OpenShift deployment (`config/base`) applies JSON patches to ensure compliance with the `restricted-v2` SCC:\n- Removes hardcoded `runAsUser` to allow dynamic UID assignment\n- Adds `seccompProfile: RuntimeDefault` for container sandboxing\n- Maintains `runAsNonRoot`, `allowPrivilegeEscalation: false`, and `readOnlyRootFilesystem: true`\n\nSee `config/base/openshift_sec_patches.yaml` for details.\n\n### Building OLM Catalog\n\nBuild the File-Based Catalog container image:\n\n```shell\n# Using Makefile (recommended)\nmake olm-all\n\n# Or manually\nopm validate catalog/\npodman build -f Containerfile.catalog -t ghcr.io/stacklok/toolhive-operator-metadata/catalog:v0.6.11 .\n```\n\n#### Custom Operator Icons\n\nCustomize the operator icon displayed in OperatorHub:\n\n```shell\n# Use custom icon for both bundle and catalog\nmake bundle BUNDLE_ICON=/path/to/your-icon.png\nmake catalog  # Inherits icon from bundle\n\n# Use different icons for bundle and catalog (advanced)\nmake bundle BUNDLE_ICON=/path/to/bundle-icon.png\nmake catalog CATALOG_ICON=/path/to/catalog-icon.gif\n\n# Validate icon before building\nmake validate-icon ICON_FILE=/path/to/your-icon.png\n```\n\n**Icon requirements**:\n- Maximum dimensions: 80px × 40px\n- Aspect ratio: 1:2 (±5%)\n- Supported formats: PNG, JPEG, GIF, SVG\n\nSee [icons/README.md](icons/README.md) for detailed documentation.\n\n### Installing via OLM\n\n#### Modern OpenShift (4.19+) - Recommended\n\n1. Deploy the CatalogSource:\n   ```shell\n   kubectl apply -f examples/catalogsource-olmv1.yaml\n   ```\n\n2. Install the operator:\n   ```shell\n   kubectl create namespace toolhive-system\n   kubectl apply -f examples/subscription.yaml\n   ```\n\n3. Verify installation:\n   ```shell\n   kubectl get csv -n toolhive-system\n   kubectl get pods -n toolhive-system\n   ```\n\n#### Legacy OpenShift (4.15-4.18)\n\nFor older OpenShift versions, use the OLMv0 index image:\n\n1. Build the OLMv0 index image:\n   ```shell\n   make index-olmv0-build\n   ```\n\n2. Deploy the CatalogSource:\n   ```shell\n   kubectl apply -f examples/catalogsource-olmv0.yaml\n   ```\n\n3. Install the operator (same as modern OpenShift)\n\n**Note**: OLMv0 support is temporary for legacy versions and will be sunset when OpenShift 4.18 reaches end-of-life.\n\n## Repository Structure\n\n```\n.\n├── bundle/                 # OLM bundle (CSV, CRDs, metadata)\n├── catalog/                # OLMv1 File-Based Catalog metadata\n├── config/                 # Kustomize manifests\n│   ├── base/              # OpenShift overlay\n│   ├── default/           # Standard Kubernetes config\n│   ├── crd/               # Custom Resource Definitions\n│   ├── manager/           # Operator deployment\n│   └── rbac/              # RBAC manifests\n├── icons/                  # Operator icon assets\n│   ├── default-icon.svg   # Default OLM-compliant icon (80×40)\n│   └── README.md          # Icon documentation\n├── scripts/                # Build and validation scripts\n│   ├── encode-icon.sh     # Base64 encoding for icons\n│   └── validate-icon.sh   # Icon validation (format, size, ratio)\n├── examples/              # Example deployment manifests\n├── Containerfile.catalog  # Catalog image build file\n├── Makefile              # Build and validation targets\n└── VALIDATION.md         # Validation status and compliance report\n```\n\n## Makefile Targets\n\n```shell\nmake help                   # Show all available targets\nmake kustomize-validate     # Validate kustomize builds\nmake bundle-validate        # Validate OLM bundle\nmake catalog-validate       # Validate FBC catalog\nmake catalog-build          # Build catalog container image\nmake catalog-push           # Push catalog image to registry\nmake validate-icon          # Validate custom icon file\nmake check-icon-deps        # Check icon processing dependencies\nmake olm-all               # Complete OLM workflow\nmake constitution-check     # Verify constitution compliance\nmake validate-all          # Run all validations\n```\n\n## Development\n\n### Constitution Compliance\n\nThis repository follows strict constitutional principles (Constitution v1.2.0):\n\n1. **Manifest Integrity**: All kustomize builds must pass\n2. **Kustomize-Based Customization**: Use overlays, not direct modifications\n3. **CRD Immutability**: CRDs are never modified here (upstream only)\n4. **OpenShift Compatibility**: Maintained via config/base overlay\n5. **Namespace Awareness**: Explicit namespace handling\n6. **OLM Catalog Multi-Bundle Support**: Supports multiple bundle versions\n7. **Scorecard Quality Assurance**: All operator-sdk scorecard tests must pass\n\nVerify compliance:\n```shell\nmake constitution-check      # Verify kustomize builds\nmake scorecard-test         # Run scorecard validation\n```\n\n### Adding New Operator Versions\n\n1. Update bundle CSV version in `bundle/manifests/toolhive-operator.clusterserviceversion.yaml`\n2. Update catalog metadata in `catalog/toolhive-operator/catalog.yaml`\n3. Add new bundle entry to the channel\n4. Validate and build:\n   ```shell\n   make olm-all\n   ```\n\n## Validation\n\nAll validation results are documented in [VALIDATION.md](VALIDATION.md).\n\n**Current status**: ✅ All validations passing (v0.6.11)\n\n- FBC Schema: ✅ opm validate passed\n- Bundle Structure: ✅ Complete and correct (1 CSV + 8 CRDs)\n- Scorecard Tests: ✅ All tests passing\n- Constitution Compliance: ✅ All 7 principles satisfied\n- Catalog Image: ✅ Built successfully\n\n## Custom Resources\n\nThe operator manages six custom resource types:\n\n- **MCPRegistry** (`mcpregistries.toolhive.stacklok.dev`) - Manages registries of MCP server definitions\n- **MCPServer** (`mcpservers.toolhive.stacklok.dev`) - Manages individual MCP server instances\n- **MCPGroup** (`mcpgroups.toolhive.stacklok.dev`) - Organizes and manages groups of MCP servers\n- **MCPRemoteProxy** (`mcpremoteproxies.toolhive.stacklok.dev`) - Configures remote proxy connections\n- **MCPExternalAuthConfig** (`mcpexternalauthconfigs.toolhive.stacklok.dev`) - Configures external authentication\n- **MCPToolConfig** (`mcptoolconfigs.toolhive.stacklok.dev`) - Configures individual tools within MCP servers\n\n## License\n\nTBD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-operator-metadata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacklok%2Ftoolhive-operator-metadata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-operator-metadata/lists"}