📖 Fix docs: "Getting Started" and "Tutorials"

[m1kola]

Description

There were several intentional breaking changes in the API which are now included in v0.18.0 release.

This commit mostly focuses on updating the documentation to reflect API changes. This includes making sure that snippets and example outputs match the current state of the project.

Relevant PRs:

• ⚠️ Move .spec.install.namespace and .spec.install.serviceAccount to .spec.namespace and .spec.serviceAccount #1439
• ⚠️ Bump catalogd to v0.36.0 #1434

---

Still need to address (in next parts):

• Need to fix "Return list of packages that support AllNamespaces install mode and do not use webhooks" query here and here. Update: see Fix "Return list of packages that support AllNamespaces install mode and do not use webhooks" catalog query in the docs #1460
• Need a better example for "Upgrade an Extension" doc: currently we use argocd 0.5.0 -> 0.6.0 which fails CRD checks. Update: see Update docs to use example which better demonstrates upgrades #1459
• We also need a better example for "Getting Started": we are currently suggesting to upgrade to 0.11.0 and it fails. Update: see Update docs to use example which better demonstrates upgrades #1459

Reviewer Checklist

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

[netlify]

✅ Deploy Preview for olmv1 ready!

Name	Link
🔨 Latest commit	c6f46e0
🔍 Latest deploy log	https://app.netlify.com/sites/olmv1/deploys/6734dc099f576e0008e357f4
😎 Deploy Preview	https://deploy-preview-1443--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]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 74.69%. Comparing base (046c3df) to head (5e1b44d).
Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1443      +/-   ##
==========================================
- Coverage   74.91%   74.69%   -0.22%     
==========================================
  Files          42       42              
  Lines        3241     3241              
==========================================
- Hits         2428     2421       -7     
- Misses        642      647       +5     
- Partials      171      173       +2     

Flag	Coverage Δ
e2e	51.77% <ø> (-0.28%)	⬇️
unit	57.14% <ø> (-0.07%)	⬇️

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.

[m1kola]

It is already quite a lot of changes. I think I'll do the rest of the docs in a separate PR. Marking as ready for review.

[camilamacedo86]

/hold

Let's create a PR for each fix. With so many changes, it is too hard to review them all.
Furthermore, it is doing many more changes than one doc.

I would suggest each PR has a goal (i.e Fix specific issue A in Y because Z) and not be something generic like "Fix many issues across the project"

[m1kola]

Let's create a PR for each fix. With so many changes, it is too hard to review them all.
Furthermore, it is doing many more changes than one doc.
I would suggest each PR has a goal (i.e Fix specific issue A in Y) and not be something generic like "Fix many issues across the project"

@camilamacedo86 I appreciate that this is difficult to review and I'm usually advocating of small PRs. However on the authoring side it is a lot of tedious manual work here. I spent most of the day today going through docs and verifying the snippets and outputs. And there a lot more to do.

Coordinating this work across multiple PRs will add serious amount of overhead.

But I see that this PR is already large - that's why I'm stopping here and will do the rest of the docs in a separate PR.

[m1kola]

/unhold

[trgeiger]

I left a few small comments, otherwise the changes look good to me

[camilamacedo86]

If you open this doc

1 - It should be using kubectl apply -f - <<EOF so that we can apply it

2 - The command should have the value instead of <extension_name> ( as you changed in the other places )

kubectl patch clusterextension <extension_name> --type='merge' -p '{"spec": {"source": {"catalog": {"version": "<target_version>"}}}}'

3 - The verification step should either have the name ( why are you changing one place and not the others? )

kubectl get clusterextension.olm.operatorframework.io/<extension_name> -o yaml

$ kubectl get clusterextension argocd -o yaml
apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"argocd"},"spec":{"namespace":"argocd","serviceAccount":{"name":"argocd-installer"},"source":{"catalog":{"packageName":"argocd-operator","version":"0.6.0"},"sourceType":"Catalog"}}}
creationTimestamp: "2024-11-11T16:50:53Z"
generation: 4
name: argocd
resourceVersion: "42713"
uid: 4bcaf118-a4cf-4013-842f-501a9da7f597
spec:
namespace: argocd
serviceAccount:
name: argocd-installer
source:
catalog:
packageName: argocd-operator
upgradeConstraintPolicy: CatalogProvided
version: 0.6.0
sourceType: Catalog

[camilamacedo86]

@trgeiger ^

[m1kola]

Updated. Note that I did not change number 1 to use kubectl apply -f - <<EOF: the snippet you are referring to is a pre-requisite. An example of the original state before upgrade.

Resolving,

[m1kola]

Re-opening for review.

Note: we will still need to iterate over "Getting Started" and "Tutorials" sections. See to-dos in the PR descriptions.

[everettraven]

Thanks for going through and updating these @m1kola - the changes LGTM!