1"use strict";(globalThis.webpackChunkratify=globalThis.webpackChunkratify||[]).push([[2905],{28453(e,n,l){l.d(n,{R:()=>s,x:()=>r});var a=l(96540);const t={},i=a.createContext(t);function s(e){const n=a.useContext(i);return a.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:s(e.components),a.createElement(i.Provider,{value:n},e.children)}},41817(e,n,l){l.r(n),l.d(n,{assets:()=>d,contentTitle:()=>r,default:()=>h,frontMatter:()=>s,metadata:()=>a,toc:()=>c});const a=JSON.parse('{"id":"quickstarts/developer-getting-started","title":"Developer getting started","description":"The intent of this document is to be a high level quick start guide to get up and running quickly. For a more in depth review on configuration please see CONTRIBUTING.MD.","source":"@site/docs/quickstarts/developer-getting-started.md","sourceDirName":"quickstarts","slug":"/quickstarts/developer-getting-started","permalink":"/docs/next/quickstarts/developer-getting-started","draft":false,"unlisted":false,"editUrl":"https://github.com/ratify-project/ratify-web/blob/main/docs/quickstarts/developer-getting-started.md","tags":[],"version":"current","frontMatter":{},"sidebar":"tutorialSidebar","previous":{"title":"Creating Plugins","permalink":"/docs/next/quickstarts/creating-plugins"},"next":{"title":"Gatekeeper Policy Authoring","permalink":"/docs/next/quickstarts/gatekeeper-policy-authoring"}}');var t=l(74848),i=l(28453);const s={},r="Developer getting started",d={},c=[{value:"Devcontainer",id:"devcontainer",level:2},{value:"Create aliases",id:"create-aliases",level:2},{value:"Export variables",id:"export-variables",level:2},{value:"Build images",id:"build-images",level:2},{value:"Ratify",id:"ratify",level:3},{value:"CRDs",id:"crds",level:3},{value:"Kind",id:"kind",level:2},{value:"Create cluster",id:"create-cluster",level:3},{value:"Delete cluster",id:"delete-cluster",level:3},{value:"Load images into kind",id:"load-images-into-kind",level:3},{value:"Gatekeeper",id:"gatekeeper",level:2},{value:"Add repo",id:"add-repo",level:3},{value:"Install",id:"install",level:3},{value:"Ratify",id:"ratify-1",level:2},{value:"Install",id:"install-1",level:3},{value:"Upgrade",id:"upgrade",level:3},{value:"Uninstall",id:"uninstall",level:3},{value:"Apply CRD",id:"apply-crd",level:2},{value:"Kubernetes constraints and templates",id:"kubernetes-constraints-and-templates",level:2},{value:"Install",id:"install-2",level:3},{value:"Delete",id:"delete",level:3},{value:"Validate running pods",id:"validate-running-pods",level:2},{value:"All namepaces",id:"all-namepaces",level:3},{value:"Ratify namespace",id:"ratify-namespace",level:3},{value:"Logs",id:"logs",level:2},{value:"Ratify logs",id:"ratify-logs",level:3},{value:"Pod logs",id:"pod-logs",level:3},{value:"Deployment logs",id:"deployment-logs",level:3},{value:"Clean up",id:"clean-up",level:2},{value:"Useful commands",id:"useful-commands",level:2},{value:"Deployments",id:"deployments",level:3},{value:"Configmaps",id:"configmaps",level:3},{value:"Pods",id:"pods",level:3}];function o(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,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"developer-getting-started",children:"Developer getting started"})}),"\n",(0,t.jsxs)(n.p,{children:["The intent of this document is to be a high level quick start guide to get up and running quickly. For a more in depth review on configuration please see ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/CONTRIBUTING.md#running-the-ratify-cli",children:"CONTRIBUTING.MD"}),"."]}),"\n",(0,t.jsx)(n.h1,{id:"getting-started",children:"Getting started"}),"\n",(0,t.jsx)(n.p,{children:"High-level steps of this document:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsx)(n.li,{children:"Start devcontainer"}),"\n",(0,t.jsx)(n.li,{children:"Set aliases and environment variables"}),"\n",(0,t.jsx)(n.li,{children:"Build images"}),"\n",(0,t.jsx)(n.li,{children:"Create Kind cluster"}),"\n",(0,t.jsx)(n.li,{children:"Install Gatekeeper (from repo via Helm)"}),"\n",(0,t.jsx)(n.li,{children:"Install Ratify (from locally built image)"}),"\n",(0,t.jsx)(n.li,{children:"Install a verifier"}),"\n",(0,t.jsx)(n.li,{children:"Apply constraints and templates"}),"\n",(0,t.jsx)(n.li,{children:"Validate"}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"devcontainer",children:"Devcontainer"}),"\n",(0,t.jsx)(n.p,{children:"Start the devcontainer using the command pallet or the green button in the lower left corner of VSCode."}),"\n",(0,t.jsx)(n.h2,{id:"create-aliases",children:"Create aliases"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'al
1ias k="kubectl"\n'})}),"\n",(0,t.jsx)(n.h2,{id:"export-variables",children:"Export variables"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"export RATIFY_NAMESPACE=gatekeeper-system\nexport KUBERNETES_VERSION=1.25.4\nexport GATEKEEPER_VERSION=3.13.0\nexport IMAGE_PULL_POLICY=IfNotPresent\nexport RATIFY_LOG_LEVEL=INFO\n"})}),"\n",(0,t.jsx)(n.h2,{id:"build-images",children:"Build images"}),"\n",(0,t.jsx)(n.h3,{id:"ratify",children:"Ratify"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"docker build \\\n --progress=plain \\\n --no-cache \\\n -f ./httpserver/Dockerfile \\\n -t localbuild:test .\n"})}),"\n",(0,t.jsx)(n.h3,{id:"crds",children:"CRDs"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'docker build \\\n --progress=plain \\\n --no-cache \\\n --build-arg KUBE_VERSION=${KUBERNETES_VERSION} \\\n --build-arg TARGETOS="linux" \\\n --build-arg TARGETARCH="amd64" \\\n -f crd.Dockerfile \\\n -t localbuildcrd:test ./charts/ratify/crds\n'})}),"\n",(0,t.jsx)(n.h2,{id:"kind",children:"Kind"}),"\n",(0,t.jsx)(n.h3,{id:"create-cluster",children:"Create cluster"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kind create cluster\n"})}),"\n",(0,t.jsx)(n.h3,{id:"delete-cluster",children:"Delete cluster"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kind delete cluster\n"})}),"\n",(0,t.jsx)(n.h3,{id:"load-images-into-kind",children:"Load images into kind"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kind load docker-image --name kind localbuild:test\nkind load docker-image --name kind localbuildcrd:test\n"})}),"\n",(0,t.jsx)(n.h2,{id:"gatekeeper",children:"Gatekeeper"}),"\n",(0,t.jsx)(n.h3,{id:"add-repo",children:"Add repo"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts\n"})}),"\n",(0,t.jsx)(n.h3,{id:"install",children:"Install"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"helm install gatekeeper/gatekeeper \\\n --name-template=gatekeeper \\\n --namespace gatekeeper-system --create-namespace \\\n --version=${GATEKEEPER_VERSION} \\\n --set validatingWebhookTimeoutSeconds=5 \\\n --set mutatingWebhookTimeoutSeconds=2 \\\n --set externaldataProviderResponseCacheTTL=10s\n"})}),"\n",(0,t.jsx)(n.h2,{id:"ratify-1",children:"Ratify"}),"\n",(0,t.jsx)(n.h3,{id:"install-1",children:"Install"}),"\n",(0,t.jsx)(n.p,{children:"Install Ratify using TLS and a self signed cert."}),"\n",(0,t.jsx)(n.p,{children:"Notes:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["See ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/CONTRIBUTING.md#deploy-from-local-helm-chart",children:"other ways"})," to install and TLS/mTLS options."]}),"\n",(0,t.jsxs)(n.li,{children:["If changes are made to a plugin, they will have to be re built using ",(0,t.jsx)(n.code,{children:"make build-plugins"})," and copy the output to ",(0,t.jsx)(n.code,{children:"./ratify/plugins/"}),"."]}),"\n"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"Supply a certificate to use with Ratify (httpserver) or use the following script to create a self-signed certificate."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"./scripts/generate-tls-certs.sh ${RATIFY_NAMESPACE}\n"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"Install ratify using a certificate"}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'helm install ratify ./charts/ratify \\\n --namespace ${RATIFY_NAMESPACE} --create-namespace \\\n --atomic \\\n --set provider.tls.skipVerify=false \\\n --set provider.tls.cabundle="$(cat certs/ca.crt | base64 | tr -d \'\\n\\r\')" \\\n --set provider.tls.key="$(cat certs/tls.key)" \\\n --set provider.tls.crt="$(cat certs/tls.crt)" \\\n --set image.repository=localbuild \\\n --set image.crdRepository=localbuildcrd \\\n --set image.tag=test \\\n --set image.pullPolicy=${IMAGE_PULL_POLICY} \\\n --set logger.level=info \n'})}),"\n",(0,t.jsx)(n.h3,{id:"upgrade",children:"Upgrade"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'helm upgrade -i ratify ./charts/ratify \\\n --namespace ${RATIFY_NAMESPACE} --create-namespace \\\n --atomic \\\n --set provider.tls.skipVerify=false \\\n --set provider.tls.cabundle="$(cat certs/ca.crt | base64 | tr -d \'\\n\\r\')" \\\n --set provider.tls.key="$(cat certs/tls.key)" \\\n --set provider.tls.crt="$(cat certs/tls.crt)" \\\n --set image.repository=localbuild \\\n --set image.crdRepository=localbuildcrd \\\n --set image.tag=test \\\n --set image.pullPolicy=${IMAGE_PULL_POLICY} \\\n --set logger.level=info \n'})}),"\n",(0,t.jsx)(n.h3,{id:"uninstall",children:"Uninstall"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"helm uninstall ratify \\\n -n ${RATIFY_NAMESPACE} \\\n --debug\n"})}),"\n",(0,t.jsx)(n.h2,{id:"apply-crd",children:"Apply CRD"}),"\n",(0,t.jsx)(n.p,{children:"Install a the SBOM verifier via a CRD definition."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl apply -f ./config/samples/config_v1alpha1_verifier_sbom.yaml\n"})}),"\n",(0,t.jsx)(n.h2,{id:"kubernetes-constraints-and-templates",children:"Kubernetes constraints and templates"}),"\n",(0,t.jsx)(n.p,{children:"The constraint targets the 'default' namespace so any deployments to that namespace will be subject to this constraint. The sample constraint must be delete, and added back after, before any helm install or upgrading commands are run. If not, the deployment will fail as it will not not meet the constraints requirements."}),"\n",(0,t.jsx)(n.h3,{id:"install-2",children:"Install"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl apply -f ./library/default/template.yaml\nkubectl apply -f ./library/default/samples/constraint.yaml\n"})}),"\n",(0,t.jsx)(n.h3,{id:"delete",children:"Delete"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl delete -f ./library/default/samples/constraint.yaml\nkubectl delete -f ./library/default/template.yaml\n"})}),"\n",(0,t.jsx)(n.h2,{id:"validate-running-pods",children:"Validate running pods"}),"\n",(0,t.jsx)(n.h3,{id:"all-namepaces",children:"All namepaces"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl get pods -A\n"})}),"\n",(0,t.jsx)(n.h3,{id:"ratify-namespace",children:"Ratify namespace"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl get pods -n ${RATIFY_NAMESPACE}\n"})}),"\n",(0,t.jsx)(n.h1,{id:"k8s-constraint-validation",children:"K8s constraint validation"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl run demo --image=wabbitnetworks.azurecr.io/test/notary-image:signed\nkubectl run demo --image=wabbitnetworks.azurecr.io/test/notary-image:unsigned\n"})}),"\n",(0,t.jsx)(n.h1,{id:"debugging",children:"Debugging"}),"\n",(0,t.jsx)(n.p,{children:"In VSCode hit F5, the cli will be called and a sample image will be verified."}),"\n",(0,t.jsxs)(n.p,{children:["See ",(0,t.jsx)(n.a,{href:"https://github.com/notaryproject/ratify/blob/main/CONTRIBUTING.md#debugging-ratify-with-vs-code",children:"debugging Ratify with VSCode"})]}),"\n",(0,t.jsx)(n.h2,{id:"logs",children:"Logs"}),"\n",(0,t.jsx)(n.h3,{id:"ratify-logs",children:"Ratify logs"}),"\n",(0,t.jsxs)(n.p,{children:["When installing Ratify the log level can be specified by specifying the switch ",(0,t.jsx)(n.code,{children:"--set logger.level=info"}),"."]}
1),"\n",(0,t.jsxs)(n.p,{children:["The log level can also be configured by setting the env variable ",(0,t.jsx)(n.code,{children:"RATIFY_LOG_LEVEL"})," with one of the follow values:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"PANIC"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"FATAL"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"ERROR"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"WARNING"})}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"INFO"})," (default)"]}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"DEBUG"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"TRACE"})}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"pod-logs",children:"Pod logs"}),"\n",(0,t.jsx)(n.p,{children:"use -p to see terminated pod logs, this is helpful when a pod starts and crashes."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl logs <pod-name> \\\n -n ${RATIFY_NAMESPACE} \\\n --since=1h\n"})}),"\n",(0,t.jsx)(n.h3,{id:"deployment-logs",children:"Deployment logs"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl logs deployment/ratify -n ${RATIFY_NAMESPACE}\n"})}),"\n",(0,t.jsx)(n.h2,{id:"clean-up",children:"Clean up"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl delete -f ./library/default/samples/constraint.yaml\nkubectl delete deployment ratify -n ${RATIFY_NAMESPACE}\nkubectl delete po ratify-update-crds-hook-<foo> -n ${RATIFY_NAMESPACE}\nkubectl delete po ratify-<foo> -n ${RATIFY_NAMESPACE}\n"})}),"\n",(0,t.jsx)(n.h2,{id:"useful-commands",children:"Useful commands"}),"\n",(0,t.jsx)(n.h3,{id:"deployments",children:"Deployments"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl get deployments -A\nkubectl describe deployment -n ${RATIFY_NAMESPACE}\nkubectl rollout restart deployment ratify -n ${RATIFY_NAMESPACE}\n"})}),"\n",(0,t.jsx)(n.h3,{id:"configmaps",children:"Configmaps"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl get configmap ratify-configuration -n ${RATIFY_NAMESPACE} -o json\nkubectl edit configmap/ratify-configuration -n ${RATIFY_NAMESPACE}\n"})}),"\n",(0,t.jsx)(n.h3,{id:"pods",children:"Pods"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"kubectl get pods -A\nkubectl describe pod -n ${RATIFY_NAMESPACE}\n"})})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(o,{...e})}):o(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.