Skip to content

Commit 44fe9b2

Browse files
skopacz1skopacz1
authored
Merge pull request #92710 from subhtk/osdocs13720
OSDOCS#13720: Added signature mirroring and verification section in oc-mirror plugin v2
2 parents e1c033d + 651fe74 commit 44fe9b2

5 files changed

+136
-0
lines changed

‎disconnected/mirroring/about-installing-oc-mirror-v2.adoc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,11 @@ include::modules/oc-mirror-proxy-support.adoc[leveloffset=+1]
117117
* xref:../../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service]
118118
* xref:../../disconnected/mirroring/about-installing-oc-mirror-v2.adoc#oc-mirror-v2-procedure-garbage-collector_about-installing-oc-mirror-v2[Resolving storage cleanup issues in the distribution registry]
119119

120+
//signature mirroring
121+
include::modules/oc-mirror-signature-mirroring.adoc[leveloffset=+1]
122+
include::modules/oc-mirror-signature-mirroring-procedure.adoc[leveloffset=+2]
123+
include::modules/oc-mirror-signature-verification.adoc[leveloffset=+2]
124+
120125
// Operator catalog filtering
121126
include::modules/oc-mirror-operator-catalog-filtering.adoc[leveloffset=+1]
122127

‎modules/oc-mirror-command-reference-v2.adoc

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,4 +98,16 @@ The following tables describe the `oc mirror` subcommands and flags for oc-mirro
9898
|`--rootless-storage-path <string>`
9999
|Overrides the default container rootless storage path (usually in `etc/containers/storage.conf`).
100100

101+
|`--remove-signatures`
102+
|Does not copy signatures from the source image.
103+
104+
|`--registries.d`
105+
|Specifies the directory that contains registry configuration files.
106+
107+
|`--secure-policy=true`
108+
|Enables signature verification for all images.
109+
110+
|`--policy`
111+
|Specifies the path to the signature verification policy file.
112+
101113
|===

‎modules/oc-mirror-signature-mirroring-procedure.adoc

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="oc-mirror-signature-mirroring-procedure_{context}"]
7+
= Enabling signature mirroring for oc-mirror plugin v2
8+
9+
By default, signature mirroring is disabled. You can enable signature mirroring for all images by setting the `--remove-signatures=false` flag for the `oc mirror` command.
10+
11+
When enabled, the oc-mirror plugin v2 mirrors `Sigstore` tag-based signatures for the following images:
12+
13+
* {product-title} release images
14+
* Operator images
15+
* Additional images
16+
* Helm charts
17+
18+
[NOTE]
19+
====
20+
If you do not provide a configuration file, the oc-mirror plugin v2 enables signature mirroring for all images by default when the `--remove-signatures=false` flag is used.
21+
22+
To specify a custom configuration directory, use the `--registries.d` flag.
23+
24+
For more details, see the link:https://github.com/containers/image/blob/main/docs/containers-registries.d.5.md[`containers-registries.d(5)`] manual.
25+
====
26+
27+
.Procedure
28+
29+
. If you want to enable signature mirroring for all images, run the following command:
30+
+
31+
[source,terminal]
32+
----
33+
$ oc mirror --remove-signatures=false
34+
----
35+
36+
. If you want to enable or disable signature mirroring for specific elements, such as transport protocol, registry, namespace or image, use the following steps:
37+
38+
.. Create a YAML file in either the `$HOME/.config/containers/registries.d/` or `/etc/containers/registries.d/` directory.
39+
40+
.. Specify the `use-sigstore-attachments` parameter and set it to either `true` or `false` under the specific element you want to control, as seen in the following examples:
41+
+
42+
.Example: Disable signature mirroring for the `quay.io` registry
43+
[source,yaml]
44+
----
45+
# ...
46+
docker:
47+
quay.io:
48+
use-sigstore-attachments: false
49+
# ...
50+
----
51+
+
52+
.Example: Enable signature mirroring for all registries
53+
[source,yaml]
54+
----
55+
# ...
56+
default-docker:
57+
use-sigstore-attachments: true
58+
# ...
59+
----

‎modules/oc-mirror-signature-mirroring.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="oc-mirror-signature-mirroring_{context}"]
7+
= Mirroring and verifying image signatures in oc-mirror plugin v2
8+
9+
Starting with {product-title} 4.19, the oc-mirror plugin v2 supports mirroring and verifying cosign tag-based signatures for container images.

‎modules/oc-mirror-signature-verification.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="oc-mirror-about-sig-mirroring-verification_{context}"]
7+
= Enabling signature verification for oc-mirror plugin v2
8+
9+
Starting with {product-title} 4.19, the oc-mirror plugin v2 supports signature verification, which is disabled by default. When enabled, the plugin verifies that container images match their signatures, ensuring they have not been altered and come from trusted sources. If a signature mismatch is detected, the mirroring workflow will fail.
10+
11+
.Procedure
12+
13+
. If you want to enable signature verification for all images, run the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc mirror --secure-policy=true
18+
----
19+
20+
. If you want to enable or disable signature verification for specific elements — such as a transport protocol, registry, namespace, or image — follow these steps:
21+
22+
.. Create a `policy.json` file in either the `$HOME/.config/containers/` or `/etc/containers/` directory.
23+
+
24+
[NOTE]
25+
====
26+
If your policy configuration file is located outside the default directory, you can specify its path by using the `--policy` flag with the `oc mirror` command.
27+
28+
For more information, see link:https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md[`containers-policy.json(5)`].
29+
====
30+
31+
.. Define verification rules for the desired scope (for example, registry or image) using the appropriate policy configuration. You can set the verification requirement by specifying the desired rule under each element.
32+
+
33+
.Example: Enable verification for only a specific image, and reject all other images
34+
+
35+
[source,json]
36+
----
37+
{
38+
"default": [{"type": "reject"}],
39+
"transports": {
40+
"docker": {
41+
"hostname:5000/myns/sigstore-signed-image": [
42+
{
43+
"type": "sigstoreSigned",
44+
"keyPath": "/path/to/sigstore-pubkey.pub",
45+
"signedIdentity": {"type": "matchRepository"}
46+
}
47+
]
48+
}
49+
}
50+
}
51+
----

0 commit comments

Comments
 (0)