Skip to content

Commit 4083df4

Browse files
michaelryanpetermichaelryanpeter
committed
📖 Update "Adding a catalog of extensions"
#693 - Add prerequisites - Format content as a procedure with steps - Add PollInterval field Signed-off-by: Michael Ryan Peter <[email protected]>
1 parent 6cb56f7 commit 4083df4

File tree

1 file changed

+113
-70
lines changed

1 file changed

+113
-70
lines changed

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

+113-70
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,121 @@
1-
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.
1+
Extension authors can publish their products in catalogs.
2+
Catalogs are curated collections of Operators and extensions.
3+
Cluster administrators can add these catalogs to their cluster.
4+
When extension authors publish updates to their catalogs, cluster administrators can install and update those changes.
25

3-
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.
6+
## Prerequisites
47

5-
To consume this catalog on cluster, create a `Catalog` Custom Resource(CR) with the image specified in the `spec.source.image` field:
8+
* Access to a Kubernetes cluster, for example `kind`, using an account with `cluster-admin` permissions
9+
* [Operator Controller installed](https://github.com/operator-framework/operator-controller/releases) on the cluster
10+
* [Catalogd installed](https://github.com/operator-framework/catalogd/releases/) on the cluster
11+
* Kubernetes CLI (`kubectl`) installed on your workstation
612

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-
```
13+
## Procedure
2014

21-
The packages made available for installation/receiving updates on cluster can then be explored by querying the `Package` and `BundleMetadata` CRs:
15+
1. Create a catalog custom resource (CR):
16+
```yaml
17+
apiVersion: catalogd.operatorframework.io/v1alpha1
18+
kind: Catalog
19+
metadata:
20+
name: operatorhubio
21+
spec:
22+
source:
23+
type: image
24+
image:
25+
ref: <catalog_image>
26+
pollInterval: <poll_interval_duration>
27+
```
28+
where:
2229
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-
.
30+
`catalog_image`
31+
:Specifies the image reference for the catalog you want to install, such as `quay.io/operatorhubio/catalog:latest`.
32+
`poll_interval_duration`
33+
:Specifies the interval for polling the remote registry for newer image digests.
34+
The default value is `24h`.
35+
Valid units include seconds (`s`), minutes (`m`), and hours (`h`).
36+
To disable polling, set a zero value, such as `0s`.
4737

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-
```
38+
<details>
39+
<summary>Example `operatorhub.yaml` CR</summary>
40+
```yaml
41+
apiVersion: catalogd.operatorframework.io/v1alpha1
42+
kind: Catalog
43+
metadata:
44+
name: operatorhub
45+
spec:
46+
source:
47+
type: image
48+
image:
49+
ref: quay.io/operatorhubio/catalog:latest
50+
pollInterval: 1h
51+
```
7752

53+
1. Apply the catalog CR:
54+
```bash
55+
$ kubectl apply -f <catalog_cr>.yaml
56+
```
7857

58+
**Example output**
59+
```text
60+
catalog.catalogd.operatorframework.io/redhat-operators created
61+
```
62+
63+
### Verification
64+
65+
* Run the following commands to verify the status of your catalog:
66+
67+
* Check if your catalog is available on the cluster:
68+
```terminal
69+
$ kubectl get catalog
70+
```
71+
72+
**Example output**
73+
```text
74+
NAME PHASE AGE
75+
operatorhubio 9s
76+
```
77+
78+
* Check the status of your catalog:
79+
```terminal
80+
$ kubectl describe catalog
81+
```
82+
83+
**Example output**
84+
```text
85+
Name: operatorhubio
86+
Namespace:
87+
Labels: <none>
88+
Annotations: <none>
89+
API Version: catalogd.operatorframework.io/v1alpha1
90+
Kind: Catalog
91+
Metadata:
92+
Creation Timestamp: 2024-03-12T19:34:50Z
93+
Finalizers:
94+
catalogd.operatorframework.io/delete-server-cache
95+
Generation: 2
96+
Resource Version: 6469
97+
UID: 2e2778cb-dda6-4645-96b7-992e8dd37503
98+
Spec:
99+
Source:
100+
Image:
101+
Poll Interval: 15m0s
102+
Ref: quay.io/operatorhubio/catalog:latest
103+
Type: image
104+
Status:
105+
Conditions:
106+
Last Transition Time: 2024-03-12T19:35:34Z
107+
Message:
108+
Reason: UnpackSuccessful
109+
Status: True
110+
Type: Unpacked
111+
Content URL: http://catalogd-catalogserver.catalogd-system.svc/catalogs/operatorhubio/all.json
112+
Observed Generation: 2
113+
Phase: Unpacked
114+
Resolved Source:
115+
Image:
116+
Last Poll Attempt: 2024-03-12T19:35:26Z
117+
Ref: quay.io/operatorhubio/catalog:latest
118+
Resolved Ref: quay.io/operatorhubio/catalog@sha256:dee29aaed76fd1c72b654b9bc8bebc4b48b34fd8d41ece880524dc0c3c1c55ec
119+
Type: image
120+
Events: <none>
121+
```

0 commit comments

Comments
 (0)