Installing Kritis

March 7, 2020 · View on GitHub

Requirements

The only currently supported backend for vulnerability data is the Google Cloud Container Analysis API. You will need access to it, along with:

Google Cloud account with billing enabled
Google Cloud SDK (gcloud)
Kubernetes 1.9.2+
GnuPG

Step #1: Create a Google Cloud Project

Follow the prompts at Google Cloud Console: New Project.

For convenience, save the project ID as an environment variable:

PROJECT=<project ID assigned to you>

Configure gcloud to use the correct project.

gcloud config set project $PROJECT

If you do not know your project ID, you may use:

gcloud projects list

Step #2: Enable the requisite API's for your Google Cloud Project

Enable the necessary API's:

Enable the Container Analysis API:

gcloud services enable containeranalysis.googleapis.com

Enable the Kubernetes API:

gcloud services enable container.googleapis.com

Enable the Container Registry API:

gcloud services enable containerregistry.googleapis.com

Enable the Vulnerability Scanning API:

gcloud services enable containerscanning.googleapis.com

Wait for the above API's to be fully enabled, and verify that vulnerability scanning is indeed enabled. The blue button on the page should display as "Disable Vulnerability Scanning".

For more documentation, see Container Analysis Overview.

Step #3: Create a cluster

kritis requires a cluster running Kubernetes v1.9.2 or newer. You may create one named kritis-test by executing:

gcloud components update
gcloud config set compute/zone us-central1-a
gcloud container clusters create kritis-test --num-nodes=2

After creating your cluster, you need to get authentication credentials to interact with the cluster. This command will also configure kubectl for your newly created cluster:

gcloud container clusters get-credentials kritis-test

For more documentation, see Kubernetes Engine: Creating a Cluster.

Step #4: Create service account & configure roles

This creates a service account named kritis-ca-admin:

gcloud iam service-accounts create kritis-ca-admin \
  --display-name "Kritis Service Account"

Which must be bound to the appropriate roles:

gcloud projects add-iam-policy-binding $PROJECT \
  --member=serviceAccount:kritis-ca-admin@${PROJECT}.iam.gserviceaccount.com \
  --role=roles/containeranalysis.notes.viewer

gcloud projects add-iam-policy-binding $PROJECT \
  --member=serviceAccount:kritis-ca-admin@${PROJECT}.iam.gserviceaccount.com \
  --role=roles/containeranalysis.notes.editor

gcloud projects add-iam-policy-binding $PROJECT \
  --member=serviceAccount:kritis-ca-admin@${PROJECT}.iam.gserviceaccount.com \
  --role=roles/containeranalysis.occurrences.viewer

gcloud projects add-iam-policy-binding $PROJECT \
  --member=serviceAccount:kritis-ca-admin@${PROJECT}.iam.gserviceaccount.com \
  --role=roles/containeranalysis.occurrences.editor

gcloud projects add-iam-policy-binding $PROJECT \
  --member=serviceAccount:kritis-ca-admin@${PROJECT}.iam.gserviceaccount.com \
  --role=roles/containeranalysis.notes.occurrences.viewer

Step #5: Upload the Service Account Key

Download the service key from Google Cloud:

gcloud iam service-accounts keys create gac.json \
  --iam-account kritis-ca-admin@${PROJECT}.iam.gserviceaccount.com

Then upload the service key to your Kubernetes cluster:

kubectl create secret generic gac-ca-admin --from-file=gac.json

Step #6: Install and Configure Helm

Install helm, and execute the following to create an account for helm in your cluster:

kubectl create serviceaccount --namespace kube-system tiller

kubectl create clusterrolebinding tiller-cluster-role \
  --clusterrole=cluster-admin \
  --serviceaccount=kube-system:tiller

Then deploy helm:

helm init --wait --service-account tiller

Installing Kritis to your cluster

Install the resolve-tags kubectl plugin and binary:

Mac OS X

curl -LO https://storage.googleapis.com/resolve-tags/latest/resolve-tags-darwin-amd64.tar.gz && \
  RESOLVE_TAGS_DIR=$HOME/.kube/plugins/resolve && \
  mkdir -p $RESOLVE_TAGS_DIR && tar -C $RESOLVE_TAGS_DIR -xzf resolve-tags-darwin-amd64.tar.gz && \
  mv $RESOLVE_TAGS_DIR/resolve-tags-darwin-amd64 $RESOLVE_TAGS_DIR/resolve-tags && \
  sudo cp $RESOLVE_TAGS_DIR/resolve-tags /usr/local/bin/

Linux

curl -LO https://storage.googleapis.com/resolve-tags/latest/resolve-tags-linux-amd64.tar.gz && \
  RESOLVE_TAGS_DIR=$HOME/.kube/plugins/resolve && \
  mkdir -p $RESOLVE_TAGS_DIR && tar -C $RESOLVE_TAGS_DIR -xzf resolve-tags-linux-amd64.tar.gz && \
  mv $RESOLVE_TAGS_DIR/resolve-tags-linux-amd64 $RESOLVE_TAGS_DIR/resolve-tags && \
  sudo cp $RESOLVE_TAGS_DIR/resolve-tags /usr/local/bin/

For more information, please see the resolve-tags documentation.

Install kritis to your cluster:

helm install https://storage.googleapis.com/kritis-charts/repository/kritis-charts-0.2.2.tgz

You may use the --set flag, to override the installation defaults:

Value	Default	Description
serviceNamespace	default	namespace to install kritis within
gacSecret.name	gac-ca-admin	name of the secret created above with container analysis permissions

The kritis installation will create 3 pods:

kritis-preinstall creates a CertificateSigningRequest and TLS Secret for the webhook
kritis-postinstall creates the ValidatingWebhookConfiguration
kritis-validation-hook-xxx serves the webhook

The deployment status may be viewed using:

kubectl get pods

Sample output:

NAME                                      READY     STATUS             RESTARTS   AGE
kritis-postinstall                        0/1       Completed          0          2m
kritis-preinstall                         0/1       Completed          0          2m
kritis-validation-hook-7c84c48f47-lsjpg   1/1       Running            0          2m

The installation is complete once:

kritis-preinstall and kritis-postinstall have status Completed
kritis-validation-hook-xxx is Running

Tutorial

Once installed, follow our tutorial to learn how to test and manage Kritis.

Uninstalling Kritis

Find the name of your helm release to delete:

helm ls

example:

NAME          REVISION  UPDATED                   STATUS    CHART         NAMESPACE
loopy-numbat    1       Fri Jul 27 14:25:44 2018  DEPLOYED  kritis-0.1.0  default

Then delete the name of the release:

helm delete <name>

name in this case is loopy-numbat.

This command will also kick off the kritis-predelete pod, which deletes the CertificateSigningRequest, TLS Secret, and Webhooks created during installation. You may view the status using:

kubectl get pods kritis-predelete

And the logs using:

kubectl logs kritis-predelete

Most resources created by kritis will be deleted from your cluster once this Pod has reached Completed status.

To delete the remaining resources, run:

kubectl delete pods,serviceaccount,clusterrolebinding \
  --selector kritis.grafeas.io/install \
  --namespace <your namespace>

If you did not specifically select a namespace during installation, the default value is default.

NOTE: This will not delete the container analysis secret created above.

Troubleshooting

Logs

If you're unable to install or delete kritis, looking at logs for the following pods could provide more information:

kritis-validation-hook-xxx
kritis-preinstall (during installation)
kritis-postinstall (during installation)
kritis-predelete (during deletion)

You can view their status using:

kubectl get pods

Deleting Kritis Manually

If you're unable to delete kritis via helm delete <DEPLOYMENT NAME>, you can manually delete all kritis resources with the following commands:

kubectl delete all,validatingwebhookconfiguration,serviceaccount,secret,csr,crd \
  --selector kritis.grafeas.io/install \
  --namespace <your namespace>

You should then be able to delete the helm deployment with

helm delete [deployment name] --no-hooks