|
1 | 1 | # CoolCatalog |
2 | | -Repository that showcases example workflows for building OLM Catalogs via Declarative Configurations |
| 2 | +Welcome! This repository showcases example workflows for building OLM Catalogs via Declarative Configurations |
| 3 | + |
| 4 | +## Quickstart |
| 5 | +1. fork this repository |
| 6 | +2. determine the desired storage format of the resulting FBC catalog hierarchy (unversioned per-operator partitions? nested versions? etc.) |
| 7 | +3. add/modify/adjust action CI configurations in [.github/workflows](.github/workflows) |
| 8 | +4. communicate your desired storage format to contributors |
| 9 | +5. push changes |
| 10 | + |
| 11 | + |
| 12 | +## Detailed HOWTO |
| 13 | + |
| 14 | +### Actors and Terms |
| 15 | +- [`File-Based Catalog`](https://olm.operatorframework.io/docs/reference/file-based-catalogs/) (FBC) is the declarative expression of operators and their relationships with other operators, other versions of themselves. |
| 16 | +- [`Veneers`](https://olm.operatorframework.io/docs/reference/veneers/) are a general class of objects which can provide a simplified interaction with FBC. |
| 17 | +- `Operator Author` is the role related to expressing an individual operator versions, channels, properties, etc. in a destination catalog. |
| 18 | +- `Catalog` is the FBC-based catalog composed of the FBC contributions of one or more operators. |
| 19 | +- `Catalog Owner` is the role related to integrating Operator Authors' catalog contributions. |
| 20 | +- `Catalog Contribution` is the FBC that a Catalog Ownder receives from an Operator Author. The format needs to be negotiated with the Operator Author. |
| 21 | +For this example, the Catalog Owner receives contributions of a single, unversioned directory named after the operator which contain all FBC files, e.g.: |
| 22 | + |
| 23 | +```tree |
| 24 | +catalog |
| 25 | +├── .indexignore (to make `opm validate` ignore README.md) |
| 26 | +├── README.md |
| 27 | +├── testoperator |
| 28 | +│ ├── .indexignore |
| 29 | +│ ├── OWNERS |
| 30 | +│ └── catalog.yaml |
| 31 | +└── testoperator2 |
| 32 | + ├── .indexignore |
| 33 | + ├── OWNERS |
| 34 | + └── catalog.yaml |
| 35 | +``` |
| 36 | + |
| 37 | +### Lifecycle |
| 38 | + |
| 39 | +This repository models an operator catalog which receives contributions from one or more Operator Authors, merges and organizes those contributions. This repository has pre-configured GitHub actions to validate contributed content, validate FBC contributions, auto-merge contribution PRs, and push updated catalog images capable of serving as [Catalog Sources](https://olm.operatorframework.io/docs/concepts/crds/catalogsource/). |
| 40 | + |
| 41 | + |
| 42 | +```mermaid |
| 43 | +%%{init: {'securityLevel': 'strict', 'theme':'forest'}}%% |
| 44 | +sequenceDiagram |
| 45 | +autonumber |
| 46 | +participant CatalogOwner |
| 47 | +participant Catalog |
| 48 | +participant GHAction |
| 49 | +participant ImageRepo |
| 50 | +CatalogOwner--xCatalog: fork repo |
| 51 | +CatalogOwner--xCatalog: adjust CI |
| 52 | +CatalogOwner--xCatalog: push updates to remote |
| 53 | +CatalogOwner->>+Catalog: Approves PR, merges (auto-merge trivial case) |
| 54 | +activate CatalogOwner |
| 55 | +activate Catalog |
| 56 | +Catalog->>+GHAction: Integrate contribution to catalog |
| 57 | +activate GHAction |
| 58 | +GHAction->>GHAction: validate contribution's Operator Author |
| 59 | +GHAction->>GHAction: generate image contiaining updated catalog |
| 60 | +GHAction->>GHAction: validate catalog in image |
| 61 | +GHAction->>+ ImageRepo: push catalog image to repo |
| 62 | +activate ImageRepo |
| 63 | +deactivate ImageRepo |
| 64 | +deactivate GHAction |
| 65 | +deactivate Catalog |
| 66 | +deactivate CatalogOwner |
| 67 | +``` |
| 68 | + |
| 69 | +1. Fork and Clone Remote Repository |
| 70 | +IMPORTANT! Failure to customize could result in unwanted contributions. |
| 71 | + |
| 72 | +2. Determine Storage Strategy and Adjust CI |
| 73 | +The default configuration for this repository is a collection of operator-titled directories which individually and collectively validate successfully via [`opm validate`](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#opm-validate). The storage strategy must be communicated to any contributing Operator Authors. |
| 74 | + |
| 75 | +3. Customize CI workflows in [.github/workflows](.github/workflows) to suit your authorization, validation, organization, and publication needs. At a minimum, to suit the "as-is" for this repository, you must: |
| 76 | + 1. define a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) `GH_PAT` for the [auto-merge action](https://github.com/marketplace/actions/enable-pull-request-automerge) |
| 77 | + |
| 78 | + 2. Set branch protection rules for the fork (`Settings --> Branches`): |
| 79 | + 1. Add a new rule |
| 80 | + 2. Set the following fields: |
| 81 | + - `Require a pull request before merging` |
| 82 | + - `Require status checks to pass before merging` |
| 83 | + - `Require branches to be up to date before merging` |
| 84 | + 3. Set `Status Checks that are required` by searching for `build` and selecting it from the search results. (Note: you may have to attempt a submission action before this will be available.) |
| 85 | + |
| 86 | + 3. Set general settings for the fork (`Settings --> General`): |
| 87 | + 1. `Allow merge commits` |
| 88 | + 2. `Allow squash merging` |
| 89 | + 3. `Allow auto-merge` |
| 90 | + 4. (optional) `Automatically delete head branches` |
| 91 | + |
| 92 | + 4. (Optional) If you wish to push images to other than docker's image repository |
| 93 | + 1. Add a `repository` field to the docker/login-action, for e.g. quay.io: |
| 94 | + ``` |
| 95 | + - name: login to registry |
| 96 | + uses: docker/login-action@v1 |
| 97 | + with: |
| 98 | + registry: "quay.io" |
| 99 | + username: ${{ secrets.DOCKER_USERNAME }} |
| 100 | + password: ${{ secrets.DOCKER_PASSWORD }} |
| 101 | + ``` |
| 102 | +
|
| 103 | + 2. Add a corresponding `images` field to the docker/metadata-action (e.g. quay.io/exampleuser/cool-catalog) |
| 104 | +
|
| 105 | + ``` |
| 106 | + - name: Docker meta |
| 107 | + id: docker_meta |
| 108 | + uses: docker/metadata-action@v3 |
| 109 | + with: |
| 110 | + images: quay.io/exampleuser/cool-catalog |
| 111 | + tags: ${{ github.event.number }} |
| 112 | + ``` |
| 113 | +
|
| 114 | +4. Push Changes to Remote |
| 115 | +Once finishing customization, push changes to the remote repo to ready it to receive contributions. |
| 116 | +
|
| 117 | +5. Catalog Contribution Approval |
| 118 | +The default configuration of this repo will auto-approve an Operator Author's contribution if: |
| 119 | +
|
| 120 | + 1. the Operator Author is listed in the CODEOWNERS file |
| 121 | + 2. the Catalog Contribution passes validation. This is currently just `opm validate`. |
| 122 | + 3. the Catalog Contribution can be automerged without conflict. |
| 123 | +
|
| 124 | +6. Catalog Publication |
| 125 | +Once a PR merges, a GitHub action will be triggered to build and push a Docker catalog image. |
| 126 | +
|
0 commit comments