Publish /docs to github pages

Closes #291 Signed-off-by: Anik <anikbhattacharya93@gmail.com>
operator-framework · Jul 26, 2023 · 2d4ed17 · 2d4ed17
1 parent 1dd8d67
commit 2d4ed17
Show file tree

Hide file tree

Showing 11 changed files with 641 additions and 21 deletions.
diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml
@@ -0,0 +1,24 @@
+name: Deploy Documentation site 
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
@@ -34,3 +34,5 @@ install.sh
 \#*\#
 .\#*
 
+# documentation website asset folder
+docs/_site
diff --git a/docs/Tasks/adding-a-catalog.md b/docs/Tasks/adding-a-catalog.md
@@ -0,0 +1,85 @@
+---
+layout: default
+title: Adding a catalog of operators to the cluster
+nav_order: 1
+parent: Tasks
+---
+
+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.  
+
+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. 
+
+To consume this catalog on cluster, create a `Catalog` Custom Resource(CR) with the image specified in the `spec.source.image` field: 
+
+```bash
+$ kubectl apply -f - <<EOF
+apiVersion: catalogd.operatorframework.io/v1alpha1
+kind: Catalog
+metadata:
+  name: operatorhubio
+spec:
+  source:
+    type: image
+    image:
+      ref: quay.io/operatorhubio/catalog:latest
+EOF
+```
+
+The packages made available for installation/receiving updates on cluster can then be explored by querying the `Package` and `BundleMetadata` CRs: 
+
+```bash
+$ kubectl get packages 
+NAME                                                     AGE
+operatorhubio-ack-acm-controller                         3m12s
+operatorhubio-ack-apigatewayv2-controller                3m12s
+operatorhubio-ack-applicationautoscaling-controller      3m12s
+operatorhubio-ack-cloudtrail-controller                  3m12s
+operatorhubio-ack-dynamodb-controller                    3m12s
+operatorhubio-ack-ec2-controller                         3m12s
+operatorhubio-ack-ecr-controller                         3m12s
+operatorhubio-ack-eks-controller                         3m12s
+operatorhubio-ack-elasticache-controller                 3m12s
+operatorhubio-ack-emrcontainers-controller               3m12s
+operatorhubio-ack-eventbridge-controller                 3m12s
+operatorhubio-ack-iam-controller                         3m12s
+operatorhubio-ack-kinesis-controller                     3m12s
+operatorhubio-ack-kms-controller                         3m12s
+operatorhubio-ack-lambda-controller                      3m12s
+operatorhubio-ack-memorydb-controller                    3m12s
+operatorhubio-ack-mq-controller                          3m12s
+operatorhubio-ack-opensearchservice-controller           3m12s
+.
+.
+.
+
+$ kubectl get bundlemetadata 
+NAME                                                            AGE
+operatorhubio-ack-acm-controller.v0.0.1                         3m58s
+operatorhubio-ack-acm-controller.v0.0.2                         3m58s
+operatorhubio-ack-acm-controller.v0.0.4                         3m58s
+operatorhubio-ack-acm-controller.v0.0.5                         3m58s
+operatorhubio-ack-acm-controller.v0.0.6                         3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.10               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.11               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.12               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.13               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.14               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.15               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.16               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.17               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.18               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.19               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.20               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.21               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.22               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.9                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.0                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.1                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.2                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.3                3m58s
+.
+.
+.
+```
+
+
diff --git a/docs/Tasks/deleting-an-operator.md b/docs/Tasks/deleting-an-operator.md
@@ -0,0 +1,21 @@
+---
+layout: default
+title: Deleting an operator from the cluster
+nav_order: 4
+parent: Tasks
+---
+
+Deleting an operator is as simple as deleting an existing Operator CR: 
+
+```bash
+$ kubectl get operators 
+NAME                          AGE
+operatorhubio-argocd-operator   53s
+
+$ kubectl delete operator argocd-operator 
+operator.operators.operatorframework.io "argocd-operator" deleted
+$ kubectl get namespaces | grep argocd
+$
+$ kubectl get crds | grep argocd-operator 
+$
+```
diff --git a/docs/Tasks/explore-available-packages.md b/docs/Tasks/explore-available-packages.md
@@ -0,0 +1,142 @@
+---
+layout: default
+title: Exploring packages available for installation on cluster
+nav_order: 2
+parent: Tasks
+---
+
+The packages available for installation/receiving updates on cluster can be explored by querying the `Package` and `BundleMetadata` CRs: 
+
+```bash
+$ kubectl get packages 
+NAME                                                     AGE
+operatorhubio-ack-acm-controller                         3m12s
+operatorhubio-ack-apigatewayv2-controller                3m12s
+operatorhubio-ack-applicationautoscaling-controller      3m12s
+operatorhubio-ack-cloudtrail-controller                  3m12s
+operatorhubio-ack-dynamodb-controller                    3m12s
+operatorhubio-ack-ec2-controller                         3m12s
+operatorhubio-ack-ecr-controller                         3m12s
+operatorhubio-ack-eks-controller                         3m12s
+operatorhubio-ack-elasticache-controller                 3m12s
+operatorhubio-ack-emrcontainers-controller               3m12s
+operatorhubio-ack-eventbridge-controller                 3m12s
+operatorhubio-ack-iam-controller                         3m12s
+operatorhubio-ack-kinesis-controller                     3m12s
+operatorhubio-ack-kms-controller                         3m12s
+operatorhubio-ack-lambda-controller                      3m12s
+operatorhubio-ack-memorydb-controller                    3m12s
+operatorhubio-ack-mq-controller                          3m12s
+operatorhubio-ack-opensearchservice-controller           3m12s
+.
+.
+.
+
+$ kubectl get bundlemetadata 
+NAME                                                            AGE
+operatorhubio-ack-acm-controller.v0.0.1                         3m58s
+operatorhubio-ack-acm-controller.v0.0.2                         3m58s
+operatorhubio-ack-acm-controller.v0.0.4                         3m58s
+operatorhubio-ack-acm-controller.v0.0.5                         3m58s
+operatorhubio-ack-acm-controller.v0.0.6                         3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.10               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.11               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.12               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.13               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.14               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.15               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.16               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.17               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.18               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.19               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.20               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.21               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.22               3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.0.9                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.0                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.1                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.2                3m58s
+operatorhubio-ack-apigatewayv2-controller.v0.1.3                3m58s
+.
+.
+.
+``` 
+
+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`: 
+
+```bash
+$ kubectl get packages | grep argocd 
+operatorhubio-argocd-operator                            5m19s
+operatorhubio-argocd-operator-helm                       5m19s
+
+$ kubectl get package operatorhubio-argocd-operator -o yaml 
+apiVersion: catalogd.operatorframework.io/v1alpha1
+kind: Package
+metadata:
+  creationTimestamp: "2023-06-16T14:34:04Z"
+  generation: 1
+  labels:
+    catalog: operatorhubio
+  name: operatorhubio-argocd-operator
+  ownerReferences:
+  - apiVersion: catalogd.operatorframework.io/v1alpha1
+    blockOwnerDeletion: true
+    controller: true
+    kind: Catalog
+    name: operatorhubio
+    uid: 9a949664-9069-4376-9a66-a9921f7488e2
+  resourceVersion: "3765"
+  uid: 43396920-4af4-4daf-a069-be68b8a0631e
+spec:
+  catalog:
+    name: operatorhubio
+  channels:
+  - entries:
+    - name: argocd-operator.v0.0.11
+      replaces: argocd-operator.v0.0.9
+    - name: argocd-operator.v0.0.12
+      replaces: argocd-operator.v0.0.11
+    - name: argocd-operator.v0.0.13
+      replaces: argocd-operator.v0.0.12
+    - name: argocd-operator.v0.0.14
+      replaces: argocd-operator.v0.0.13
+    - name: argocd-operator.v0.0.15
+      replaces: argocd-operator.v0.0.14
+    - name: argocd-operator.v0.0.2
+    - name: argocd-operator.v0.0.3
+      replaces: argocd-operator.v0.0.2
+    - name: argocd-operator.v0.0.4
+      replaces: argocd-operator.v0.0.3
+    - name: argocd-operator.v0.0.5
+      replaces: argocd-operator.v0.0.4
+    - name: argocd-operator.v0.0.6
+      replaces: argocd-operator.v0.0.5
+    - name: argocd-operator.v0.0.8
+      replaces: argocd-operator.v0.0.6
+    - name: argocd-operator.v0.0.9
+      replaces: argocd-operator.v0.0.8
+    - name: argocd-operator.v0.1.0
+      replaces: argocd-operator.v0.0.15
+    - name: argocd-operator.v0.2.0
+      replaces: argocd-operator.v0.1.0
+    - name: argocd-operator.v0.2.1
+      replaces: argocd-operator.v0.2.0
+    - name: argocd-operator.v0.3.0
+      replaces: argocd-operator.v0.2.1
+    - name: argocd-operator.v0.4.0
+      replaces: argocd-operator.v0.3.0
+    - name: argocd-operator.v0.5.0
+      replaces: argocd-operator.v0.4.0
+    - name: argocd-operator.v0.6.0
+      replaces: argocd-operator.v0.5.0
+    name: ""
+  defaultChannel: ""
+  description: ""
+  icon:
+    data: PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2Z==
+    mediatype: image/svg+xml
+  packageName: argocd-operator
+status: {}
+```
+
+**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).
diff --git a/docs/Tasks/installing-an-operator.md b/docs/Tasks/installing-an-operator.md
@@ -0,0 +1,69 @@
+---
+layout: default
+title: Installing an operator on cluster
+nav_order: 3
+parent: Tasks
+---
+
+Creating an Operator CR installs the operator on cluster:  
+
+```bash
+$ kubectl get packages | grep argocd 
+operatorhubio-argocd-operator                            5m19s
+operatorhubio-argocd-operator-helm                       5m19s
+
+$ kubectl apply -f - <<EOF
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: argocd-operator
+spec:
+  packageName: operatorhubio-argocd-operator
+EOF
+
+$ kubectl get operators 
+NAME                          AGE
+operatorhubio-argocd-operator   53s
+
+$  kubectl get operator argocd-operator -o yaml 
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  annotations:
+    kubectl.kubernetes.io/last-applied-configuration: |
+      {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"argocd-operator"},"spec":{"packageName":"argocd-operator"}}
+  creationTimestamp: "2023-06-21T14:57:50Z"
+  generation: 1
+  name: argocd-operator
+  resourceVersion: "10690"
+  uid: 6e0c67a5-eb9c-41c6-a455-140b28714d34
+spec:
+  packageName: operatorhubio-argocd-operator
+status:
+  conditions:
+  - lastTransitionTime: "2023-06-21T14:57:51Z"
+    message: resolved to "quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6"
+    observedGeneration: 1
+    reason: Success
+    status: "True"
+    type: Resolved
+  - lastTransitionTime: "2023-06-21T14:57:57Z"
+    message: installed from "quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6"
+    observedGeneration: 1
+    reason: Success
+    status: "True"
+    type: Installed
+  installedBundleResource: quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6
+  resolvedBundleResource: quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6
+```
+
+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: 
+
+```bash 
+$ kubectl get namespaces | grep argocd 
+argocd-operator-system       Active   4m17s
+
+$ kubectl get pods -n argocd-operator-system 
+NAME                                                 READY   STATUS    RESTARTS   AGE
+argocd-operator-controller-manager-bb496c545-ljbbr   2/2     Running   0          4m32s
+```
diff --git a/docs/components.md b/docs/components.md
@@ -0,0 +1,12 @@
+OLM v1 is composed of various component projects: 
+
+* [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
+
+* [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.
+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.
+
+
+* [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.
+
+
+* [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.