1"use strict";(globalThis.webpackChunkratify=globalThis.webpackChunkratify||[]).push([[4339],{28453(e,n,s){s.d(n,{R:()=>a,x:()=>o});var r=s(96540);const t={},i=r.createContext(t);function a(e){const n=r.useContext(i);return r.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:a(e.components),r.createElement(i.Provider,{value:n},e.children)}},68555(e,n,s){s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>o,default:()=>h,frontMatter:()=>a,metadata:()=>r,toc:()=>l});const r=JSON.parse('{"id":"plugins/store/oras","title":"ORAS","description":"ORAS is a built-in Store plugin. It leverages the ORAS project to authenticate, discover, list, and download artifacts from OCI compliant registries.","source":"@site/versioned_docs/version-1.4/plugins/store/oras.md","sourceDirName":"plugins/store","slug":"/plugins/store/oras","permalink":"/docs/plugins/store/oras","draft":false,"unlisted":false,"editUrl":"https://github.com/ratify-project/ratify-web/blob/main/versioned_docs/version-1.4/plugins/store/oras.md","tags":[],"version":"1.4","frontMatter":{},"sidebar":"tutorialSidebar","previous":{"title":"Plugins","permalink":"/docs/category/plugins"},"next":{"title":"Verifiers","permalink":"/docs/plugins/verifier/"}}');var t=s(74848),i=s(28453);const a={},o="ORAS",c={},l=[{value:"Configuration",id:"configuration",level:2},{value:"Kubernetes",id:"kubernetes",level:3},{value:"CLI",id:"cli",level:3},{value:"Authentication Providers",id:"authentication-providers",level:2},{value:"Example config.json",id:"example-configjson",level:3},{value:"Supported Providers",id:"supported-providers",level:3},{value:"Docker Config",id:"docker-config",level:4},{value:"Azure Workload Identity",id:"azure-workload-identity",level:4},{value:"Kubernetes Secrets",id:"kubernetes-secrets",level:4},{value:"Sample install guide using service account image pull secrets",id:"sample-install-guide-using-service-account-image-pull-secrets",level:5},{value:"Sample Store Resource with specified k8s secrets",id:"sample-store-resource-with-specified-k8s-secrets",level:5},{value:"AWS IAM Roles for Service Accounts (IRSA)",id:"aws-iam-roles-for-service-accounts-irsa",level:4},{value:"User steps to set up IAM Roles for Service Accounts with Amazon EKS to access Amazon ECR",id:"user-steps-to-set-up-iam-roles-for-service-accounts-with-amazon-eks-to-access-amazon-ecr",level:5},{value:"Alibaba Cloud RAM Roles for Service Accounts (RRSA)",id:"alibaba-cloud-ram-roles-for-service-accounts-rrsa",level:4},{value:"Notational Conventions",id:"notational-conventions",level:2}];function d(e){const n={a:"a",blockquote:"blockquote",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",h4:"h4",h5:"h5",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"oras",children:"ORAS"})}),"\n",(0,t.jsxs)(n.p,{children:["ORAS is a built-in ",(0,t.jsx)(n.code,{children:"Store"})," plugin. It leverages the ",(0,t.jsx)(n.a,{href:"https://github.com/oras-project",children:"ORAS project"})," to authenticate, discover, list, and download artifacts from OCI compliant registries.\nThe ORAS store leverages the ",(0,t.jsx)(n.code,{children:"oras-go"})," ",(0,t.jsx)(n.a,{href:"https://github.com/oras-project/oras-go",children:"library"}),"."]}),"\n",(0,t.jsxs)(n.p,{children:["ORAS store is the default and currently ONLY supported ",(0,t.jsx)(n.code,{children:"Store"})," implementation."]}),"\n",(0,t.jsxs)(n.p,{children:["Here's an example ",(0,t.jsx)(n.code,{children:"oras"})," referrer store CRD spec for a local development registy (insecure + tls-check disabled) that caches registry content."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yml",children:"apiVersion: config.ratify.deislabs.io/v1beta1\nkind: Store\
1nmetadata:\n name: store-oras\nspec:\n name: oras\n parameters: \n cacheEnabled: true\n ttl: 10\n useHttp: true\n"})}),"\n",(0,t.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,t.jsx)(n.h3,{id:"kubernetes",children:"Kubernetes"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yml",children:"apiVersion: config.ratify.deislabs.io/v1beta1\nkind: Store\nmetadata:\n name: store-oras\nspec:\n name: oras\n parameters: \n cacheEnabled: # defaults to true\n ttl: # TTL in seconds for ORAS cache. Default is 10\n useHttp: # Local testing ONLY. Disables TLS checks uses HTTP. Default is false.\n cosignEnabled: # enables discovery of cosign artifacts from registry. Default is false.\n localCachePath: # absolute file path to an existing/new ORAS OCI local store\n authProvider:\n name: # name of the auth provider type\n # auth provider specific fields here\n"})}),"\n",(0,t.jsxs)(n.table,{children:[(0,t.jsx)(n.thead,{children:(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.th,{children:"Name"}),(0,t.jsx)(n.th,{children:"Required"}),(0,t.jsx)(n.th,{children:"Description"}),(0,t.jsx)(n.th,{children:"Default Value"})]})}),(0,t.jsxs)(n.tbody,{children:[(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"cosignEnabled"}),(0,t.jsx)(n.td,{children:"no"}),(0,t.jsxs)(n.td,{children:["This must be ",(0,t.jsx)(n.code,{children:"true"})," if cosign verifier is enabled. Read more about cosign verifier ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/plugins/verifier/cosign/README.md",children:"here"}),"."]}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"false"})})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"authProvider"}),(0,t.jsx)(n.td,{children:"no"}),(0,t.jsxs)(n.td,{children:["This is only required if pulling from a private repository. For all supported auth mode, please review ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/docs/reference/oras-auth-provider.md",children:"oras-auth-provider"})," doc"]}),(0,t.jsx)(n.td,{children:"dockerAuth"})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"cacheEnabled"}),(0,t.jsx)(n.td,{children:"no"}),(0,t.jsx)(n.td,{children:"Oras cache, cache for all referrers for a subject. Note: global cache must be enabled first"}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"false"})})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"ttl"}),(0,t.jsx)(n.td,{children:"no"}),(0,t.jsx)(n.td,{children:"Time to live for entries in oras cache"}),(0,t.jsx)(n.td,{children:"10 seconds"})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"useHttp"}),(0,t.jsx)(n.td,{children:"no"}),(0,t.jsxs)(n.td,{children:["Local testing ONLY. This needs to be set to ",(0,t.jsx)(n.code,{children:"true"})," for local insecure registries"]}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"false"})})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"localCachePath"}),(0,t.jsx)(n.td,{children:"no"}),(0,t.jsx)(n.td,{children:"Absolute file path to an existing/new ORAS OCI local store"}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"/.ratify/local_oras_cache"})})]})]})]}),"\n",(0,t.jsx)(n.h3,{id:"cli",children:"CLI"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "store": {\n "version": "1.0.0",\n "plugins": [\n {\n "name": "oras",\n }\n ]\n },\n "policy": {\n "version": "1.0.0",\n "plugin": {\n "name": "configPolicy",\n "artifactVerificationPolicies": {\n "application/vnd.dev.cosign.artifact.sig.v1+json": "any"\n }\n }\n },\n "verifier": {\n "version": "1.0.0",\n "plugins": [\n {\n "name":"cosign",\n "artifactTypes": "application/vnd.dev.cosign.artifact.sig.v1+json",\n "key": "/path/to/cosign.pub"\n }\n ]\n }\n}\n'})}),"\n",(0,t.jsx)(n.h2,{id:"authentication-providers",children:"Authentication Providers"}),"\n",(0,t.jsx)(n.p,{children:"ORAS uses authentication credentials to authenticate to a registry and access referrer artifacts. Ratify contains many Authentication Providers to support different authentication scenarios. The user specifies which authentication provider to use in the configuration."}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"authProvider"})," section of configuration file specifies the authentication provider. The ",(0,t.jsx)(n.code,{children:"name"})," field is REQUIRED for Ratify to bind to the correct provider implementation."]}),"\n",(0,t.jsx)(n.h3,{id:"example-configjson",children:"Example config.json"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "store": {\n "version": "1.0.0",\n "plugins": [\n {\n "name": "oras",\n "localCachePath": "./local_oras_cache",\n "authProvider": {\n "name": "<auth provider name>",\n <other provider specific fields>\n }\n }\n ]\n },\n "policy": {\n "version": "1.0.0",\n "plugin": {\n "name": "configPolicy",\n "artifactVerificationPolicies": {\n "application/vnd.cncf.notary.signature": "any"\n }\n }\n },\n "verifier": {\n "version": "1.0.0",\n "plugins": [\n {\n "name":"notation",\n "artifactTypes" : "application/vnd.cncf.notary.signature",\n "verificationCerts": [\n "<cert folder>"\n ]\n } \n ]\n }\n}\n'})}),"\n",(0,t.jsx)(n.p,{children:"NOTE: ORAS will attempt to use anonymous access if the authentication provider fails to resolve credentials."}),"\n",(0,t.jsx)(n.h3,{id:"supported-providers",children:"Supported Providers"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#docker-config",children:"Docker Config file"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#azure-workload-identity",children:"Azure Workload Identity"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#kubernetes-secrets",children:"Kubernetes Secrets"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#aws-iam-roles-for-service-accounts-irsa",children:"AWS IAM Roles for Service Accounts (IRSA)"})}),"\n",(0,t.jsx)(n.li,{children:"Azure Managed Identity"}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#alibaba-cloud-ram-roles-for-service-accounts-rrsa",children:"Alibaba Cloud RAM Roles for Service Accounts (RRSA)"})}),"\n"]}),"\n",(0,t.jsx)(n.h4,{id:"docker-config",children:"Docker Config"}),"\n",(0,t.jsxs)(n.p,{children:["This is the default authentication provider. Ratify attempts to look for credentials at the default docker
1configuration path ($HOME/.docker/config.json) if the ",(0,t.jsx)(n.code,{children:"authProvider"})," section is not specified."]}),"\n",(0,t.jsxs)(n.p,{children:["Specify the ",(0,t.jsx)(n.code,{children:"configPath"})," field for the ",(0,t.jsx)(n.code,{children:"dockerConfig"})," authentication provider to use a different docker config file path."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'"store": {\n "version": "1.0.0",\n "plugins": [\n {\n "name": "oras",\n "localCachePath": "./local_oras_cache",\n "authProvider": {\n "name": "dockerConfig",\n "configPath": <custom file path string>\n }\n }\n ]\n }\n'})}),"\n",(0,t.jsxs)(n.p,{children:["Both the above modes uses a k8s secret of type ",(0,t.jsx)(n.code,{children:"dockerconfigjson"})," that is described in the ",(0,t.jsx)(n.a,{href:"https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/",children:"document"})]}),"\n",(0,t.jsx)(n.h4,{id:"azure-workload-identity",children:"Azure Workload Identity"}),"\n",(0,t.jsxs)(n.p,{children:["Ratify pulls artifacts from a private Azure Container Registry using Workload Federated Identity in an Azure Kubernetes Service cluster. For an overview on how workload identity operates in Azure, refer to the ",(0,t.jsx)(n.a,{href:"https://docs.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation",children:"documentation"}),". You can use workload identity federation to configure an Azure AD app registration or user-assgined managed identity."]}),"\n",(0,t.jsxs)(n.p,{children:["Please refer to ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/docs/quickstarts/ratify-on-azure.md#configure-workload-identity-for-acr",children:"quick start"})," to configure workload identity for ACR.\nThe official steps for setting up Workload Identity on AKS can be found ",(0,t.jsx)(n.a,{href:"https://azure.github.io/azure-workload-identity/docs/quick-start.html",children:"here"}),"."]}),"\n",(0,t.jsx)(n.h4,{id:"kubernetes-secrets",children:"Kubernetes Secrets"}),"\n",(0,t.jsxs)(n.p,{children:["Ratify resolves registry credentials from ",(0,t.jsx)(n.a,{href:"https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets",children:"Docker Config Kubernetes secrets"})," in the cluster. Ratify considers kubernetes secrets in two ways:"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["The configuration can specify a list of ",(0,t.jsx)(n.code,{children:"secrets"}),". Each entry REQUIRES the ",(0,t.jsx)(n.code,{children:"secretName"})," field. The ",(0,t.jsx)(n.code,{children:"namespace"})," field MUST also be provided if the secret does not exist in the namespace Ratify is deployed in. The Ratify helm chart contains a ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/charts/ratify/templates/ratify-manager-role-clusterrole.yaml",children:"ratify-manager-role-clusterrole.yaml"})," file with role assignments. If a namespace other than Ratify's namespace is provided in the secret list, the user MUST add a new role binding to the cluster role for that new namespace."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["Ratify considers the ",(0,t.jsx)(n.code,{children:"imagePullSecrets"})," specified in the service account associated with Ratify. The ",(0,t.jsx)(n.code,{children:"serviceAccountName"})," field specifies the service account associated with Ratify. Ratify MUST be assigned a role to read the service account and secrets in the Ratify namespace."]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Ratify only supports the kubernetes.io/dockerconfigjson secret type."}),"\n",(0,t.jsxs)(n.blockquote,{children:["\n",(0,t.jsx)(n.p,{children:"Note: Kubernetes secrets are reloaded and refreshed for Ratify to use every 12 hours. Changes to the Secret may not be reflected immediately."}),"\n"]}),"\n",(0,t.jsx)(n.h5,{id:"sample-install-guide-using-service-account-image-pull-secrets",children:"Sample install guide using service account image pull secrets"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Create a k8s secret by providing credentials on the command line. This secret should be in the same namespace that c
1ontains Ratify deployment."}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl create secret docker-registry ratify-regcred -n <ratify-namespace> --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>\n"})}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Deploy Ratify using helm"}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"helm install ratify \\\n ratify/ratify --atomic \\\n --namespace gatekeeper-system \\\n --set-file notationCerts={./notation.crt} \\\n --set oras.authProviders.k8secretsEnabled=true\n"})}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Patch the Ratify service account (default is ",(0,t.jsx)(n.code,{children:"ratify-admin"}),") for the ratify namespace (default is ",(0,t.jsx)(n.code,{children:"gatekeeper-system"}),") to append ",(0,t.jsx)(n.code,{children:"ratify-regcred"})," secret to ",(0,t.jsx)(n.code,{children:"imagePullSecrets"})," array"]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'kubectl patch serviceaccount ratify-admin -n gatekeeper-system -p \'{"imagePullSecrets": [{"name": "ratify-regcred"}]}\'\n'})}),"\n",(0,t.jsxs)(n.blockquote,{children:["\n",(0,t.jsx)(n.p,{children:"This mode can be used to authenticate with a single registry. If authentication to multiple registries is needed, docker config file can be used as described below"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"If Docker config file is used for the registry login process, the same file can be used to create a k8s secret."}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Deploy Ratify by specifying the path to the Docker config file."}),"\n"]}),"\n",(0,t.jsxs)(n.blockquote,{children:["\n",(0,t.jsx)(n.p,{children:"Note: If you use a Docker credentials store, you won't see that auth entry but a credsStore entry with the name of the store as value. In such cases, this option cannot be used."}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"helm install ratify charts/ratify --set-file dockerConfig=<path to the local Docker config file>\n"})}),"\n",(0,t.jsxs)(n.p,{children:["Both the above modes uses a k8s secret of type ",(0,t.jsx)(n.code,{children:"dockerconfigjson"})," that is described in the ",(0,t.jsx)(n.a,{href:"https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/",children:"document"})]}),"\n",(0,t.jsx)(n.h5,{id:"sample-store-resource-with-specified-k8s-secrets",children:"Sample Store Resource with specified k8s secrets"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"apiVersion: config.ratify.deislabs.io/v1beta1\nkind: Store\
1nmetadata:\n name: store-oras\nspec:\n name: oras\n parameters: \n cacheEnabled: true\n ttl: 10\n useHttp: true \n authProvider:\n name: k8Secrets\n serviceAccountName: ratify-admin\n secrets: \n - secretName: artifact-pull-dockerConfig\n - secretName: artifact-pull-dockerConfig2\n namespace: test \n"})}),"\n",(0,t.jsx)(n.h4,{id:"aws-iam-roles-for-service-accounts-irsa",children:"AWS IAM Roles for Service Accounts (IRSA)"}),"\n",(0,t.jsxs)(n.p,{children:["Ratify pulls artifacts from a private Amazon Elastic Container Registry (ECR) using an ECR auth token. This token is accessed using the federated workload identity assigned to pods via ",(0,t.jsx)(n.a,{href:"https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html",children:"IAM Roles for Service Accounts"}),". The AWS IAM Roles for Service Accounts Basic Auth provider uses the ",(0,t.jsx)(n.a,{href:"https://github.com/aws/aws-sdk-go-v2",children:"AWS SDK for Go v2"})," to retrieve basic auth credentials based on a role assigned to a Kubernetes Service Account referenced by a pod specification. For a specific example of how IAM Roles for Service Accounts, a.k.a. IRSA, works with pods running the AWS SDK for Go v2, please see this ",(0,t.jsx)(n.a,{href:"https://blog.jimmyray.io/kubernetes-workload-identity-with-aws-sdk-for-go-v2-927d2f258057",children:"post"}),"."]}),"\n",(0,t.jsx)(n.h5,{id:"user-steps-to-set-up-iam-roles-for-service-accounts-with-amazon-eks-to-access-amazon-ecr",children:"User steps to set up IAM Roles for Service Accounts with Amazon EKS to access Amazon ECR"}),"\n",(0,t.jsxs)(n.p,{children:["The official steps for setting up IAM Roles for Service Accounts with Amazon EKS can be found ",(0,t.jsx)(n.a,{href:"https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts-technical-overview.html",children:"here"}),"."]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["Create an OIDC enabled Amazon EKS cluster by following steps ",(0,t.jsx)(n.a,{href:"https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html",children:"here"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["Connect to cluster using ",(0,t.jsx)(n.code,{children:"kubectl"})," by following steps ",(0,t.jsx)(n.a,{href:"https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html",children:"here"})]}),"\n",(0,t.jsxs)(n.li,{children:["Create an AWS Identity and Access Management (IAM) policy with permissions needed for Ratify to access Amazon ECR. Please see the official ",(0,t.jsx)(n.a,{href:"https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html",children:"documentation"})," for creating AWS IAM policies. The AWS managed policy ",(0,t.jsx)(n.code,{children:"arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"})," will work for this purpose."]}),"\n",(0,t.jsxs)(n.li,{children:["Create the ",(0,t.jsx)(n.code,{children:"ratify"})," Namespace in your Amazon EKS cluster."]}),"\n",(0,t.jsxs)(n.li,{children:["Using ",(0,t.jsx)(n.a,{href:"https://eksctl.io/usage/iamserviceaccounts/",children:"eksctl"}),", create a Kubernetes Service Account that uses the policy from above."]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"eksctl create iamserviceaccount \\\n --name ratify-admin \\\n --namespace ratify \\\n --cluster ratify \\\n --attach-policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly \\\n --approve \\\n --override-existing-serviceaccounts\n"})}),"\n",(0,t.jsxs)(n.ol,{start:"6",children:["\n",(0,t.jsx)(n.li,{children:"Verify that the Service Account was successfully created and annotated with a newly created role."}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"kubectl -n ratify get sa ratify -oyaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n annotations:\n eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>\n labels:\n app.kubernetes.io/managed-by: eksctl\n name: ratify-admin\n namespace: ratify\nsecrets:\n- name: ratify-token-...\n"})}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsxs)(n.em,{children:[(0,t.jsx)(n.strong,{children:"Note"}),": The creation of the role was done in the background by ",(0,t.jsx)(n.code,{children:"eksctl"})," and an AWS CloudFormation stack, created by ",(0,t.jsx)(n.code,{children:"eksctl"}),"."]})}),"\n",(0,t.jsxs)(n.ol,{start:"7",children:["\n",(0,t.jsx)(n.li,{children:"The Service Account created above should be referenced in the helm chart values, without creating the Service Account."}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"serviceAccount:\n create: false\n name: ratify-admin\n"})}),"\n",(0,t.jsxs)(n.ol,{start:"8",children:["\n",(0,t.jsxs)(n.li,{children:["Specify the ",(0,t.jsx)(n.em,{children:"AWS ECR Basic Auth"})," provider in the Ratify helm chart ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/charts/ratify/values.yaml",children:"values"})," file."]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'oras:\n authProviders:\n azureWorkloadIdentityEnabled: false\n azureManagedIdentityEnabled: false\n k8secretsEnabled: false\n awsEcrBasicEnabled: true\n awsApiOverride:\n enabled: false\n endpoint: ""\n partition: "" # defaults to aws\n region: ""\n'})}),"\n",(0,t.jsxs)(n.ol,{start:"9",children:["\n",(0,t.jsxs)(n.li,{children:["If your AWS environment requires you to use a custom AWS endpoint resolver then you need to enable this feature in the helm chart ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/charts/ratify/values.yaml",children:"values"})," file."]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"oras:\n authProviders:\n azureWorkloadIdentityEnabled: false\n azureManagedIdentityEnabled: false\n k8secretsEnabled: false\n awsEcrBasicEnabled: true\n awsApiOverride:\n enabled: true\n endpoint: <AWS_ENDPOINT>\n partition: <AWS_PARTITION> # defaults to aws\n region: <AWS_REGION>\n"})}),"\n",(0,t.jsx)(n.p,{children:"Once ratify is started, if an AWS custom endpoint resolver is successfully enabled, you will see the following log entries in the ratify pod logs, with no following errors:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"\nAWS ECR basic auth using custom endpoint resolver...\nAWS ECR basic auth API override endpoint: <AWS_ENDPOINT>\nAWS ECR basic auth API override partition: <AWS_PARTITION>\nAWS ECR basic auth API override region: <AWS_REGION>\n"})}),"\n",(0,t.jsxs)(n.ol,{start:"10",children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"https://github.com/ratify-project/ratify#quick-start",children:"Install Ratify"})}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"helm install ratify \\\n ratify/ratify --atomic \\\n --namespace ratify --values values.yaml\n"})}),"\n",(0,t.jsxs)(n.ol,{start:"11",children:["\n",(0,t.jsxs)(n.li,{children:["After install, verify that the Service Account is referenced by the ",(0,t.jsx)(n.code,{children:"ratify"})," pod(s)."]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"kubectl -n ratify get pod ratify-... -oyaml | grep serviceAccount\n serviceAccount: ratify-admin\n serviceAccountName: ratify-admin\n - serviceAccountToken:\n - serviceAccountToken:\n"})}),"\n",(0,t.jsxs)(n.ol,{start:"12",children:["\n",(0,t.jsxs)(n.li,{children:["Verify that the ",(0,t.jsx)(n.a,{href:"https://github.com/aws/amazon-eks-pod-identity-webhook",children:"Amazon EKS Pod Identity Webhook"})," created the environment variables, projected volumes, and volume mounts for the Ratify pod(s)."]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:"kubectl -n ratify get po ratify-... -oyaml\n...\n - name: AWS_STS_REGIONAL_ENDPOINTS\n value: regional\n - name: AWS_DEFAULT_REGION\n value: us-east-2\n - name: AWS_REGION\n value: us-east-2\n - name: AWS_ROLE_ARN\n value: <AWS_ROLE_ARN>\n - name: AWS_WEB_IDENTITY_TOKEN_FILE\n value: /var/run/secrets/eks.amazonaws.com/serviceaccount/token\n...\n volumeMounts:\n...\n - mountPath: /var/run/secrets/eks.amazonaws.com/serviceaccount\n name: aws-iam-token\n readOnly: true\n...\n volumes:\n - name: aws-iam-token\n projected:\n defaultMode: 420\n sources:\n - serviceAccountToken:\n audience: sts.amazonaws.com\n expirationSeconds: 86400\n path: token\n...\n"})}),"\n",(0,t.jsxs)(n.ol,{start:"13",children:["\n",(0,t.jsxs)(n.li,{children:["Verify the ",(0,t.jsx)(n.em,{children:"AWS ECR Basic Auth"})," provider is configured in the ",(0,t.jsx)(n.code,{children:"ratify-configuration"})," ConfigMap."]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:'kubectl -n ratify get cm ratify-configuration -oyaml\n...\n"stores": {\
1n "version": "1.0.0",\n "plugins": [\n {\n "name": "oras",\n "localCachePath": "./local_oras_cache",\n "auth-provider": {\n "name": "awsEcrBasic"\n }\n }\n ]\n }\n...\n'})}),"\n",(0,t.jsx)(n.h4,{id:"alibaba-cloud-ram-roles-for-service-accounts-rrsa",children:"Alibaba Cloud RAM Roles for Service Accounts (RRSA)"}),"\n",(0,t.jsxs)(n.p,{children:["Ratify pulls artifacts from a private AlibabaCloud Container Registry (ACR) using an ACR authorization token. This token is accessed using the federated workload identity assigned to pods via ",(0,t.jsx)(n.a,{href:"https://www.alibabacloud.com/help/en/ack/serverless-kubernetes/user-guide/use-rrsa-to-authorize-pods-to-access-different-cloud-services",children:"RAM Roles for Service Accounts"}),". The AlibabaCloud RRSA Auth provider uses the ",(0,t.jsx)(n.a,{href:"https://www.alibabacloud.com/help/en/sdk/developer-reference/v2-manage-go-access-credentials#ec8021b053aqe",children:"Alibaba SDK V2.0 GO SDK"})," to retrieve basic auth credentials based on a role assigned to a Kubernetes Service Account referenced by a pod specification. For an overview on how to enable and work with RAM Roles for Service Accounts, a.k.a. RRSA, please refer to ",(0,t.jsx)(n.a,{href:"https://www.alibabacloud.com/help/en/ack/serverless-kubernetes/user-guide/use-rrsa-to-authorize-pods-to-access-different-cloud-services#section-rmr-eeh-878",children:"official document"}),"."]}),"\n",(0,t.jsxs)(n.p,{children:["Please refer to ",(0,t.jsx)(n.a,{href:"/docs/quickstarts/ratify-on-alibabacloud#pulling-acr-private-image-signature-manifest-with-rrsa",children:"quick start"})," to configure Ratify for pulling from ACR private repository using RRSA."]}),"\n",(0,t.jsx)(n.h2,{id:"notational-conventions",children:"Notational Conventions"}),"\n",(0,t.jsxs)(n.p,{children:['The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in ',(0,t.jsx)(n.a,{href:"http://tools.ietf.org/html/rfc2119",children:"RFC 2119"}),"."]}),"\n",(0,t.jsxs)(n.p,{children:['The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the ',(0,t.jsx)(n.a,{href:"http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18",children:"rationale for the C99 standard"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.