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:
- Adding the Contrast agent
- Configure authentication
- Configure the agent settings
- 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.
Example of a Kubernetes deployment with the Java agent:
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.
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: |
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 |
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 |
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 requiredagent.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
Known Issues
- Problem resolving features when using ISTIO in Kubernetes
- SSL communication issues when using slim images