OSDOCS#8714: OSUS 5.0.3 release image signature changes #74995
Conversation
openshift-ci-robot
added
the
jira/valid-reference
|
@skopacz1: This pull request references OSDOCS-8714 which is a valid jira issue. Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.16.0" version, but no target version was set. 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 openshift-eng/jira-lifecycle-plugin repository. |
| = Configuring the Cluster Version Operator (CVO) to retrieve release image signatures | ||
|
|
||
| If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can configure the Cluster Version Operator (CVO) to retrieve release image signatures from an endpoint on the local OSUS Operator. | ||
| This configuration is done by adding the URI of OSUS Operator's signature serving endpoint to the CVO's list of signature stores. |
There was a problem hiding this comment.
I added this line based on the draft doc, but let me know if this is too much technical detail for the end user.
There was a problem hiding this comment.
I think this line is helpful, but it might be long in the same paragraph as the This is a one-time configuration... qualifier?
There was a problem hiding this comment.
That sounds good, I can move it to the other paragraph for now.
openshift-ci
bot
added
the
size/M
| [NOTE] | ||
| ==== | ||
| The oc-mirror OpenShift CLI (`oc`) plugin creates this graph data container image in addition to mirroring release images. If you used the oc-mirror plugin to mirror your release images, you can skip this procedure. | ||
| ==== |
There was a problem hiding this comment.
I basically shifted this note about graph data images being unnecessary with oc-mirror higher up to the top of the section.
But if anyone thinks this entire module should be deleted so that our "updating with OSUS" page only documents the oc-mirror + OSUS workflow, let me know.
|
|
||
| * The Cluster Version Operator (CVO) is configured to use your locally-installed OpenShift Update Service application. | ||
| * The release image signature config map for the new release is applied to your cluster. | ||
| * Your cluster is able to retrieve release image signatures for the update target release images. |
There was a problem hiding this comment.
Rather than adding an additional statement about how oc mirror 4.15+ and OSUS 5.0.3+ makes this step unnecessary, I just broadened this condition to state that "the cluster can access signatures somehow".
If it's worth specifying the two different ways that can happen depending on your workflow, I can add that in level two bullets underneath this one.
|
@skopacz1: This pull request references OSDOCS-8714 which is a valid jira issue. Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.16.0" version, but no target version was set. 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 openshift-eng/jira-lifecycle-plugin repository. |
skopacz1
changed the title
openshift-ci-robot
removed
the
jira/valid-reference
|
@skopacz1: No Jira issue is referenced in the title of this pull request. 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 openshift-eng/jira-lifecycle-plugin repository. |
| If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can configure the Cluster Version Operator (CVO) to retrieve release image signatures from an endpoint on the local OSUS Operator. | ||
| This configuration is done by adding the URI of OSUS Operator's signature serving endpoint to the CVO's list of signature stores. | ||
|
|
||
| This is a one-time configuration that prevents the need to apply release image signatures each time you mirror a new set of release images. |
There was a problem hiding this comment.
Maybe "prevents" -> "avoids"? Not entirely sure why I feel that way; maybe I expect "prevents" for bad things and "avoids" for annoying things, and per-update signature application is annoying, but not bad? Feel free to ignore if this makes no sense :)
There was a problem hiding this comment.
I'm not super opinionated so "avoids" would be fine by me! The logic makes sense to me, personally
| ---- | ||
| $ oc patch clusterversion version --type=merge -p '{"spec":{"signatureStores":[{"url": "<signature_serving_url>"}]}}' | ||
| ---- | ||
| // Is the URL from the OSUS Operator going to be obvious to the user/easy for them to find? Or should we either give some hint or an example somewhere in this procedure? |
There was a problem hiding this comment.
There's a new MetadataURI property in UpdateService status, which the user setting up ClusterVersion can use right around when they use PolicyEngineURI to populate their ClusterVersion spec.upstream.
There was a problem hiding this comment.
Is there a command we can offer to users to retrieve the URL from this property, or should we just mention the property in a note and leave it at that? The note could be worded like the following:
| // Is the URL from the OSUS Operator going to be obvious to the user/easy for them to find? Or should we either give some hint or an example somewhere in this procedure? | |
| + | |
| [NOTE] | |
| ==== | |
| You can find the signature serving URL of the OSUS Operator by searching for the `MetadataURI` property of `UpdateServiceStatus`. | |
| ==== |
Or whatever the technically accurate wording would be.
There was a problem hiding this comment.
or we can have something like this
while sleep 1; do SIGNATURES_URI=“$(oc -n “${NAMESPACE}” get -o jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures/{“\n”}’ updateservice “${NAME}“)”; SCHEME=“${SIGNATURES_URI%%:*}“; if test “${SCHEME}” = http -o “${SCHEME}” = https; then break; fi; doneThere was a problem hiding this comment.
@PratikMahajan does that command print out the URI, or does it set the URI to SIGNATURES_URI which you'd then use in place of <signature_serving_url> in the actual command, like this?
$ oc patch clusterversion version --type=merge -p '{"spec":{"signatureStores":[{"url": "${SIGNATURES_URI}"}]}}'
If it's just a way to print it out then this could stay in the note, but if it sets a value then maybe that should be step one of this procedure
|
/cc |
| If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can configure the Cluster Version Operator (CVO) to retrieve release image signatures from an endpoint on the local OSUS Operator. | ||
|
|
||
| This configuration is done by adding the URI of OSUS Operator's signature serving endpoint to the CVO's list of signature stores through the `signatureStores` property. |
There was a problem hiding this comment.
OSUS and OSUS Operator are two distinct (although connected) things, and we describe OSUS capabilities as OSUS Operator ones here. OSUS has a signature serving endpoint, not the operator.
OSUS is the server that serves update data to clusters. It has endpoints that provide update graph and now the signatures, too.
OSUS Operator is a separate piece of software that makes installing and operating OSUS instances easier (software managing other software is called "operator pattern").
There was a problem hiding this comment.
Will rephrase the two instances of OSUS Operator to just OSUS, thanks
|
|
||
| .Prerequisites | ||
|
|
||
| * You have installed the OSUS Operator 5.0.3 or later. |
There was a problem hiding this comment.
I'd rephrase this as "You have deployed OSUS using OSUS Operator 5.0.3"
| ==== | ||
| If you are mirroring Operators instead of clusters, you do not need to run `$ oc apply -f ./oc-mirror-workspace/results-1639608409/release-signatures/`. Running that command will return an error, as there are no release image signatures to apply. | ||
| * If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can skip this step. | ||
| However, the Cluster Version Operator must be configured to retrieve release image signatures from the OSUS Operator. |
| [id="configure-cvo-retrieve-image-signatures_{context}"] | ||
| = Configuring the Cluster Version Operator (CVO) to retrieve release image signatures | ||
|
|
||
| If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can configure the Cluster Version Operator (CVO) to retrieve release image signatures from an endpoint on the local OpenShift Update Service (OSUS). |
There was a problem hiding this comment.
from an endpoint on the local OpenShift Update Service (OSUS).
I'm not sure about the "local". Our recommended topology is to have a single OSUS deployed somewhere (on one OCP cluster) and and let more (many!) OCP clusters consume its services. In technical context I'd read "local" as "running in the same cluster" which is not necessary and I'm worried that it reinforces the anti-pattern that you should run one OSUS inside every cluster.
I guess "local" can also mean "local to your organization; not RH-operated" but I'd still avoid call that "local" because of the possible confusion.
There was a problem hiding this comment.
If you look at the rest of the page that this content is being added to and search for "local", you'll find many instances where we use this "local OSUS" wording.
I don't disagree with implementing this change generally and in this PR, but I think that if we do try to shy away from this wording, we'd want to make a broader sweep throughout this page to make the change effective.
Would it also be better to find another word to convey "not the OSUS hosted by RH"? I guess without it, the context of the page is probably enough to inform users, but maybe clarity wherever possible might be a safer bet.
What about this wording?
| If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can configure the Cluster Version Operator (CVO) to retrieve release image signatures from an endpoint on the local OpenShift Update Service (OSUS). | |
| If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can configure the Cluster Version Operator (CVO) to retrieve release image signatures from an endpoint on the OpenShift Update Service (OSUS) in your environment. |
There was a problem hiding this comment.
Good point about consistency with other instances. I haven't searched but I agree that if we use it in more places then fixing it in a separate, broad PR is preferable over changing a single instance in this PR 👍
"in your environment" sounds good to me
There was a problem hiding this comment.
Sounds good! I guess I'll keep "local" in this PR and then I can create another Jira issue to cover the broader change. That'll also give us all more time to discuss possible wording options in addition to "in your environment"
There was a problem hiding this comment.
Since I'm starting the work to update the "local" wording before this PR is finished, I'll go ahead and update this one instance here.
|
@JianLi-RH could you PTAL when you have a chance? Thanks! |
|
New changes are detected. LGTM label has been removed. |
|
|
||
| If you are using the oc-mirror plugin 4.15 or later and the OSUS Operator 5.0.3 or later to update your cluster in a disconnected environment, you can configure the Cluster Version Operator (CVO) to retrieve release image signatures from an endpoint on the OpenShift Update Service (OSUS) in your environment. | ||
|
|
||
| This configuration is done by adding the URI of OSUS' signature serving endpoint to the CVO's list of signature stores through the `signatureStores` property. |
There was a problem hiding this comment.
To avoid passive voice, can we reword this sentence to something like:
You can adding the URI of OSUS' signature serving endpoint to the CVO's list of signature stores through the signatureStores property to finish the configuration.
There was a problem hiding this comment.
Sure, I'm changing this line to:
You can configure this by adding the URI of OSUS' signature serving endpoint to the CVO's list of signature stores through the signatureStores property.
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ while sleep 1; do SIGNATURES_URI=“$(oc -n “${NAMESPACE}” get -o jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures/{“\n”}’ updateservice “${NAME}“)”; SCHEME=“${SIGNATURES_URI%%:*}“; if test “${SCHEME}” = http -o “${SCHEME}” = https; then break; fi; done |
There was a problem hiding this comment.
It seems “ should be ", ‘ should be '?
There was a problem hiding this comment.
I ran below command on my cluster which has OSUS and updateservice installed, but stucked:
[jianl@localhost 415]$ NAME=sample
[jianl@localhost 415]$ NAMESPACE=openshift-update-service
[jianl@localhost 415]$ while sleep 1; do SIGNATURES_URI="$(oc -n "${NAMESPACE}" get -o jsonpath='{.status.metadataURI}/api/upgrades_info/signatures/{"\n"}' updateservice "${NAME}")"; SCHEME="${SIGNATURES_URI%%:*}"; if test "${SCHEME}" = http -o "${SCHEME}" = https; then break; fi; done
There was a problem hiding this comment.
@JianLi-RH I can fix the quotation marks, sure.
When you ran the command, did you directly copy and paste from this line, or did you change the quotation marks yourself before running the command?
There was a problem hiding this comment.
I copy the command line from UI to notebook, then update quotations, then run it.
Copy it to terminal doesn't work.
There was a problem hiding this comment.
jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures/{“\n”}’
jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures{“\n”}’
There was a problem hiding this comment.
@JianLi-RH understood, thanks for explaining.
@jiajliu I'll remove the / from that part of the path, thanks.
| $ while sleep 1; do SIGNATURES_URI=“$(oc -n “${NAMESPACE}” get -o jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures/{“\n”}’ updateservice “${NAME}“)”; SCHEME=“${SIGNATURES_URI%%:*}“; if test “${SCHEME}” = http -o “${SCHEME}” = https; then break; fi; done | ||
| ---- | ||
| . Patch the cluster version resource by running the following command: |
There was a problem hiding this comment.
Because above command stuck, I can't run the patch command.
But I can get SIGNATURES_URI by running below command:
[jianl@localhost 415]$ SIGNATURES_URI="$(oc -n "${NAMESPACE}" get -o jsonpath='{.status.metadataURI}/api/upgrades_info/signatures/{"\n"}' updateservice "${NAME}")"
[jianl@localhost 415]$ echo $SIGNATURES_URI
/api/upgrades_info/signatures/
[jianl@localhost 415]$
| However, the Cluster Version Operator must be configured to retrieve release image signatures from the OpenShift Update Service (OSUS). | ||
| For more information, see "Configuring the Cluster Version Operator (CVO) to retrieve release image signatures" in the "Additional resources" section. | ||
| * If you are mirroring Operators instead of clusters, you can skip this step. Running the previous command will return an error, as there are no release image signatures to apply. |
There was a problem hiding this comment.
If you are mirroring Operators instead of clusters maybe made confusing, I think If you are mirroring Operators instead of release images or If you are mirroring Operators instead of payload images will be better, thought?
There was a problem hiding this comment.
Good catch, thanks! I think that was probably meant to say "cluster Operators" or something similar to your suggestions.
I can change it to say "release images" since that seems to make the most sense here.
| [NOTE] | ||
| ==== | ||
| The release image signature config map allows the Cluster Version Operator (CVO) to ensure the integrity of release images by verifying that the actual image signatures match the expected signatures. | ||
| Release image signatures allow the Cluster Version Operator (CVO) to ensure the integrity of release images by verifying that the actual image signatures match the expected signatures. |
There was a problem hiding this comment.
It's hard for me to understand this text :( Any one have any idea to make it easy to understand? cc @jiajliu @shellyyang1989
There was a problem hiding this comment.
I can rephrase this sentence if it's hard to understand. I think it's explaining how the CVO uses release image signatures to verify that the release images you are trying to apply during an update match the images that Red Hat serves (and thus haven't been modified by someone else).
Maybe the note could be rephrased to this:
| Release image signatures allow the Cluster Version Operator (CVO) to ensure the integrity of release images by verifying that the actual image signatures match the expected signatures. | |
| The Cluster Version Operator (CVO) uses release image signatures to ensure that release images have not been modified, by verifying that the release image signatures match the expected result. |
Let me know if that rephrasing would make more sense to you.
There was a problem hiding this comment.
Cool! Right now it is very clear for me. Thank you @skopacz1
| .Prerequisites | ||
|
|
||
| * You have deployed OSUS using the OSUS Operator 5.0.3 or later. | ||
| * You are using the oc mirror plugin 4.15 or later to mirror release images. |
There was a problem hiding this comment.
suggest to add and setting 'graph:true' in the image set configuration. behind using the oc mirror plugin 4.15 or later
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ while sleep 1; do SIGNATURES_URI=“$(oc -n “${NAMESPACE}” get -o jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures/{“\n”}’ updateservice “${NAME}“)”; SCHEME=“${SIGNATURES_URI%%:*}“; if test “${SCHEME}” = http -o “${SCHEME}” = https; then break; fi; done |
There was a problem hiding this comment.
jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures/{“\n”}’
jsonpath=‘{.status.metadataURI}/api/upgrades_info/signatures{“\n”}’
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc patch clusterversion version --type=merge -p '{"spec":{"signatureStores":[{"url": "${SIGNATURES_URI}"}]}}' |
There was a problem hiding this comment.
s/"${SIGNATURES_URI}"/"'${SIGNATURES_URI}'"
# ./oc patch clusterversion version --type=merge -p '{"spec":{"signatureStores":[{"url": "${SIGNATURES_URI}"}]}}'
The ClusterVersion "version" is invalid: spec.signatureStores[0].url: Invalid value: "string": url must be a valid absolute URL
# ./oc patch clusterversion version --type=merge -p '{"spec":{"signatureStores":[{"url": "'${SIGNATURES_URI}'"}]}}'
clusterversion.config.openshift.io/version patched
| Before updating your cluster, confirm that the following conditions are met: | ||
|
|
||
| * The Cluster Version Operator (CVO) is configured to use your locally-installed OpenShift Update Service application. | ||
| * The release image signature config map for the new release is applied to your cluster. |
There was a problem hiding this comment.
original signature config map is still support, so i think we should not remove it, right? so suggest to add or the cluster is able to retrieve release image signatures for the update target release images from osus
There was a problem hiding this comment.
I can keep the old statement while including the new option in the same sentence, thanks
skopacz1
force-pushed
the
OSDOCS-8174
branch
2 times, most recently
from
3f22e3d to
09bb07e
Compare
|
@JianLi-RH and @jiajliu thank you both for your feedback! Could you please take a look when you have a chance and see if I've addressed everything correctly? Thanks. |
| [source,terminal] | ||
| ---- | ||
| $ oc patch clusterversion version --type=merge -p '{"spec":{"signatureStores":[{"url": "'${SIGNATURES_URI}'"}]}}' | ||
| ---- |
There was a problem hiding this comment.
Because the signaturestore provided by osus is behind self-signed ingress CA, if the ca is not enabled in cluster-wide proxy, CVO provides a config through above api to setting it explicitly. Following is an example steps to add the ca cm.
# ./oc -n openshift-config create configmap valid-ca --from-file=ca.crt
configmap/valid-ca created
# ./oc patch clusterversion version --type merge -p '{"spec": {"signatureStores": [{"url": "https://update-service-oc-mirror-meta-route-openshift-update-service.apps.jliu416d.qe.gcp.devcluster.openshift.com/api/upgrades_info/signatures","ca": {"name": "valid-ca"}}]}}'
clusterversion.config.openshift.io/version patched
I'd suggest to add the note here as a plus configure step.
There was a problem hiding this comment.
new update about the ca support of signaturestore:
the pr for https://issues.redhat.com/browse/OCPBUGS-24700 has been reverted due to regression hours ago, i guess the ca part which implemented in the bug will miss the scope of 4.16 GA, so maybe we could ignore above comment to mention the set of ca.
cc @wking @PratikMahajan
There was a problem hiding this comment.
Is the rest of the content in this section still at risk of not making it to 4.16? I can still proceed with QE review and peer review just in case, but I'm curious if there are any updates on the state of the features this PR is documenting
|
@skopacz1: all tests passed! Full PR test history. Your PR dashboard. 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-sigs/prow repository. I understand the commands that are listed here. |
|
Closing this PR as it seems that the signature store feature, which makes up the core of what this PR is documenting, will likely not make it to 4.16. If it turns out that the feature will still be implemented for 4.16, I'll reopen this PR. |
8 participants
OSDOCS-8174
Version(s): 4.16+
This PR adds changes enabled/introduced with the release of the OSUS Operator 5.0.3. The changes include the ability to configure the CVO to retrieve release image signatures from an OSUS endpoint, preventing the need to manually apply the signatures with each new release image payload a user mirrors.
QE review:
Previews: