You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `olm.channel` schema defines a channel within a package, the bundle entries that are members of the channel, and the upgrade edges for those bundles.
9
+
10
+
If a bundle entry represents an edge in multiple `olm.channel` blobs, it can only appear once per channel.
11
+
12
+
It is valid for an entry's `replaces` value to reference another bundle name that cannot be found in this catalog or another catalog. However, all other channel invariants must hold true, such as a channel not having multiple heads.
13
+
14
+
.`olm.channel` schema
15
+
[%collapsible]
16
+
====
17
+
[source,go]
18
+
----
19
+
#Channel: {
20
+
schema: "olm.channel"
21
+
package: string & !=""
22
+
name: string & !=""
23
+
entries: [...#ChannelEntry]
24
+
}
25
+
26
+
#ChannelEntry: {
27
+
// name is required. It is the name of an `olm.bundle` that
28
+
// is present in the channel.
29
+
name: string & !=""
30
+
31
+
// replaces is optional. It is the name of bundle that is replaced
32
+
// by this entry. It does not have to be present in the entry list.
33
+
replaces?: string & !=""
34
+
35
+
// skips is optional. It is a list of bundle names that are skipped by
36
+
// this entry. The skipped bundles do not have to be present in the
37
+
// entry list.
38
+
skips?: [...string & !=""]
39
+
40
+
// skipRange is optional. It is the semver range of bundle versions
41
+
// that are skipped by this entry.
42
+
skipRange?: string & !=""
43
+
}
44
+
----
45
+
====
46
+
47
+
[WARNING]
48
+
====
49
+
When using the `skipRange` field, the skipped Operator versions are pruned from the update graph and are longer installable by users with the `spec.startingCSV` property of `Subscription` objects.
50
+
51
+
You can update an Operator incrementally while keeping previously installed versions available to users for future installation by using both the `skipRange` and `replaces` field. Ensure that the `replaces` field points to the immediate previous version of the Operator version in question.
The optional `olm.deprecations` schema defines deprecation information for packages, bundles, and channels in a catalog. Operator authors can use this schema to provide relevant messages about their Operators, such as support status and recommended upgrade paths, to users running those Operators from a catalog.
9
+
10
+
An `olm.deprecations` schema entry contains one or more of the following `reference` types, which indicates the deprecation scope. After the Operator is installed, any specified messages can be viewed as status conditions on the related `Subscription` object.
11
+
12
+
.Deprecation `reference` types
13
+
[cols="1,2,1",options="header"]
14
+
|===
15
+
|Type |Scope |Status condition
16
+
17
+
|`olm.package`
18
+
|Represents the entire package
19
+
|`PackageDeprecated`
20
+
21
+
|`olm.channel`
22
+
|Represents one channel
23
+
|`ChannelDeprecated`
24
+
25
+
|`olm.bundle`
26
+
|Represents one bundle version
27
+
|`BundleDeprecated`
28
+
29
+
|===
30
+
31
+
Each `reference` type has their own requirements, as detailed in the following example.
32
+
33
+
.Example `olm.deprecations` schema with each `reference` type
34
+
[%collapsible]
35
+
====
36
+
[source,yaml]
37
+
----
38
+
schema: olm.deprecations
39
+
package: my-operator <1>
40
+
entries:
41
+
- reference:
42
+
schema: olm.package <2>
43
+
message: | <3>
44
+
The 'my-operator' package is end of life. Please use the
45
+
'my-operator-new' package for support.
46
+
- reference:
47
+
schema: olm.channel
48
+
name: alpha <4>
49
+
message: |
50
+
The 'alpha' channel is no longer supported. Please switch to the
51
+
'stable' channel.
52
+
- reference:
53
+
schema: olm.bundle
54
+
name: my-operator.v1.68.0 <5>
55
+
message: |
56
+
my-operator.v1.68.0 is deprecated. Uninstall my-operator.v1.68.0 and
57
+
install my-operator.v1.72.0 for support.
58
+
----
59
+
<1> Each deprecation schema must have a `package` value, and that package reference must be unique across the catalog. There must not be an associated `name` field.
60
+
<2> The `olm.package` schema must not include a `name` field, because it is determined by the `package` field defined earlier in the schema.
61
+
<3> All `message` fields, for any `reference` type, must be a non-zero length and represented as an opaque text blob.
62
+
<4> The `name` field for the `olm.channel` schema is required.
63
+
<5> The `name` field for the `olm.bundle` schema is required.
64
+
====
65
+
66
+
[NOTE]
67
+
====
68
+
The deprecation feature does not consider overlapping deprecation, for example package versus channel versus bundle.
69
+
====
70
+
71
+
Operator authors can save `olm.deprecations` schema entries as a `deprecations.yaml` file in the same directory as the package's `index.yaml` file:
72
+
73
+
.Example directory structure for a catalog with deprecations
Copy file name to clipboardExpand all lines: modules/olm-fb-catalogs-schemas.adoc
+1-117
Original file line number
Diff line number
Diff line change
@@ -42,120 +42,4 @@ Each Operator package in a catalog requires exactly one `olm.package` blob, at l
42
42
[NOTE]
43
43
====
44
44
All `olm.*` schemas are reserved for OLM-defined schemas. Custom schemas must use a unique prefix, such as a domain that you own.
45
-
====
46
-
47
-
[id="olm-fb-catalogs-package-schema_{context}"]
48
-
== olm.package schema
49
-
50
-
The `olm.package` schema defines package-level metadata for an Operator. This includes its name, description, default channel, and icon.
51
-
52
-
.`olm.package` schema
53
-
[%collapsible]
54
-
====
55
-
[source,go]
56
-
----
57
-
#Package: {
58
-
schema: "olm.package"
59
-
60
-
// Package name
61
-
name: string & !=""
62
-
63
-
// A description of the package
64
-
description?: string
65
-
66
-
// The package's default channel
67
-
defaultChannel: string & !=""
68
-
69
-
// An optional icon
70
-
icon?: {
71
-
base64data: string
72
-
mediatype: string
73
-
}
74
-
}
75
-
----
76
-
====
77
-
78
-
[id="olm-fb-catalogs-channel-schema_{context}"]
79
-
== olm.channel schema
80
-
81
-
The `olm.channel` schema defines a channel within a package, the bundle entries that are members of the channel, and the upgrade edges for those bundles.
82
-
83
-
A bundle can included as an entry in multiple `olm.channel` blobs, but it can have only one entry per channel.
84
-
85
-
It is valid for an entry's replaces value to reference another bundle name that cannot be found in this catalog or another catalog. However, all other channel invariants must hold true, such as a channel not having multiple heads.
86
-
87
-
.`olm.channel` schema
88
-
[%collapsible]
89
-
====
90
-
[source,go]
91
-
----
92
-
#Channel: {
93
-
schema: "olm.channel"
94
-
package: string & !=""
95
-
name: string & !=""
96
-
entries: [...#ChannelEntry]
97
-
}
98
-
99
-
#ChannelEntry: {
100
-
// name is required. It is the name of an `olm.bundle` that
101
-
// is present in the channel.
102
-
name: string & !=""
103
-
104
-
// replaces is optional. It is the name of bundle that is replaced
105
-
// by this entry. It does not have to be present in the entry list.
106
-
replaces?: string & !=""
107
-
108
-
// skips is optional. It is a list of bundle names that are skipped by
109
-
// this entry. The skipped bundles do not have to be present in the
110
-
// entry list.
111
-
skips?: [...string & !=""]
112
-
113
-
// skipRange is optional. It is the semver range of bundle versions
114
-
// that are skipped by this entry.
115
-
skipRange?: string & !=""
116
-
}
117
-
----
118
-
====
119
-
120
-
[WARNING]
121
-
====
122
-
When using the `skipRange` field, the skipped Operator versions are pruned from the update graph and are therefore no longer installable by users with the `spec.startingCSV` property of `Subscription` objects.
123
-
124
-
If you want to have direct (one version increment) updates to an Operator version from multiple previous versions, and also keep those previous versions available to users for installation, always use the `skipRange` field along with the `replaces` field. Ensure that the `replaces` field points to the immediate previous version of the Operator version in question.
125
-
====
126
-
127
-
[id="olm-fb-catalogs-olm-bundle_{context}"]
128
-
== olm.bundle schema
129
-
130
-
.`olm.bundle` schema
131
-
[%collapsible]
132
-
====
133
-
[source,go]
134
-
----
135
-
#Bundle: {
136
-
schema: "olm.bundle"
137
-
package: string & !=""
138
-
name: string & !=""
139
-
image: string & !=""
140
-
properties: [...#Property]
141
-
relatedImages?: [...#RelatedImage]
142
-
}
143
-
144
-
#Property: {
145
-
// type is required
146
-
type: string & !=""
147
-
148
-
// value is required, and it must not be null
149
-
value: !=null
150
-
}
151
-
152
-
#RelatedImage: {
153
-
// image is the image reference
154
-
image: string & !=""
155
-
156
-
// name is an optional descriptive name for an image that
157
-
// helps identify its purpose in the context of the bundle
Copy file name to clipboardExpand all lines: modules/olm-fb-catalogs-structure.adoc
+2-1
Original file line number
Diff line number
Diff line change
@@ -35,6 +35,7 @@ catalog
35
35
│ └── packageB.v0.1.0.clusterserviceversion.yaml
36
36
└── packageC
37
37
└── index.json
38
+
└── deprecations.yaml
38
39
----
39
40
40
-
This recommended structure has the property that each subdirectory in the directory hierarchy is a self-contained catalog, which makes catalog composition, discovery, and navigation trivial file system operations. The catalog could also be included in a parent catalog by copying it into the parent catalog's root directory.
41
+
This recommended structure has the property that each subdirectory in the directory hierarchy is a self-contained catalog, which makes catalog composition, discovery, and navigation trivial file system operations. The catalog can also be included in a parent catalog by copying it into the parent catalog's root directory.
Copy file name to clipboardExpand all lines: modules/olm-filtering-fbc.adoc
+17-4
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,14 @@ endif::[]
13
13
[id="olm-filtering-fbc_{context}"]
14
14
= Updating or filtering a file-based catalog image
15
15
16
-
You can use the `opm` CLI to update or filter (also known as prune) a catalog image that uses the file-based catalog format. By extracting and modifying the contents of an existing catalog image, you can update, add, or remove one or more Operator package entries from the catalog. You can then rebuild the image as an updated version of the catalog.
16
+
You can use the `opm` CLI to update or filter a catalog image that uses the file-based catalog format. By extracting the contents of an existing catalog image, you can modify the catalog as needed, for example:
17
+
18
+
* Adding packages
19
+
* Removing packages
20
+
* Updating existing package entries
21
+
* Detailing deprecation messages per package, channel, and bundle
22
+
23
+
You can then rebuild the image as an updated version of the catalog.
17
24
18
25
// This note points to a topic that's excluded from OSD and ROSA.
Alternatively, you can use the `-o json` flag to output in JSON format.
50
57
====
51
58
52
-
. Modify the contents of the resulting `index.yaml` file to your specifications by updating, adding, or removing one or more Operator package entries.
59
+
. Modify the contents of the resulting `index.yaml` file to your specifications:
53
60
+
54
61
[IMPORTANT]
55
62
====
56
63
After a bundle has been published in a catalog, assume that one of your users has installed it. Ensure that all previously published bundles in a catalog have an update path to the current or newer channel head to avoid stranding users that have that version installed.
57
64
====
58
65
+
59
-
For example, if you wanted to remove an Operator package, the following example lists a set of `olm.package`, `olm.channel`, and `olm.bundle` blobs which must be deleted to remove the package from the catalog:
66
+
--
67
+
* To add an Operator, follow the steps for creating package, bundle, and channel entries in the "Creating a file-based catalog image" procedure.
68
+
69
+
* To remove an Operator, delete the set of `olm.package`, `olm.channel`, and `olm.bundle` blobs that relate to the package. The following example shows a set that must be deleted to remove the `example-operator` package from the catalog:
60
70
+
61
71
.Example removed entries
62
72
[%collapsible]
@@ -122,7 +132,10 @@ schema: olm.bundle
122
132
----
123
133
====
124
134
125
-
. Save your changes to the `index.yaml` file.
135
+
* To add or update deprecation messages for an Operator, ensure there is a `deprecations.yaml` file in the same directory as the package's `index.yaml` file. For information on the `deprecations.yaml` file format, see "olm.deprecations schema".
* xref:../../operators/understanding/olm-packaging-format.adoc#olm-deprecations-schema_olm-packaging-format[Packaging format -> Schemas -> olm.deprecations schema]
65
66
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#updating-mirror-registry-content[Mirroring images for a disconnected installation using the oc-mirror plugin -> Keeping your mirror registry content updated]
66
67
* xref:../../operators/admin/olm-restricted-networks.adoc#olm-creating-catalog-from-index_olm-restricted-networks[Adding a catalog source to a cluster]
0 commit comments