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.
High-level steps of this document:
- Start devcontainer
- Set aliases and environment variables
- Build images
- Create Kind cluster
- Install Gatekeeper (from repo via Helm)
- Install Ratify (from locally built image)
- Install a verifier
- Apply constraints and templates
- Validate
Start the devcontainer using the command pallet or the green button in the lower left corner of VSCode.
alias k="kubectl"
export RATIFY_NAMESPACE=gatekeeper-system
export KUBERNETES_VERSION=1.25.4
export GATEKEEPER_VERSION=3.13.0
export IMAGE_PULL_POLICY=IfNotPresent
export RATIFY_LOG_LEVEL=INFO
docker build \
--progress=plain \
--no-cache \
-f ./httpserver/Dockerfile \
-t localbuild:test .
docker build \
--progress=plain \
--no-cache \
--build-arg KUBE_VERSION=${KUBERNETES_VERSION} \
--build-arg TARGETOS="linux" \
--build-arg TARGETARCH="amd64" \
-f crd.Dockerfile \
-t localbuildcrd:test ./charts/ratify/crds
kind create cluster
kind delete cluster
kind load docker-image --name kind localbuild:test
kind load docker-image --name kind localbuildcrd:test
helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm install gatekeeper/gatekeeper \
--name-template=gatekeeper \
--namespace gatekeeper-system --create-namespace \
--version=${GATEKEEPER_VERSION} \
--set validatingWebhookTimeoutSeconds=5 \
--set mutatingWebhookTimeoutSeconds=2 \
--set externaldataProviderResponseCacheTTL=10s
Install Ratify using TLS and a self signed cert.
Notes:
- See other ways to install and TLS/mTLS options.
- If changes are made to a plugin, they will have to be re built using
make build-plugins
and copy the output to./ratify/plugins/
.
-
Supply a certificate to use with Ratify (httpserver) or use the following script to create a self-signed certificate.
./scripts/generate-tls-certs.sh ${RATIFY_NAMESPACE}
-
Install ratify using a certificate
helm install ratify ./charts/ratify \
--namespace ${RATIFY_NAMESPACE} --create-namespace \
--atomic \
--set provider.tls.skipVerify=false \
--set provider.tls.cabundle="$(cat certs/ca.crt | base64 | tr -d '\n\r')" \
--set provider.tls.key="$(cat certs/tls.key)" \
--set provider.tls.crt="$(cat certs/tls.crt)" \
--set image.repository=localbuild \
--set image.crdRepository=localbuildcrd \
--set image.tag=test \
--set image.pullPolicy=${IMAGE_PULL_POLICY} \
--set logger.level=info
helm upgrade -i ratify ./charts/ratify \
--namespace ${RATIFY_NAMESPACE} --create-namespace \
--atomic \
--set provider.tls.skipVerify=false \
--set provider.tls.cabundle="$(cat certs/ca.crt | base64 | tr -d '\n\r')" \
--set provider.tls.key="$(cat certs/tls.key)" \
--set provider.tls.crt="$(cat certs/tls.crt)" \
--set image.repository=localbuild \
--set image.crdRepository=localbuildcrd \
--set image.tag=test \
--set image.pullPolicy=${IMAGE_PULL_POLICY} \
--set logger.level=info
helm uninstall ratify \
-n ${RATIFY_NAMESPACE} \
--debug
Install a the SBOM verifier via a CRD definition.
kubectl apply -f ./config/samples/config_v1alpha1_verifier_sbom.yaml
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.
kubectl apply -f ./library/default/template.yaml
kubectl apply -f ./library/default/samples/constraint.yaml
kubectl delete -f ./library/default/samples/constraint.yaml
kubectl delete -f ./library/default/template.yaml
kubectl get pods -A
kubectl get pods -n ${RATIFY_NAMESPACE}
kubectl run demo --image=wabbitnetworks.azurecr.io/test/notary-image:signed
kubectl run demo --image=wabbitnetworks.azurecr.io/test/notary-image:unsigned
In VSCode hit F5, the cli will be called and a sample image will be verified.
See debugging Ratify with VSCode
When installing Ratify the log level can be specified by specifying the switch --set logger.level=info
.
The log level can also be configured by setting the env variable RATIFY_LOG_LEVEL
with one of the follow values:
PANIC
FATAL
ERROR
WARNING
INFO
(default)DEBUG
TRACE
use -p to see terminated pod logs, this is helpful when a pod starts and crashes.
kubectl logs <pod-name> \
-n ${RATIFY_NAMESPACE} \
--since=1h
kubectl logs deployment/ratify -n ${RATIFY_NAMESPACE}
kubectl delete -f ./library/default/samples/constraint.yaml
kubectl delete deployment ratify -n ${RATIFY_NAMESPACE}
kubectl delete po ratify-update-crds-hook-<foo> -n ${RATIFY_NAMESPACE}
kubectl delete po ratify-<foo> -n ${RATIFY_NAMESPACE}
kubectl get deployments -A
kubectl describe deployment -n ${RATIFY_NAMESPACE}
kubectl rollout restart deployment ratify -n ${RATIFY_NAMESPACE}
kubectl get configmap ratify-configuration -n ${RATIFY_NAMESPACE} -o json
kubectl edit configmap/ratify-configuration -n ${RATIFY_NAMESPACE}
kubectl get pods -A
kubectl describe pod -n ${RATIFY_NAMESPACE}