Container Service for Kubernetes:Notation and Ratify: Sign and verify OCI artifacts

1. Prepare an image in Container Registry

1. Use an Enterprise Edition instance to build an image or build and push a multi-arch image to Container Registry.

   Note

   Container Registry Enterprise Edition instances support the OCI Image and Distribution Specification v1.1.0, which allows you to use client tools such as ORAS to manage and distribute OCI artifacts that are not container images. For more information, see Use the OCI v1.1.0 specification to manage and associate container images and their derivative artifacts.

2. Configure access control for your Enterprise Edition instance to connect via a VPC or the internet. For more information, see Network access control.

3. Obtain the password to log in to your Container Registry Enterprise Edition instance. If you forget or lose the password, you can reset it by configuring access credentials. For more information, see Configure access credentials.

2. Sign an image with Notation and KMS

You can use the notation-alibabacloud-secret-manager plugin to sign a specified image in Container Registry with a KMS-managed private key and certificate.notation-alibabacloud-secret-manager plugin to sign a specified image in Container Registry with a private key and certificate from Secrets Manager in Key Management Service (KMS).

To use the notation-alibabacloud-secret-manager plugin with the KMS Instance SDK (Go), you must meet specific conditions and configure custom environment variables.

1. Run the following command to log in to the image repository.

   ./notation login --username=tsh_ram@11380257155*** test-for-doc-registry.cn-hangzhou.cr.aliyuncs.com

2. Run the following command to sign the specified image and generate a certificate. In the command, <dirPath> specifies the path to store the generated certificate, for example, /root.

   ./notation sign  --id <keyId> --plugin alibabacloud.secretmanager.plugin test-for-doc-registry.cn-hangzhou.cr.aliyuncs.com/test/nginx:2.11 --plugin-config output_cert_dir=<dirPath>

   Expected output:

   Successfully signed test-for-doc-registry.cn-hangzhou.cr.aliyuncs.com/test/nginx@sha256:f57e1908e63538ad5159fa99443d0492d23b9d34ba7******

3. You can use the following Notation CLI command to sign an artifact.

   notation sign --id <keyId> --plugin alibabacloud.secretmanager.plugin  <myRegistry>/<myRepo>@<digest> --plugin-config output_cert_dir=<dirPath>

   Parameter	Description
   id	The ID of the Key Management Service (KMS) key.
   plugin-config	Custom plugin parameters. The following options are supported: output_cert_dir: Specifies the directory to export the X.509 certificate that is generated from the KMS key during signing. ca_certs: Specifies the file path to the self-signed certificate. Use this parameter when signing with a self-signed key that is imported into a KMS instance and also used to issue an X.509 certificate.

1. Install Ratify and Gatekeeper

1. Enable Gatekeeper-based policy governance. For more information, see Enable security policy management.

2. Install Ratify.

   1. Create the ratify namespace.

      kubectl create ns ratify

   2. Log on to the ACK console. In the left navigation pane, click Clusters.

   3. On the Clusters page, click the name of your cluster. In the left navigation pane, click Applications > Helm.

   4. On the Helm page, click Deploy. In the Basic Information section, set the following parameters, select the ratify chart, and then click Next.

      Parameter	Example value
      Application name	ratify
      Namespace	Select ratify.
      Source	The default value is Marketplace.
      Chart	For Use scenarios, select All. For Supported architecture, select amd64. In the Search box, enter ratify.

   5. On the Parameters page, select a Chart Version. To pull images by using RAM Roles for Service Accounts (RRSA), modify the parameters as shown in the Configuration example column. Then, click OK.

      Parameter	Description	Default	Configuration example
      ServiceAccount.create	Determines whether to create a dedicated service account for Ratify. Valid values: true (default): A service account named ratify-admin is automatically created. false: A service account is not automatically created. If you use RRSA to pull images, you must create a service account manually before you install Ratify.	true	Keep the default value.
      ServiceAccount.name	The name of the Ratify service account.	ratify-admin	Keep the default value.
      ServiceAccount.annotations	Custom annotations for the service account.	{}	Add the pod-identity.alibabacloud.com/role-name: <Your-RRSA-role> annotation to enable automatic injection. Note Replace <Your-RRSA-role> with the name of your RRSA role.
      oras.authProviders.k8secretsEnabled	Enables the Kubernetes Secrets Provider for image repository authentication.	false	Keep the default value. Note For more information about ORAS configurations, see ORAS Store configuration example.
      oras.authProviders.alibabacloudAcrBasicEnabled	Enables the Alibaba Cloud ACR Provider for RRSA authentication with Container Registry instances.	false	true
      oras.cache.enabled	Enables ORAS store caching for ListReferrers and GetSubjectDescriptor. Important TTL-based caching might cause inconsistencies between the cache and the data source. If you require strong consistency, disable this parameter.	true	Keep the default value.
      oras.cache.ttl	Sets the time-to-live (TTL) for the ORAS Store cache.	10	Keep the default value.
      alibabacloudAcrConfig.defaultInstanceId	The default instance ID of the Container Registry instance that stores the target artifact.		Required. Enter the ID of your Container Registry Enterprise Edition instance.
      alibabacloudAcrConfig.acrInstancesConfig	To pull images from different Container Registry instances, define the instanceName and instanceId for each instance in this list.	[]	Configure this parameter as shown in the following example to connect to a private Container Registry repository.
      upgradeCRDs.enabled	Enables or disables the pre-install chart hook for upgrading Ratify CRDs.	true	Set this to false to skip upgrading the Ratify CRDs. Note Setting this to true triggers a pre-install hook, which may cause the installation to time out.
      featureFlags.RATIFY_CERT_ROTATION	Enables or disables automatic TLS certificate rotation. When enabled, Ratify automatically generates and rotates certificates.	false	Set to true to enable automatic certificate generation and rotation by the Ratify backend.
      notationCert	Deprecated. Use notationCerts instead to specify an array of verification certificates for the Notation verifier. The Notation verifier uses the specified certificates and certificate chain public keys to create its built-in certstore.	None	Keep the default value.
      notationCerts	An array of public key certificates and certificate chains for the Notation verifier's built-in certstore.		Enter the KMS verification certificate that was returned when you signed the artifact with the Notation plugin. For example:

3. In the left-side navigation pane, choose Security > Policy Governance. Click the My Policies tab and verify that the RatifyVerification policy exists.

2. Configure RRSA for private image signatures

Ratify supports authenticating with private Container Registry repositories by using RAM Roles for Service Accounts (RRSA) to pull signature data. For more information, see Use RRSA to grant RAM permissions to service accounts for pod-level access control.

1. Install the ack-pod-identity-webhook component from the Add-ons page of your cluster.

2. Create a RAM role named ratify-role. Set its trusted entity type to Identity Provider (IdP) and configure the condition fields in the trust policy. You can also use the ack-ram-tool CLI to automate the configuration.

   In the oidc:sub value, replace <namespace> and <service_account> with the namespace and service account used for the Ratify installation.

   {
     "Action": "sts:AssumeRole",
     "Condition": {
       "StringEquals": {
         "oidc:aud": "sts.aliyuncs.com",
         "oidc:iss": "<oidc_issuer_url>",
         "oidc:sub": "system:serviceaccount:<namespace>:<service_account>"
       }
     },
     "Effect": "Allow",
     "Principal": {
       "Federated": [
         "<oidc_provider_arn>"
       ]
     }
   }

3. Attach the AliyunContainerRegistryFullAccess policy to the ratify-role RAM role.

4. When you deploy Ratify, create a service account and add the following annotations to both the service account and its namespace. After Ratify is deployed, the ALIBABA_CLOUD_ROLE_ARN, ALIBABA_CLOUD_OIDC_PROVIDER_ARN, and ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variables are automatically injected into the Ratify pod template.

   Note

   If the service account already exists, add the pod-identity.alibabacloud.com/role-name: ratify-role annotation to it.

   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: ratify  # The name of the namespace.
     labels:
       pod-identity.alibabacloud.com/injection: 'on'
   
   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: ratify-admin    # The name of the service account.
     namespace: ratify     # The name of the namespace.
     annotations:
       pod-identity.alibabacloud.com/role-name: ratify-role # The name of the RAM role created earlier.
   
   ---

Notation verifier configuration

In a verifier, you can define the name and artifactType fields to specify the artifact types it handles. Verifiers can be defined at the cluster scope or at the namespace scope by using the NamespacedVerifier kind. For more information, see the official Ratify documentation.

After you install Ratify with the default settings, a Notation verifier instance is automatically created in the cluster. You can configure the trustPolicyDoc policy as needed. The following is a sample configuration.

apiVersion: config.ratify.deislabs.io/v1beta1
kind: Verifier
metadata:
  name: verifier-notation
spec:
  artifactTypes: application/vnd.cncf.notary.signature
  name: notation
  parameters:
    trustPolicyDoc:
      trustPolicies:
      - name: default
        registryScopes:
        - '*'
        signatureVerification:
          level: strict
        trustStores:
        - ca:certs
        trustedIdentities:
        - '*'
      version: "1.0"
    verificationCertStores:
      certs:
      - ratify-notation-inline-cert
  version: 1.0.0
status:
  issuccess: true

KMP configuration

You can define custom KeyManagementProvider (KMP) instances with inline public keys or X.509 certificates to meet various signature verification needs. During signature verification, verifiers like Notation and Cosign use an associated KMP resource. KMP resources can be defined at the cluster or namespace scope. For more information, see the official Ratify documentation. The following is a sample configuration.

apiVersion: config.ratify.deislabs.io/v1beta1
kind: KeyManagementProvider
metadata:
  name: ratify-notation-inline-cert
spec:
  parameters:
    contentType: certificate
    value: |
      -----BEGIN CERTIFICATE-----
      XXXXXX
      XXXXXX
      XXXXXX
      -----END CERTIFICATE-----
  type: inline

ORAS store configuration

After you install Ratify, you can configure the authProvider parameter in the default ORAS store instance to connect to your private repositories in Alibaba Cloud Container Registry (ACR). The following is a sample configuration.

apiVersion: config.ratify.deislabs.io/v1beta1
kind: Store
metadata:
  name: store-oras
spec:
  name: oras
  parameters:
    authProvider:
      acrInstancesConfig:
      - instanceName: name1
        instanceId: cri-aaaaaaaaaaaa
      - instanceName: name2
        instanceId: cri-bbbbbbbbbbbb
      defaultInstanceId: cri-ccccccccc
      name: alibabacloudAcrBasic