Skip to content

Commit 3d6edb4

Browse files
grokspawngrokspawn
committed
update for
Signed-off-by: Jordan Keister <[email protected]>
1 parent de3d871 commit 3d6edb4

File tree

1 file changed

+54
-99
lines changed

1 file changed

+54
-99
lines changed

‎content/en/docs/Reference/catalog-templates.md

Lines changed: 54 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ The templates supported by [`opm`](https://github.com/operator-framework/operato
2222

2323
## Basic Template
2424
The `basic template` is an input schema which eliminates FBC information that can be retrieved from existing registries when we process it.
25-
Users provide all components of an [FBC schema](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#olm-defined-schemas), but supply only the bundle image reference for any `olm.bundle` objects. This results in a greatly simplified, smaller document.
26-
This approach may be attractive to operator authors who maintain existing catalogs and just want to make the job easier, or for operator authors who need to retain a channel graph which is not based on `semver`.
25+
Within the schema, users can add entries composed of any valid [FBC schema](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#olm-defined-schemas) components, but supply only the bundle image reference for any `olm.bundle` objects. This results in a greatly simplified, smaller document.
26+
This approach may be attractive to operator authors who maintain existing catalogs and just want to simplify the format, or for operator authors who need to retain an update graph which cannot be based on `semver`.
2727

2828
### Usage
2929

@@ -45,30 +45,26 @@ opm alpha render-template basic [flags] <filename>
4545

4646
In a very simple example, we define an `olm.package` and an `olm.channel` composed of two `olm.bundle` objects that have an image name attribute but no other attributes/properties.
4747
```yaml
48-
---
49-
schema: olm.package
50-
name: example-operator
51-
defaultChannel: stable
52-
---
53-
schema: olm.channel
54-
package: example-operator
55-
name: stable
48+
schema: olm.template.basic
5649
entries:
57-
- name: example-operator.v0.1.0
58-
- name: example-operator.v0.2.0
59-
replaces: example-operator.v0.1.0
60-
---
61-
schema: olm.bundle
62-
image: docker.io/example/example-operator-bundle:0.1.0
63-
---
64-
schema: olm.bundle
65-
image: docker.io/example-operator-bundle:0.2.0
50+
- schema: olm.package
51+
name: example-operator
52+
defaultChannel: stable
53+
- schema: olm.channel
54+
package: example-operator
55+
name: stable
56+
entries:
57+
- name: example-operator.v0.1.0
58+
- name: example-operator.v0.2.0
59+
replaces: example-operator.v0.1.0
60+
- schema: olm.bundle
61+
image: docker.io/example/example-operator-bundle:0.1.0
62+
- schema: olm.bundle
63+
image: docker.io/example/example-operator-bundle:0.2.0
6664
```
6765
6866
69-
Using the `opm alpha render-template basic` command on this input generates the full FBC:<details><summary> (click here to display full output)</summary>
70-
71-
(data blobs truncated with '... [snip] ...' for brevity)
67+
Using the `opm alpha render-template basic` command on this input generates the full FBC (skipping large bundle metadata objects):
7268

7369
```yaml
7470
---
@@ -97,21 +93,6 @@ properties:
9793
value:
9894
packageName: example-operator
9995
version: 0.1.0
100-
- type: olm.bundle.object
101-
value:
102-
data: eyJhcGlWZXJzaW9uIjoidjEiLCJraW5kIjoiU2VydmljZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJsYWJlbHMiOnsiY29udHJvbC1wbGFuZSI6ImNvbnRyb2xsZXItbWFuYWdlciJ9LCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1jb250cm9sbGVyLW1hbmFnZXItbWV0cmljcy1zZXJ2aWNlIn0sInNwZWMiOnsicG9ydHMiOlt7Im5hbWUiOiJodHRwcyIsInBvcnQiOjg0NDMsInByb3RvY29sIjoiVENQIiwidGFyZ2V0UG9ydCI6Imh0dHBzIn1dLCJzZWxlY3RvciI6eyJjb250cm9sLXBsYW5lIjoiY29udHJvbGxlci1tYW5hZ2VyIn19LCJzdGF0dXMiOnsibG9hZEJhbGFuY2VyIjp7fX19
103-
- type: olm.bundle.object
104-
value:
105-
data: eyJhcGlWZXJzaW9uIjoidjEiLCJkYXRhIjp7ImNvbnRyb2xsZXJfbWFuYWdlcl9jb25maWcueWFtbCI6ImFwaVZlcnNpb246IGNvbnRyb2xsZXItcnVudGltZS5zaWdzLms4cy5pby92MWFscGhhMVxua2luZDogQ29udHJvbGxlck1hbmFnZXJDb25maWdcbmhlYWx0aDpcbiAgaGVhbHRoUHJvYmVCaW5kQWRkcmVzczogOjgwODFcbm1ldHJpY3M6XG4gIGJpbmRBZGRyZXNzOiAxMjcuMC4wLjE6ODA4MFxud2ViaG9vazpcbiAgcG9ydDogOTQ0M1xubGVhZGVyRWxlY3Rpb246XG4gIGxlYWRlckVsZWN0OiB0cnVlXG4gIHJlc291cmNlTmFtZTogY2RmNjA0MTIuY29tXG4ifSwia2luZCI6IkNvbmZpZ01hcCIsIm1ldGFkYXRhIjp7Im5hbWUiOiJleGFtcGxlLW9wZXJhdG9yLW1hbmFnZXItY29uZmlnIn19
106-
- type: olm.bundle.object
107-
value:
108-
data: eyJhcGlWZXJzaW9uIjoicmJhYy5hdXRob3JpemF0aW9uLms4cy5pby92MSIsImtpbmQiOiJDbHVzdGVyUm9sZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1tZXRyaWNzLXJlYWRlciJ9LCJydWxlcyI6W3sibm9uUmVzb3VyY2VVUkxzIjpbIi9tZXRyaWNzIl0sInZlcmJzIjpbImdldCJdfV19
109-
- type: olm.bundle.object
110-
value:
111-
data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ==
112-
- type: olm.bundle.object
113-
value:
114-
data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ==
11596
relatedImages:
11697
- image: gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0
11798
name: ""
@@ -134,21 +115,6 @@ properties:
134115
value:
135116
packageName: example-operator
136117
version: 0.2.0
137-
- type: olm.bundle.object
138-
value:
139-
data: eyJhcGlWZXJzaW9uIjoidjEiLCJraW5kIjoiU2VydmljZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJsYWJlbHMiOnsiY29udHJvbC1wbGFuZSI6ImNvbnRyb2xsZXItbWFuYWdlciJ9LCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1jb250cm9sbGVyLW1hbmFnZXItbWV0cmljcy1zZXJ2aWNlIn0sInNwZWMiOnsicG9ydHMiOlt7Im5hbWUiOiJodHRwcyIsInBvcnQiOjg0NDMsInByb3RvY29sIjoiVENQIiwidGFyZ2V0UG9ydCI6Imh0dHBzIn1dLCJzZWxlY3RvciI6eyJjb250cm9sLXBsYW5lIjoiY29udHJvbGxlci1tYW5hZ2VyIn19LCJzdGF0dXMiOnsibG9hZEJhbGFuY2VyIjp7fX19
140-
- type: olm.bundle.object
141-
value:
142-
data: eyJhcGlWZXJzaW9uIjoidjEiLCJkYXRhIjp7ImNvbnRyb2xsZXJfbWFuYWdlcl9jb25maWcueWFtbCI6ImFwaVZlcnNpb246IGNvbnRyb2xsZXItcnVudGltZS5zaWdzLms4cy5pby92MWFscGhhMVxua2luZDogQ29udHJvbGxlck1hbmFnZXJDb25maWdcbmhlYWx0aDpcbiAgaGVhbHRoUHJvYmVCaW5kQWRkcmVzczogOjgwODFcbm1ldHJpY3M6XG4gIGJpbmRBZGRyZXNzOiAxMjcuMC4wLjE6ODA4MFxud2ViaG9vazpcbiAgcG9ydDogOTQ0M1xubGVhZGVyRWxlY3Rpb246XG4gIGxlYWRlckVsZWN0OiB0cnVlXG4gIHJlc291cmNlTmFtZTogY2RmNjA0MTIuY29tXG4ifSwia2luZCI6IkNvbmZpZ01hcCIsIm1ldGFkYXRhIjp7Im5hbWUiOiJleGFtcGxlLW9wZXJhdG9yLW1hbmFnZXItY29uZmlnIn19
143-
- type: olm.bundle.object
144-
value:
145-
data: eyJhcGlWZXJzaW9uIjoicmJhYy5hdXRob3JpemF0aW9uLms4cy5pby92MSIsImtpbmQiOiJDbHVzdGVyUm9sZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1tZXRyaWNzLXJlYWRlciJ9LCJydWxlcyI6W3sibm9uUmVzb3VyY2VVUkxzIjpbIi9tZXRyaWNzIl0sInZlcmJzIjpbImdldCJdfV19
146-
- type: olm.bundle.object
147-
value:
148-
data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ==
149-
- type: olm.bundle.object
150-
value:
151-
data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ==
152118
relatedImages:
153119
- image: gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0
154120
name: ""
@@ -157,67 +123,56 @@ relatedImages:
157123
- image: docker.io/example/example-operator:0.2.0
158124
name: ""
159125
schema: olm.bundle
160-
161126
```
162-
</details>
163127

164-
#### Converting from FBC to Basic Template
165-
Operator authors can convert a File-Based Catalog (FBC) to a basic template by processing the output of the `opm render` command through either `jq` or `yq`.
128+
## Converting from FBC to Basic Template
129+
Opm provides the capability to render existing File-Based Catalogs to basic catalog templates in JSON or YAML formats.
166130

167-
To convert a File-Based Catalog to a Basic Template using `jq`, run the following command:
131+
### Usage
168132

169133
```sh
170-
opm render <catalogRef> -o json | jq 'if (.schema == "olm.bundle") then {schema: .schema, image: .image} else . end'
134+
opm alpha convert-template basic [flags] <filename>
171135
```
172136

137+
| Flag | Description |
138+
| ------------------- | -------------------------------------------------------------------------------------- |
139+
| -h, --help | prints help/usage information |
140+
| -o, --output <type> | the output format, can be `yaml` or `json` |
141+
| --skip-tls-verify | skip TLS certificate verification for container image registries while pulling bundles |
142+
| --use-http | use plain HTTP for container image registries while pulling bundles |
143+
144+
`--skip-tls-verify` and `--use-http` are mutually exclusive flags.
145+
146+
147+
173148
Example template in JSON format after the conversion:
174149

175150
```json
176151
{
177-
"schema": "olm.package",
178-
"name": "hello-kubernetes",
179-
"defaultChannel": "alpha",
180-
"description": "hello-kubernetes"
181-
}
182-
{
183-
"schema": "olm.channel",
184-
"name": "alpha",
185-
"package": "hello-kubernetes",
152+
"schema": "olm.template.basic",
186153
"entries": [
187154
{
188-
"name": "hello-kubernetes.v0.0.1"
155+
"schema": "olm.package",
156+
"name": "hello-kubernetes",
157+
"defaultChannel": "alpha",
158+
"description": "hello-kubernetes"
159+
},
160+
{
161+
"schema": "olm.channel",
162+
"name": "alpha",
163+
"package": "hello-kubernetes",
164+
"entries": [
165+
{
166+
"name": "hello-kubernetes.v0.0.1"
167+
}
168+
]
169+
},
170+
{
171+
"schema": "olm.bundle",
172+
"image": "docker.io/test/hello-kubernetes-operator-bundle:v0.0.1"
189173
}
190174
]
191175
}
192-
{
193-
"schema": "olm.bundle",
194-
"image": "docker.io/test/hello-kubernetes-operator-bundle:v0.0.1"
195-
}
196-
```
197-
198-
To convert a File-Based Catalog to a Basic Template using `yq`, run the following command:
199-
200-
```sh
201-
opm render <catalogRef> -o yaml | yq eval -i 'select(.schema == "olm.bundle") = {"schema": .schema, "image": .image}' test.yaml - test.yaml
202-
```
203-
204-
Example basic template in YAML format after the conversion:
205-
206-
```yaml
207-
---
208-
schema: olm.package
209-
defaultChannel: alpha
210-
description: hello-kubernetes
211-
name: hello-kubernetes
212-
---
213-
schema: olm.channel
214-
name: alpha
215-
package: hello-kubernetes
216-
entries:
217-
- name: hello-kubernetes.v0.0.1
218-
---
219-
schema: olm.bundle
220-
image: docker.io/test/hello-kubernetes-operator-bundle:v0.0.1
221176
```
222177

223178
## Semver Template
@@ -339,7 +294,7 @@ GenerateMajorChannels: true
339294
GenerateMinorChannels: false
340295
```
341296

342-
we generate the following major channels (filtering out `olm.bundle` objects):
297+
we generate the following major channels (filtering out large bundle metadata):
343298
```yaml
344299
---
345300
defaultChannel: stable-v1
@@ -417,7 +372,7 @@ GenerateMinorChannels: true
417372
GenerateMajorChannels: false
418373
```
419374

420-
we generate the following minor channels (again filtering out `olm.bundle` objects):
375+
we generate the following minor channels (again filtering out large bundle metadata):
421376

422377
```yaml
423378
---

0 commit comments

Comments
 (0)