Skip to content

Commit

Permalink
📖 Content organization (#1324)
Browse files Browse the repository at this point in the history
* organize docs

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>

* First stab at doc hierarchy

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>

---------

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>
Co-authored-by: Per Goncalves da Silva <pegoncal@redhat.com>
  • Loading branch information
perdasilva and Per Goncalves da Silva authored Oct 3, 2024
1 parent 117bece commit 814bf63
Show file tree
Hide file tree
Showing 40 changed files with 487 additions and 327 deletions.
11 changes: 7 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,16 @@ Operator Controller is an Apache 2.0 licensed project and accepts contributions
By contributing to this project you agree to the Developer Certificate of
Origin (DCO). This document was created by the Linux Kernel community and is a
simple statement that you, as a contributor, have the legal right to make the
contribution. See the [DCO](DCO) file for details.
contribution. See the [DCO](https://github.com/operator-framework/operator-controller/blob/main/DCO) file for details.

## Overview

Thank you for your interest in contributing to the Operator-Controller.

As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](github.com/operator-framework/operator-lifecycle-manager).
As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](https://github.com/operator-framework/operator-lifecycle-manager).

The user experience captured in the OLM V1 PRD introduces many requirements that are best satisfied by a microservices architecture. The OLM V1 experience currently relies on two projects:

- [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 Expand Up @@ -45,14 +46,15 @@ Please keep this workflow in mind as you read through the document.
## How are Milestones Designed?

It's unreasonable to attempt to consider all of the design requirements laid out in the [OLM V1 PRD](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit) from the onset of the project. Instead, the community attempts to design Milestones with the following principles:

- Milestones are tightly scoped units of work, ideally lasting one to three weeks.
- Milestones are derived from the OLM V1 PRD.
- Milestones are "demo driven", meaning that a set of acceptance criteria is defined upfront and the milestone is done as soon as some member of the community can run the demo.
- Edge cases found during development are captured in issues and assigned to the GA Milestone, which contains a list of issues that block the release of operator-controller v1.0.0 .

This "demo driven" development model will allow us to collect user experience and regularly course correct based on user feedback. Subsequent milestone may revert features or change the user experience based on community feedback.

The project maintainer will create a [GitHub Discussion](github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion.
The project maintainer will create a [GitHub Discussion](https://github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion.

## Where are Operator Controller Milestones?

Expand All @@ -67,6 +69,7 @@ As discussed earlier, the operator-controller adheres to a microservice architec
## Submitting Issues

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 All @@ -87,7 +90,7 @@ approach of changes.
When contributing changes that require a new dependency, check whether it's feasible to directly vendor that
code [without introducing a new dependency](https://go-proverbs.github.io/).

Currently, PRs require at least one approval from a operator-controller maintainer in order to get merged.
Currently, PRs require at least one approval from an operator-controller maintainer in order to get merged.

### Code style

Expand Down
13 changes: 7 additions & 6 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -312,17 +312,18 @@ quickstart: $(KUSTOMIZE) manifests #EXHELP Generate the installation release man
OPERATOR_CONTROLLER_API_REFERENCE_FILENAME := operator-controller-api-reference.md
CATALOGD_API_REFERENCE_FILENAME := catalogd-api-reference.md
CATALOGD_TMP_DIR := $(ROOT_DIR)/.catalogd-tmp/
API_REFERENCE_DIR := $(ROOT_DIR)/docs/api-reference
crd-ref-docs: $(CRD_REF_DOCS) #EXHELP Generate the API Reference Documents.
rm -f $(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME)
rm -f $(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME)
$(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api \
--config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \
--renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME);
--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME);
rm -rf $(CATALOGD_TMP_DIR)
git clone --depth 1 --branch $(CATALOGD_VERSION) https://github.com/operator-framework/catalogd $(CATALOGD_TMP_DIR)
rm -f $(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME)
rm -f $(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME)
$(CRD_REF_DOCS) --source-path=$(CATALOGD_TMP_DIR)/api \
--config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \
--renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME)
--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME)
rm -rf $(CATALOGD_TMP_DIR)/

VENVDIR := $(abspath docs/.venv)
Expand Down
128 changes: 8 additions & 120 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,137 +2,25 @@
The operator-controller is the central component of Operator Lifecycle Manager (OLM) v1.
It extends Kubernetes with an API through which users can install extensions.

## Mission
## Overview

OLM v1 is the follow-up to [OLM v0](https://github.com/operator-framework/operator-lifecycle-manager). Its purpose is to provide APIs,
controllers, and tooling that support the packaging, distribution, and lifecycling of Kubernetes extensions. It aims to:

OLM’s purpose is to provide APIs, controllers, and tooling that support the packaging, distribution, and lifecycling of Kubernetes extensions. It aims to:
- align with Kubernetes designs and user assumptions
- provide secure, high-quality, and predictable user experiences centered around declarative GitOps concepts
- give cluster admins the minimal necessary controls to build their desired cluster architectures and to have ultimate control

## Overview

OLM v1 is the follow-up to OLM v0, located [here](https://github.com/operator-framework/operator-lifecycle-manager).

OLM v1 consists of two different components:

* operator-controller (this repository)
* [catalogd](https://github.com/operator-framework/catalogd)

For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/olmv1_overview.md).

### Installation

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.
The latest version of Operator Controller can be installed with the following command:

```bash
curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
```

## Getting Started with OLM v1

This quickstart procedure will guide you through the following processes:
* Deploying a catalog
* Installing, upgrading, or downgrading an extension
* Deleting catalogs and extensions

### Create a Catalog

OLM v1 is designed to source content from an on-cluster catalog in the file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) format.
These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs
can be found [here](./docs/Tasks/adding-a-catalog).

The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different
extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages
will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md).

To create the catalog, run the following command:

```bash
# Create ClusterCatalog
kubectl apply -f - <<EOF
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: ClusterCatalog
metadata:
name: operatorhubio
spec:
source:
type: image
image:
ref: quay.io/operatorhubio/catalog:latest
pollInterval: 10m
EOF
```

Once the catalog is unpacked successfully, its content will be available for installation.

```bash
# Wait for the ClusterCatalog to be unpacked
kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeout=60s
```

### Install a Cluster Extension

For simplicity, the following example manifest includes all necessary resources to install the ArgoCD operator.
The manifest includes installation namespace, installer service account and associated minimal set of RBAC permissions
needed for installation, and the ClusterExtension resource, which specifies the name and version of the extension to install.
More information on installing extensions can be found [here](docs/Tasks/installing-an-extension).

```bash
# Apply the sample ClusterExtension. Manifest already includes
# namespace and adequately privileged service account
kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1alpha1_clusterextension.yaml
```

### Upgrade the Cluster Extension

To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
there must be CRD compatibility between the versions being upgraded, and the target version must be
compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension).

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

```

For information on the downgrade process, see [here](docs/drafts/downgrading-an-extension.md).

### Uninstall the Cluster Extension

To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will
remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension).

```bash
# Delete cluster extension and residing namespace
kubectl delete clusterextension/argocd
```

#### Cleanup

Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
extension is uninstalled, these resources can be cleaned up.

```bash
# Delete namespace, and by extension, the installer service account, Role, and RoleBinding
kubectl delete namespace argocd
```
For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/project/olmv1_design_decisions.md).

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

```bash
# Delete installer service account cluster role bindings
kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
```
To get started with OLM v1, please see our [Getting Started](docs/getting-started/olmv1_getting_started.md) documentation.

## License

Expand Down
File renamed without changes.
File renamed without changes.
98 changes: 98 additions & 0 deletions docs/assets/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ spec:
catalog:
selector:
matchLabels:
olm.operatorframework.io/metadata.name: my-catalog
olm.operatorframework.io/metadata.name: my-content-management
```
In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`.
Expand Down Expand Up @@ -93,7 +93,7 @@ spec:
- key: olm.operatorframework.io/metadata.name
operator: NotIn
values:
- unwanted-catalog
- unwanted-content-management
```

This excludes the catalog named `unwanted-catalog` from consideration.
Expand Down Expand Up @@ -134,7 +134,7 @@ spec:
source:
type: image
image:
ref: quay.io/example/high-priority-catalog:latest
ref: quay.io/example/high-priority-content-management:latest
```

Catalogs have a default priority of `0`. The priority can be any 32-bit integer. Catalogs with higher priority values are preferred during bundle resolution.
Expand Down Expand Up @@ -171,7 +171,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
source:
type: image
image:
ref: quay.io/example/catalog-a:latest
ref: quay.io/example/content-management-a:latest
```

```yaml
Expand All @@ -186,7 +186,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
source:
type: image
image:
ref: quay.io/example/catalog-b:latest
ref: quay.io/example/content-management-b:latest
```
NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied

Expand All @@ -209,8 +209,8 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
3. **Apply the Resources**

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

Expand Down
File renamed without changes.
Loading

0 comments on commit 814bf63

Please sign in to comment.