1"use strict";(globalThis.webpackChunkratify=globalThis.webpackChunkratify||[]).push([[4169],{28453(e,n,i){i.d(n,{R:()=>r,x:()=>o});var t=i(96540);const s={},a=t.createContext(s);function r(e){const n=t.useContext(a);return t.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(s):e.components||s:r(e.components),t.createElement(a.Provider,{value:n},e.children)}},78535(e,n,i){i.r(n),i.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>d,frontMatter:()=>r,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"id":"quickstarts/ratify-on-aws","title":"Ratify on AWS","description":"This guide will explain how to get up and running with Ratify on AWS using EKS and ECR. This will involve setting up necessary AWS resources, installing necessary components, and configuring them properly. Once everything is set up we will walk through a simple scenario of verifying the signature on a container image at deployment time.","source":"@site/versioned_docs/version-1.0/quickstarts/ratify-on-aws.md","sourceDirName":"quickstarts","slug":"/quickstarts/ratify-on-aws","permalink":"/docs/1.0/quickstarts/ratify-on-aws","draft":false,"unlisted":false,"editUrl":"https://github.com/ratify-project/ratify-web/blob/main/versioned_docs/version-1.0/quickstarts/ratify-on-aws.md","tags":[],"version":"1.0","frontMatter":{},"sidebar":"tutorialSidebar","previous":{"title":"Install Ratify for High Availability","permalink":"/docs/1.0/quickstarts/ratify-high-availability"},"next":{"title":"Ratify on Azure","permalink":"/docs/1.0/quickstarts/ratify-on-azure"}}');var s=i(74848),a=i(28453);const r={},o="Ratify on AWS",l={},c=[{value:"Table of Contents",id:"table-of-contents",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Set Up ECR",id:"set-up-ecr",level:2},{value:"Set Up EKS",id:"set-up-eks",level:2},{value:"Prepare Container Image",id:"prepare-container-image",level:2},{value:"Using Cosign",id:"using-cosign",level:3},{value:"Using Notation",id:"using-notation",level:3},{value:"Configure Ratify",id:"configure-ratify",level:2},{value:"Ratify",id:"ratify",level:3},{value:"Gatekeeper",id:"gatekeeper",level:3},{value:"Deploy Ratify",id:"deploy-ratify",level:2},{value:"Deploy Container Image",id:"deploy-container-image",level:2},{value:"Other AWS Integrations",id:"other-aws-integrations",level:2},{value:"IAM Roles for Service Accounts",id:"iam-roles-for-service-accounts",level:3},{value:"AWS Signer",id:"aws-signer",level:3},{value:"Cleaning Up",id:"cleaning-up",level:2}];function h(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,a.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"ratify-on-aws",children:"Ratify on AWS"})}),"\n",(0,s.jsx)(n.p,{children:"This guide will explain how to get up and running with Ratify on AWS using EKS and ECR. This will involve setting up necessary AWS resources, installing necessary components, and configuring them properly. Once everything is set up we will walk through a simple scenario of verifying the signature on a container image at deployment time."}),"\n",(0,s.jsx)(n.p,{children:"By the end of this guide you will have a public ECR repository, an EKS cluster with Gatekeeper and Ratify installed, and have validated that only images signed with a particular key can be deployed."}),"\n",(0,s.jsx)(n.p,{children:"This guide assumes you are starting from scratch, but portions of the guide can be skipped if you have an existing EKS cluster or ECR repository."}),"\n",(0,s.jsx)(n.h2,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#prerequisites",children:"Prerequisites"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#set-up-ecr",children:"Setting Up ECR"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#set-up-eks",children:"Setting Up EKS"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#prepare-container-image",children:"Prepare Container Image"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#configure-ratify",children:"Configure Ratify"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#deploy-ratify",children:"Deploy Ratify"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#deploy-container-image",children:"Deploy Container Image"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#other-aws-integrations",children:"Other AWS Integrations"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"#cleaning-up",children:"Cleaning Up"})}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsx)(n.p,{children:"There are a couple tools you will need locally to complete this guide:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://aws.amazon.com/cli/",children:"awscl
1i"}),": This is used to interact with AWS and provision necessary resources"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html",children:"eksctl"}),": This is used to easily provision EKS clusters"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://kubernetes.io/docs/tasks/tools/",children:"kubectl"}),": This is used to interact with the EKS cluster we will create"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://helm.sh/docs/intro/quickstart/",children:"helm"}),": This is used to install ratify components into the EKS cluster"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://www.docker.com/get-started",children:"docker"}),": This is used to build the container image we will deploy in this guide"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://github.com/sigstore/cosign",children:"cosign"}),": This is used to sign the container image we will deploy in this guide"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://github.com/notaryproject/notation",children:"notation"}),": This is used to sign the container image we will deploy in this guide"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://github.com/ratify-project/ratify/releases",children:"ratify"}),": This is used to check images from ECR locally"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://stedolan.github.io/jq/",children:"jq"}),": This is used to capture variables from json returned by commands"]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["If you have not done so already, configure awscli to interact with your AWS account by following these ",(0,s.jsx)(n.a,{href:"https://docs.aws.amazon.com/cli/latest/userguide/getting-started-prereqs.html",children:"instructions"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"set-up-ecr",children:"Set Up ECR"}),"\n",(0,s.jsx)(n.p,{children:"We need to provision a public container repository to make our container images and their associated artifacts\navailable to our EKS cluster. We will do this using awscli. For this guide we will be provisioning a public ECR repository to keep things simple."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:'export REPO_NAME=ratifydemo\nexport REPO_URI=$(aws ecr-public create-repository --repository-name $REPO_NAME --region us-east-1 | jq -r ."repository"."repositoryUri" )\n'})}),"\n",(0,s.jsx)(n.p,{children:"We will use the repository URI returned by the create command later to build and tag the images we create."}),"\n",(0,s.jsxs)(n.p,{children:["For more information on provisioning ECR repositories check the ",(0,s.jsx)(n.a,{href:"https://docs.aws.amazon.com/AmazonECR/latest/public/public-getting-started.html",children:"documentation"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"set-up-eks",children:"Set Up EKS"}),"\n",(0,s.jsxs)(n.p,{children:["We will need to provision a Kubernetes cluster to deploy everything on. We will do this using the ",(0,s.jsx)(n.code,{children:"eksctl"})," command line\nutility. Before provisioning our EKS cluster we will need to create a key pair for the nodes:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"aws ec2 create-key-pair --region us-east-1 --key-name ratifyDemo\n"})}),"\n",(0,s.jsx)(n.p,{children:"Save the output to your local machine, then run the following to create the cluster:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"eksctl create cluster \\\n --name ratify-demo \\\n --region us-east-1 \\\n --zones us-east-1c,us-east-1d \\\n --with-oidc \\\n --ssh-access \\\n --ssh-public-key ratifyDemo\n"})}),"\n",(0,s.jsx)(n.p,{children:"The template will provision a basic EKS cluster with default settings."}),"\n",(0,s.jsxs)(n.p,{children:["Additional information on EKS deployment can be found in the EKS ",(0,s.jsx)(n.a,{href:"https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html",children:"documentation"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"prepare-container-image",children:"Prepare Container Image"}),"\n",(0,s.jsx)(n.p,{children:"For this guide we will create a basic container image we can use to simulate deployments of a service. We will start by\nbuilding the container image:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"docker build -t $REPO_URI:v1 https://github.com/wabbit-networks/net-monitor.git#main\n"})}),"\n",(0,s.jsx)(n.p,{children:"After the container is built we need to push it to the repository:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"aws ecr-public get-login-password --region us-east-1 | docker login --u
1sername AWS --password-stdin $REPO_URI\n\ndocker push $REPO_URI:v1\n"})}),"\n",(0,s.jsx)(n.h3,{id:"using-cosign",children:"Using Cosign"}),"\n",(0,s.jsx)(n.p,{children:"Once the container is built and pushed, we will use cosign to create a key and sign the container image:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"cosign generate-key-pair\n\ncosign sign --key cosign.key $REPO_URI:v1\n"})}),"\n",(0,s.jsx)(n.p,{children:"Both the container image and the signature should now be in the public ECR repository. We can use cosign to verify the signature and image are present and valid:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"docker rmi $REPO_URI:v1\n\ncosign verify --key cosign.pub $REPO_URI:v1\n"})}),"\n",(0,s.jsx)(n.h3,{id:"using-notation",children:"Using Notation"}),"\n",(0,s.jsx)(n.p,{children:"We can also use notation to generate a test key and sign the container image:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:'notation cert generate-test --default "wabbit-networks.io"\n\naws ecr-public get-login-password --region us-east-1 | notation login --username AWS --password-stdin $REPO_URI\n\nnotation sign $REPO_URI:v1\n'})}),"\n",(0,s.jsx)(n.p,{children:"Another signature should be present in the public ECR repository now. We can use notation to verify signatures associated with the image:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"notation verify $REPO_URI:v1\n"})}),"\n",(0,s.jsx)(n.h2,{id:"configure-ratify",children:"Configure Ratify"}),"\n",(0,s.jsx)(n.h3,{id:"ratify",children:"Ratify"}),"\n",(0,s.jsx)(n.p,{children:"We need to ensure that Ratify is properly configured to find signature artifacts for our container image. This is done\nusing a json configuration file. The Ratify configuration file for the guide is created and deployed by the helm chart,\nbut we can look at what will be generated below:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n "store": {\n "version": "1.0.0",\n "plugins": [\n {\n "name": "oras",\n "cosignEnabled": true,\n "localCachePath": "./local_oras_cache"\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": "/usr/local/ratify-certs/cosign/cosign.pub"\n }\n ] \n }\n}\n'})}),"\n",(0,s.jsx)(n.p,{children:"This configuration file does the following:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Enables the built-in ",(0,s.jsx)(n.code,{children:"oras"})," referrer store with cosign support which will retrieve the necessary manifests and signature artifacts from the container registry"]}),"\n",(0,s.jsxs)(n.li,{children:["Enables the ",(0,s.jsx)(n.code,{children:"cosign"})," verifier that will validate cosign signatures on container images"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The configuration file and cosign public key will be mounted into the Ratify container via the helm chart."}),"\n",(0,s.jsx)(n.h3,{id:"gatekeeper",children:"Gatekeeper"}),"\n",(0,s.jsxs)(n.p,{children:["The Ratify container will perform the actual validation of images and their artifacts, but\n",(0,s.jsx)(n.a,{href:"https://github.com/open-policy-agent/gatekeeper",children:"Gatekeeper"}),' is used as the policy controller for Kubernetes. The helm\nchart for this guide has a basic Gatekeeper rego that checks for the string "false" in the results from the Ratify\ncontainer.']}),"\n",(0,s.jsxs)(n.p,{children:["This rego is kept simple to demonstrate the capability of Ratify. More complex combinations of regos and Ratify\nverifiers can be used to accomplish many types of checks. See the ",(0,s.jsx)(n.a,{href:"https://open-policy-agent.github.io/gatekeeper/website/docs/",children:"Gatekeeper docs"}),"\nfor more information on rego authoring."]}),"\n",(0,s.jsx)(n.h2,{id:"deploy-ratify",children:"Deploy Ratify"}),"\n",(0,s.jsx)(n.p,{children:"We first need to install Gatekeeper into the cluster. We will use the Gatekeeper helm chart with some customizations:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts\n\nhelm install gatekeeper/gatekeeper \\\n --name-template=gatekeeper \\\n --namespace gatekeeper-system --create-namespace \\\n --set enableExternalData=true \\\n --set validatingWebhookTimeoutSeconds=5 \\\n --set mutatingWebhookTimeoutSeconds=2\n"})}),"\n",(0,s.jsx)(n.p,{children:"Once Gatekeeper has been deployed into the cluster, we can deploy Ratify with the provided helm chart. For validating cosign signatures, we can deploy Ratify configured with the public key we created earlier:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"\nhelm install ratify ratify/ratify --atomic \\\n --namespace gatekeeper-system \\\n --set-file cosign.key=cosign.pub\n"})}),"\n",(0,s.jsxs)(n.p,{children:["For validating notation signatures, we can deploy Ratify configured with the notation certificate generated earlier. We can get the path to the certificate generated by notation using the ",(0,s.jsx)(n.code,{children:"notation cert list"})," command:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"notation cert list\n\nhelm install ratify ratify/ratify --atomic \\\n --namespace gatekeeper-system \\\n --set-file notationCert=path/to/wabbit-networks.io.crt\n"})}),"\n",(0,s.jsx)(n.p,{children:"After deploying Ratify, we can apply the default Gatekeeper policy and constraint:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"kubectl apply -f ./library/default/template.yaml\nkubectl apply -f ./library/default/samples/constraint.yaml\n"})}),"\n",(0,s.jsx)(n.p,{children:"We can then confirm all pods are running:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"kubectl get po -A\n"})}),"\n",(0,s.jsx)(n.p,{children:"We should see a ratify pod and some gatekeeper pods running"}),"\n",(0,s.jsx)(n.h2,{id:"deploy-container-image",children:"Deploy Container Image"}),"\n",(0,s.jsx)(n.p,{children:"Now that the signed container image is in the registry and Ratify is installed into the EKS cluster we can deploy our\ncontainer image:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"kubectl create ns demo\n\nkubectl run demosigned -n demo --image $REPO_URI:v1\n"})}),"\n",(0,s.jsx)(n.p,{children:"We should be able to see from the Ratify and Gate
1keeper logs that the container signature was validated. The pod for\nthe container should also be running."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"kubectl logs deployment/ratify\n"})}),"\n",(0,s.jsx)(n.p,{children:"We can also test that an image without a valid signature is not able to run:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"kubectl run demounsigned -n demo --image hello-world\n"})}),"\n",(0,s.jsx)(n.p,{children:"The command should fail with an error and we should be able to see from the Ratify and Gatekeeper logs that the\nsignature validation failed."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"kubectl logs deployment/ratify\n"})}),"\n",(0,s.jsx)(n.h2,{id:"other-aws-integrations",children:"Other AWS Integrations"}),"\n",(0,s.jsx)(n.h3,{id:"iam-roles-for-service-accounts",children:"IAM Roles for Service Accounts"}),"\n",(0,s.jsxs)(n.p,{children:["Ratify can be configured to use IAM credentials to authenticate for any requests made to AWS services, such as for running and validating images stored in ECR Private Repositories. This can be done by configuring IAM Roles for Service Accounts (IRSA). For more information, ",(0,s.jsx)(n.a,{href:"/docs/1.0/reference/oras-auth-provider#5-aws-iam-roles-for-service-accounts-irsa",children:"read here"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"aws-signer",children:"AWS Signer"}),"\n",(0,s.jsxs)(n.p,{children:["Ratify can be configured to use notation to verify signatures generated by AWS Signer. AWS Signer manages the code-signing certificate's public and private keys, and enables central management of the code-signing lifecycle. For more information, ",(0,s.jsx)(n.a,{href:"/docs/1.0/quickstarts/ratify-with-aws-signer",children:"read here"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"cleaning-up",children:"Cleaning Up"}),"\n",(0,s.jsx)(n.p,{children:"We can use awscli and eksctl to delete our ECR repository and EKS cluster:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"aws ecr-public delete-repository --region us-east-1 --repository-name $REPO_NAME\n\neksctl delete cluster --region us-east-1 --name ratify-demo\n"})})]})}function d(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(h,{...e})}):h(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.