Skip to content

OSDOCS#8714: OSUS 5.0.3 release image signature changes #74995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

OSDOCS#8714: OSUS 5.0.3 release image signature changes #74995

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions installing/disconnected_install/installing-mirroring-disconnected.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,11 @@ include::modules/oc-mirror-disk-to-mirror.adoc[leveloffset=+3]
// Configuring your cluster to use the resources generated by oc-mirror
include::modules/oc-mirror-updating-cluster-manifests.adoc[leveloffset=+1]

[role="_additional-resources"]
.Additional resources

* xref:../../updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc#configure-cvo-retrieve-image-signatures_updating-restricted-network-cluster-osus[Configuring the Cluster Version Operator (CVO) to retrieve release image signatures]

// About updating your mirror registry content
include::modules/oc-mirror-updating-registry-about.adoc[leveloffset=+1]

Expand Down
36 changes: 36 additions & 0 deletions modules/configure-cvo-retrieve-image-signatures.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
// Module included in the following assemblies:
// * updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc

:_mod-docs-content-type: PROCEDURE
[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 OpenShift Update Service (OSUS) in your environment.

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.
This is a one-time configuration that avoids the need to apply release image signatures each time you mirror a new set of release images.

:FeatureName: The `signatureStores` property
include::snippets/technology-preview.adoc[]

.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, and have set `graph:true` in the image set configuration.
* You have enabled the `TechPreviewNoUpgrade` feature set in your cluster.
.Procedure

. Retrieve the signature serving URI of OSUS by running the following command:
+
[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
----
. Patch the cluster version resource by running the following command:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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]$

+
[source,terminal]
----
$ oc patch clusterversion version --type=merge -p '{"spec":{"signatureStores":[{"url": "'${SIGNATURES_URI}'"}]}}'
----
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

6 changes: 5 additions & 1 deletion modules/oc-mirror-updating-cluster-manifests.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,11 @@ $ oc apply -f ./oc-mirror-workspace/results-1639608409/release-signatures/
+
[NOTE]
====
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 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 release images, you can skip this step. Running the previous command will return an error, as there are no release image signatures to apply.
====

// TODO: Any example output to show?
Expand Down
2 changes: 1 addition & 1 deletion modules/update-service-configure-cvo.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
// * updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc

:_mod-docs-content-type: PROCEDURE
[id="update-service-configure-cvo"]
[id="update-service-configure-cvo_{context}"]
= Configuring the Cluster Version Operator (CVO)

After the OpenShift Update Service Operator has been installed and the OpenShift Update Service application has been created, the Cluster Version Operator (CVO) can be updated to pull graph data from the locally installed OpenShift Update Service.
Expand Down
4 changes: 2 additions & 2 deletions modules/update-service-graph-data.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
[id="update-service-graph-data_{context}"]
= Creating the OpenShift Update Service graph data container image

The OpenShift Update Service requires a graph data container image, from which the OpenShift Update Service retrieves information about channel membership and blocked update edges. Graph data is typically fetched directly from the update graph data repository. In environments where an internet connection is unavailable, loading this information from an init container is another way to make the graph data available to the OpenShift Update Service. The role of the init container is to provide a local copy of the graph data, and during pod initialization, the init container copies the data to a volume that is accessible by the service.

[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.
====
Comment on lines 8 to 11
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 OpenShift Update Service requires a graph data container image, from which the OpenShift Update Service retrieves information about channel membership and blocked update edges. Graph data is typically fetched directly from the update graph data repository. In environments where an internet connection is unavailable, loading this information from an init container is another way to make the graph data available to the OpenShift Update Service. The role of the init container is to provide a local copy of the graph data, and during pod initialization, the init container copies the data to a volume that is accessible by the service.

.Procedure

. Create a Dockerfile, for example, `./Dockerfile`, containing the following:
Expand Down
9 changes: 6 additions & 3 deletions .../updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,24 +114,27 @@ and must be no more than 63 characters`, try creating the Update Service with a
====

// Configuring the Cluster Version Operator (CVO)
include::modules/update-service-configure-cvo.adoc[leveloffset=+3]
include::modules/update-service-configure-cvo.adoc[leveloffset=+1]

[NOTE]
====
See xref:../../../networking/enable-cluster-wide-proxy.adoc#enable-cluster-wide-proxy[Configuring the cluster-wide proxy] to configure the CA to trust the update server.
====

// Configuring the Cluster Version Operator (CVO) to retrieve release image signatures
include::modules/configure-cvo-retrieve-image-signatures.adoc[leveloffset=+2]

[id="next-steps_updating-restricted-network-cluster-osus"]
== Next steps

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can keep the old statement while including the new option in the same sentence, thanks

* The release image signature config map for the new release is applied to your cluster, or the cluster is able to retrieve signatures for the target release images from OSUS.
+
[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.
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.
====
* The current release and update target release images are mirrored to a locally accessible registry.
* A recent graph data container image has been mirrored to your local registry.
Expand Down