Developer getting started

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.

Getting started

High-level steps of this document:

1. Start devcontainer
2. Set aliases and environment variables
3. Build images
4. Create Kind cluster
5. Install Gatekeeper (from repo via Helm)
6. Install Ratify (from locally built image)
7. Install a verifier
8. Apply constraints and templates
9. Validate

Devcontainer

Start the devcontainer using the command pallet or the green button in the lower left corner of VSCode.

Create aliases

alias k="kubectl"

Export variables

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

Build images

Ratify

docker build \
    --progress=plain \
    --no-cache \
    -f ./httpserver/Dockerfile \
    -t localbuild:test .

CRDs

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 create cluster

Delete cluster

kind delete cluster

Load images into kind

kind load docker-image --name kind localbuild:test
kind load docker-image --name kind localbuildcrd:test

Gatekeeper

Add repo

helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts

Install

helm install gatekeeper/gatekeeper  \
    --name-template=gatekeeper \
    --namespace gatekeeper-system --create-namespace \
    --version=${GATEKEEPER_VERSION} \
    --set validatingWebhookTimeoutSeconds=5 \
    --set mutatingWebhookTimeoutSeconds=2 \
    --set externaldataProviderResponseCacheTTL=10s

Ratify

Install

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/.

1. 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}

2. 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      

Upgrade

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    

Uninstall

helm uninstall ratify \
    -n ${RATIFY_NAMESPACE} \
    --debug

Apply CRD

Install a the SBOM verifier via a CRD definition.

kubectl apply -f ./config/samples/config_v1alpha1_verifier_sbom.yaml

Kubernetes constraints and templates

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.

Install

kubectl apply -f ./library/default/template.yaml
kubectl apply -f ./library/default/samples/constraint.yaml

Delete

kubectl delete -f ./library/default/samples/constraint.yaml
kubectl delete -f ./library/default/template.yaml

Validate running pods

All namepaces

kubectl get pods -A

Ratify namespace

kubectl get pods -n ${RATIFY_NAMESPACE}

K8s constraint validation

kubectl run demo --image=wabbitnetworks.azurecr.io/test/notary-image:signed
kubectl run demo --image=wabbitnetworks.azurecr.io/test/notary-image:unsigned

Debugging

In VSCode hit F5, the cli will be called and a sample image will be verified.

See debugging Ratify with VSCode

Logs

Ratify logs

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

Pod logs

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

Deployment logs

kubectl logs deployment/ratify -n ${RATIFY_NAMESPACE}

Clean up

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}

Useful commands

Deployments

kubectl get deployments -A
kubectl describe deployment -n ${RATIFY_NAMESPACE}
kubectl rollout restart deployment ratify -n ${RATIFY_NAMESPACE}

Configmaps

kubectl get configmap ratify-configuration -n ${RATIFY_NAMESPACE} -o json
kubectl edit configmap/ratify-configuration -n ${RATIFY_NAMESPACE}

Pods

kubectl get pods -A
kubectl describe pod -n ${RATIFY_NAMESPACE}