mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
272 lines
13 KiB
Plaintext
272 lines
13 KiB
Plaintext
// Module included in the following assemblies:
|
||
//
|
||
// * nodes/nodes-sigstore-using.adoc
|
||
|
||
:_mod-docs-content-type: PROCEDURE
|
||
[id="nodes-sigstore-configure-cluster-policy_{context}"]
|
||
= Creating a cluster image policy CR
|
||
|
||
[role="_abstract"]
|
||
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.
|
||
|
||
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."
|
||
|
||
[NOTE]
|
||
====
|
||
The default `ClusterImagePolicy` object, named `openshift`, provides sigstore support for the required {product-title} images, which are stored in the `quay.io/openshift-release-dev/ocp-release` repository. You must not remove or modify this cluster image policy object. Cluster image policy names beginning with `openshift` are reserved for future system use.
|
||
====
|
||
|
||
.Prerequisites
|
||
// Taken from https://issues.redhat.com/browse/OCPSTRAT-918
|
||
* You have a sigstore-supported public key infrastructure (PKI) key, a Bring Your Own Public Key Infrastructure (BYOPKI) certificate, or provide a link:https://docs.sigstore.dev/cosign/signing/overview/[Cosign public and private key pair] for signing operations.
|
||
* You have a signing process in place to sign your images.
|
||
* You have access to a registry that supports Cosign signatures, if you are using Cosign signatures.
|
||
* If a mirror registry is configured for the {product-title} release image repositories, `quay.io/openshift-release-dev/ocp-release` and `quay.io/openshift-release-dev/ocp-v4.0-art-dev`, you must mirror the sigstore signatures for the {product-title} release images into your mirror registry. Otherwise, the default `openshift` cluster image policy, which enforces signature verification for the release repository, blocks the ability of the Cluster Version Operator to move the CVO pod to new nodes, preventing the node update.
|
||
+
|
||
You can use the `oc image mirror` command to mirror the signatures. For example:
|
||
+
|
||
[source,terminal]
|
||
----
|
||
$ oc image mirror quay.io/openshift-release-dev/ocp-release:sha256-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef.sig \
|
||
mirror.com/image/repo:sha256-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef.sig
|
||
----
|
||
|
||
.Procedure
|
||
|
||
. Create a cluster image policy object similar to the following examples. See "About image policy parameters" for specific details on these parameters.
|
||
+
|
||
--
|
||
.Example cluster image policy object with a public key policy and the `MatchRepoDigestOrExact` match policy
|
||
[source,yaml]
|
||
----
|
||
apiVersion: config.openshift.io/v1
|
||
kind: ClusterImagePolicy <1>
|
||
metadata:
|
||
name: p1
|
||
spec:
|
||
scopes: <2>
|
||
- example.com
|
||
policy: <3>
|
||
rootOfTrust: <4>
|
||
policyType: PublicKey <5>
|
||
publicKey:
|
||
keyData: a2V5RGF0YQ== <6>
|
||
rekorKeyData: cmVrb3JLZXlEYXRh <7>
|
||
signedIdentity: <8>
|
||
matchPolicy: MatchRepoDigestOrExact
|
||
----
|
||
<1> Creates a `ClusterImagePolicy` object.
|
||
<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.
|
||
<3> Specifies the parameters that define how the images are verified.
|
||
<4> Defines a root of trust for the policy.
|
||
<5> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. This example uses a public key with Rekor verification.
|
||
<6> For a public key policy, specifies a base64-encoded public key in the PEM format. The maximum length is 8192 characters.
|
||
<7> Optional: Specifies a base64-encoded Rekor public key in the PEM format. The maximum length is 8192 characters.
|
||
<8> Optional: Specifies one of the following processes to verify the identity in the signature and the actual image identity:
|
||
* `MatchRepoDigestOrExact`.
|
||
* `MatchRepository`.
|
||
* `ExactRepository`. The `exactRepository` parameter must be specified.
|
||
* `RemapIdentity`. The `prefix` and `signedPrefix` parameters must be specified.
|
||
--
|
||
+
|
||
--
|
||
.Example cluster image policy object for a BYOPKI policy and the `MatchRepository` match policy
|
||
[source,yaml]
|
||
----
|
||
apiVersion: config.openshift.io/v1alpha1
|
||
kind: ClusterImagePolicy <1>
|
||
metadata:
|
||
name: pki-policy
|
||
spec:
|
||
scopes:
|
||
- example.io <2>
|
||
policy: <3>
|
||
rootOfTrust: <4>
|
||
policyType: PKI <5>
|
||
pki: <6>
|
||
caRootsData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk....URS0tLS0t
|
||
caIntermediatesData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1J....lDQVRFLS0tLS0=
|
||
pkiCertificateSubject: <7>
|
||
email: email@example.com
|
||
hostname: myhost.example.com
|
||
signedIdentity:
|
||
matchPolicy: MatchRepository <8>
|
||
----
|
||
<1> Creates a `ClusterImagePolicy` object.
|
||
<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.
|
||
<3> Specifies the parameters that define how the images are verified.
|
||
<4> Defines a root of trust for the policy.
|
||
<5> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. This example uses a BYOPKI certificate.
|
||
<6> For a BYOPKI certificate, specify `caRootsData`. This parameter specifies a base64-encoded CA root certificate in the PEM format. The maximum length is 8192 characters. Optionally with `caIntermediatesData`, specifies a base64-encoded intermediate CA root certificate in the PEM format. The maximum length is 8192 characters.
|
||
<7> Specifies a subject alternative name (SAN) to authenticate the user’s identity by using a hostname and an email address:
|
||
* `email`. Specifies the email address specified when the certificate was generated.
|
||
* `hostname`. Specifies the hostname specified when the certificate was generated.
|
||
<8> For a BYOPKI certificate, specify the `MatchRepository` parameter to verify the identity in the signature and the actual image identity. The default signed identity is `matchRepoDigestOrExact`, which requires a digest reference in the signature identity for verification. The signature identity in this case uses a repository reference, and does not include the image digest.
|
||
--
|
||
+
|
||
--
|
||
.Example cluster image policy object with a Fulcio certificate policy and the `remapIdentity` match policy
|
||
[source,yaml]
|
||
----
|
||
apiVersion: config.openshift.io/v1
|
||
kind: ClusterImagePolicy <1>
|
||
metadata:
|
||
name: p1
|
||
spec:
|
||
scopes: <2>
|
||
- example.com
|
||
policy: <3>
|
||
rootOfTrust: <4>
|
||
policyType: FulcioCAWithRekor <5>
|
||
fulcioCAWithRekor: <6>
|
||
fulcioCAData: a2V5RGF0YQ==
|
||
fulcioSubject:
|
||
oidcIssuer: "https://expected.OIDC.issuer/"
|
||
signedEmail: "expected-signing-user@example.com"
|
||
rekorKeyData: cmVrb3JLZXlEYXRh <7>
|
||
signedIdentity:
|
||
matchPolicy: RemapIdentity <8>
|
||
remapIdentity:
|
||
prefix: example.com <9>
|
||
signedPrefix: mirror-example.com <10>
|
||
----
|
||
<1> Creates a `ClusterImagePolicy` object.
|
||
<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.
|
||
<3> Specifies the parameters that define how the images are verified.
|
||
<4> Defines a root of trust for the policy.
|
||
<5> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. This example uses a Fulcio certificate with required Rekor verification.
|
||
<6> For a Fulcio certificate policy, the following parameters are required:
|
||
* `fulcioCAData`: Specifies a base64-encoded Fulcio certificate in the PEM format. The maximum length is 8192 characters.
|
||
* `fulcioSubject`: Specifies the OIDC issuer and the email of the Fulcio authentication configuration.
|
||
<7> Specifies a base64-encoded Rekor public key in the PEM format. This parameter is required when the `policyType` is `FulcioCAWithRekor`. The maximum length is 8192 characters.
|
||
<8> Optional: Specifies one of the following processes to verify the identity in the signature and the actual image identity.
|
||
* `MatchRepoDigestOrExact`.
|
||
* `MatchRepository`.
|
||
* `ExactRepository`. The `exactRepository` parameter must be specified.
|
||
* `RemapIdentity`. The `prefix` and `signedPrefix` parameters must be specified.
|
||
<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.
|
||
<10> For the `remapIdentity` match policy, specifies the image prefix to be remapped, if needed. The maximum length is 512 characters.
|
||
--
|
||
|
||
. Create the cluster image policy object:
|
||
+
|
||
[source,terminal]
|
||
----
|
||
$ oc create -f <file_name>.yaml
|
||
----
|
||
+
|
||
The Machine Config Operator (MCO) updates the machine config pools (MCP) in your cluster. Scheduling on each node is disabled as the change is being applied.
|
||
|
||
.Verification
|
||
|
||
* After the nodes in your cluster are updated, you can verify that the cluster image policy has been configured:
|
||
|
||
.. Start a debug pod for the node by running the following command:
|
||
+
|
||
[source,terminal]
|
||
----
|
||
$ oc debug node/<node_name>
|
||
----
|
||
|
||
.. Set `/host` as the root directory within the debug shell by running the following command:
|
||
+
|
||
[source,terminal]
|
||
----
|
||
sh-5.1# chroot /host/
|
||
----
|
||
|
||
.. Examine the `policy.json` file by running the following command:
|
||
+
|
||
[source,terminal]
|
||
----
|
||
sh-5.1# cat /etc/containers/policy.json
|
||
----
|
||
+
|
||
.Example output for the cluster image policy object with a public key showing the new cluster image policy
|
||
[source,json]
|
||
----
|
||
# ...
|
||
"transports": {
|
||
# ...
|
||
"docker": {
|
||
"example.com": [
|
||
{
|
||
"type": "sigstoreSigned",
|
||
"keyData": "a2V5RGF0YQ==",
|
||
"rekorPublicKeyData": "cmVrb3JLZXlEYXRh",
|
||
"signedIdentity": {
|
||
"type": "matchRepoDigestOrExact"
|
||
}
|
||
}
|
||
],
|
||
# ...
|
||
----
|
||
+
|
||
.Example output for the cluster image policy object for a BYOPKI certificate showing the new cluster image policy
|
||
[source,json]
|
||
----
|
||
# ...
|
||
"transports": {
|
||
# ...
|
||
"docker": {
|
||
"example.io": [
|
||
{
|
||
"type": "sigstoreSigned",
|
||
"pki": {
|
||
"caRootsData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk....URS0tLS0t",
|
||
"caIntermediatesData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1J....lDQVRFLS0tLS0=",
|
||
"subjectEmail": "email@example.com",
|
||
"subjectHostname": "myhost.example.com"
|
||
},
|
||
"signedIdentity": {
|
||
"type": "matchRepository"
|
||
}
|
||
}
|
||
],
|
||
----
|
||
+
|
||
.Example output for the cluster image policy object with a Fulcio certificate showing the new cluster image policy
|
||
[source,json]
|
||
----
|
||
# ...
|
||
"transports": {
|
||
# ...
|
||
"docker": {
|
||
"example.com": [
|
||
{
|
||
"type": "sigstoreSigned",
|
||
"fulcio": {
|
||
"caData": "a2V5RGF0YQ==",
|
||
"oidcIssuer": "https://expected.OIDC.issuer/",
|
||
"subjectEmail": "expected-signing-user@example.com"
|
||
},
|
||
"rekorPublicKeyData": "cmVrb3JLZXlEYXRh",
|
||
"signedIdentity": {
|
||
"type": "remapIdentity",
|
||
"prefix": "example.com",
|
||
"signedPrefix": "mirror-example.com"
|
||
}
|
||
}
|
||
],
|
||
# ...
|
||
----
|
||
|
||
.. Examine the `sigstore-registries.yaml` file by running the following command:
|
||
+
|
||
[source,terminal]
|
||
----
|
||
sh-5.1# cat /etc/containers/registries.d/sigstore-registries.yaml
|
||
----
|
||
+
|
||
.Example output showing that the scoped registry was added
|
||
[source,yaml]
|
||
----
|
||
docker:
|
||
example.com:
|
||
use-sigstore-attachments: true <1>
|
||
quay.io/openshift-release-dev/ocp-release:
|
||
use-sigstore-attachments: true
|
||
----
|
||
<1> When `true`, specifies that sigstore signatures are going to be read along with the image.
|
||
// https://github.com/openshift/api/blob/master/config/v1alpha1/zz_generated.crd-manifests/0000_10_config-operator_01_clusterimagepolicies-TechPreviewNoUpgrade.crd.yaml
|