24/07/2023 • Jan Beerden

Do you need a custom container image to include the New Relic agent jar in Kubernetes?

“ Are we building a custom container image simply to include the New Relic agent jar? ”
That was the question we asked ourselves the last time we were updating one of our Atlassian applications. When you are working with a container image that is built and provided by the application vendor, creating a new custom image just to include the New Relic agent jar for each application and each New Relic agent version can be a tedious and time-consuming task.


To implement this alternative approach, there are a few requirements that must be met:

  1. You must be deploying the container in a Kubernetes cluster.
  2. The application must support adding JVM parameters via an environment variable.

Starting Point

Let's assume that your application is using a StatefulSet that looks something like this:

The name of the JAVA_OPTS environment variable may vary depending on the specific application.

Packaging the New Relic agent jar

To simplify the deployment process, we will create  a custom image which contains the New Relic agent jar. To create this image, we will use  a Container File, which might look something like this:

"Injecting" the New Relic agent into the application container

In order to direct the application to use the New Relic agent jar, we will utilize the Kubernetes Init Container and emptyDir concepts.

The resulting StatefulSet will look like this:

Instead of including the New Relic agent jar in the application image, we use our custom newrelic-agent image as an Init Container. This container copies the newrelic.jar file to an emptyDir volume.

Since the Init Container runs before the regular application container and both share the same volume, the newrelic.jar file is accessible when the JVM starts.

Apart from the shared volume, we need a few New Relic agent specific environment variables:

  • NEW_RELIC_APP_NAME: to set the application name
  • NEW_RELIC_LICENSE_KEY: to provide the license key
  • NEW_RELIC_LOG_FILE_NAME: to optionally set a non-default log location, in this case STDOUT

There are a few additional environment variables available in the New Relic Java agent documentation that can be used.

In addition to this basic configuration, you can use the New Relic server-side agent configuration.

As you can see in the JAVA_OPTS environment variable, we still need to instruct the JVM to use the New Relic agent jar. It’s worth mentioning that this particular file is located on the shared volume.

Also note the "imagePullPolicy" which we have set to "Always" to ensure we always retrieve the latest image version even if it is still using the same tag.

Updating the New Relic agent

To ensure that the New Relic agent is always up-to-date, you can set up a Continuous Integration pipeline that automatically builds a new container image whenever a new agent version becomes available. 

Additionally, you can tag the image with major, major.minor, and major.minor.patch, in addition to "latest". This allows you to pin the agent version based on the specific requirements of your application.

Depending on the image tag specified in the application's manifest file, updating could be as easy as restarting the application pods.

If you prefer to pin the New Relic agent to a specific version, you will need to update the newrelic-agent image tag in the StatefulSet and deploy this change to your Kubernetes cluster.

In any case, you no longer need to build a custom image just to add the New Relic agent jar, which should allow for more frequent updates to the agent.


Do you want to discover more about Kubernetes?