This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Getting started

This chapter shows you how to install APIClarity, and guides you through the most common tasks that you can perform with APIClarity.

1 - Install APIClarity

Install APIClarity in a K8s cluster using Helm

  1. Add the Helm repository.

    helm repo add apiclarity
  2. Save the default chart values into the values.yaml file.

    helm show values apiclarity/apiclarity > values.yaml

    Note: The file values.yaml is used to deploy and configure APIClarity on your cluster via Helm. This ConfigMap is used to define the list of headers to ignore when reconstructing the spec.

  3. Update values.yaml with the required traffic source values.

  4. Deploy APIClarity with Helm.

    helm install --values values.yaml --create-namespace apiclarity apiclarity/apiclarity --namespace apiclarity
  5. Port forward to the APIClarity UI:

    kubectl port-forward --namespace apiclarity svc/apiclarity-apiclarity 9999:8080
  6. Open the APIClarity UI in your browser at http://localhost:9999/

  7. Generate some traffic in the traced applications, for example, using a demo application.

  8. Check the APIClarity UI.

Uninstall APIClarity from Kubernetes using Helm

  1. Uninstall the Helm deployment.

    helm uninstall apiclarity --namespace apiclarity
  2. Clean the resources. By default, Helm will not remove the PVCs and PVs for the StatefulSets. Run the following command to delete them all:

    kubectl delete pvc -l --namespace apiclarity

Build from source

  1. Build and push the image to your repo:

    DOCKER_IMAGE=<your docker registry>/apiclarity DOCKER_TAG=<your tag> make push-docker
  2. Update values.yaml accordingly.

Run locally with demo data

  1. Build the UI and the backend locally.

    make ui && make backend
  2. Copy the built site:

    cp -r ./ui/build ./site
  3. Run the backend and frontend locally using demo data:

    Note: You might need to delete the old local state file and local db:

    rm state.gob; rm db.db
    DATABASE_DRIVER=LOCAL K8S_LOCAL=true FAKE_TRACES=true FAKE_TRACES_PATH=./backend/pkg/test/trace_files \
    ENABLE_DB_INFO_LOGS=true ./backend/bin/backend run

    Note: this command requires a proper KUBECONFIG in your environment when K8S_LOCAL=true is used. If you want to run without Kubernetes, use ENABLE_K8S=false instead.

  4. Open the APIClarity UI in your browser at: http://localhost:8080/

2 - Install demo application

If you want to use a demo application to try APIClarity, you can use the Sock Shop Demo. To deploy the Sock Shop Demo, complete the following steps.

  1. Create the sock-shop namespace and enable Istio injection.

    kubectl create namespace sock-shop
    kubectl label namespaces sock-shop istio-injection=enabled
  2. Deploy the Sock Shop Demo to your cluster.

    kubectl apply -f
  3. Deploy APIClarity in the sock-shop namespace (with the Istio service-mesh traffic source):

    helm repo add apiclarity
    helm install --set 'trafficSource.envoyWasm.enabled=true' --set 'trafficSource.envoyWasm.namespaces={sock-shop}' --create-namespace apiclarity apiclarity/apiclarity --namespace apiclarity
  4. Port forward to Sock Shop’s front-end service to access the Sock Shop Demo App:

    kubectl port-forward -n sock-shop svc/front-end 7777:80
  5. Open the Sock Shop Demo App UI in your browser at http://localhost:7777/ and run some transactions to generate data to review on the APIClarity dashboard.