Skip to content

Commit 1f6f074

Browse files
oceanc80oceanc80
committed
Update render graph docs
1 parent 83da557 commit 1f6f074

File tree

2 files changed

+142
-0
lines changed

2 files changed

+142
-0
lines changed

‎content/en/docs/Reference/images/full-upgrade-graph.png‎

69.8 KB
Loading

‎content/en/docs/Reference/upgrade-graph-visualization.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: "Upgrade Graph Visualization"
3+
linkTitle: "Upgrade Graph Visualization (alpha)"
4+
weight: 5
5+
date: 2024-11-18
6+
---
7+
8+
>Note: `upgrade graph visualization` is **ALPHA** functionality and may adopt breaking changes
9+
10+
11+
## Concept
12+
13+
File-Based Catalogs (FBC) are a major improvement to the imperative update graph approaches of previous versions. FBCs give operator authors a [declarative and deterministic approach to defining their update graph](https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/). However, FBCs can get complex, especially as the number of releases and dependencies scale. The upgrade graphs, in particular, for an operator can be difficult to reason about abstractly. Having an easy way to understand and quickly troubleshoot issues such as orphaned or stranded versions where there is no upgrade path forward from the orphaned or stranded version. To support understanding the upgrade graphs of operators in an index, we introduce a tool to generate a mermaid-formatted visualization through the `render-graph` command.
14+
15+
## Visualizing Upgrade Graphs
16+
17+
The `render-graph` command generates the upgrade graphs of operators for a given index in mermaid-format. The resulting output can then be viewed in online services such as [mermaid.live](https://mermaid.live) or converted to an image using a tool such as [mermaid-cli](https://github.com/mermaid-js/mermaid-cli).
18+
19+
### Usage
20+
21+
```sh
22+
opm alpha render-graph [index-image | fbc-dir] [flags]
23+
```
24+
25+
| Flag | Description |
26+
| ------------------------- | ----------------------------------------------------------------------------------------- |
27+
| -h, --help | prints help/usage information |
28+
| --minimum-edge string | the channel edge to use as the lower bound of the set of edges composing the upgrade graph; default is to include all edges |
29+
| -p, --package-name string | a specific package name to filter output; default is to include all packages in reference |
30+
| --skip-tls-verify | skip TLS certificate verification for container image registries while pulling bundles |
31+
| --use-http | use plain HTTP for container image registries while pulling bundles |
32+
33+
`--skip-tls-verify` and `--use-http` are mutually exclusive flags.
34+
35+
### Examples
36+
For the following examples, we define a catalog with the following FBC directory structure:
37+
```
38+
example_catalog/
39+
└── testoperator
40+
└── index.yaml
41+
```
42+
43+
The index.yaml file contains the following:
44+
```yaml
45+
---
46+
defaultChannel: stable-v1
47+
name: testoperator
48+
schema: olm.package
49+
---
50+
entries:
51+
- name: testoperator.v0.1.0
52+
- name: testoperator.v0.1.1
53+
- name: testoperator.v0.1.2
54+
- name: testoperator.v0.1.3
55+
skips:
56+
- testoperator.v0.1.0
57+
- testoperator.v0.1.1
58+
- testoperator.v0.1.2
59+
- name: testoperator.v0.2.0
60+
- name: testoperator.v0.2.1
61+
- name: testoperator.v0.2.2
62+
replaces: testoperator.v0.1.3
63+
skips:
64+
- testoperator.v0.2.0
65+
- testoperator.v0.2.1
66+
- name: testoperator.v0.2.3
67+
skips:
68+
- testoperator.v0.2.2
69+
- name: testoperator.v0.3.0
70+
replaces: testoperator.v0.2.2
71+
name: candidate-v0
72+
package: testoperator
73+
schema: olm.channel
74+
---
75+
entries:
76+
- name: testoperator.v0.2.1
77+
- name: testoperator.v0.2.2
78+
skips:
79+
- testoperator.v0.2.1
80+
- name: testoperator.v0.3.0
81+
replaces: testoperator.v0.2.2
82+
name: fast-v0
83+
package: testoperator
84+
schema: olm.channel
85+
---
86+
entries:
87+
- name: testoperator.v0.2.2
88+
name: stable-v0
89+
package: testoperator
90+
schema: olm.channel
91+
```
92+
93+
#### Generating a channel graph
94+
To generate the upgrade graphs of each channel, run the following:
95+
96+
`opm alpha render-graph example_catalog/`
97+
98+
This will output a mermaid graph that looks like this when rendered into an image:
99+
100+
![Full Upgrade Graph](/content/en/docs/Reference/images/full-upgrade-graph.png)
101+
102+
#### Generating a scaled vector graphic (SVG)
103+
To generate a scaled vector graphic (SVG) directly from the output results of the `render-graph` command, use the following:
104+
105+
```
106+
opm alpha render-graph example_catalog | \
107+
docker run --rm -i -v "$PWD":/data ghcr.io/mermaid-js/mermaid-cli/mermaid-cli -o /data/example_catalog.svg
108+
```
109+
110+
#### Generating a channel graph for a single operator in a catalog
111+
Say we now have multiple operators in our example_catalog:
112+
```
113+
example_catalog/
114+
└── testoperator
115+
└── index.yaml
116+
└── anotheroperator
117+
└── index.yaml
118+
└── yetanotheroperator
119+
└── index.yaml
120+
```
121+
Running the `render-graph` command on the `example_catalog/` directory would now generate upgrade graphs for all of these operators. To limit the generated graph to only the testoperator, we would use the following:
122+
`opm alpha render-graph -p testoperator example_catalog/`
123+
124+
### Advanced Examples
125+
The following examples expand on advanced topics related to upgrade graphs that can be understood more easily via visualizations generated by the `render-graph` command.
126+
127+
#### Visualizing skipRanges
128+
Consistently using skipRanges allows for a given version to be upgraded to any other newer versions. A real-world example of this can be seen in the security-profiles-operator upgrade graph:
129+
130+
#TODO Show full graph of security-profiles-operator
131+
132+
#### Limiting the upgrade graph to a particular version context
133+
Say we are only interested in the upgrade graph after version v0.8.0. We can limit the upgrade graph to the v0.8.0+ context using the following:
134+
`opm alpha render-graph -p security-profiles-operator --minimum-edge security-profiles-operator.v0.8.0 quay.io/operatorhubio/catalog:latest`
135+
136+
#TODO Show limited graph of security-profiles-operator
137+
138+
#### Visualizing orphaned or stranded versions
139+
Orphaned or stranded versions are versions that are not the latest version and do not have an update path available.
140+
This can happen, for example, by not providing an upgrade version for a version and also via graph truncation.
141+
142+
A real-world scenario that can necessitate graph truncation would be to restrict installable operator version ranges.

0 commit comments

Comments
 (0)