📖 (docs) draft catalogd docs with new metas endpoint #1841

anik120 · 2025-03-04T19:42:48Z

Description

Reviewer Checklist

API Go Documentation
Tests: Unit Tests (and E2E Tests, if appropriate)
Comprehensive Commit Messages
Links to related GitHub Issue(s)

netlify · 2025-03-04T19:43:06Z

✅ Deploy Preview for olmv1 ready!

Name	Link
🔨 Latest commit	`5791b14`
🔍 Latest deploy log	https://app.netlify.com/sites/olmv1/deploys/67d43aabab1ef60008889d40
😎 Deploy Preview	https://deploy-preview-1841--olmv1.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

codecov · 2025-03-04T19:51:31Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 69.04%. Comparing base (66b97ad) to head (5791b14).
Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1841   +/-   ##
=======================================
  Coverage   69.04%   69.04%           
=======================================
  Files          65       65           
  Lines        5263     5263           
=======================================
  Hits         3634     3634           
  Misses       1396     1396           
  Partials      233      233

Flag	Coverage Δ
e2e	`50.01% <ø> (-0.08%)`	⬇️
unit	`56.96% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

docs/api-reference/catalogd-webserver.md

docs/howto/catalog-queries.md

azych

added a few comments, but /lgtm

docs/api-reference/catalogd-webserver.md

azych · 2025-03-05T08:10:58Z

docs/api-reference/catalogd-webserver.md

@@ -13,6 +18,21 @@ As an example, to access the full FBC via the v1 API endpoint (indicated by path

 the URL to access the service would be `https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio/api/v1/all`

+2. `api/v1/metas` endpoint that allows clients to retrive filtered portions of the FBC. 
+
+The metas endpoint accepts additional parameters following the pattern `/api/v1/metas?<parameters>`, and accepts parameters that corresponds to any combination of the fields of the [FBC Meta structure](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#schema) (except for `Blob`).


additional parameters following the pattern

I think we could just say 'query parameters'?

Also, accepts parameters repeats right after comma. Maybe just: The metas endpoint accepts query parameters that correspond to...?

to any combination of the fields ... (except for Blob)

maybe being more explicit here and for listing for example the elements of the Meta schema might make sense?

Another thing is, what does Blob refer to? Reading the documentation, there is this for example:

Each operator package in a catalog requires exactly one olm.package blob, at least one olm.channel blob, and one or more olm.bundle blobs.

but those would be valid query params, right?

Yea it's a little confusing. The Blob I was trying to highlight isn't a valid query parameter is this Blob.

I agree, there's a lot of blobs ;)

docs/howto/catalog-queries.md

docs/api-reference/catalogd-webserver.md

docs/howto/catalog-queries.md

docs/tutorials/explore-available-content.md

azych · 2025-03-06T09:51:53Z

docs/howto/catalog-queries.md

@@ -12,6 +12,9 @@ Then you can query the catalog by using `curl` commands and the `jq` CLI tool to
    By default, Catalogd is installed with TLS enabled for the catalog webserver.
    The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag.

+!!! note 


this doesn't render correctly, I think the syntax is [!NOTE], or maybe [!IMPORTANT]?

Similar case for https://github.com/operator-framework/operator-controller/pull/1841/files#diff-6295b5bd58ccf02e628fe42adbc43f32b9df3f3ad4ab61ac813366162d65a490R54 and https://github.com/operator-framework/operator-controller/pull/1841/files#diff-944a5a8340da19a891934706c3a6a9f5eeded7eacdce3c107edd1f9dfdd7f173R36

resolved in #1841 (comment)

anik120 · 2025-03-06T19:24:36Z

Not sure if I clicked any button but I did not dismiss any reviews 👀

joelanford · 2025-03-06T20:18:40Z

docs/api-reference/catalogd-webserver.md

For net-new functionality, the process default is to add a new "drafts" doc.

Also, this feature is still feature gated and off by default. Official docs should probably not include information about feature gated features, except potentially in a separate doc that lists all of the feature gates and describes what they do.

It totally slipped my mind that this feature is behind a feature gate and isn't GA yet. I've moved the docs that need updating with the new endpoint (when feature gate is enabled) to the /docs/drafts folder as per our discussion in slack. PTAL

anik120 · 2025-03-12T19:26:02Z

Rebased and pushed cc: @joelanford @grokspawn @azych

azych · 2025-03-13T15:03:58Z

docs/draft/api-reference/catalogd-webserver-metas-endpoint.md

+
+Responses are encoded as a [JSON Lines](https://jsonlines.org/) stream of [File-Based Catalog](https://olm.operatorframework.io/docs/reference/file-based-catalogs) (FBC) [Meta](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#schema) objects delimited by newlines.
+
+??? example "Example JSON-encoded FBC snippet"


same here, this doesn't display correctly, together with the two ``` blocks below

This is fine with our rendering system ... just not the github review front-end.
This doc includes both sequences: https://operator-framework.github.io/operator-controller/api-reference/catalogd-webserver/

good to know, thanks. @anik120 feel free to resolve, as I can't do it with my access level :-)

azych

apart from multiple places where formatting doesn't display correctly (!!!, ???, ```), the actual documentation looks good to me

/lgtm

anik120 · 2025-03-13T18:08:26Z

I see multiple instances of !!! note and ??? example etc in other places in the documentation, so that means we'll have to do a full sweep of these based off of what @azych has discovered.

I'm merging this PR with the lgtm I have since it's in /docs/draft, and a follow up PR to sweep the whole area for !!! note, ??? example etc will take care of the ones @azych pointed here anyway (also because PR hasn't received any other feedback other than 👈🏽 for a while now).

anik120 · 2025-03-13T18:09:55Z

Actually, looks like @grokspawn has a requested review, going to wait for a bit

grokspawn · 2025-03-13T18:22:00Z

docs/draft/api-reference/catalogd-webserver-metas-endpoint.md

+
+For more examples of valid queries that can be made to the `api/v1/metas` service endpoint, please see [Catalog Queries](../howto/catalog-queries.md).
+
+!!! note


We don't have a problem here. The !!! note notation is supported by the mkdocs pipeline.
For e.g. see existing rendered docs here, immediately before the section 3 header: "Granting User Access to API Resources".

grokspawn · 2025-03-13T18:46:07Z

docs/draft/tutorials/explore-available-content-metas-endpoint.md

+    !!! important
+        Currently, OLM 1.0 does not support the installation of extensions that use webhooks or that target a single or specified set of namespaces.
+
+3. Return list of packages where the channel head version use `olm.csv.metadata` format, support `AllNamespaces` install mode and do not use webhooks:


nit:

Suggested change

3. Return list of packages where the channel head version use `olm.csv.metadata` format, support `AllNamespaces` install mode and do not use webhooks:

3. Return list of packages which support `AllNamespaces` install mode, do not use webhooks, and where the channel head version uses `olm.csv.metadata` format:

blocking updates were resolved

Closes operator-framework#1782 Signed-off-by: Anik Bhattacharjee <[email protected]>

openshift-ci · 2025-03-14T14:18:20Z

New changes are detected. LGTM label has been removed.

anik120 requested a review from a team as a code owner March 4, 2025 19:42

tmshort reviewed Mar 4, 2025

View reviewed changes

docs/api-reference/catalogd-webserver.md Outdated Show resolved Hide resolved

tmshort reviewed Mar 4, 2025

View reviewed changes

docs/howto/catalog-queries.md Outdated Show resolved Hide resolved

tmshort reviewed Mar 4, 2025

View reviewed changes

docs/howto/catalog-queries.md Outdated Show resolved Hide resolved

azych previously approved these changes Mar 5, 2025

View reviewed changes

anik120 force-pushed the metas-api-docs branch from e8cce48 to 39acdca Compare March 5, 2025 20:09

grokspawn reviewed Mar 5, 2025

View reviewed changes

docs/api-reference/catalogd-webserver.md Outdated Show resolved Hide resolved

grokspawn reviewed Mar 5, 2025

View reviewed changes

docs/api-reference/catalogd-webserver.md Outdated Show resolved Hide resolved

anik120 force-pushed the metas-api-docs branch from 39acdca to 8c9ba36 Compare March 5, 2025 20:29

grokspawn previously requested changes Mar 5, 2025

View reviewed changes

anik120 force-pushed the metas-api-docs branch from 8c9ba36 to 8e7acd2 Compare March 5, 2025 22:06

azych reviewed Mar 6, 2025

View reviewed changes

anik120 dismissed azych’s stale review via 8e7acd2 March 6, 2025 17:46

joelanford reviewed Mar 6, 2025

View reviewed changes

anik120 force-pushed the metas-api-docs branch from 8e7acd2 to bafe6e4 Compare March 7, 2025 20:26

anik120 changed the title ~~📖 (docs) update catalogd docs to include new metas endpoint~~ 📖 (docs) draft catalogd docs with new metas endpoint Mar 7, 2025

anik120 force-pushed the metas-api-docs branch from bafe6e4 to e88bcf9 Compare March 12, 2025 19:25

azych reviewed Mar 13, 2025

View reviewed changes

azych approved these changes Mar 13, 2025

View reviewed changes

openshift-ci bot assigned azych Mar 13, 2025

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Mar 13, 2025

anik120 enabled auto-merge March 13, 2025 18:08

grokspawn reviewed Mar 13, 2025

View reviewed changes

(docs) draft catalogd docs with new metas endpoint

5791b14

Closes operator-framework#1782 Signed-off-by: Anik Bhattacharjee <[email protected]>

anik120 force-pushed the metas-api-docs branch from e88bcf9 to 5791b14 Compare March 14, 2025 14:18

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Mar 14, 2025

perdasilva approved these changes Mar 17, 2025

View reviewed changes

anik120 added this pull request to the merge queue Mar 17, 2025

Merged via the queue into operator-framework:main with commit 18a4638 Mar 17, 2025
20 checks passed

grokspawn mentioned this pull request Mar 26, 2025

📖 removing duplicated content #1879

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📖 (docs) draft catalogd docs with new metas endpoint #1841

📖 (docs) draft catalogd docs with new metas endpoint #1841

anik120 commented Mar 4, 2025

netlify bot commented Mar 4, 2025 •

edited

Loading

codecov bot commented Mar 4, 2025 •

edited

Loading

azych left a comment

azych Mar 5, 2025

azych Mar 5, 2025

anik120 Mar 6, 2025

azych Mar 6, 2025

azych Mar 6, 2025

azych Mar 14, 2025

anik120 commented Mar 6, 2025

joelanford Mar 6, 2025

anik120 Mar 7, 2025

anik120 commented Mar 12, 2025

azych Mar 13, 2025

grokspawn Mar 13, 2025

azych Mar 14, 2025

azych left a comment

anik120 commented Mar 13, 2025

anik120 commented Mar 13, 2025

grokspawn Mar 13, 2025 •

edited

Loading

grokspawn Mar 13, 2025 •

edited

Loading

anik120 Mar 14, 2025

openshift-ci bot commented Mar 14, 2025


		Responses are encoded as a [JSON Lines](https://jsonlines.org/) stream of [File-Based Catalog](https://olm.operatorframework.io/docs/reference/file-based-catalogs) (FBC) [Meta](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#schema) objects delimited by newlines.

		??? example "Example JSON-encoded FBC snippet"


		For more examples of valid queries that can be made to the `api/v1/metas` service endpoint, please see [Catalog Queries](../howto/catalog-queries.md).

		!!! note

	3. Return list of packages where the channel head version use `olm.csv.metadata` format, support `AllNamespaces` install mode and do not use webhooks:
	3. Return list of packages which support `AllNamespaces` install mode, do not use webhooks, and where the channel head version uses `olm.csv.metadata` format:

📖 (docs) draft catalogd docs with new metas endpoint #1841

📖 (docs) draft catalogd docs with new metas endpoint #1841

Conversation

anik120 commented Mar 4, 2025

Description

Reviewer Checklist

netlify bot commented Mar 4, 2025 • edited Loading

✅ Deploy Preview for olmv1 ready!

codecov bot commented Mar 4, 2025 • edited Loading

Codecov Report

azych left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anik120 commented Mar 6, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anik120 commented Mar 12, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

azych left a comment

Choose a reason for hiding this comment

anik120 commented Mar 13, 2025

anik120 commented Mar 13, 2025

grokspawn Mar 13, 2025 • edited Loading

Choose a reason for hiding this comment

grokspawn Mar 13, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openshift-ci bot commented Mar 14, 2025

netlify bot commented Mar 4, 2025 •

edited

Loading

codecov bot commented Mar 4, 2025 •

edited

Loading

grokspawn Mar 13, 2025 •

edited

Loading

grokspawn Mar 13, 2025 •

edited

Loading