Serverless Patcher

The Sysdig serverless-patcher tool allows you to instrument your CloudFormation templates.

serverless-patcher can run both in the cloud and locally. You can also integrate the serverless-patcher as part of your CI/CD pipeline or automations to automatically instrument templates right before deploying them to your staging environment.

The following instructions describe how to run serverless-patcher locally. If you want to run it in the cloud, refer to Deploy the Instrumentation Stack

What does patching a CloudFormation template mean?

Patching a CloudFormation template means performing the following changes to its TaskDefinition:

• Adding a sidecar container that exposes a volume to provide the Sysdig workload agent to the workload containers;
• Making each workload container mount a data volume from the sidecar container;
• Modifying the original entrypoint of each workload container to run the Sysdig instrumentation into it;
• Adding the Linux capability SYS_PTRACE to each workload container.
• Adding the Sysdig environment variables to each workload container.

How to instrument CloudFormation Templates

serverless-patcher is a containerized application you can download and execute locally in your computer or environment.

At this time, serverless-patcher handles JSON files only. If you use YAML templates you can easily convert them to JSON, apply the instrumentation and then flip back them to YAML again.

1. Download the latest version of serverless-patcher:

   docker pull quay.io/sysdig/serverless-patcher:latest
   

2. Instrument your workload template:

   docker run -e KILT_MODE="local" -e KILT_SRC_TEMPLATE="/path/to/src/template" -e KILT_OUT_TEMPLATE="/path/to/out/template" [OPTIONS] -v /host/path/template:/path/template quay.io/sysdig/serverless-patcher:latest
   

Common environment variables are:

serverless-patcher can be further configured as described below.

Configuration Options

Sysdig Environment Variables Parameterization

Since the Orchestrator Host and Port could be unknown at instrumentation time, serverless-patcher can be configured to parameterize the Sysdig environment variables in the instrumented workload template.

The option that follows enables the parameterization of the Sysdig environment variables.

For example:

docker run [OPTIONS] -e SYSDIG_ORCHESTRATOR_HOST="my.orchestrator.host.com" -e KILT_PARAMETERIZE_ENVARS="true" -v /host/path/template:/path/template quay.io/sysdig/serverless-patcher:latest

will produce the following template:

Parameters:
  ...
  sysdigOrchestrator:
    Default: "my.orchestrator.host.com"
    Type: "String"

Resources:
  MyTaskDefinition:
    Type: AWS::ECS::TaskDefinition
    ...
    ContainerDefinitions:
      - Name: "myWorkloadContainer"
        Environment:
          - Name: "SYSDIG_ORCHESTRATOR"
            Value: !Ref sysdigOrchestrator
            ...

Public vs Private Registries

serverless-patcher inspects the workload image to patch the entrypoint/command.

If the workload image is hosted in a public repo, no additional options are required. Instead, if the workload image is hosted in a private repo, serverless-patcher needs authentication credentials to pull the workload image.

To provide serverless-patcher with authentication credentials, mount the host ~/.docker/config.json directory to /tmp/.docker.

Alternatively, you will need to explicitly define the entrypoint/command of the workload container in the template before running serverless-patcher.

If serverless-patcher fails to pull the image, the instrumentation of the entrypoint/command fails and the resulting container looks as follows:

MyTaskDefinition:
    Type: AWS::ECS::TaskDefinition
    ...
    ContainerDefinitions:
      - Name: "myWorkloadContainer"
        Command: [],
        Entrypoint: ["/opt/draios/bin/instrument"],
        ...

Configure the Instrumentation AWS LogGroup

serverless-patcher can be configured to store instrumentation logs in a certain log group. The log group must already exist if the workload task does not have the permission to create a new one.

OptIn/OptOut Containers

serverless-patcher supports two modes of operation:

• OptOut: Explicit consensus to instrument containers is not required (default - all the containers in the TaskDefinition will be instrumented)
• OptIn: Explicit consensus to instrument containers is required

To enable the OptIn mode, use the following configuration option:

OptOut

OptOut means serverless-patcher will instrument all the containers by default. You can configure serverless-patcher to skip certain containers by adding the special tags that follow in the TaskDefinition:

• kilt-ignore: <any_value> prevents serverless-patcher from instrumenting all the containers in the TaskDefinition;
• kilt-ignore-containers: "container_A_name:container_B_name:..." colon-separated list of containers to skip.

For example, the snippet below configures serverless-patcher to skip the containers containerA and containerB. The other containers containerC and containerD will be instrumented.

TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      Tags:
        - Key: "kilt-ignore-containers"
          Value: "containerA:containerB"
      ContainerDefinitions:
        - Name: containerA
          ...
        - Name: containerB
          ...
        - Name: containerC
          ...
        - Name: containerD
          ...

OptIn

OptIn means serverless-patcher won’t instrument any containers by default. You can include containers by adding the special tags that follow in the TaskDefinition:

• kilt-inclulde: <any_value> configures serverless-patcher to instrument all the containers in the TaskDefinition;
• kilt-include-containers: "container_A_name:container_B_name:..." colon-separated list of containers to instrument.

For example, the snippet below configures serverless-patcher (running in OptIn mode) to instrument containerAand containerB. The other containers containerB and containerC won’t be instrumented.

TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      Tags:
        - Key: "kilt-include-containers"
          Value: "containerA:containerB"
      ContainerDefinitions:
        - Name: containerA
          ...
        - Name: containerB
          ...
        - Name: containerC
          ...
        - Name: containerD
          ...