Kubernetes and Contrast

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 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. Create Kubernetes Secret
2. Configure agents using Secrets
3. Modify deployment to load Contrast configurations
4. Deploy applications to Kubernetes

This guide assumes you have:

• Some familiarity with DevOps practices and how Kubernetes works
• The information needed to connect a Contrast agent for the language you use to the Contrast dashboard: Install an agent
• The Contrast agent is already installed within the container image. See our language-specific deployment guides for more information on installing Contrast in containers:
  .NET Core with Docker [here]
  Java with Docker [here]
  Node.js with Docker [here]
  Python with Docker [here]
  Ruby with Docker [here]

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. Create Kubernetes Secret

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

You can also add any other application or agent-specific configuration information to the contrast_security.yaml file, as described in the Docker deployment guides. 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>

2. Create Kubernetes Deployment

After the Secret object is created, you can leverage it other places within Kubernetes, such as 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

Apply the deployment using the following command:

$ kubectl apply -f <deployment_filename>

FAQ

• How do I display the configuration of the Secret object after I’ve created it?
  To check the contents of the Secret, run the following command:

$ kubectl get secret contrast-security -o yaml

This will give output something like this, where the data is base64 encoded:

apiVersion: v1
data:
  contrast_security.yaml: YXBpOiAKICB1cmw6IFlPVVJfQ09OVFJBU1RfVVJMCiAgYXBpX2tleTogWU9VUl9BUElfS0VZCiAgc2VydmljZV9rZXk6IFlPVVJfU0VSVklDRV9LRVkKICB1c2VyX25hbWU6IGFnZW50X0dVSURAT3JnYW5pemF0aW9uTmFtZQo=
kind: Secret
metadata:
  creationTimestamp: "2020-08-20T13:46:11Z"
  managedFields:
  - apiVersion: v1
fieldsType: FieldsV1
fieldsV1:
   f:data:
     .: {}
     f:contrast_security.yaml: {}
   f:type: {}
manager: kubectl
operation: Update
time: "2020-08-20T13:46:11Z"
  name: contrast-security
  namespace: default
  resourceVersion: "882771"
  selfLink: /api/v1/namespaces/default/secrets/contrast-security
  uid: 9f081ef0-1c7f-4c46-8817-4ac1c43cec71
type: Opaque

You can copy the data section and decode manually, or run the following to output just the data within the secret and base64 decode it:

$ kubectl get secret contrast-security -o=custom-columns=':data.contrast_security\.yaml' | base64 -d

The output will look something like this:

api:
  url: YOUR_CONTRAST_URL
  api_key: YOUR_API_KEY
  service_key: YOUR_SERVICE_KEY
  user_name: agent_GUID@OrganizationName

Known Issues

• SSL communication issues when using slim images