Skip to content

Commit 9fde96d

Browse files
committed
Explain why subscriptions do not adopt CSVs
Update the subscription.md document to explain why a Subscription cannot adopt existing ClusterServiceVersions that are not associated with it. Signed-off-by: Alexander Greene <greene.al1991@gmail.com>
1 parent 50cf7e0 commit 9fde96d

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

content/en/docs/Tasks/Troubleshooting/subscription.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,35 @@ If the `Status` block does not provide enough information, check the [Catalog op
2929

3030
`Subscriptions` cannot install operators provided by `CatalogSources` that are not in the same namespace unless the `CatalogSource` is created in the `olm` namespace.
3131

32+
### A subscription fails because I deleted a similar subscription and left the CSV it installed
33+
34+
By creating a `Subscription`, the user is "subscribing" to updates from a particular package and channel within a `CatalogSource`. When a `ClusterServiceVersion (CSV)` is created to fulfill the `Subscription`, the `Subscription` is updated so it is "associated" with that `CSV`. "Associated" `CSVs` do not need to appear in the solution set allowing the `Subscription's` requirements to be met by `CSVs` in the channel that are valid upgrades from the existing `CSV`.
35+
36+
When you delete a `Subscription`, the `CSV` is no longer "associated" with any `Subscriptions`. `CSVs` that are not "associated" with a `Subscription` must appear in the solution set returned by the resolver. Historically, this allowed users to "pin" a specific version of the operator and cancel any upgrades.
37+
38+
Once a `CSV` is no longer "associated" with a `Subscription`, creating a new `Subscription` that subscribes to the same package and channel within a `CatalogSource` will not "associate" the existing `CSV` with the `Subscription` because there is no guarantee that the package, channel, and `CatalogSource` defined in the `Subscription` are globally unique.
39+
40+
Creating a new `Subscription` for the existing `CSV` causes the resolver to fail because of the following requirements:
41+
- The `Subscription` requires an `CSV` that fulfills it.
42+
- The existing `CSV` must appear in the solution set (remember, it cannot fulfill the requirements of `Subscriptions` it is not associated with).
43+
44+
This ultimately returns a failure message similar to:
45+
```bash
46+
message: 'constraints not satisfiable: @existing/namespace-foo/operator-foo.v1.0.0
47+
and catalogSource-foo/namespace-foo/4.Y/operator-foo.v1.1.0
48+
originate from package foo-operator, subscription subscription-foo
49+
requires catalogSource-foo/namespace-foo/4.Y/operator-foo.v1.1.0,
50+
subscription subscription-foo exists, clusterserviceversion
51+
operator-foo.v1.0.0 exists and is not referenced by a subscription'
52+
reason: ConstraintsNotSatisfiable
53+
status: "True"
54+
type: ResolutionFailed
55+
```
56+
57+
There are two potential workarounds:
58+
- If you want to upgrade the operator, you will need to delete the existing `CSV`.
59+
- If you do not want to upgrade the operator, you will need to delete the `Subscription`.
60+
3261
### Why does a single failing subscription cause all subscriptions in a namespace to fail?
3362

3463
Each Subscription in a namespace acts as a part of a set of operators for the namespace - think of a Subscription as an entry in a python `requirements.txt`. If OLM is unable to resolve part of the set, it knows that resolving the entire set will fail, so it will bail out of the installation of operators for that particular namespace. Subscriptions are separate objects but within a namespace they are all synced and resolved together.

0 commit comments

Comments
 (0)