Skip to content

Commit 4d4d4b4

Browse files
petr-mullerpetr-muller
committed
Modernize README.md to contain user-facing information
But there are way more CVO consumers than there are CVO devs. We should aim the README at "what does the CVO do for my clusters?"``
1 parent e6aeb8d commit 4d4d4b4

File tree

1 file changed

+99
-45
lines changed

1 file changed

+99
-45
lines changed

‎README.md

+99-45
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,124 @@
1-
# Cluster Version Operator (CVO)
1+
# Cluster Version Operator
22

3-
## Building and Publishing CVO
3+
The Cluster Version Operator (CVO) is one of the [Cluster Operators][dev-guide-operators] that run in every OpenShift
4+
cluster. CVO consumes an artifact called a _"release payload image,"_ which represents a specific version of OpenShift.
5+
The release payload image contains the [resource manifests][kube-glossary-manifest] necessary for the cluster to
6+
function, like all Cluster Operator ones. CVO reconciles the resources within the cluster to match the manifests in the
7+
release payload image. As a result, CVO implements _cluster upgrades_. After being provided a release payload image for
8+
a newer OpenShift version, CVO reconciles all Cluster Operators to their updated versions, and Cluster Operators
9+
similarly update their operands.
410

5-
```sh
6-
./hack/build-image.sh && REPO=<your personal repo (quay.io/ahbinavdahiya | docker.io/abhinavdahiya)> ./hack/push-image.sh
7-
```
11+
## OpenShift Upgrades
12+
13+
For information about upgrading OpenShift clusters, please see the respective documentation:
14+
15+
- [OKD Documentation: Updating clusters][okd-updating-clusters]
16+
- [Red Hat OpenShift Container Platform: Updating clusters][ocp-updating-clusters]
817

9-
1. This builds image locally and then pushes `${VERSION}` and `latest` tags to `${REPO}/origin-cluster-version-operator`.
18+
## `ClusterVersion` Resource
1019

11-
2. `${VERSION}` encodes the Git commit used to build the images.
20+
Like other Cluster Operators, the Cluster Version Operator is configured by a Config API resource in the cluster:
21+
a [`ClusterVersion`][ocp-clusterversion]:
1222

13-
## Building release image using local CVO
23+
```console
24+
$ oc explain clusterversion
25+
KIND: ClusterVersion
26+
VERSION: config.openshift.io/v1
1427

15-
1. Make sure you have `oc` binary from https://github.com/openshift/origin master as it requires `adm release` subcommand.
28+
DESCRIPTION:
29+
ClusterVersion is the configuration for the ClusterVersionOperator. This is
30+
where parameters related to automatic updates can be set. Compatibility
31+
level 1: Stable within a major release for a minimum of 12 months or 3
32+
minor releases (whichever is longer).
1633

17-
2. Run the following command to create release-image at `docker.io/abhinavdahiya/origin-release:latest`:
34+
FIELDS:
35+
...
36+
spec <Object> -required-
37+
spec is the desired state of the cluster version - the operator will work
38+
to ensure that the desired version is applied to the cluster.
1839

19-
```sh
20-
oc adm release new -n origin \
21-
--from-image-stream=origin-v4.0 \
22-
--to-image-base=docker.io/abhinavdahiya/origin-cluster-version-operator:latest \
23-
--to-image docker.io/abhinavdahiya/origin-release:latest
40+
status <Object>
41+
status contains information about the available updates and any in-progress
42+
updates.
2443
```
2544

26-
## Installing CVO and operators in cluster.
45+
`ClusterVersion` resource follows the established [Kubernetes pattern][kube-spec-and-status] where the `spec`
46+
property describes the desired state that CVO should achieve and maintain, and the `status` property is populated by the
47+
CVO to describe its status and the observed state.
2748

28-
1. Use CVO `render` to render all the manifests from release-payload to a directory. Refer the [Using CVO to render the release-image locally](#using-cvo-to-render-the-release-image-locally) section for more information.
49+
In a typical OpenShift cluster, there will be a cluster-scoped `ClusterVersion` resource called `version`:
2950

30-
2. Create the operators from the manifests by using `oc create -f <directory when CVO rendered manifests>`.
51+
```console
52+
$ oc get clusterversion version
53+
NAME VERSION AVAILABLE PROGRESSING SINCE STATUS
54+
version 4.11.17 True False 6d5h Cluster version is 4.11.17
55+
```
3156

32-
## Using CVO to render the release-image locally
57+
Note that as a user or a cluster administrator, you usually do not interact with the `ClusterVersion` resource directly
58+
but via either the [`oc adm upgrade`][ocp-oc-adm-upgrade] CLI or the [web console][ocp-webconsole-upgrades].
3359

34-
1. Run the following command to get render the release-payload contents to `/tmp/cvo`
60+
## Understanding Upgrades
3561

36-
```sh
37-
podman run --rm -ti \
38-
-v /tmp/cvo:/tmp/cvo:z \
39-
<release image> \
40-
render \
41-
--output-dir=/tmp/cvo \
42-
--release-image="<release image>"
43-
```
62+
> :bulb: This section is only a high-level overview. See the [Update Process][dev-guide-upgrade-workflow] and
63+
> [Reconciliation][dev-guide-reconciliation] documents in the [dev-guide][dev-guide] for more details.
4464
45-
`<release image>` can be personal release image generated using [this](#building-release-image-using-local-cvo) or Origin's release image like `registry.ci.openshift.org/openshift/origin-release:v4.0`.
65+
The Cluster Version Operator continuously fetches information about upgrade paths for the configured channel from the
66+
OpenShift Update Service (OSUS). It stores the recommended update options in the `status.availableUpdates` field of
67+
its `ClusterVersion` resource.
4668

47-
## Running CVO tests
69+
The intent to upgrade the cluster to another version is expressed by storing the desired version in
70+
the `spec.desiredUpdate` field. When `spec.desiredUpdate` does not match the current cluster version, CVO will start
71+
updating the cluster. It downloads the release payload image, validates it,
72+
and [systematically reconciles][dev-guide-reconciliation] the Cluster Operator resources to match the updated manifests
73+
delivered in the release payload image.
4874

49-
```sh
50-
# Run all unit tests
51-
go test ./...
75+
## Troubleshooting
5276

53-
# Run integration tests against a cluster (creates content in a given namespace)
54-
# Requires the CVO CRD to be installed.
55-
export KUBECONFIG=<admin kubeconfig>
56-
TEST_INTEGRATION=1 go test ./... -test.run=^TestIntegration
77+
A typical OpenShift cluster will have a `Deployment` resource called `cluster-version-operator` in
78+
the `openshift-cluster-version` namespace, configured to run a single CVO replica. Confirm that its `Pod` is up and
79+
optionally inspect its log:
80+
81+
```console
82+
$ oc get deployment -n openshift-cluster-version cluster-version-operator
83+
NAME READY UP-TO-DATE AVAILABLE AGE
84+
cluster-version-operator 1/1 1 1 2y227d
85+
86+
$ oc get pods -n openshift-cluster-version -l k8s-app=cluster-version-operator
87+
NAME READY STATUS RESTARTS AGE
88+
cluster-version-operator-6885cc574-674n6 1/1 Running 0 6d5h
89+
90+
$ oc logs -n openshift-cluster-version -l k8s-app=cluster-version-operator
91+
...
5792
```
5893

59-
## Contributing
94+
The CVO follows the [Kubernetes API conventions][kube-api-conventions-status] and sets `Conditions` in the status of
95+
its `ClusterVersion` resource. These conditions are surfaced by both the OpenShift web console and the `oc adm upgrade`
96+
CLI.
97+
98+
## Development
99+
100+
Contributions welcome! Please follow [CONTRIBUTING.md](CONTRIBUTING.md) and [developer documentation](./docs/dev).
101+
102+
[dev-guide]: https://github.com/openshift/enhancements/blob/master/dev-guide
103+
104+
[dev-guide-operators]: https://github.com/openshift/enhancements/blob/master/dev-guide/operators.md#what-is-an-openshift-clusteroperator
105+
106+
[dev-guide-reconciliation]: https://github.com/openshift/enhancements/blob/master/dev-guide/cluster-version-operator/user/reconciliation.md
107+
108+
[dev-guide-upgrade-workflow]: https://github.com/openshift/enhancements/blob/master/dev-guide/cluster-version-operator/user/update-workflow.md
109+
110+
[kube-api-conventions-status]: https://github.com/kubernetes/community/blob/4c9ef2d135294355e7ca33ec7a5e01d31438df12/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
111+
112+
[kube-spec-and-status]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#object-spec-and-status
113+
114+
[kube-glossary-manifest]: https://kubernetes.io/docs/reference/glossary/?all=true#term-manifest
115+
116+
[okd-updating-clusters]: https://docs.okd.io/latest/updating/index.html
60117

61-
[Contributions welcome](CONTRIBUTING.md)!
118+
[ocp-updating-clusters]: https://docs.openshift.com/container-platform/latest/updating/index.html
62119

63-
## Documentation
120+
[ocp-clusterversion]: https://docs.openshift.com/container-platform/latest/rest_api/config_apis/clusterversion-config-openshift-io-v1.html
64121

65-
The documentation around CVO is split between two code repositories i.e. [enhancements/dev-guide/cluster-version-operator](https://github.com/openshift/enhancements/tree/master/dev-guide/cluster-version-operator) and [cluster-version-operator/docs](./docs).
122+
[ocp-oc-adm-upgrade]: https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/administrator-cli-commands.html#oc-adm-upgrade
66123

67-
Here are some pointers to start with the documentation
68-
- [Update workflow](https://github.com/openshift/enhancements/blob/master/dev-guide/cluster-version-operator/user/update-workflow.md)
69-
- [Reconcilation logic](https://github.com/openshift/enhancements/blob/master/dev-guide/cluster-version-operator/user/reconciliation.md)
70-
- [Runlevels](https://github.com/openshift/enhancements/blob/master/dev-guide/cluster-version-operator/dev/upgrades.md)
124+
[ocp-webconsole-upgrades]: https://docs.openshift.com/container-platform/latest/updating/updating-cluster-within-minor.html#update-upgrading-web_updating-cluster-within-minor

0 commit comments

Comments
 (0)