Our docs say: In OpenShift Container Platform 4.1, you must not customize the ClusterVersion resource for production clusters. Instead, follow the process to update a cluster. but the api docs itself just say: spec <Object> -required- spec is the desired state of the cluster version - the operator will work to ensure that the desired version is applied to the cluster. Which can lead to admins trying to edit this themselves and getting in trouble. The api docs should make it clear this should not be edited by hand.
The spec is editable by human, cli, automatic upgrade controller (_when that exists_). So I don't think there is value in specifying that the spec "should not be edited by hand".
how about "should not be edited directly"? I assume the idea here is that we don't want people putting in values that point to untested upgrade paths. Alternatively if the docs are totally off-base (ie it is fine for someone to oc edit clusterversion and we are endorsing doing so), please submit a PR to change the docs and use that to close this bug.
> In OpenShift Container Platform 4.1, you must not customize the ClusterVersion resource for production clusters. Instead, follow the process to update a cluster. where in docs is that recommendation? Can you provide the link. And the api docs don't need to match with best-practices, personally that doesn't seem like the best co-relation...
> where in docs is that recommendation? Can you provide the link. https://docs.openshift.com/container-platform/4.1/installing/install_config/customizations.html#configuration-resources_customizations though I do have a pull open that's affecting that file, so if you have new wording you can tell me here and i will update my PR to include it. https://github.com/openshift/openshift-docs/pull/15806 > And the api docs don't need to match with best-practices, personally that doesn't seem like the best co-relation... Not necessarily, but the api docs should steer users away from actions that could allow them to brick their cluster.
Abhinav, what additional info do you need from me? Comment 4 was my attempt to address your previous info request. (My docs PR has since merged, but of course those changes aren't reflected in the 4.1 docs, only in master)
https://github.com/openshift/openshift-docs/pull/15905 merged the changes to master. should end up in 4.2 docs.
Not sure why you assigned this back to me?
(The bug is/was that the clusterversion api doc doesn't make it clear the field should not be directly edited by a user. The product doc is ok. Has the api doc been updated?)
i don't think this is resolved and i don't want to lose track of it until we resolve the api doc discussion. reopening and reassigning.
> The bug is/was that the clusterversion api doc doesn't make it clear the field should not be directly edited by a user. And I think I was pretty clear that the API doc correctly mentions that the fields can be changed. Endorsements of safety based on who edits that field should not be part of the API doc.
I don't think you were, since you did not address my statement of: the api docs should steer users away from actions that could allow them to brick their cluster. And we have made these changes to other apis. We are directing users to use "oc explain" to understand how to manage their cluster. If oc explain does not make it clear how they can/cannot use those fields, then that is a problem. Just stating that the fact that a field can be changed is not sufficient documentation of how that field should be used, when changing that field can break your cluster or put it in an unsupported state.
We have already made it pretty clear that setting this value to anything other than the ones in the Available updates might cause the upgrade to fail https://github.com/openshift/api/blob/b5570061b31fed3b06c24077c534b1a1bf7ecf8b/config/v1/types_cluster_version.go#L40-L43 We already do not upgrade to a release-image that's not trusted. https://github.com/openshift/api/blob/b5570061b31fed3b06c24077c534b1a1bf7ecf8b/config/v1/types_cluster_version.go#L209-L218 Therefore, there are enough checks to make sure that the field to editable by all, and would require user consent to brick their cluster.