Container Service for Kubernetes:Use Notation and Ratify for OCI artifact signing and signature verification

Build and push the image

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

   Container Registry Enterprise Edition supports OCI Image and Distribution Specification 1.1.0, which lets you use tools like OCI Registry As Storage (ORAS) to manage and distribute non-image artifacts. See Using OCI v1.1.0 specification to manage and associate container images and their derivative artifacts.

2. Configure VPC or internet access control for your Container Registry Enterprise Edition instance. See Network access control.

3. Get the password for your Container Registry Enterprise Edition instance. If you've forgotten it, reset it by configuring access credentials. See Configure access credentials for a Container Registry Enterprise Edition instance.

Sign the image

notation-alibabacloud-secret-manager retrieves the private key and certificate from KMS to sign images in Container Registry. All sign commands use --plugin alibabacloud.secretmanager.plugin with the --id parameter set to your KMS key ID.

1. Log in to your image repository:

   ./notation login --username=<username> <registry-domain>

   Example:

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

2. Sign the image. Replace <dirPath> with the directory where you want 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. To sign an artifact by digest (recommended for production):

   Parameter	Description
   id	The ID of the KMS key.
   plugin-config output_cert_dir	Directory to export the X.509 certificate generated during signing with a KMS key.
   plugin-config ca_certs	Path to the certificate generated when using a self-signed key imported to KMS.

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

Install Ratify and Gatekeeper

1. Enable Gatekeeper-based policy governance in your cluster. See Enable policy governance.

2. Install Ratify via Helm.

   1. Create the ratify namespace: ``bash kubectl create ns ratify ``

   2. In the ACK console, click Clusters in the left-side navigation pane. Find your cluster and click its name. In the left-side navigation pane, choose Applications > Helm.

   3. On the Helm page, click Deploy. In the Basic Information step, configure the following parameters, select the ratify Helm chart, and click Next.

      Parameter	Example
      Application Name	ratify
      Namespaces	Select the ratify namespace.
      Source	Marketplace (default)
      Chart	Set Use Scenarios to All and Supported Architecture to amd64. Search for ratify and select it.

   4. In the Parameters step, select a chart version and configure the following parameters. Click OK when done.

      Important

      The notationCert parameter is deprecated. Use notationCerts instead to specify an array of verification certificates for the Notation verifier.

      Parameter	Description	Default	Recommended value
      ServiceAccount.create	Creates a ServiceAccount named ratify-admin when set to true. Set to false if you create the ServiceAccount manually for RRSA.	true	Keep default
      ServiceAccount.name	Name of the Ratify ServiceAccount.	ratify-admin	Keep default
      ServiceAccount.annotations	Custom annotations. Add pod-identity.alibabacloud.com/role-name: <Your-RRSA-role> to enable RRSA. Replace <Your-RRSA-role> with your RRSA role name.	{}	Set for RRSA
      oras.authProviders.k8secretsEnabled	Enables Kubernetes Secrets Provider for image repository authentication.	false	Keep default
      oras.authProviders.alibabacloudAcrBasicEnabled	Enables Container Registry Provider for image repository authentication.	false	true
      oras.cache.enabled	Enables ORAS store caching for ListReferrers and GetSubjectDescriptor. Disable if you require strong data consistency.	true	Keep default
      oras.cache.ttl	Time-to-live (TTL) of the ORAS store cache (seconds).	10	Keep default
      alibabacloudAcrConfig.defaultInstanceId	ID of the default Container Registry instance. Required. Set to the ID of your Container Registry Enterprise Edition instance.	`	Required
      alibabacloudAcrConfig.acrInstancesConfig	List of Container Registry instances if you pull images from multiple registries. Specify instanceName and instanceId for each.	[]	Set as needed
      upgradeCRDs.enabled	Enables Ratify CustomResourceDefinition (CRD) upgrades via pre-install Helm chart hooks. Set to false if you don't need to upgrade the Ratify CRD. Note that true triggers pre-install hooks, which may slow down installation.	true	Keep default
      featureFlags.RATIFY_CERT_ROTATION	Enables automatic TLS certificate generation and rotation.	false	Set to true to enable automatic certificate rotation
      notationCerts	Array of public key certificates and certificate chains for the Notation verifier's built-in cert store. Specify the KMS verification certificates generated when you signed your image.		Required

3. In the left-side navigation pane, choose Security > Policy Governance, then click the My Policies tab. Confirm that the RatifyVerification policy exists.

   

Configure RRSA to pull private image signatures

Ratify supports RAM Roles for Service Accounts (RRSA) to authenticate with Container Registry when pulling private image signatures. See Use RRSA to authorize different pods to access different cloud services.

1. On the Add-ons page of your ACK cluster, install ack-pod-identity-webhook.

2. Create a RAM role named ratify-role with IdP as the trusted entity type. Use ack-ram-tool to automate role creation with the following trust policy. Replace the placeholders with your actual OIDC values and the namespace and ServiceAccount you specify when installing Ratify.

   {
     "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 ratify-role.

4. Apply the following YAML to create the namespace and ServiceAccount with RRSA annotation. If you already created a ServiceAccount for Ratify, add the pod-identity.alibabacloud.com/role-name: ratify-role annotation to its configuration.

   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: ratify
     labels:
       pod-identity.alibabacloud.com/injection: 'on'
   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: ratify-admin
     namespace: ratify
     annotations:
       pod-identity.alibabacloud.com/role-name: ratify-role
   ---

   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 Ratify pod templates.