Installing Contrast Agents within Kubernetes

Agent installation guide

Overview

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:

• Some familiarity with DevOps practices and how Kubernetes works.
• Agent connection and authentication information: Here in our official documentation
  
  

Instructions

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 Quay.io

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.

  containers:
  - name: myapp
    image: myapp:latest
    ports:
    - containerPort: 8080
    volumeMounts:
    - name: contrast-volume
      mountPath: /opt/contrast        
  env:
    - name: JAVA_TOOL_OPTIONS
      value: "-javaagent:/opt/contrast/contrast-agent.jar -Dcontrast.config.path=/etc/contrast/contrast_security.yaml"
  initContainers:
    - name: copy-contrast image: contrast/agent-java
      volumeMounts:
      - mountPath: /opt/contrast
        name: contrast-volume
      command: ["cp", "/contrast/contrast-agent.jar", "/opt/contrast/contrast-agent.jar"]                  
  volumes:
      - 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: 
  url: YOUR_CONTRAST_URL
  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
metadata:
  name: contrast-security
type: Opaque
stringData:
  contrast_security.yaml: |-
    api:
      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
metadata:
  name: myapp-deployment
  labels:
    app: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      volumes:
      - name: contrast-security
        secret:
          secretName: contrast-security
      containers:
      - name: myapp
        image: myapp:latest
        env:
        - name: "CONTRAST_CONFIG_PATH"
          value: "/etc/contrast/contrast_security.yaml"
        volumeMounts:
        - name: contrast-security
          readOnly: true
          mountPath: "/etc/contrast"
        ports:
        - 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.

• application.name: Sets the name of the application within the Contrast UI
• server.name: 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>.   

  Example: myapp.qa.eks.us-east-1

• server.environment: The environment within the Contrast UI where this server will be identified (development, QA, production).
• api.proxy.host / 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. 

env:
        - name: CONTRAST__APPLICATION__NAME
          value: "myApp"
        - name: CONTRAST__SERVER__NAME
          value: "myapp.qa.eks.us-esat-1"
        - name: CONTRAST__SERVER__ENVIRONMENT
          value: "QA"
        - name: CONTRAST_CONFIG_PATH
          value: "/etc/contrast/contrast_security.yaml"
        - name: CONTRAST__AGENT__LOGGER__STDOUT
          value: "true"
        - name: CONTRAST__AGENT__LOGGER__LEVEL
          value: "INFO"

Options 2: Using a configMap. 

Create a file called contrast.properties with the same environment variables defined.

CONTRAST__SERVER__NAME=myapp.qa.eks.us-esat-1
CONTRAST__SERVER__ENVIRONMENT=QA
CONTRAST_CONFIG_PATH=/etc/contrast/contrast_security.yaml
CONTRAST__AGENT__LOGGER__STDOUT=true
CONTRAST__AGENT__LOGGER__LEVEL=INFO

Create the configMap

kubectl create configmap contrast-config --from-env-file=contrast.properties

Update the deployment file to reference the configmap.

    spec:
      containers:
      - name: myApp
        image: myApp
        ports: 
          - containerPort: 8080
        envFrom:
          - 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

• Java agent with Kubernetes
• Node.js Agent with Kubernetes
• .NET Core Agent with Kubernetes

Known Issues

• Problem resolving features when using ISTIO in Kubernetes
• SSL communication issues when using slim images