Skip to content

📖 Improve formatting on the docs website#1446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
m1kola merged 1 commit into from
Nov 13, 2024
Merged

📖 Improve formatting on the docs website #1446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -43,28 +43,28 @@ you can follow the steps below to test your changes:

1. Create the cluster:

```sh
kind create cluster operator-controller
```
```sh
kind create cluster operator-controller

@m1kolam1kolaNov 12, 2024

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was rendering fine in GH UI. However this doc is also used in the website. This formatting works fine in both GH and on the website.

```

2. Build your changes:

```sh
make build docker-build
```
```sh
make build docker-build
```

3. Load the image locally and Deploy to Kind

```sh
make kind-load kind-deploy
```
```sh
make kind-load kind-deploy
```

### Communication Channels

- Email: [operator-framework-olm-dev](mailto:operator-framework-olm-dev@googlegroups.com)
- Slack: [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2)
- Google Group: [olm-gg](https://groups.google.com/g/operator-framework-olm-dev)
- Weekly in Person Working Group Meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)
- Weekly in Person Working Group Meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)

## How are Milestones Designed?

Expand All@@ -91,7 +91,7 @@ As discussed earlier, the operator-controller adheres to a microservice architec

## Submitting Issues

Unsure where to submit an issue?
Unsure where to submit an issue?

- [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install.
- [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content.
Expand Down
105 changes: 53 additions & 52 deletions docs/concepts/controlling-catalog-selection.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -159,70 +159,71 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera

1. **Create or Update `ClusterCatalogs` with Appropriate Labels and Priority**

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
name: catalog-a
labels:
example.com/support: "true"
spec:
priority: 1000
source:
type: Image
image:
ref: quay.io/example/content-management-a:latest
```

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
name: catalog-b
labels:
example.com/support: "false"
spec:
priority: 500
source:
type: Image
image:
ref: quay.io/example/content-management-b:latest
```
NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied
```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
name: catalog-a
labels:
example.com/support: "true"
spec:
priority: 1000
source:
type: Image
image:
ref: quay.io/example/content-management-a:latest
```

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
name: catalog-b
labels:
example.com/support: "false"
spec:
priority: 500
source:
type: Image
image:
ref: quay.io/example/content-management-b:latest
```
!!! note
An `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied


2. **Create a `ClusterExtension` with Catalog Selection**

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
name: install-my-operator
spec:
packageName: my-operator
catalog:
selector:
matchLabels:
example.com/support: "true"
```
```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
name: install-my-operator
spec:
packageName: my-operator
catalog:
selector:
matchLabels:
example.com/support: "true"
```

3. **Apply the Resources**

```shell
kubectl apply -f content-management-a.yaml
kubectl apply -f content-management-b.yaml
kubectl apply -f install-my-operator.yaml
```
```shell
kubectl apply -f content-management-a.yaml
kubectl apply -f content-management-b.yaml
kubectl apply -f install-my-operator.yaml
```

4. **Verify the Installation**

Check the status of the `ClusterExtension`:
Check the status of the `ClusterExtension`:

```shell
kubectl get clusterextension install-my-operator -o yaml
```
```shell
kubectl get clusterextension install-my-operator -o yaml
```

The status should indicate that the bundle was resolved from `catalog-a` due to the higher priority and matching label.
The status should indicate that the bundle was resolved from `catalog-a` due to the higher priority and matching label.

## Important Notes

Expand Down
19 changes: 11 additions & 8 deletions docs/concepts/upgrade-support.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -17,10 +17,12 @@ When determining upgrade edges, also known as upgrade paths or upgrade constrain

By supporting legacy OLM semantics, OLM v1 now honors the upgrade graph from catalogs accurately.

* If there are multiple possible successors, OLM v1 behavior differs in the following ways:
* In legacy OLM, the successor closest to the channel head is chosen.
* In OLM v1, the successor with the highest semantic version (semver) is chosen.
* Consider the following set of file-based catalog (FBC) channel entries:
If there are multiple possible successors, OLM v1 behavior differs in the following ways:

* In legacy OLM, the successor closest to the channel head is chosen.
* In OLM v1, the successor with the highest semantic version (semver) is chosen.

Consider the following set of file-based catalog (FBC) channel entries:

```yaml
# ...
Expand DownExpand Up@@ -51,7 +53,7 @@ spec:
version: "<version_or_version_range>"
```

where setting the `upgradeConstraintPolicy` to:
Setting the `upgradeConstraintPolicy` to:

`SelfCertified`
: Does not limit the next version to the set of successors, and instead allows for any downgrade, sidegrade, or upgrade.
Expand All@@ -63,8 +65,8 @@ where setting the `upgradeConstraintPolicy` to:

Comment thread
m1kola marked this conversation as resolved.
OLM supports Semver to provide a simplified way for package authors to define compatible upgrades. According to the Semver standard, releases within a major version (e.g. `>=1.0.0 <2.0.0`) must be compatible. As a result, package authors can publish a new package version following the Semver specification, and OLM assumes compatibility. Package authors do not have to explicitly define upgrade edges in the catalog.

> [!NOTE]
> Currently, OLM 1.0 does not support automatic upgrades to the next major version. You must manually verify and perform major version upgrades. For more information about major version upgrades, see [Manually verified upgrades and downgrades](#manually-verified-upgrades-and-downgrades).
!!! note
Currently, OLM 1.0 does not support automatic upgrades to the next major version. You must manually verify and perform major version upgrades. For more information about major version upgrades, see [Manually verified upgrades and downgrades](#manually-verified-upgrades-and-downgrades).
Comment on lines -66 to +69

@m1kolam1kolaNov 12, 2024•
edited
Loading

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

!!! note This renders well in our mkdocs website, but not on GitHub. [!NOTE] renders well on GitHub, but not in mkdocs.

Same applies to other admonitions.

Ref: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#classic-admonitions-docsstylesheetsextracss

We are changing these admonitions in docs dir because these are docs which will be rendered on the website. Leaving everything outside of docs dir as is - these will likely be viewed via GitHub UI.


### Upgrades within the major version zero

Expand All@@ -77,7 +79,8 @@ You must verify and perform upgrades manually in cases where automatic upgrades

## Manually verified upgrades and downgrades

**Warning:** If you want to force an upgrade manually, you must thoroughly verify the outcome before applying any changes to production workloads. Failure to test and verify the upgrade might lead to catastrophic consequences such as data loss.
!!! warning
If you want to force an upgrade manually, you must thoroughly verify the outcome before applying any changes to production workloads. Failure to test and verify the upgrade might lead to catastrophic consequences such as data loss.

As a package admin, if you must upgrade or downgrade to version that might be incompatible with the currently installed version, you can set the `.spec.upgradeConstraintPolicy` field to `SelfCertified` on the relevant `ClusterExtension` resource.

Expand Down
52 changes: 27 additions & 25 deletions docs/contribute/developer.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,10 +3,10 @@

The following `make run` starts a [KIND](https://sigs.k8s.io/kind) cluster for you to get a local cluster for testing, see the manual install steps below for how to run against a remote cluster.

> [!NOTE]
> You will need a container runtime environment, like Docker, or experimentally, Podman, installed, to run Kind.
>
> If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos).
!!! note
You will need a container runtime environment, like Docker, or experimentally, Podman, installed, to run Kind.

If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos).

### Quickstart Installation

Expand All@@ -20,9 +20,9 @@ This will build a local container image of the operator-controller, create a new

### To Install Any Given Release

> [!CAUTION]
> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
> may affect an existing installation of cert-manager and cause cluster instability.
!!! warning
Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
may affect an existing installation of cert-manager and cause cluster instability.

The latest version of Operator Controller can be installed with the following command:

Expand All@@ -33,21 +33,21 @@ curl -L -s https://github.com/operator-framework/operator-controller/releases/la
### Manual Step-by-Step Installation
1. Install Instances of Custom Resources:

```sh
kubectl apply -f config/samples/
```
```sh
kubectl apply -f config/samples/
```

2. Build and push your image to the location specified by `IMG`:

```sh
make docker-build docker-push IMG=<some-registry>/operator-controller:tag
```
```sh
make docker-build docker-push IMG=<some-registry>/operator-controller:tag
```

3. Deploy the controller to the cluster with the image specified by `IMG`:

```sh
make deploy IMG=<some-registry>/operator-controller:tag
```
```sh
make deploy IMG=<some-registry>/operator-controller:tag
```

### Uninstall CRDs
To delete the CRDs from the cluster:
Comment thread
m1kola marked this conversation as resolved.
Expand All@@ -72,7 +72,8 @@ make manifests

---

**NOTE:** Run `make help` for more information on all potential `make` targets.
!!! note
Run `make help` for more information on all potential `make` targets.

### Rapid Iterative Development with Tilt

Expand DownExpand Up@@ -124,17 +125,18 @@ This is typically as short as:
tilt up
```

**NOTE:** if you are using Podman, at least as of v4.5.1, you need to do this:
!!! note
If you are using Podman, at least as of v4.5.1, you need to do this:

```shell
DOCKER_BUILDKIT=0 tilt up
```
```shell
DOCKER_BUILDKIT=0 tilt up
```

Otherwise, you'll see an error when Tilt tries to build your image that looks similar to:
Otherwise, you'll see an error when Tilt tries to build your image that looks similar to:

```text
Build Failed: ImageBuild: stat /var/tmp/libpod_builder2384046170/build/Dockerfile: no such file or directory
```
```text
Build Failed: ImageBuild: stat /var/tmp/libpod_builder2384046170/build/Dockerfile: no such file or directory
```

When Tilt starts, you'll see something like this in your terminal:

Expand Down
6 changes: 3 additions & 3 deletions docs/getting-started/olmv1_getting_started.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,9 +2,9 @@

The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind).

> [!CAUTION]
> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
> may affect an existing installation of cert-manager and cause cluster instability.
!!! warning
Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
may affect an existing installation of cert-manager and cause cluster instability.

The latest version of Operator Controller can be installed with the following command:

Expand Down
5 changes: 3 additions & 2 deletions docs/howto/catalog-queries.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
# Catalog queries

**Note:** 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
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.


You can use the `curl` command with `jq` to query catalogs that are installed on your cluster.
Expand Down
Loading