|
1 | | -Extension authors have the mechanisms to offer their product as part of a curated catalog of extensions, 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 in that catalog become available on cluster for installation and receiving updates. |
2 | | - |
3 | | -For example, the [k8s-operatorhub/community-operators](https://github.com/k8s-operatorhub/community-operators) is a catalog of curated extensions that contains a list of extensions being developed by the community. The list of extensions 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. |
4 | | - |
5 | | -To consume this catalog on cluster, create a `Catalog` Custom Resource(CR) with the image specified in the `spec.source.image` field: |
6 | | - |
7 | | -```bash |
8 | | -$ kubectl apply -f - <<EOF |
9 | | -apiVersion: catalogd.operatorframework.io/v1alpha1 |
10 | | -kind: Catalog |
11 | | -metadata: |
12 | | - name: operatorhubio |
13 | | -spec: |
14 | | - source: |
15 | | - type: image |
16 | | - image: |
17 | | - ref: quay.io/operatorhubio/catalog:latest |
18 | | -EOF |
19 | | -``` |
20 | | - |
21 | | -The packages made available for installation/receiving updates on cluster can then be explored by querying the `Package` and `BundleMetadata` CRs: |
22 | | - |
23 | | -```bash |
24 | | -$ kubectl get packages |
25 | | -NAME AGE |
26 | | -operatorhubio-ack-acm-controller 3m12s |
27 | | -operatorhubio-ack-apigatewayv2-controller 3m12s |
28 | | -operatorhubio-ack-applicationautoscaling-controller 3m12s |
29 | | -operatorhubio-ack-cloudtrail-controller 3m12s |
30 | | -operatorhubio-ack-dynamodb-controller 3m12s |
31 | | -operatorhubio-ack-ec2-controller 3m12s |
32 | | -operatorhubio-ack-ecr-controller 3m12s |
33 | | -operatorhubio-ack-eks-controller 3m12s |
34 | | -operatorhubio-ack-elasticache-controller 3m12s |
35 | | -operatorhubio-ack-emrcontainers-controller 3m12s |
36 | | -operatorhubio-ack-eventbridge-controller 3m12s |
37 | | -operatorhubio-ack-iam-controller 3m12s |
38 | | -operatorhubio-ack-kinesis-controller 3m12s |
39 | | -operatorhubio-ack-kms-controller 3m12s |
40 | | -operatorhubio-ack-lambda-controller 3m12s |
41 | | -operatorhubio-ack-memorydb-controller 3m12s |
42 | | -operatorhubio-ack-mq-controller 3m12s |
43 | | -operatorhubio-ack-opensearchservice-controller 3m12s |
44 | | -. |
45 | | -. |
46 | | -. |
47 | | - |
48 | | -$ kubectl get bundlemetadata |
49 | | -NAME AGE |
50 | | -operatorhubio-ack-acm-controller.v0.0.1 3m58s |
51 | | -operatorhubio-ack-acm-controller.v0.0.2 3m58s |
52 | | -operatorhubio-ack-acm-controller.v0.0.4 3m58s |
53 | | -operatorhubio-ack-acm-controller.v0.0.5 3m58s |
54 | | -operatorhubio-ack-acm-controller.v0.0.6 3m58s |
55 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.10 3m58s |
56 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.11 3m58s |
57 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.12 3m58s |
58 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.13 3m58s |
59 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.14 3m58s |
60 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.15 3m58s |
61 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.16 3m58s |
62 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.17 3m58s |
63 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.18 3m58s |
64 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.19 3m58s |
65 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.20 3m58s |
66 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.21 3m58s |
67 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.22 3m58s |
68 | | -operatorhubio-ack-apigatewayv2-controller.v0.0.9 3m58s |
69 | | -operatorhubio-ack-apigatewayv2-controller.v0.1.0 3m58s |
70 | | -operatorhubio-ack-apigatewayv2-controller.v0.1.1 3m58s |
71 | | -operatorhubio-ack-apigatewayv2-controller.v0.1.2 3m58s |
72 | | -operatorhubio-ack-apigatewayv2-controller.v0.1.3 3m58s |
73 | | -. |
74 | | -. |
75 | | -. |
76 | | -``` |
| 1 | +======= |
| 2 | +Extension authors can publish their products in catalogs. |
| 3 | +Catalogs are curated collections of Operators and extensions. |
| 4 | +Cluster administrators can add these catalogs to their cluster. |
| 5 | +When extension authors publish updates to their catalogs, cluster administrators can install and update those changes. |
| 6 | + |
| 7 | +For example, the [Kubernetes community Operators catalog](https://github.com/k8s-operatorhub/community-operators) is a catalog of curated extensions that is developed by the Kubernetes community. |
| 8 | +You can see the available extensions at [Operatorhub.io](https://operatorhub.io). |
| 9 | +This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://quay.io/repository/operatorhubio/catalog?tag=latest&tab=tags) that can be installed on clusters. |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +* Access to a Kubernetes cluster, for example `kind`, using an account with `cluster-admin` permissions |
| 14 | +* [Operator Controller installed](https://github.com/operator-framework/operator-controller/releases) on the cluster |
| 15 | +* [Catalogd installed](https://github.com/operator-framework/catalogd/releases/) on the cluster |
| 16 | +* Kubernetes CLI (`kubectl`) installed on your workstation |
| 17 | + |
| 18 | +## Procedure |
| 19 | + |
| 20 | +1. Create a catalog custom resource (CR): |
| 21 | + ```yaml |
| 22 | + apiVersion: catalogd.operatorframework.io/v1alpha1 |
| 23 | + kind: Catalog |
| 24 | + metadata: |
| 25 | + name: operatorhubio |
| 26 | + spec: |
| 27 | + source: |
| 28 | + type: image |
| 29 | + image: |
| 30 | + ref: <catalog_image> |
| 31 | + pollInterval: <poll_interval_duration> |
| 32 | + ``` |
| 33 | + where: |
| 34 | +
|
| 35 | + `catalog_image` |
| 36 | + :Specifies the image reference for the catalog you want to install, such as `quay.io/operatorhubio/catalog:latest`. |
| 37 | + |
| 38 | + `poll_interval_duration` |
| 39 | + :Specifies the interval for polling the remote registry for newer image digests. |
| 40 | + The default value is `24h`. |
| 41 | + Valid units include seconds (`s`), minutes (`m`), and hours (`h`). |
| 42 | + To disable polling, set a zero value, such as `0s`. |
| 43 | + |
| 44 | + <details> |
| 45 | + <summary>Example `operatorhub.yaml` CR</summary> |
| 46 | + ```yaml |
| 47 | + apiVersion: catalogd.operatorframework.io/v1alpha1 |
| 48 | + kind: Catalog |
| 49 | + metadata: |
| 50 | + name: operatorhub |
| 51 | + spec: |
| 52 | + source: |
| 53 | + type: image |
| 54 | + image: |
| 55 | + ref: quay.io/operatorhubio/catalog:latest |
| 56 | + pollInterval: 1h |
| 57 | + ``` |
| 58 | + |
| 59 | +1. Apply the catalog CR: |
| 60 | + ```terminal |
| 61 | + $ kubectl apply -f <catalog_cr>.yaml |
| 62 | + ``` |
| 63 | + |
| 64 | + **Example output** |
| 65 | + ```text |
| 66 | + catalog.catalogd.operatorframework.io/redhat-operators created |
| 67 | + ``` |
| 68 | + |
| 69 | +### Verification |
| 70 | + |
| 71 | +* Run the following commands to verify the status of your catalog: |
| 72 | + |
| 73 | + * Check if your catalog is available on the cluster: |
| 74 | + ```terminal |
| 75 | + $ kubectl get catalog |
| 76 | + ``` |
| 77 | + |
| 78 | + **Example output** |
| 79 | + ```text |
| 80 | + NAME PHASE AGE |
| 81 | + operatorhubio 9s |
| 82 | + ``` |
| 83 | + |
| 84 | + * Check the status of your catalog: |
| 85 | + ```terminal |
| 86 | + $ kubectl describe catalog |
| 87 | + ``` |
| 88 | + |
| 89 | + **Example output** |
| 90 | + ```text |
| 91 | + Name: operatorhubio |
| 92 | + Namespace: |
| 93 | + Labels: <none> |
| 94 | + Annotations: <none> |
| 95 | + API Version: catalogd.operatorframework.io/v1alpha1 |
| 96 | + Kind: Catalog |
| 97 | + Metadata: |
| 98 | + Creation Timestamp: 2024-03-12T19:34:50Z |
| 99 | + Finalizers: |
| 100 | + catalogd.operatorframework.io/delete-server-cache |
| 101 | + Generation: 2 |
| 102 | + Resource Version: 6469 |
| 103 | + UID: 2e2778cb-dda6-4645-96b7-992e8dd37503 |
| 104 | + Spec: |
| 105 | + Source: |
| 106 | + Image: |
| 107 | + Poll Interval: 15m0s |
| 108 | + Ref: quay.io/operatorhubio/catalog:latest |
| 109 | + Type: image |
| 110 | + Status: |
| 111 | + Conditions: |
| 112 | + Last Transition Time: 2024-03-12T19:35:34Z |
| 113 | + Message: |
| 114 | + Reason: UnpackSuccessful |
| 115 | + Status: True |
| 116 | + Type: Unpacked |
| 117 | + Content URL: http://catalogd-catalogserver.catalogd-system.svc/catalogs/operatorhubio/all.json |
| 118 | + Observed Generation: 2 |
| 119 | + Phase: Unpacked |
| 120 | + Resolved Source: |
| 121 | + Image: |
| 122 | + Last Poll Attempt: 2024-03-12T19:35:26Z |
| 123 | + Ref: quay.io/operatorhubio/catalog:latest |
| 124 | + Resolved Ref: quay.io/operatorhubio/catalog@sha256:dee29aaed76fd1c72b654b9bc8bebc4b48b34fd8d41ece880524dc0c3c1c55ec |
| 125 | + Type: image |
| 126 | + Events: <none> |
| 127 | + ``` |
0 commit comments