Skip to content

Lightrun on Minikube

Running Lightrun on Kubernetes is generally the same as running it anywhere else.

Since we're an application-level tool by design, Lightrun's installation happens at the application level - in the world of Kubernetes, that means that our agents are meant to be installed inside the Docker image itself and not at the orchestrator level or lower tiers of the infrastructure.

There are 2 main methods to install Lightrun in Kubernetes:

The Lightrun best practice is, without a doubt, the former - adding the Lightrun agent files or using a language's package manager to install the Lightrun agents. As we're an application-level tool, it makes sense for our agents to live next to the application.

However, it might be beneficial to show how one might instrument Lightrun inside an existing application running on Kubernetes without modifying the original image at all. This is great for experimentation purposes and allows for spinning up Lightrun quickly in an existing setting.

In this tutorial, we will follow the full process of installing Lightrun in a simple application deployed to Minikube using an Init Container.


minikube provides a “toy” Kubernetes cluster that is not suitable for anything beyond simple experimentation.


This tutorial requires you to install Minikube on your local machine:

Set Up Lightrun to run in Minicube

As a short reminder, Minikube is a CLI tool that provisions and manages the lifecycle of single-node Kubernetes clusters running inside Virtual Machines (VM), on your local system.

Start a local Kubernetes cluster

Minikube takes care of all the bootstrapping steps for you. To start a local cluster, run:

minikube start
Starting Minikube
Starting Minikube

The initialization process takes several minutes as it retrieves any necessary dependencies and executes various container images.

Verify the status of your cluster

To make sure everything in Minikube works as expected, run:

minikube status

You should see a status message that looks similar to this one:

Minikube status message
Minikube status message

Launch the Minikube dashboard

In another terminal, launch the dashboard:

minikube dashboard

The operating system's default browser opens and displays the dashboard.

Minikube dashboard
Minikube dashboard

Deploy a sample Java application with Lightrun

The application we'll use in this tutorial is a simple prime number checker - it goes through a range of numbers, and then outputs the number of prime numbers in that range at the end of the application’s run.

Let's first containerize the application - you can get a copy of the Dockerfile here as well. Note that we have not installed the agent just yet - we'll take care of it using an Init Container later, in the deployment:

FROM openjdk:11
COPY /app
RUN javac -g
RUN jar --create --file /app/PrimeMain.jar --main-class PrimeMain PrimeMain.class
ENTRYPOINT ["java", "-jar"]

Now that we have our Dockerfile, we need to build it.

Note that Minikube ships with its own Docker daemon, that has its image registry. We can make that registry the default by running the following command:

eval $(minikube -p minikube docker-env)

This will allow us to build the image locally and have it accessible to Minikube - preventing us from the need to use Docker Hub or any other external repository.

We can now build the image and push it to the local registry:

docker build -t primeapp .

Let's now add your organization details as secrets - save the following file as secrets.yaml or download it from here:

apiVersion: v1
kind: Secret
  name: app-secret
  lightrun_key: <LIGHTRUN_KEY>
  lightrun_company: <LIGHTRUN_COMPANY_ID>

You should have received your LIGHTRUN_KEY and LIGHTRUN_COMPANY_ID during the onboarding process. If not, you can get them again from the web console's agent setup page:

Get your organization details
Get your organization details

Now it's time to prepare our Kubernetes deployment - save it as a file called deployment.yaml or download it from here:

apiVersion: apps/v1
kind: Deployment
  name: app
    app: app
  replicas: 1
      app: app
        app: app
      - name: lightrun-installer
        image: curlimages/curl
        - name: LIGHTRUN_KEY
              name: app-secret
              key: lightrun_key
        - name: LIGHTRUN_COMPANY
              name: app-secret
              key: lightrun_company
        command: ["/bin/sh", "-c"]
        args: ["curl -o /tmp/ -L$LIGHTRUN_COMPANY/; cd /tmp; sh /tmp/"]
        - name: init-script
          mountPath: /tmp/
      - name: app
        image: primeapp
        args: ["-agentpath:/lightrun/agent/", "/app/PrimeMain.jar"]
        - name: init-script
          mountPath: /lightrun
      - name: init-script
        emptyDir: {}

What happens under the hood here is that the Init container downloads the Lightrun agent and then, via the shared volume, delivers it to your main application. In addition, we're supplying a new JVM argument - -agentpath - to the container's entry point command to ensure the application spins up with Lightrun.

Apply the resources

Finally, we can now apply both of these resources to the cluster:

kubectl apply -f secrets.yaml
kubectl apply -f deployment.yaml

Once the pod has finished initialization stage, you should see it up and ready in the minikube dashboard:

Dashboard showing the pod
Dashboard showing the pod

Check that agent was connected via the Lightrun web console:

Lightrun web console with the agent showing
Lightrun web console with the agent showing

And now you've got a Lightrun agent up and running! Install our plugin to get started adding Lightrun Actions to your application.


Just a quick reminder - Init Containers could increase the time it takes your application to start. Installing Lightrun via Init Containers is acceptable for local testing, but not for production usage. You should "bake" the Lightrun agent into your application when preparing it for production.

Last update: May 20, 2024