Skip to content

Commit 3c55b14

Browse files
anik120anik120
authored
Publish /docs to github pages (#265)
Closes #291 Signed-off-by: Anik <[email protected]>
1 parent 18a6be4 commit 3c55b14

File tree

10 files changed

+404
-21
lines changed

10 files changed

+404
-21
lines changed

‎.github/workflows/pages.yaml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Deploy Documentation site
2+
on:
3+
push:
4+
branches:
5+
- main
6+
permissions:
7+
contents: write
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v3
13+
- uses: actions/setup-python@v4
14+
with:
15+
python-version: 3.x
16+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
17+
- uses: actions/cache@v3
18+
with:
19+
key: mkdocs-material-${{ env.cache_id }}
20+
path: .cache
21+
restore-keys: |
22+
mkdocs-material-
23+
- run: pip install mkdocs-material
24+
- run: mkdocs gh-deploy --force

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,5 @@ install.sh
3434
\#*\#
3535
.\#*
3636

37+
# documentation website asset folder
38+
docs/_site

‎docs/Tasks/adding-a-catalog.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
layout: default
3+
title: Adding a catalog of operators to the cluster
4+
nav_order: 1
5+
parent: Tasks
6+
---
7+
8+
Operator authors have the mechanisms to offer their product as part of a curated catalog of operators, that they can push updates to over-the-air (eg publish new versions, publish patched versions with CVEs, etc). Cluster admins can sign up to receive these updates on clusters, by adding the catalog to the cluster. When a catalog is added to a cluster, the kubernetes extension packages (operators, or any other extension package) in that catalog become available on cluster for installation and receiving updates.
9+
10+
For example, the [k8s-operatorhub/community-operators](https://github.com/k8s-operatorhub/community-operators) is a catalog of curated operators that contains a list of operators being developed by the community. The list of operators can be viewed in [Operatorhub.io](https://operatorhub.io). This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://quay.io/repository/operatorhubio/catalog?tag=latest&tab=tags) for consumption on clusters.
11+
12+
To consume this catalog on cluster, create a `Catalog` Custom Resource(CR) with the image specified in the `spec.source.image` field:
13+
14+
```bash
15+
$ kubectl apply -f - <<EOF
16+
apiVersion: catalogd.operatorframework.io/v1alpha1
17+
kind: Catalog
18+
metadata:
19+
name: operatorhubio
20+
spec:
21+
source:
22+
type: image
23+
image:
24+
ref: quay.io/operatorhubio/catalog:latest
25+
EOF
26+
```
27+
28+
The packages made available for installation/receiving updates on cluster can then be explored by querying the `Package` and `BundleMetadata` CRs:
29+
30+
```bash
31+
$ kubectl get packages
32+
NAME AGE
33+
operatorhubio-ack-acm-controller 3m12s
34+
operatorhubio-ack-apigatewayv2-controller 3m12s
35+
operatorhubio-ack-applicationautoscaling-controller 3m12s
36+
operatorhubio-ack-cloudtrail-controller 3m12s
37+
operatorhubio-ack-dynamodb-controller 3m12s
38+
operatorhubio-ack-ec2-controller 3m12s
39+
operatorhubio-ack-ecr-controller 3m12s
40+
operatorhubio-ack-eks-controller 3m12s
41+
operatorhubio-ack-elasticache-controller 3m12s
42+
operatorhubio-ack-emrcontainers-controller 3m12s
43+
operatorhubio-ack-eventbridge-controller 3m12s
44+
operatorhubio-ack-iam-controller 3m12s
45+
operatorhubio-ack-kinesis-controller 3m12s
46+
operatorhubio-ack-kms-controller 3m12s
47+
operatorhubio-ack-lambda-controller 3m12s
48+
operatorhubio-ack-memorydb-controller 3m12s
49+
operatorhubio-ack-mq-controller 3m12s
50+
operatorhubio-ack-opensearchservice-controller 3m12s
51+
.
52+
.
53+
.
54+
55+
$ kubectl get bundlemetadata
56+
NAME AGE
57+
operatorhubio-ack-acm-controller.v0.0.1 3m58s
58+
operatorhubio-ack-acm-controller.v0.0.2 3m58s
59+
operatorhubio-ack-acm-controller.v0.0.4 3m58s
60+
operatorhubio-ack-acm-controller.v0.0.5 3m58s
61+
operatorhubio-ack-acm-controller.v0.0.6 3m58s
62+
operatorhubio-ack-apigatewayv2-controller.v0.0.10 3m58s
63+
operatorhubio-ack-apigatewayv2-controller.v0.0.11 3m58s
64+
operatorhubio-ack-apigatewayv2-controller.v0.0.12 3m58s
65+
operatorhubio-ack-apigatewayv2-controller.v0.0.13 3m58s
66+
operatorhubio-ack-apigatewayv2-controller.v0.0.14 3m58s
67+
operatorhubio-ack-apigatewayv2-controller.v0.0.15 3m58s
68+
operatorhubio-ack-apigatewayv2-controller.v0.0.16 3m58s
69+
operatorhubio-ack-apigatewayv2-controller.v0.0.17 3m58s
70+
operatorhubio-ack-apigatewayv2-controller.v0.0.18 3m58s
71+
operatorhubio-ack-apigatewayv2-controller.v0.0.19 3m58s
72+
operatorhubio-ack-apigatewayv2-controller.v0.0.20 3m58s
73+
operatorhubio-ack-apigatewayv2-controller.v0.0.21 3m58s
74+
operatorhubio-ack-apigatewayv2-controller.v0.0.22 3m58s
75+
operatorhubio-ack-apigatewayv2-controller.v0.0.9 3m58s
76+
operatorhubio-ack-apigatewayv2-controller.v0.1.0 3m58s
77+
operatorhubio-ack-apigatewayv2-controller.v0.1.1 3m58s
78+
operatorhubio-ack-apigatewayv2-controller.v0.1.2 3m58s
79+
operatorhubio-ack-apigatewayv2-controller.v0.1.3 3m58s
80+
.
81+
.
82+
.
83+
```
84+
85+

‎docs/Tasks/deleting-an-operator.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
layout: default
3+
title: Deleting an operator from the cluster
4+
nav_order: 4
5+
parent: Tasks
6+
---
7+
8+
Deleting an operator is as simple as deleting an existing Operator CR:
9+
10+
```bash
11+
$ kubectl get operators
12+
NAME AGE
13+
operatorhubio-argocd-operator 53s
14+
15+
$ kubectl delete operator argocd-operator
16+
operator.operators.operatorframework.io "argocd-operator" deleted
17+
$ kubectl get namespaces | grep argocd
18+
$
19+
$ kubectl get crds | grep argocd-operator
20+
$
21+
```

‎docs/Tasks/explore-available-packages.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
layout: default
3+
title: Exploring packages available for installation on cluster
4+
nav_order: 2
5+
parent: Tasks
6+
---
7+
8+
The packages available for installation/receiving updates on cluster can be explored by querying the `Package` and `BundleMetadata` CRs:
9+
10+
```bash
11+
$ kubectl get packages
12+
NAME AGE
13+
operatorhubio-ack-acm-controller 3m12s
14+
operatorhubio-ack-apigatewayv2-controller 3m12s
15+
operatorhubio-ack-applicationautoscaling-controller 3m12s
16+
operatorhubio-ack-cloudtrail-controller 3m12s
17+
operatorhubio-ack-dynamodb-controller 3m12s
18+
operatorhubio-ack-ec2-controller 3m12s
19+
operatorhubio-ack-ecr-controller 3m12s
20+
operatorhubio-ack-eks-controller 3m12s
21+
operatorhubio-ack-elasticache-controller 3m12s
22+
operatorhubio-ack-emrcontainers-controller 3m12s
23+
operatorhubio-ack-eventbridge-controller 3m12s
24+
operatorhubio-ack-iam-controller 3m12s
25+
operatorhubio-ack-kinesis-controller 3m12s
26+
operatorhubio-ack-kms-controller 3m12s
27+
operatorhubio-ack-lambda-controller 3m12s
28+
operatorhubio-ack-memorydb-controller 3m12s
29+
operatorhubio-ack-mq-controller 3m12s
30+
operatorhubio-ack-opensearchservice-controller 3m12s
31+
.
32+
.
33+
.
34+
35+
$ kubectl get bundlemetadata
36+
NAME AGE
37+
operatorhubio-ack-acm-controller.v0.0.1 3m58s
38+
operatorhubio-ack-acm-controller.v0.0.2 3m58s
39+
operatorhubio-ack-acm-controller.v0.0.4 3m58s
40+
operatorhubio-ack-acm-controller.v0.0.5 3m58s
41+
operatorhubio-ack-acm-controller.v0.0.6 3m58s
42+
operatorhubio-ack-apigatewayv2-controller.v0.0.10 3m58s
43+
operatorhubio-ack-apigatewayv2-controller.v0.0.11 3m58s
44+
operatorhubio-ack-apigatewayv2-controller.v0.0.12 3m58s
45+
operatorhubio-ack-apigatewayv2-controller.v0.0.13 3m58s
46+
operatorhubio-ack-apigatewayv2-controller.v0.0.14 3m58s
47+
operatorhubio-ack-apigatewayv2-controller.v0.0.15 3m58s
48+
operatorhubio-ack-apigatewayv2-controller.v0.0.16 3m58s
49+
operatorhubio-ack-apigatewayv2-controller.v0.0.17 3m58s
50+
operatorhubio-ack-apigatewayv2-controller.v0.0.18 3m58s
51+
operatorhubio-ack-apigatewayv2-controller.v0.0.19 3m58s
52+
operatorhubio-ack-apigatewayv2-controller.v0.0.20 3m58s
53+
operatorhubio-ack-apigatewayv2-controller.v0.0.21 3m58s
54+
operatorhubio-ack-apigatewayv2-controller.v0.0.22 3m58s
55+
operatorhubio-ack-apigatewayv2-controller.v0.0.9 3m58s
56+
operatorhubio-ack-apigatewayv2-controller.v0.1.0 3m58s
57+
operatorhubio-ack-apigatewayv2-controller.v0.1.1 3m58s
58+
operatorhubio-ack-apigatewayv2-controller.v0.1.2 3m58s
59+
operatorhubio-ack-apigatewayv2-controller.v0.1.3 3m58s
60+
.
61+
.
62+
.
63+
```
64+
65+
Individual `Package`/`BundleMetadata` CRs can then be explored more by retrieving their yamls. Eg the `operatorhubio-argocd-operator` CR has more detailed information about the `argocd-operator`:
66+
67+
```bash
68+
$ kubectl get packages | grep argocd
69+
operatorhubio-argocd-operator 5m19s
70+
operatorhubio-argocd-operator-helm 5m19s
71+
72+
$ kubectl get package operatorhubio-argocd-operator -o yaml
73+
apiVersion: catalogd.operatorframework.io/v1alpha1
74+
kind: Package
75+
metadata:
76+
creationTimestamp: "2023-06-16T14:34:04Z"
77+
generation: 1
78+
labels:
79+
catalog: operatorhubio
80+
name: operatorhubio-argocd-operator
81+
ownerReferences:
82+
- apiVersion: catalogd.operatorframework.io/v1alpha1
83+
blockOwnerDeletion: true
84+
controller: true
85+
kind: Catalog
86+
name: operatorhubio
87+
uid: 9a949664-9069-4376-9a66-a9921f7488e2
88+
resourceVersion: "3765"
89+
uid: 43396920-4af4-4daf-a069-be68b8a0631e
90+
spec:
91+
catalog:
92+
name: operatorhubio
93+
channels:
94+
- entries:
95+
- name: argocd-operator.v0.0.11
96+
replaces: argocd-operator.v0.0.9
97+
- name: argocd-operator.v0.0.12
98+
replaces: argocd-operator.v0.0.11
99+
- name: argocd-operator.v0.0.13
100+
replaces: argocd-operator.v0.0.12
101+
- name: argocd-operator.v0.0.14
102+
replaces: argocd-operator.v0.0.13
103+
- name: argocd-operator.v0.0.15
104+
replaces: argocd-operator.v0.0.14
105+
- name: argocd-operator.v0.0.2
106+
- name: argocd-operator.v0.0.3
107+
replaces: argocd-operator.v0.0.2
108+
- name: argocd-operator.v0.0.4
109+
replaces: argocd-operator.v0.0.3
110+
- name: argocd-operator.v0.0.5
111+
replaces: argocd-operator.v0.0.4
112+
- name: argocd-operator.v0.0.6
113+
replaces: argocd-operator.v0.0.5
114+
- name: argocd-operator.v0.0.8
115+
replaces: argocd-operator.v0.0.6
116+
- name: argocd-operator.v0.0.9
117+
replaces: argocd-operator.v0.0.8
118+
- name: argocd-operator.v0.1.0
119+
replaces: argocd-operator.v0.0.15
120+
- name: argocd-operator.v0.2.0
121+
replaces: argocd-operator.v0.1.0
122+
- name: argocd-operator.v0.2.1
123+
replaces: argocd-operator.v0.2.0
124+
- name: argocd-operator.v0.3.0
125+
replaces: argocd-operator.v0.2.1
126+
- name: argocd-operator.v0.4.0
127+
replaces: argocd-operator.v0.3.0
128+
- name: argocd-operator.v0.5.0
129+
replaces: argocd-operator.v0.4.0
130+
- name: argocd-operator.v0.6.0
131+
replaces: argocd-operator.v0.5.0
132+
name: ""
133+
defaultChannel: ""
134+
description: ""
135+
icon:
136+
data: PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2Z==
137+
mediatype: image/svg+xml
138+
packageName: argocd-operator
139+
status: {}
140+
```
141+
142+
**This CR is most helpful when exploring the versions of a package that are available for installation on cluster, and the upgrade graph of versions** (eg if v0.5.0 of `argocd-operator` is installed on cluster, what is the next upgrade available? The answer is v0.6.0).

‎docs/Tasks/installing-an-operator.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
layout: default
3+
title: Installing an operator on cluster
4+
nav_order: 3
5+
parent: Tasks
6+
---
7+
8+
Creating an Operator CR installs the operator on cluster:
9+
10+
```bash
11+
$ kubectl get packages | grep argocd
12+
operatorhubio-argocd-operator 5m19s
13+
operatorhubio-argocd-operator-helm 5m19s
14+
15+
$ kubectl apply -f - <<EOF
16+
apiVersion: operators.operatorframework.io/v1alpha1
17+
kind: Operator
18+
metadata:
19+
name: argocd-operator
20+
spec:
21+
packageName: operatorhubio-argocd-operator
22+
EOF
23+
24+
$ kubectl get operators
25+
NAME AGE
26+
operatorhubio-argocd-operator 53s
27+
28+
$ kubectl get operator argocd-operator -o yaml
29+
apiVersion: operators.operatorframework.io/v1alpha1
30+
kind: Operator
31+
metadata:
32+
annotations:
33+
kubectl.kubernetes.io/last-applied-configuration: |
34+
{"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"argocd-operator"},"spec":{"packageName":"argocd-operator"}}
35+
creationTimestamp: "2023-06-21T14:57:50Z"
36+
generation: 1
37+
name: argocd-operator
38+
resourceVersion: "10690"
39+
uid: 6e0c67a5-eb9c-41c6-a455-140b28714d34
40+
spec:
41+
packageName: operatorhubio-argocd-operator
42+
status:
43+
conditions:
44+
- lastTransitionTime: "2023-06-21T14:57:51Z"
45+
message: resolved to "quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6"
46+
observedGeneration: 1
47+
reason: Success
48+
status: "True"
49+
type: Resolved
50+
- lastTransitionTime: "2023-06-21T14:57:57Z"
51+
message: installed from "quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6"
52+
observedGeneration: 1
53+
reason: Success
54+
status: "True"
55+
type: Installed
56+
installedBundleResource: quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6
57+
resolvedBundleResource: quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6
58+
```
59+
60+
The status condition type `Installed`:`true` indicates that the operator was installed successfully. We can confirm this by looking at the workloads that were created as a result of this operator installation:
61+
62+
```bash
63+
$ kubectl get namespaces | grep argocd
64+
argocd-operator-system Active 4m17s
65+
66+
$ kubectl get pods -n argocd-operator-system
67+
NAME READY STATUS RESTARTS AGE
68+
argocd-operator-controller-manager-bb496c545-ljbbr 2/2 Running 0 4m32s
69+
```

‎docs/components.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
OLM v1 is composed of various component projects:
2+
3+
* [operator-controller](https://github.com/operator-framework/operator-controller): Operator-controller is the central component of OLM v1, that consumes all of the components below to extend Kubernetes to allows users to install, and manage the lifecycle of other extensions
4+
5+
* [rukpak](https://github.com/operator-framework/rukpak): RukPak is a pluggable solution for the packaging and distribution of cloud-native content and supports advanced strategies for installation, updates, and policy. The project provides a content ecosystem for installing a variety of artifacts, such as Git repositories, Helm charts, OLM bundles, and more onto a Kubernetes cluster. These artifacts can then be managed, scaled, and upgraded in a safe way to enable powerful cluster extensions.
6+
At its core, RukPak is a small set of APIs, packaged as Kubernetes CustomResourceDefinitions, and controllers that watch for those APIs. These APIs express what content is being installed on-cluster and how to create a running deployment of the content.
7+
8+
9+
* [deppy](https://github.com/operator-framework/deppy): Deppy is a Kubernetes API that runs on- or off-cluster for resolving constraints over catalogs of RukPak bundles. Deppy is part of the next iteration of OLM and was first introduced here. The initial goal of the project is to remove the dependency manager from the Operator Lifecycle Manager (OLM) and make it its own generic component.
10+
11+
12+
* [catalogD](https://github.com/operator-framework/catalogd): Catalogd is a Kubernetes extension that unpacks [file-based catalog (FBC)](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs) content that is packaged and shipped in container images, for consumption by clients on-clusters (unpacking from other sources, like git repos, OCI artifacts etc, are in the roadmap for catalogD). As component of the Operator Lifecycle Manager (OLM) v1 microservices architecture, catalogD hosts metadata for Kubernetes extensions packaged by the authors of the extensions, as a result helping customers discover installable content.

0 commit comments

Comments
 (0)