Skip to content

Commit 1df52c7

Browse files
perdasilvaPer Goncalves da Silva
andauthored
📖[Docs] Update quickstart documentation (#1225)
Signed-off-by: Per Goncalves da Silva <[email protected]> Co-authored-by: Per Goncalves da Silva <[email protected]>
1 parent de0a41e commit 1df52c7

9 files changed

+243
-130
lines changed

README.md

Lines changed: 52 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -17,16 +17,12 @@ OLM v1 consists of two different components:
1717
* operator-controller (this repository)
1818
* [catalogd](https://github.com/operator-framework/catalogd)
1919

20-
For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](./docs/olmv1_overview.md).
21-
22-
## Getting Started
23-
You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
24-
25-
> [!NOTE]
26-
> Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
20+
For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/olmv1_overview.md).
2721

2822
### Installation
2923

24+
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).
25+
3026
> [!CAUTION]
3127
> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
3228
> may affect an existing installation of cert-manager and cause cluster instability.
@@ -37,10 +33,24 @@ The latest version of Operator Controller can be installed with the following co
3733
curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
3834
```
3935

40-
### Create a ClusterCatalog
36+
## Getting Started with OLM v1
37+
38+
This quickstart procedure will guide you through the following processes:
39+
* Deploying a catalog
40+
* Installing, upgrading, or downgrading an extension
41+
* Deleting catalogs and extensions
42+
43+
### Create a Catalog
4144

42-
The ClusterCatalog resource supports file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) images.
43-
The following example uses the official [OperatorHub](https://operatorhub.io) catalog.
45+
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.
46+
These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs
47+
can be found [here](./docs/Tasks/adding-a-catalog).
48+
49+
The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different
50+
extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages
51+
will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md).
52+
53+
To create the catalog, run the following command:
4454

4555
```bash
4656
# Create ClusterCatalog
@@ -58,148 +68,70 @@ spec:
5868
EOF
5969
```
6070

71+
Once the catalog is unpacked successfully, its content will be available for installation.
72+
6173
```bash
6274
# Wait for the ClusterCatalog to be unpacked
6375
kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeout=60s
6476
```
6577

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

6885
```bash
6986
# Apply the sample ClusterExtension. Manifest already includes
7087
# namespace and adequately privileged service account
71-
kubectl apply -f config/samples/olm_v1alpha1_clusterextension.yaml
72-
```
73-
74-
#### Upgrade/Downgrade
75-
76-
```bash
77-
# Update the required version
78-
kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"version": "0.11.0"}}'
79-
```
80-
81-
#### Uninstall
82-
83-
```bash
84-
# Delete cluster extension and residing namespace
85-
kubectl delete clusterextension/argocd && kubectl delete namespace argocd
86-
```
87-
88-
```bash
89-
# Delete cluster-scoped resources
90-
kubectl delete --ignore-not-found=true -f config/samples/olm_v1alpha1_clusterextension.yaml
88+
kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1alpha1_clusterextension.yaml
9189
```
9290

93-
### Advanced Usage
94-
95-
> [!WARNING]
96-
> The scripts referenced in this section are best-effort and may not always work as
97-
> intended. They are provided as a stopgap until we can offer production grade tooling
98-
> for tasks such as: searching the catalog, discovering supported bundles, and determining
99-
> the least-privilege set of permissions required by the installer service account to install
100-
> the content.
91+
### Upgrade the Cluster Extension
10192

102-
#### Installation
103-
104-
An extension needs a namespace in which to be installed and a service account with sufficient
105-
privileges to install the content. For instance:
93+
To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
94+
there must be CRD compatibility between the versions being upgraded, and the target version must be
95+
compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
96+
compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
97+
and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension).
10698

10799
```bash
108-
# Create argocd namespace for the argocd-operator
109-
kubectl create ns argocd
110-
```
100+
# Update to v0.11.0
101+
kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
111102

112-
```bash
113-
# Create installer service account
114-
kubectl create serviceaccount -n argocd-system argocd-installer
115103
```
116104

117-
> [!WARNING]
118-
> We work around the absence of reliable tooling to determine the set of least privileges
119-
> for the installer service account to be able to install a given bundle by giving
120-
> the installer service account cluster admin privileges.
121-
> This is not an option for production clusters due to the security implications.
122-
> The OLM community is working hard to bridge this tooling gap.
105+
For information on the downgrade process, see [here](./docs/drafts/Tasks/downgrading-an-extension.md).
123106

124-
```bash
125-
# Give service account cluster admin privileges
126-
# This works with KIND - consult documentation for instructions on how
127-
# to grant admin privileges for your kubernetes distribution
128-
kubectl create clusterrolebinding "argocd-operator-installer-cluster-admin" \
129-
--clusterrole=cluster-admin \
130-
--serviceaccount="argocd-system:argocd-operator-installer"
131-
```
107+
### Uninstall the Cluster Extension
132108

133-
```bash
134-
# Apply ClusterExtension
135-
cat <<EOF
136-
apiVersion: olm.operatorframework.io/v1alpha1
137-
kind: ClusterExtension
138-
metadata:
139-
name: argocd
140-
spec:
141-
installNamespace: argocd-system
142-
packageName: argocd-operator
143-
version: 0.6.0
144-
serviceAccount:
145-
name: argocd-operator-installer
146-
EOF | kubectl apply -f -
147-
```
109+
To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will
110+
remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension).
148111

149112
```bash
150-
# Wait for installation to finish successfully
151-
kubectl wait --for=condition=Success=True clusterextension/argocd --timeout=60s
113+
# Delete cluster extension and residing namespace
114+
kubectl delete clusterextension/argocd
152115
```
153116

154-
#### Finding Content
117+
#### Cleanup
155118

156-
The catalog content can be downloaded locally as a json file and queried using tools like [jq](The catalog content can be downloaded locally as a json file and queried using tools like [jq](The catalog content can be downloaded locally as a json file and queried using tools like [jq](https://jqlang.github.io/jq/).
157-
The _catalogd-catalogserver_ service in the _olmv1-system_ namespace provides an endpoint from which to
158-
download the catalog. This endpoint can be found in the status (.status.contentURL).
159-
160-
The [download-catalog.sh](hack/tools/catalogs/download-catalog) script automates this process:
119+
Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
120+
extension is uninstalled, these resources can be cleaned up.
161121

162122
```bash
163-
# Download the catalog provided by the unpacked ClusterCatalog called operatorhuio
164-
# The catalog will be downloaded to operatorhubio-catalog.json
165-
./hack/tools/catalogs/download-catalog operatorhubio
123+
# Delete namespace, and by extension, the installer service account, Role, and RoleBinding
124+
kubectl delete namespace argocd
166125
```
167126

168-
OLM v1 currently supports the installation of bundles that:
169-
- support the 'AllNamespaces' install mode
170-
- do not have any package or gvk dependencies
171-
- do not have webhooks
172-
173-
The [list-compatible-bundles.sh](hack/tools/catalogs/list-compatible-bundles) script attempts
174-
to filter out unsupported bundles:
175-
176127
```bash
177-
# Returns a JSON array of {packageName: "", versions: ["", ...]} objects
178-
# This array can be further queried with jq
179-
./hack/tools/catalogs/list-compatible-bundles < operatorhubio-catalog.json
180-
# The -r option also allows you to define a regular expression for the package name
181-
# for futher filtering
182-
./hack/tools/catalogs/list-compatible-bundles -r 'argocd' < operatorhubio-catalog.json
128+
# Delete installer service account cluster roles
129+
kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole
183130
```
184131

185-
#### Determining Service Account Privileges
186-
187-
The installer service account needs sufficient privileges to create the bundle's resources,
188-
as well as to assign RBAC to those resources. This information can be derived from the
189-
bundle's ClusterServiceVersion manifest.
190-
191-
The [install-bundle.sh](hack/tools/catalogs/bundle-manifests) script generates all required
192-
manifests for a bundle installation (including Namespace, and ClusterExtension resources), but can also
193-
be used to determine the RBAC for the installer service account:
194-
195132
```bash
196-
# Get RBAC for a ClusterExtension called 'argocd'
197-
# using package 'argocd-operator' at version '0.6.0'
198-
# in namespace 'argocd-system'
199-
RBAC_ONLY=1 ./hack/tools/catalogs/bundle-manifests argocd argocd-operator 0.6.0 argocd-system < operatorhubio-catalog.json
200-
# Or, let the script do all the heavy lifting (creation of Namespace, and ClusterExtension, as well as
201-
# the ServiceAccount and all required RBAC
202-
./hack/tools/catalogs/bundle-manifests argocd argocd-operator 0.6.0 argocd-system < operatorhubio-catalog.json | kubectl apply -f -
133+
# Delete installer service account cluster role bindings
134+
kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
203135
```
204136

205137
## License

docs/Tasks/explore-available-packages.md renamed to docs/Tasks/exploring-available-packages.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Exploring Available Packages
2+
13
After you add a catalog of extensions to your cluster, you must port forward your catalog as a service.
24
Then you can query the catalog by using `curl` commands and the `jq` CLI tool to find extensions to install.
35

docs/Tasks/installing-an-extension.md

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,13 @@
33
In Operator Lifecycle Manager (OLM) 1.0, Kubernetes extensions are scoped to the cluster.
44
After you add a catalog to your cluster, you can install an extension by creating a custom resource (CR) and applying it.
55

6-
!!! important
7-
8-
Currently, extensions that use webhooks or target a single or specified set of namespaces cannot be installed.
9-
Extensions must not include webhooks and must use the `AllNamespaces` install mode.
10-
11-
126
## Prerequisites
137

14-
* The `jq` CLI tool is installed.
15-
* You have added a catalog to your cluster.
8+
* A deployed and unpacked catalog
9+
* The name, and optionally version, or channel, of the extension to be installed
10+
* The extension must be compatible with OLM 1.0 (see [current OLM v1 limitations](../drafts/refs/olmv1-limitations.md))
11+
* An existing namespace in which to install the extension
12+
* A suitable service account for installation (more information can be found [here](../drafts/Tasks/create-installer-service-account.md))
1613

1714
## Procedure
1815

docs/Tasks/uninstall-an-extension.md renamed to docs/Tasks/uninstalling-an-extension.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,7 @@ You can uninstall a Kubernetes extension and its associated custom resource defi
3232
``` text title="Example output"
3333
No resources found
3434
```
35+
36+
### Cleanup
37+
38+
* Remove the extension namespace, and installer service account cluster-scoped RBAC resources (if applicable).
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Create Installer Service Account
2+
3+
Placeholder. We need to document this.
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Downgrade an Extension
2+
3+
Placeholder. This topic is under development.

0 commit comments

Comments
 (0)