Skip to content

Commit 6777eb8

Browse files
authored
Merge pull request #86087 from mburke5678/nodes-sigstore
OSDOCS-12627/OSDOCS-12728 Sigstore Support
2 parents 121d5ec + 0e9e636 commit 6777eb8

5 files changed

+596
-5
lines changed
Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * nodes/nodes-sigstore-using.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="nodes-sigstore-configure-cluster-policy_{context}"]
7+
= Creating a cluster image policy CR
8+
9+
A `ClusterImagePolicy` custom resource (CR) enables a cluster administrator to configure a sigstore signature verification policy for the entire cluster. When enabled, the Machine Config Operator (MCO) watches the `ClusterImagePolicy` object and updates the `/etc/containers/policy.json` and `/etc/containers/registries.d/sigstore-registries.yaml` files on all the nodes in the cluster.
10+
11+
The following example shows general guidelines on how to configure a `ClusterImagePolicy` object. For more details on the parameters, see "About cluster and image policy parameters."
12+
13+
.Prerequisites
14+
// Taken from https://issues.redhat.com/browse/OCPSTRAT-918
15+
* You have a sigstore-supported public key infrastructure (PKI) or a link:https://docs.sigstore.dev/cosign/[Cosign public and private key pair] for signing operations.
16+
* You have a signing process in place to sign your images.
17+
* You have access to a registry that supports Cosign signatures, if you are using Cosign signatures.
18+
* You enabled the required Technology Preview features for your cluster by editing the `FeatureGate` CR named `cluster`:
19+
+
20+
[source,terminal]
21+
----
22+
$ oc edit featuregate cluster
23+
----
24+
+
25+
.Example `FeatureGate` CR
26+
[source,yaml]
27+
----
28+
apiVersion: config.openshift.io/v1
29+
kind: FeatureGate
30+
metadata:
31+
name: cluster
32+
spec:
33+
featureSet: TechPreviewNoUpgrade <1>
34+
----
35+
<1> Enables the required `SigstoreImageVerification` feature.
36+
+
37+
[WARNING]
38+
====
39+
Enabling the `TechPreviewNoUpgrade` feature set on your cluster cannot be undone and prevents minor version updates. This feature set allows you to enable these Technology Preview features on test clusters, where you can fully test them. Do not enable this feature set on production clusters.
40+
====
41+
+
42+
After you save the changes, new machine configs are created, the machine config pools are updated, and scheduling on each node is disabled while the change is being applied.
43+
44+
.Procedure
45+
46+
. Create a cluster image policy object similar to the following examples. See "About image policy parameters" for specific details on these parameters.
47+
+
48+
--
49+
.Example cluster image policy object with a public key policy and the `MatchRepoDigestOrExact` match policy
50+
[source,yaml]
51+
----
52+
apiVersion: config.openshift.io/v1alpha1
53+
kind: ClusterImagePolicy <1>
54+
metadata:
55+
name: p1
56+
spec:
57+
scopes: <2>
58+
- example.com
59+
policy: <3>
60+
rootOfTrust: <4>
61+
policyType: PublicKey <5>
62+
publicKey:
63+
keyData: a2V5RGF0YQ== <6>
64+
rekorKeyData: cmVrb3JLZXlEYXRh <7>
65+
signedIdentity: <8>
66+
matchPolicy: MatchRepoDigestOrExact
67+
----
68+
<1> Creates a `ClusterImagePolicy` object.
69+
<2> Defines a list of repositories or images assigned to this policy. In a cluster image policy, make sure that the policy does not block the deployment of the {product-title} images in the `quay.io/openshift-release-dev/ocp-release` and `quay.io/openshift-release-dev/ocp-v4.0-art-dev` repositories. Images in these repositories are required for cluster operation.
70+
<3> Specifies the parameters that define how the images are verified.
71+
<4> Defines a root of trust for the policy.
72+
<5> Specifies the policy types that define the root of trust, either a public key or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certifice]. Here, a public key with Rekor verification.
73+
<6> For a public key policy, specifies a base64-encoded public key in the PEM format. The maximum length is 8192 characters.
74+
<7> Optional: Specifies a base64-encoded Rekor public key in the PEM format. The maximum length is 8192 characters.
75+
<8> Optional: Specifies one of the following processes to verify the identity in the signature and the actual image identity:
76+
* `MatchRepoDigestOrExact`.
77+
* `MatchRepository`.
78+
* `ExactRepository`. The `exactRepository` parameter must be specified.
79+
* `RemapIdentity`. The `prefix` and `signedPrefix` parameters must be specified.
80+
--
81+
+
82+
--
83+
.Example cluster image policy object with a Fulcio certificate policy and the `remapIdentity` match policy
84+
[source,yaml]
85+
----
86+
apiVersion: config.openshift.io/v1alpha1
87+
kind: ClusterImagePolicy <1>
88+
metadata:
89+
name: p1
90+
spec:
91+
scopes: <2>
92+
- example.com
93+
policy: <3>
94+
rootOfTrust: <4>
95+
policyType: FulcioCAWithRekor <5>
96+
fulcioCAWithRekor: <6>
97+
fulcioCAData: a2V5RGF0YQ==
98+
fulcioSubject:
99+
oidcIssuer: "https://expected.OIDC.issuer/"
100+
signedEmail: "expected-signing-user@example.com"
101+
rekorKeyData: cmVrb3JLZXlEYXRh <7>
102+
signedIdentity:
103+
matchPolicy: RemapIdentity <8>
104+
remapIdentity:
105+
prefix: example.com <9>
106+
signedPrefix: mirror-example.com <10>
107+
----
108+
<1> Creates a `ClusterImagePolicy` object.
109+
<2> Defines a list of repositories or images assigned to this policy. In a cluster image policy, make sure that the policy does not block the deployment of the {product-title} images in the `quay.io/openshift-release-dev/ocp-release` and `quay.io/openshift-release-dev/ocp-v4.0-art-dev` repositories. Images in these repositories are required for cluster operation.
110+
<3> Specifies the parameters that define how the images are verified.
111+
<4> Defines a root of trust for the policy.
112+
<5> Specifies the policy types that define the root of trust, either a public key or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. Here, a Fulcio certificate with required Rekor verification.
113+
<6> For a Fulcio certificate policy, the following parameters are required:
114+
* `fulcioCAData`: Specifies a base64-encoded Fulcio certificate in the PEM format. The maximum length is 8192 characters.
115+
* `fulcioSubject`: Specifies the OIDC issuer and the email of the Fulcio authentication configuration.
116+
<7> Specifies a base64-encoded Rekor public key in the PEM format. This parameter is required when when the `policyType` is `FulcioCAWithRekor`. The maximum length is 8192 characters.
117+
<8> Optional: Specifies one of the following processes to verify the identity in the signature and the actual image identity.
118+
* `MatchRepoDigestOrExact`.
119+
* `MatchRepository`.
120+
* `ExactRepository`. The `exactRepository` parameter must be specified.
121+
* `RemapIdentity`. The `prefix` and `signedPrefix` parameters must be specified.
122+
<9> For the `remapIdentity` match policy, specifies the prefix that should be matched against the scoped image prefix. If the two match, the scoped image prefix is replaced with the value of `signedPrefix`. The maximum length is 512 characters.
123+
<10> For the `remapIdentity` match policy, specifies the image prefix to be remapped, if needed. The maximum length is 512 characters.
124+
--
125+
126+
. Create the cluster image policy object:
127+
+
128+
[source,terminal]
129+
----
130+
$ oc create -f <file_name>.yaml
131+
----
132+
+
133+
The Machine Config Operator (MCO) updates the machine config pools (MCP) in your cluster.
134+
135+
.Verification
136+
137+
* After the nodes in your cluster are updated, you can verify that the cluster image policy has been configured:
138+
139+
.. Start a debug pod for the node by running the following command:
140+
+
141+
[source,terminal]
142+
----
143+
$ oc debug node/<node_name>
144+
----
145+
146+
.. Set `/host` as the root directory within the debug shell by running the following command:
147+
+
148+
[source,terminal]
149+
----
150+
sh-5.1# chroot /host/
151+
----
152+
153+
.. Examine the `policy.json` file by running the following command:
154+
+
155+
[source,terminal]
156+
----
157+
sh-5.1# cat /etc/containers/policy.json
158+
----
159+
+
160+
.Example output for the cluster image policy object with a public key showing the new cluster image policy
161+
[source,json]
162+
----
163+
# ...
164+
"transports": {
165+
# ...
166+
"docker": {
167+
"example.com": [
168+
{
169+
"type": "sigstoreSigned",
170+
"keyData": "a2V5RGF0YQ==",
171+
"rekorPublicKeyData": "cmVrb3JLZXlEYXRh",
172+
"signedIdentity": {
173+
"type": "matchRepoDigestOrExact"
174+
}
175+
}
176+
],
177+
# ...
178+
----
179+
+
180+
.Example output for the cluster image policy object with a Fulcio certificate showing the new cluster image policy
181+
[source,json]
182+
----
183+
# ...
184+
"transports": {
185+
# ...
186+
"docker": {
187+
"example.com": [
188+
{
189+
"type": "sigstoreSigned",
190+
"fulcio": {
191+
"caData": "a2V5RGF0YQ==",
192+
"oidcIssuer": "https://expected.OIDC.issuer/",
193+
"subjectEmail": "expected-signing-user@example.com"
194+
},
195+
"rekorPublicKeyData": "cmVrb3JLZXlEYXRh",
196+
"signedIdentity": {
197+
"type": "remapIdentity",
198+
"prefix": "example.com",
199+
"signedPrefix": "mirror-example.com"
200+
}
201+
}
202+
],
203+
# ...
204+
----
205+
206+
.. Examine the `sigstore-registries.yaml` file by running the following command:
207+
+
208+
[source,terminal]
209+
----
210+
sh-5.1# cat /etc/containers/registries.d/sigstore-registries.yaml
211+
----
212+
+
213+
.Example output showing that the scoped registry was added
214+
[source,yaml]
215+
----
216+
docker:
217+
example.com:
218+
use-sigstore-attachments: true <1>
219+
quay.io/openshift-release-dev/ocp-release:
220+
use-sigstore-attachments: true
221+
----
222+
<1> When `true`, specifies that sigstore signatures are going to be read along with the image.
223+
// https://github.com/openshift/api/blob/master/config/v1alpha1/zz_generated.crd-manifests/0000_10_config-operator_01_clusterimagepolicies-TechPreviewNoUpgrade.crd.yaml

0 commit comments

Comments
 (0)