Installing Contrast Agents within Kubernetes

  • Updated
Contrast has released an Agent Operator for Kubernetes which can simplify the addition of Contrast agents into your environment. More information can be found here in our documentation.


Agent installation guide


This guide offers examples for deploying Contrast Security agents in Kubernetes environments. We encourage you to take this guide, make it your own, and distribute it to teams who need to instrument applications in this way. 

The main portion of the guide details the most popular methods customers use to instrument applications deployed to Kubernetes or its derivatives.


Main steps

You will do the following in this guide:

  1. Adding the Contrast agent
  2. Configure authentication
  3. Configure the agent settings
  4. Deploy applications to Kubernetes

This guide assumes you have:


These instructions will guide you through creating a Contrast configuration using Kubernetes secrets and how to get that configuration into a container via a Kubernetes deployment spec.


1. Adding the Contrast agent

 For agents that can be installed at runtime like Java, NodeJS, .NET and PHP, Contrast publishes images for these agents that can be utilized in docker builds or Kubernetes init containers. You can see the available versions here on Docker Hub or on

In Kubernetes, Init containers can be utilized to mount our agent binaries on a volume for the application container. This method installs the agent directly into the testing environment without the need to modify docker images at an earlier stage.

Example of a Kubernetes deployment with the Java agent:

 - name: myapp
   image: myapp:latest
   - containerPort: 8080
   - name: contrast-volume
     mountPath: /opt/contrast       
     value: "-javaagent:/opt/contrast/contrast-agent.jar -Dcontrast.config.path=/etc/contrast/contrast_security.yaml"
   - name: copy-contrast image: contrast/agent-java
     - mountPath: /opt/contrast
       name: contrast-volume
     command: ["cp", "/contrast/contrast-agent.jar", "/opt/contrast/contrast-agent.jar"]                 
     - name: contrast-volume
       emptyDir: {}

If you'd rather include the agent binaries within the application image, refer to our Docker instructions below. 

  • .NET Core with Docker [here]
  • .NET Framework with Docker [here]
  • Java with Docker [here]
  • Node.js with Docker [here]

For agents that must be added during build time like Python and Ruby. Contrast must be included in the Dockerfile and configured within the source code of the application. 

  • Python with Docker [here]
  • Ruby with Docker [here]


2. Configure authentication

For sensitive credentials, such as the Contrast agent API keys, you should use Kubernetes Secrets. Contrast uses a YAML file to store configuration settings, including the credentials. In this guide, we will store credentials and configuration settings all within a single Secret for convenience. This could also be done separately with both a ConfigMap and a Secret.

There are two options for creating a Kubernetes Secret:

  • Option 1: Manually create a Secret object
  • Option 2: Automatically create a Secret object in the pipeline

Option 1: Manually create a Secret object

Download the contrast_security.yaml file from the Contrast console. This should contain values similar to the following:

 api_key: YOUR_API_KEY
 service_key: YOUR_SERVICE_KEY
  user_name: agent_GUID@OrganizationName

 Then you can run the following command to create the Secret:

$ kubectl create secret generic contrast-security --from-file=./contrast_security.yaml

Option 2: Automatically create a Secret object in the pipeline

First, define the Secret in code by creating the file below. Use your deployment tool to find and replace template variables. You can store the Secret using the following definition:

apiVersion: v1
kind: Secret
 name: contrast-security
type: Opaque
 contrast_security.yaml: |-
     url: {{url}}
     api_key: {{api_key}}
     service_key: {{service_key}}
      user_name: {{user_name}}

Then, create the Secret from this file by running the following command:

$ kubectl apply -f <secret_filename>

After the Secret object is created, we can leverage it within the application deployment. For example, we can mount the Secret as a volume within the container, which makes the contrast_security.yaml file available. Specify the location of this file via the CONTRAST_CONFIG_PATH environment variable to inform the agent of the mounted config:

apiVersion: apps/v1
kind: Deployment
 name: myapp-deployment
   app: myapp
 replicas: 3
     app: myapp
       app: myapp
     - name: contrast-security
         secretName: contrast-security
     - name: myapp
       image: myapp:latest
       - name: "CONTRAST_CONFIG_PATH"
         value: "/etc/contrast/contrast_security.yaml"
       - name: contrast-security
         readOnly: true
         mountPath: "/etc/contrast"
        - containerPort: 80


2. Configure the agent settings

There is some basic information you will want to configure for each application and environment. All available configuration options are fully documented here. This will only cover a small portion of the options available to you. 

Tip: use the Contrast agent configuration editor to create or upload a YAML configuration file, validate YAML, and export environmental variables.

  • Sets the name of the application within the Contrast UI
  • Sets the name of the server in the Contrast UI where the Contrast agent is installed.  With ephemeral containers it can be easier to label these according to it's environment: <container name>.<environment>.<service>.<region>.   


  • server.environment: The environment within the Contrast UI where this server will be identified (development, QA, production).
  • / api.proxy.port: The proxy URL and PORT if required
  • agent.logger.level  agent.logger.path  agent.logger.stdout: Basic logging configuration for the Contrast agent.

There are a few options when adding different properties into your running containers. 

Option 1: Specify them in your deployment file as environmental variables. 

          value: "myApp"
        - name: CONTRAST__SERVER__NAME
          value: ""
          value: "QA"
        - name: CONTRAST_CONFIG_PATH
          value: "/etc/contrast/contrast_security.yaml"
          value: "true"
          value: "INFO"

Options 2: Using a configMap. 

Create a file called with the same environment variables defined.

Create the configMap

kubectl create configmap contrast-config

Update the deployment file to reference the configmap.

      - name: myApp
        image: myApp
          - containerPort: 8080
          - configMapRef:
              name: contrast-config

Some agent languages also have additional methods to add configuration properties to the app.  See the app-specific configuration pages in our docs


Deploy applications to Kubernetes

 At this point you are ready to deploy the application to kubernetes

kubectl apply -f myapp.yaml

Deployment examples

Known Issues


Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request