Skip to content

Commit

Permalink
Fix docs: "Getting Started" and "Tutorials"
Browse files Browse the repository at this point in the history 
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:
* #1439
* #1434

Signed-off-by: Mikalai Radchuk <[email protected]>
  • Loading branch information
Mikalai Radchuk committed Nov 13, 2024
1 parent 6d79092 commit 7fd5eac
Show file tree
Hide file tree
Showing 7 changed files with 183 additions and 183 deletions.
8 changes: 4 additions & 4 deletions docs/concepts/crd-upgrade-safety.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,18 +61,18 @@ kind: ClusterExtension
metadata:
name: clusterextension-sample
spec:
namespace: default
serviceAccount:
name: argocd-installer
source:
sourceType: Catalog
catalog:
packageName: argocd-operator
version: 0.6.0
install:
namespace: default
serviceAccount:
name: argocd-installer
preflight:
crdUpgradeSafety:
disabled: true
enforcement: "None"
```
You cannot disable individual field validators. If you disable the CRD Upgrade Safety preflight check, all field validators are disabled.
Expand Down
9 changes: 4 additions & 5 deletions docs/getting-started/olmv1_getting_started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ spec:
type: Image
image:
ref: quay.io/operatorhubio/catalog:latest
pollInterval: 10m
pollIntervalMinutes: 10
EOF
```

Expand Down Expand Up @@ -78,8 +78,7 @@ and on the extension upgrade process [here](../tutorials/upgrade-extension.md).

```bash
# Update to v0.11.0
kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"content-management": {"version": "0.11.0"}}}}'

kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
```

For information on the downgrade process, see [here](../tutorials/downgrade-extension.md).
Expand All @@ -106,10 +105,10 @@ kubectl delete namespace argocd

```bash
# Delete installer service account cluster roles
kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole
kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-installer-rbac-clusterrole
```

```bash
# Delete installer service account cluster role bindings
kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
kubectl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-installer-rbac-binding
```
64 changes: 31 additions & 33 deletions docs/tutorials/add-catalog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,41 +29,39 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
name: operatorhubio
name: <catalog_name>
spec:
source:
type: Image
image:
ref: <catalog_image>
pollInterval: <poll_interval_duration>
pollIntervalMinutes: <poll_interval_duration>
```
`catalog_name`
`catalog_image`
: Specifies the image reference for the catalog you want to install, such as `quay.io/operatorhubio/catalog:latest`.

`poll_interval_duration`
: Specifies the interval for polling the remote registry for newer image digests.
The default value is `24h`.
Valid units include seconds (`s`), minutes (`m`), and hours (`h`).
To disable polling, set a zero value, such as `0s`.
: Specifies the number of minutes for polling the remote registry for newer image digests.
This field is optional. To disable polling, unset the field.

``` yaml title="Example `operatorhubio.yaml` CR"
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
name: operatorhub
name: operatorhubio
spec:
source:
type: Image
image:
ref: quay.io/operatorhubio/catalog:latest
pollInterval: 10m
pollIntervalMinutes: 10
```
2. Apply the ClusterCatalog CR:
``` terminal
kubectl apply -f <clustercatalog_cr>.yaml
kubectl apply -f operatorhubio.yaml
```

``` text title="Example output"
Expand All @@ -81,8 +79,8 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://
```

``` terminal title="Example output"
NAME LASTUNPACKED AGE
operatorhubio 9m31s 9m55s
NAME LASTUNPACKED SERVING AGE
operatorhubio 18s True 27s
```

* Check the status of your catalog:
Expand All @@ -99,40 +97,40 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://
API Version: olm.operatorframework.io/v1
Kind: ClusterCatalog
Metadata:
Creation Timestamp: 2024-10-02T19:51:24Z
Finalizers:
Creation Timestamp: 2024-11-13T15:11:08Z
Finalizers:
olm.operatorframework.io/delete-server-cache
Generation: 1
Resource Version: 33321
UID: 52894532-0646-41a5-8285-c7f48bba49e4
Generation: 1
Resource Version: 3069
UID: 2c94ebf8-32ea-4a62-811a-c7098cd2d4db
Spec:
Priority: 0
Availability Mode: Available
Priority: 0
Source:
Image:
Poll Interval: 10m0s
Ref: quay.io/operatorhubio/catalog:latest
Type: Image
Poll Interval Minutes: 10
Ref: quay.io/operatorhubio/catalog:latest
Type: Image
Status:
Conditions:
Last Transition Time: 2024-03-12T19:35:34Z
Last Transition Time: 2024-11-13T15:11:19Z
Message: Successfully unpacked and stored content from resolved source
Observed Generation: 2
Observed Generation: 1
Reason: Succeeded
Status: False
Status: True
Type: Progressing
Last Transition Time: 2024-03-12T19:35:34Z
Last Transition Time: 2024-11-13T15:11:19Z
Message: Serving desired content from resolved source
Observed Generation: 2
Observed Generation: 1
Reason: Available
Status: True
Type: Serving
URLs:
Base: https://catalogd-server.olmv1-system.svc/catalogs/operatorhubio
Last Unpacked: 2024-03-12T19:35:34Z
Last Unpacked: 2024-11-13T15:11:18Z
Resolved Source:
Image:
Last Successful Poll Attempt: 2024-03-12T19:35:26Z
Ref: quay.io/operatorhubio/catalog@sha256:dee29aaed76fd1c72b654b9bc8bebc4b48b34fd8d41ece880524dc0c3c1c55ec
Type: Image
Events: <none>
Ref: quay.io/operatorhubio/catalog@sha256:3cd8fde1dfd4269467451c4b2c77d4196b427004f2eb82686376f28265655c1c
Type: Image
Urls:
Base: https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio
Events: <none>
```
47 changes: 26 additions & 21 deletions docs/tutorials/downgrade-extension.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Custom Resource Definitions (CRDs) ensure that the resources used by the `Cluste

**Disable CRD Safety Check Configuration:**

Add the `crdUpgradeSafety` field and set its `policy` to `Disabled` in the `ClusterExtension` resource under the `preflight` section.
Add the `crdUpgradeSafety` field and set its `enforcement` to `None` in the `ClusterExtension` resource. This configuration disables CRD safety checks during the downgrade process.

**Example:**

Expand All @@ -36,29 +36,27 @@ kind: ClusterExtension
metadata:
name: example-extension
spec:
namespace: argocd
serviceAccount:
name: argocd-installer
install:
preflight:
crdUpgradeSafety:
policy: Disabled
namespace: argocd
serviceAccount:
name: argocd-installer
enforcement: None
source:
sourceType: Catalog
catalog:
packageName: argocd-operator
version: 0.6.0
upgradeConstraintPolicy: SelfCertified
```
**Command Example:**
If you prefer using the command line, you can use `kubectl` to modify the upgrade CRD safety check configuration.

```bash
kubectl patch clusterextension <extension_name> --patch '{"spec":{"install":{"preflight":{"crdUpgradeSafety":{"policy":"Disabled"}}}}}' --type=merge
kubectl patch clusterextension example-extension --patch '{"spec":{"install":{"preflight":{"crdUpgradeSafety":{"enforcement":"None"}}}}}' --type=merge
```
Kubernetes will apply the updated configuration, disabling CRD safety checks during the downgrade process.

### 2. Ignoring Catalog Provided Upgrade Constraints

Expand All @@ -76,24 +74,27 @@ kind: ClusterExtension
metadata:
name: example-extension
spec:
namespace: argocd
serviceAccount:
name: argocd-installer
install:
preflight:
crdUpgradeSafety:
enforcement: None
source:
sourceType: Catalog
catalog:
packageName: argocd-operator
version: 0.6.0
upgradeConstraintPolicy: SelfCertified
install:
namespace: argocd
serviceAccount:
name: argocd-installer
```

**Command Example:**

If you prefer using the command line, you can use `kubectl` to modify the upgrade constraint policy.

```bash
kubectl patch clusterextension <extension_name> --patch '{"spec":{"upgradeConstraintPolicy":"SelfCertified"}}' --type=merge
kubectl patch clusterextension example-extension --patch '{"spec":{"source": {"catalog":{"upgradeConstraintPolicy":"SelfCertified"}}}}' --type=merge
```

### 3. Executing the Downgrade
Expand All @@ -105,7 +106,7 @@ Once the CRD safety checks are disabled and upgrade constraints are set, you can
Modify the `ClusterExtension` custom resource to specify the target version and adjust the upgrade constraints.

```bash
kubectl edit clusterextension <extension_name>
kubectl edit clusterextension example-extension
```

2. **Update the Version:**
Expand All @@ -116,17 +117,21 @@ Once the CRD safety checks are disabled and upgrade constraints are set, you can
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
name: <extension_name>
name: example-extension
spec:
namespace: argocd
serviceAccount:
name: argocd-installer
install:
preflight:
crdUpgradeSafety:
enforcement: None
source:
sourceType: Catalog
catalog:
packageName: <package_name>
packageName: argocd-operator
version: <target_version>
install:
namespace: <namespace>
serviceAccount:
name: <service_account>
upgradeConstraintPolicy: SelfCertified
```

`target_version`
Expand All @@ -145,7 +150,7 @@ After completing the downgrade, verify that the `ClusterExtension` is functionin
1. **Check the Status of the ClusterExtension:**

```bash
kubectl get clusterextension <extension_name> -o yaml
kubectl get clusterextension example-extension -o yaml
```

Ensure that the `status` reflects the target version and that there are no error messages.
Expand Down
Loading

0 comments on commit 7fd5eac

Please sign in to comment.