docs: add doc KMP Refresh #103
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,11 @@ | ||
| # Key Management Provider | ||
|
|
||
| > **NOTE:** `KeyManagementProvider` replaces `CertificateStore` which is now DEPRECATED. See migration [guide](#migrating-from-certificatestore-to-kmp). | ||
|
|
||
| A `KeyManagementProvider` (`KMP`) represents key(s) and/or certificate(s) that are consumed by a verifier. `KMP` contains various providers for different use cases. Each provider is responsible for defining custom configuration and providing a set of public keys and/or x.509 certificates. Notation and Cosign verifiers can consume `KMP` resources to use during signature verification. Please refer to respective [Notation](../../plugins/verifier/notation.md) and [Cosign](../../plugins/verifier/cosign.md) verifier documentation on how to consume `KMP`. | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| - [Key Management Provider](#key-management-provider) | ||
| - [Table of Contents](#table-of-contents) | ||
| - [Scope](#scope) | ||
|
|
@@ -25,15 +25,19 @@ A `KeyManagementProvider` (`KMP`) represents key(s) and/or certificate(s) that a | |
| - [Notation Verifier](#notation-verifier) | ||
|
|
||
| ## Scope | ||
|
|
||
| Key Management Provider can be defined as cluster-wide resources(using the kind `KeyManagementProvider`) or namespaced resources(using the kind `NamespacedKeyManagementProvider`). | ||
|
|
||
| ## Utilization in Verifiers | ||
|
|
||
| The KeyManagementProvider serves primarily as a reference to key/certificate stores in Verifier CRs. Given that the Key Management Provider can exist either cluster-wide or within a namespace, users need to include the appropriate namespace prefix when referencing the KMP in Verifier CRs. To reference a namespaced KMP, the format should be `namespace/kmp-name`. Conversely, to reference a cluster-wide KMP, the format should simply be `kmp-name`. | ||
|
|
||
| In general, there are 2 valid use cases. One is a namespaced verifier references a namespaced KMP within the same namespace or a cluster-wide KMP. The other is a cluster-wide verifier references a cluster-wide KMP. | ||
|
|
||
| ### Examples | ||
|
|
||
| **_Scenario 1_**: A namespaced verifier referencing both namespaced KMP and cluster-wide KMP. | ||
|
|
||
| ```yaml | ||
| apiVersion: config.ratify.deislabs.io/v1beta1 | ||
| kind: NamespacedVerifier | ||
|
|
@@ -44,14 +48,15 @@ spec: | |
| name: notation | ||
| artifactTypes: application/vnd.cncf.notary.signature | ||
| parameters: | ||
| verificationCertStores: | ||
| certs: | ||
| - default/ratify-notation-inline-cert-0 | ||
| - ratify-notation-inline-cert-0 | ||
| # skip irrelevant fields | ||
| ``` | ||
|
|
||
| **_Scenario 2_**: A cluster-wide verifier referencing cluster-wide KMP. | ||
|
|
||
| ```yaml | ||
| apiVersion: config.ratify.deislabs.io/v1beta1 | ||
| kind: Verifier | ||
|
|
@@ -61,30 +66,34 @@ spec: | |
| name: notation | ||
| artifactTypes: application/vnd.cncf.notary.signature | ||
| parameters: | ||
| verificationCertStores: | ||
| certs: | ||
| - ratify-notation-inline-cert-0 | ||
| # skip irrelevant fields | ||
| ``` | ||
|
|
||
| ## Configuration guidelines | ||
|
|
||
| ### Inline | ||
|
|
||
| #### Template | ||
|
|
||
| A provider that can specify a **single** certificate or key. The content is expected to be defined inline in the resource configuration. | ||
|
|
||
| ```yml | ||
| apiVersion: config.ratify.deislabs.io/v1beta1 | ||
| kind: KeyManagementProvider # NamespacedKeyManagementProvider has the same spec. | ||
| metadata: | ||
| name: # a unique name | ||
| spec: | ||
| type: inline | ||
| parameters: | ||
| contentType: # REQUIRED: [string] (key, certificate) | ||
| value: # REQUIRED: [string] value of content | ||
| status: | ||
| error: # error message if the operation failed | ||
| issuccess: # boolean that indicate if operation was successful | ||
| lastfetchedtime: # timestamp of last attempted fetch operation | ||
| properties: # provider specific properties of the fetched certificates/keys. If the current fetch operation fails, this property displays the properties of last successfully cached certificate/key | ||
| ``` | ||
|
|
||
|
|
@@ -93,15 +102,22 @@ status: | |
| | contentType | yes | 'key' or 'certificate'. Describes content type | "" | | ||
| | value | yes | string content | "" | | ||
|
|
||
| Samples: | ||
|
|
||
| - [Inline KMP](https://github.com/ratify-project/ratify/blob/dev/config/samples/clustered/kmp/config_v1beta1_keymanagementprovider_inline.yaml) | ||
|
|
||
| ### Azure Key Vault | ||
|
|
||
| #### Template | ||
|
|
||
| ```yml | ||
| apiVersion: config.ratify.deislabs.io/v1beta1 | ||
| kind: KeyManagementProvider | ||
| metadata: | ||
| name: # a unique name | ||
| spec: | ||
| type: azurekeyvault | ||
| refreshInterval: # OPTIONAL: [string], time duration to refresh the certificates/keys. Disabled by default. Example: 1h, 30m, 1h30m. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h" | ||
| parameters: | ||
| vaultURI: # REQUIRED: [string], azure key vault URI | ||
| tenantID: # REQUIRED: [string], Azure tenant ID | ||
|
|
@@ -111,7 +127,7 @@ spec: | |
| version: # OPTIONAL [string], version identifier | ||
| keys: # OPTIONAL: [list], keys in key vault to fetch | ||
| - name: # REQUIRED: [string], key name | ||
| version: # OPTIONAL [string], version identifier | ||
| ``` | ||
|
|
||
| | Name | Required | Description | Default Value | | ||
|
|
@@ -126,11 +142,18 @@ spec: | |
| | keys[*].name | yes | key name (as shown in key vault) | "" | | ||
| | keys[*].version | no | version identifier (as shown in key vault). If not provided, latest version will be used | "" | | ||
|
|
||
| Samples: | ||
|
|
||
| - [Azure Key Vault KMP](https://github.com/ratify-project/ratify/blob/dev/config/samples/clustered/kmp/config_v1beta1_keymanagementprovider_akv.yaml) | ||
| - [Azure Key Vault KMP Refresh Enabled](https://github.com/ratify-project/ratify/blob/dev/config/samples/clustered/kmp/config_v1beta1_keymanagementprovider_akv_refresh_enabled.yaml) | ||
|
|
||
| ## Limitation | ||
|
|
||
| - If a key/certificate is in disabled state, KMP resource creation will FAIL. Users must remove reference to a disabled Key/Certificate or re-enable in Azure Key Vault. | ||
|
|
||
| - Ratify supports periodic refresh and polling of certificates/keys from Azure Key Vault. The `refreshInterval` field can be set to a time duration to refresh the certificates/keys. When no version of the certificate or key is specified, the latest version will be fetched and the resource will be updated. However, if a version is specified, the resource will be locked to that version and will not be updated. | ||
|
There was a problem hiding this comment. we might also want to talk about limitation that auto fetching latest might result in verification failure if previous image signed are with other version of the cert. We can also link N version issue so reader is aware of the road map. There was a problem hiding this comment. Good call out, I'll add that limitation to the doc. :) There was a problem hiding this comment. @susanshi do you have a link to that issue? Or does one need to be created since the n-verion feature isn't included in the refresher for the 1.3 release? There was a problem hiding this comment. I didn't find the n-version issue, @duffney could you help create one? There was a problem hiding this comment. Certainly, here's a link. ratify-project/ratify#1751 :) It's also been added to the doc. |
||
|
|
||
| - If the `refreshInterval` is set, verification may fail if the artifact being verified is signed with an older version of the certificate/key even if the older version is still valid/enabled. This is because Ratify only uses the latest stored certificate/key for verification. However, [support n-versions of certificates/keys](https://github.com/ratify-project/ratify/issues/1751) is planned in future releases. | ||
|
|
||
| - If `keys` are configured, the managed identity with `clientID` specified MUST be assigned the correct permissions to list, view, and download keys in the configured Key Vault. | ||
|
|
||
|
|
@@ -147,7 +170,7 @@ spec: | |
| Get an overview of KMPs status: | ||
|
|
||
| ```bash | ||
| kubectl get keymanagementproviders.config.ratify.deislabs.io | ||
| ``` | ||
|
|
||
| Get specific status of each certificate/key fetched in a single KMP | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
suggestion to add an example for refresh enabled KMPs in the example section, or link to the /sample
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@susanshi I added samples to the inline and akv sections to point to the samples in the ratify repo. :) Thanks for the suggestion.