ClusterImagePolicy [config.openshift.io/v1]
Esc
Start typing to search...
On this page

ClusterImagePolicy [config.openshift.io/v1]

Description

ClusterImagePolicy holds cluster-wide configuration for image signature verification

Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).

Type
`object`
Required
  • spec

Specification

PropertyTypeDescription
apiVersionstringAPIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kindstringKind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadataObjectMetaStandard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
specobjectspec contains the configuration for the cluster image policy.
statusobjectstatus contains the observed state of the resource.

.spec

Description

spec contains the configuration for the cluster image policy.

Type
`object`
Required
  • policy
  • scopes
PropertyTypeDescription
policyobjectpolicy is a required field that contains configuration to allow scopes to be verified, and defines how images not matching the verification policy will be treated.
scopesarray (string)scopes is a required field that defines the list of image identities assigned to a policy. Each item refers to a scope in a registry implementing the "Docker Registry HTTP API V2". Scopes matching individual images are named Docker references in the fully expanded form, either using a tag or digest. For example, docker.io/library/busybox:latest (not busybox:latest). More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest), a repository namespace, or a registry host (by only specifying the host name and possibly a port number) or a wildcard expression starting with \*., for matching all subdomains (not including a port number). Wildcards are only supported for subdomain matching, and may not be used in the middle of the host, i.e. *.example.com is a valid case, but example*.*.com is not. This support no more than 256 scopes in one object. If multiple scopes match a given image, only the policy requirements for the most specific scope apply. The policy requirements for more general scopes are ignored. In addition to setting a policy appropriate for your own deployed applications, make sure that a policy on the OpenShift image repositories quay.io/openshift-release-dev/ocp-release, quay.io/openshift-release-dev/ocp-v4.0-art-dev (or on a more general scope) allows deployment of the OpenShift images required for cluster operation. If a scope is configured in both the ClusterImagePolicy and the ImagePolicy, or if the scope in ImagePolicy is nested under one of the scopes from the ClusterImagePolicy, only the policy from the ClusterImagePolicy will be applied. For additional details about the format, please refer to the document explaining the docker transport field, which can be found at: https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md#docker

.spec.policy

Description

policy is a required field that contains configuration to allow scopes to be verified, and defines how images not matching the verification policy will be treated.

Type
`object`
Required
  • rootOfTrust
PropertyTypeDescription
rootOfTrustobjectrootOfTrust is a required field that defines the root of trust for verifying image signatures during retrieval. This allows image consumers to specify policyType and corresponding configuration of the policy, matching how the policy was generated.
signedIdentityobjectsignedIdentity is an optional field specifies what image identity the signature claims about the image. This is useful when the image identity in the signature differs from the original image spec, such as when mirror registry is configured for the image scope, the signature from the mirror registry contains the image identity of the mirror instead of the original scope. The required matchPolicy field specifies the approach used in the verification process to verify the identity in the signature and the actual image identity, the default matchPolicy is "MatchRepoDigestOrExact".

.spec.policy.rootOfTrust

Description

rootOfTrust is a required field that defines the root of trust for verifying image signatures during retrieval. This allows image consumers to specify policyType and corresponding configuration of the policy, matching how the policy was generated.

Type
`object`
Required
  • policyType
PropertyTypeDescription
fulcioCAWithRekorobjectfulcioCAWithRekor defines the root of trust configuration based on the Fulcio certificate and the Rekor public key. fulcioCAWithRekor is required when policyType is FulcioCAWithRekor, and forbidden otherwise For more information about Fulcio and Rekor, please refer to the document at: https://github.com/sigstore/fulcio and https://github.com/sigstore/rekor
pkiobjectpki defines the root of trust configuration based on Bring Your Own Public Key Infrastructure (BYOPKI) Root CA(s) and corresponding intermediate certificates. pki is required when policyType is PKI, and forbidden otherwise.
policyTypestringpolicyType is a required field specifies the type of the policy for verification. This field must correspond to how the policy was generated. Allowed values are "PublicKey", "FulcioCAWithRekor", and "PKI". When set to "PublicKey", the policy relies on a sigstore publicKey and may optionally use a Rekor verification. When set to "FulcioCAWithRekor", the policy is based on the Fulcio certification and incorporates a Rekor verification. When set to "PKI", the policy is based on the certificates from Bring Your Own Public Key Infrastructure (BYOPKI).
publicKeyobjectpublicKey defines the root of trust configuration based on a sigstore public key. Optionally include a Rekor public key for Rekor verification. publicKey is required when policyType is PublicKey, and forbidden otherwise.

.spec.policy.rootOfTrust.fulcioCAWithRekor

Description

fulcioCAWithRekor defines the root of trust configuration based on the Fulcio certificate and the Rekor public key. fulcioCAWithRekor is required when policyType is FulcioCAWithRekor, and forbidden otherwise For more information about Fulcio and Rekor, please refer to the document at: https://github.com/sigstore/fulcio and https://github.com/sigstore/rekor

Type
`object`
Required
  • fulcioCAData
  • fulcioSubject
  • rekorKeyData
PropertyTypeDescription
fulcioCADatastringfulcioCAData is a required field contains inline base64-encoded data for the PEM format fulcio CA. fulcioCAData must be at most 8192 characters.
fulcioSubjectobjectfulcioSubject is a required field specifies OIDC issuer and the email of the Fulcio authentication configuration.
rekorKeyDatastringrekorKeyData is a required field contains inline base64-encoded data for the PEM format from the Rekor public key. rekorKeyData must be at most 8192 characters.

.spec.policy.rootOfTrust.fulcioCAWithRekor.fulcioSubject

Description

fulcioSubject is a required field specifies OIDC issuer and the email of the Fulcio authentication configuration.

Type
`object`
Required
  • oidcIssuer
  • signedEmail
PropertyTypeDescription
oidcIssuerstringoidcIssuer is a required filed contains the expected OIDC issuer. The oidcIssuer must be a valid URL and at most 2048 characters in length. It will be verified that the Fulcio-issued certificate contains a (Fulcio-defined) certificate extension pointing at this OIDC issuer URL. When Fulcio issues certificates, it includes a value based on an URL inside the client-provided ID token. Example: "https://expected.OIDC.issuer/"
signedEmailstringsignedEmail is a required field holds the email address that the Fulcio certificate is issued for. The signedEmail must be a valid email address and at most 320 characters in length. Example: "expected-signing-user@example.com"

.spec.policy.rootOfTrust.pki

Description

pki defines the root of trust configuration based on Bring Your Own Public Key Infrastructure (BYOPKI) Root CA(s) and corresponding intermediate certificates. pki is required when policyType is PKI, and forbidden otherwise.

Type
`object`
Required
  • caRootsData
  • pkiCertificateSubject
PropertyTypeDescription
caIntermediatesDatastringcaIntermediatesData contains base64-encoded data of a certificate bundle PEM file, which contains one or more intermediate certificates in the PEM format. The total length of the data must not exceed 8192 characters. caIntermediatesData requires caRootsData to be set.
caRootsDatastringcaRootsData contains base64-encoded data of a certificate bundle PEM file, which contains one or more CA roots in the PEM format. The total length of the data must not exceed 8192 characters.
pkiCertificateSubjectobjectpkiCertificateSubject defines the requirements imposed on the subject to which the certificate was issued.

.spec.policy.rootOfTrust.pki.pkiCertificateSubject

Description

pkiCertificateSubject defines the requirements imposed on the subject to which the certificate was issued.

Type
`object`
PropertyTypeDescription
emailstringemail specifies the expected email address imposed on the subject to which the certificate was issued, and must match the email address listed in the Subject Alternative Name (SAN) field of the certificate. The email must be a valid email address and at most 320 characters in length.
hostnamestringhostname specifies the expected hostname imposed on the subject to which the certificate was issued, and it must match the hostname listed in the Subject Alternative Name (SAN) DNS field of the certificate. The hostname must be a valid dns 1123 subdomain name, optionally prefixed by '*.', and at most 253 characters in length. It must consist only of lowercase alphanumeric characters, hyphens, periods and the optional preceding asterisk.

.spec.policy.rootOfTrust.publicKey

Description

publicKey defines the root of trust configuration based on a sigstore public key. Optionally include a Rekor public key for Rekor verification. publicKey is required when policyType is PublicKey, and forbidden otherwise.

Type
`object`
Required
  • keyData
PropertyTypeDescription
keyDatastringkeyData is a required field contains inline base64-encoded data for the PEM format public key. keyData must be at most 8192 characters.
rekorKeyDatastringrekorKeyData is an optional field contains inline base64-encoded data for the PEM format from the Rekor public key. rekorKeyData must be at most 8192 characters.

.spec.policy.signedIdentity

Description

signedIdentity is an optional field specifies what image identity the signature claims about the image. This is useful when the image identity in the signature differs from the original image spec, such as when mirror registry is configured for the image scope, the signature from the mirror registry contains the image identity of the mirror instead of the original scope. The required matchPolicy field specifies the approach used in the verification process to verify the identity in the signature and the actual image identity, the default matchPolicy is "MatchRepoDigestOrExact".

Type
`object`
Required
  • matchPolicy
PropertyTypeDescription
exactRepositoryobjectexactRepository specifies the repository that must be exactly matched by the identity in the signature. exactRepository is required if matchPolicy is set to "ExactRepository". It is used to verify that the signature claims an identity matching this exact repository, rather than the original image identity.
matchPolicystringmatchPolicy is a required filed specifies matching strategy to verify the image identity in the signature against the image scope. Allowed values are "MatchRepoDigestOrExact", "MatchRepository", "ExactRepository", "RemapIdentity". When omitted, the default value is "MatchRepoDigestOrExact". When set to "MatchRepoDigestOrExact", the identity in the signature must be in the same repository as the image identity if the image identity is referenced by a digest. Otherwise, the identity in the signature must be the same as the image identity. When set to "MatchRepository", the identity in the signature must be in the same repository as the image identity. When set to "ExactRepository", the exactRepository must be specified. The identity in the signature must be in the same repository as a specific identity specified by "repository". When set to "RemapIdentity", the remapIdentity must be specified. The signature must be in the same as the remapped image identity. Remapped image identity is obtained by replacing the "prefix" with the specified “signedPrefix” if the the image identity matches the specified remapPrefix.
remapIdentityobjectremapIdentity specifies the prefix remapping rule for verifying image identity. remapIdentity is required if matchPolicy is set to "RemapIdentity". It is used to verify that the signature claims a different registry/repository prefix than the original image.

.spec.policy.signedIdentity.exactRepository

Description

exactRepository specifies the repository that must be exactly matched by the identity in the signature. exactRepository is required if matchPolicy is set to "ExactRepository". It is used to verify that the signature claims an identity matching this exact repository, rather than the original image identity.

Type
`object`
Required
  • repository
PropertyTypeDescription
repositorystringrepository is the reference of the image identity to be matched. repository is required if matchPolicy is set to "ExactRepository". The value should be a repository name (by omitting the tag or digest) in a registry implementing the "Docker Registry HTTP API V2". For example, docker.io/library/busybox

.spec.policy.signedIdentity.remapIdentity

Description

remapIdentity specifies the prefix remapping rule for verifying image identity. remapIdentity is required if matchPolicy is set to "RemapIdentity". It is used to verify that the signature claims a different registry/repository prefix than the original image.

Type
`object`
Required
  • prefix
  • signedPrefix
PropertyTypeDescription
prefixstringprefix is required if matchPolicy is set to "RemapIdentity". prefix is the prefix of the image identity to be matched. If the image identity matches the specified prefix, that prefix is replaced by the specified “signedPrefix” (otherwise it is used as unchanged and no remapping takes place). This is useful when verifying signatures for a mirror of some other repository namespace that preserves the vendor’s repository structure. The prefix and signedPrefix values can be either host[:port] values (matching exactly the same host[:port], string), repository namespaces, or repositories (i.e. they must not contain tags/digests), and match as prefixes of the fully expanded form. For example, docker.io/library/busybox (not busybox) to specify that single repository, or docker.io/library (not an empty string) to specify the parent namespace of docker.io/library/busybox.
signedPrefixstringsignedPrefix is required if matchPolicy is set to "RemapIdentity". signedPrefix is the prefix of the image identity to be matched in the signature. The format is the same as "prefix". The values can be either host[:port] values (matching exactly the same host[:port], string), repository namespaces, or repositories (i.e. they must not contain tags/digests), and match as prefixes of the fully expanded form. For example, docker.io/library/busybox (not busybox) to specify that single repository, or docker.io/library (not an empty string) to specify the parent namespace of docker.io/library/busybox.

.status

Description

status contains the observed state of the resource.

Type
`object`
PropertyTypeDescription
conditionsarrayconditions provide details on the status of this API Resource.
conditions[]objectCondition contains details for one aspect of the current state of this API Resource.

.status.conditions

Description

conditions provide details on the status of this API Resource.

Type
`array`

.status.conditions[]

Description

Condition contains details for one aspect of the current state of this API Resource.

Type
`object`
Required
  • lastTransitionTime
  • message
  • reason
  • status
  • type
PropertyTypeDescription
lastTransitionTimestringlastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
messagestringmessage is a human readable message indicating details about the transition. This may be an empty string.
observedGenerationintegerobservedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
reasonstringreason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
statusstringstatus of the condition, one of True, False, Unknown.
typestringtype of condition in CamelCase or in foo.example.com/CamelCase.

API endpoints

The following API endpoints are available:

  • /apis/config.openshift.io/v1/clusterimagepolicies
    • DELETE: delete collection of ClusterImagePolicy
    • GET: list objects of kind ClusterImagePolicy
    • POST: create a ClusterImagePolicy
  • /apis/config.openshift.io/v1/clusterimagepolicies/{name}
    • DELETE: delete a ClusterImagePolicy
    • GET: read the specified ClusterImagePolicy
    • PATCH: partially update the specified ClusterImagePolicy
    • PUT: replace the specified ClusterImagePolicy
  • /apis/config.openshift.io/v1/clusterimagepolicies/{name}/status
    • GET: read status of the specified ClusterImagePolicy
    • PATCH: partially update status of the specified ClusterImagePolicy
    • PUT: replace status of the specified ClusterImagePolicy

/apis/config.openshift.io/v1/clusterimagepolicies

HTTP method
`DELETE`
Description
delete collection of ClusterImagePolicy

HTTP responses

HTTP codeReponse body
200 - OKStatus schema
401 - UnauthorizedEmpty
HTTP method
`GET`
Description
list objects of kind ClusterImagePolicy

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicyList schema
401 - UnauthorizedEmpty
HTTP method
`POST`
Description
create a ClusterImagePolicy

Query parameters

ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Body parameters

ParameterTypeDescription
bodyClusterImagePolicy schema

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicy schema
201 - CreatedClusterImagePolicy schema
202 - AcceptedClusterImagePolicy schema
401 - UnauthorizedEmpty

/apis/config.openshift.io/v1/clusterimagepolicies/{name}

Global path parameters

ParameterTypeDescription
namestringname of the ClusterImagePolicy
HTTP method
`DELETE`
Description
delete a ClusterImagePolicy

Query parameters

ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

HTTP responses

HTTP codeReponse body
200 - OKStatus schema
202 - AcceptedStatus schema
401 - UnauthorizedEmpty
HTTP method
`GET`
Description
read the specified ClusterImagePolicy

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicy schema
401 - UnauthorizedEmpty
HTTP method
`PATCH`
Description
partially update the specified ClusterImagePolicy

Query parameters

ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicy schema
401 - UnauthorizedEmpty
HTTP method
`PUT`
Description
replace the specified ClusterImagePolicy

Query parameters

ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Body parameters

ParameterTypeDescription
bodyClusterImagePolicy schema

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicy schema
201 - CreatedClusterImagePolicy schema
401 - UnauthorizedEmpty

/apis/config.openshift.io/v1/clusterimagepolicies/{name}/status

Global path parameters

ParameterTypeDescription
namestringname of the ClusterImagePolicy
HTTP method
`GET`
Description
read status of the specified ClusterImagePolicy

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicy schema
401 - UnauthorizedEmpty
HTTP method
`PATCH`
Description
partially update status of the specified ClusterImagePolicy

Query parameters

ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicy schema
401 - UnauthorizedEmpty
HTTP method
`PUT`
Description
replace status of the specified ClusterImagePolicy

Query parameters

ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Body parameters

ParameterTypeDescription
bodyClusterImagePolicy schema

HTTP responses

HTTP codeReponse body
200 - OKClusterImagePolicy schema
201 - CreatedClusterImagePolicy schema
401 - UnauthorizedEmpty