Add docs for dependency resolution #51
Conversation
| There are two rules that govern catalog preference: | ||
|
|
||
| - Options in higher-priority catalogs are preferred to options in lower-priority catalogs | ||
| - Options in the same catalog as the depender are preferred to any other catalogs. |
There was a problem hiding this comment.
Nit:
| - Options in the same catalog as the depender are preferred to any other catalogs. | |
| - Options in the same catalog as the depender are preferred to any other catalogs |
|
|
||
| ### No compound constraints ("AND") | ||
|
|
||
| There is not a way to specify an "AND" relationship between constraints. In other words, there is no way to say: "this operator depends on another operator that both provides `Foo` api and has version `>1.1.0`". |
There was a problem hiding this comment.
Ah, this is a pretty big caveat. Up until now I thought the constraints were exactly olm.package AND olm.gvk.
But now I guess I can see there's nothing to intersect the two constraints on.
There was a problem hiding this comment.
It might help to have an example that pulls in two operator dependencies, so it's more clear?
There was a problem hiding this comment.
+1
Also, do we want to rephrase the statement There is not a way to specify an "AND" relationship between constraints or is it just me?
|
|
||
| `dependencies.yaml` is supported in 0.16.1+ versions of OLM. | ||
|
|
||
| In versions of OLM < 0.16.1, only GVK constraints are supported, and only via the `required` section of the ClusterServiceVersion. |
There was a problem hiding this comment.
| In versions of OLM < 0.16.1, only GVK constraints are supported, and only via the `required` section of the ClusterServiceVersion. | |
| In versions of OLM < `0.16.1`, only GVK constraints are supported, and only via the `required` section of the ClusterServiceVersion. |
openshift-ci-robot
added
lgtm
ecordell
force-pushed
the
depresdocs
branch
3 times, most recently
from
6c4db47 to
267bac9
Compare
There was a problem hiding this comment.
Great write up @ecordell
Have a couple of nits.
Also, do you think Concepts is a better place for this doc than References? I was under the assumption that we'll be using the References section to refer to external resources, how this doc for example refers to kubernetes docs for "further information" on admission webhooks.
| This is made possible with two types of data: | ||
|
|
||
| - **Properties** - typed metadata about the operator that constutes the public interface for it in the dependency resolver. Examples include the GVKs of the APIs provided by the operator and the SemVer version of the operator | ||
| - **Constraints** or **Dependencies** - an operator's requirements that should be satisfied by other operators (that may or may not have already been installed) or the target cluster. These act as queries / filters over all available operators and constrain the selection when resolving or installing. Examples include requiring a specific API to be available on the cluster, or expecting a particular operator with a particular version to be installed. |
There was a problem hiding this comment.
| - **Constraints** or **Dependencies** - an operator's requirements that should be satisfied by other operators (that may or may not have already been installed) or the target cluster. These act as queries / filters over all available operators and constrain the selection when resolving or installing. Examples include requiring a specific API to be available on the cluster, or expecting a particular operator with a particular version to be installed. | |
| - **Constraints** or **Dependencies** - an operator's requirements that should be satisfied by other operators (that may or may not have already been installed) on the target cluster. These act as queries / filters over all available operators and constrain the selection when resolving or installing. Examples include requiring a specific API to be available on the cluster, or expecting a particular operator with a particular version to be installed. |
Did you mean that?
|
|
||
| ***Note***: The `version` field above follows the [SemVer 2.0 Spec](https://semver.org/) for version ranges, and specifically uses [blang/semver](https://github.com/blang/semver) to parse. | ||
|
|
||
| The resolver sees these constraints as (assuming this is for `FooOperator v1.0.0`): |
There was a problem hiding this comment.
Is it better to talk about installing the Bar operator here instead of the foo operator since that's what we've been discussing so far in the doc?
|
|
||
| ### No compound constraints ("AND") | ||
|
|
||
| There is not a way to specify an "AND" relationship between constraints. In other words, there is no way to say: "this operator depends on another operator that both provides `Foo` api and has version `>1.1.0`". |
There was a problem hiding this comment.
+1
Also, do we want to rephrase the statement There is not a way to specify an "AND" relationship between constraints or is it just me?
ecordell
force-pushed
the
depresdocs
branch
from
267bac9 to
68d82ad
Compare
|
@anik120 Addressed your feedback and moved to I hear the feedback on the "ADD" constraint - if it's okay, I'd like to merge the doc as-is and then come back with a follow up PR to think about how to better explain that / make it less surprising. |
|
/cherry-pick legacy |
|
@anik120: new pull request created: #65 In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
For now, I've added support for a mermaid shortcode. It would be nicer to pre-render them, and use a markdown code fence to indicate mermaid content (which would match hackmd), but this will get us running for now.