-
Notifications
You must be signed in to change notification settings - Fork 47
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.
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
Publish /docs to github pages #265
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -34,3 +34,5 @@ install.sh | |
\#*\# | ||
.\#* | ||
|
||
# documentation website asset folder | ||
docs/_site |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
. | ||
. | ||
. | ||
``` | ||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
$ | ||
``` |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is a good highlight. Have we landed on a concrete way we want to use that yet? catalogD? catalogd? CatalogD? Catalogd? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would typically recommend using the repository name but to be fair I have gone against that myself and used most if not all of these variations. I definitely think we need to pick one and make sure it is consistent throughout these docs though. My personal preferences are either catalogd or Catalogd There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. For comparison, we use "containerd" in most instances in the downstream docs, unless we are specifically referring to
everettraven marked this conversation as resolved.
Show resolved
Hide resolved
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this be in the
catalogd
repo? I thought our plan was to co-locate docs and code for technical details / reference information.And then we'd have a separate place to collect the higher level concepts/tasks/tutorials/etc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That is the general plan yes, this one's just to get us started, for us to have a place to keep putting things until all the sites for all the repos are ready. Hopefully that'll be soon and we won't have to do a surgical procedure to separate things, but it's at least better than having no where to put docs until then. Catching up to a docs backlog is much harder than reorganizing docs from my perspective.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fyi @michaelryanpeter and I plan on working on a Brief that'll capture all of these decisions, I.e put docs effort in the Briefs/RFC path too