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.
Download the latest version of serverless-patcher:
docker pull quay.io/sysdig/serverless-patcher:latest
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:
Environment Variable | Required | Default | Description |
---|---|---|---|
KILT_MODE | Yes | `` | Use local to run `serverless-patcher locally. |
KILT_SRC_TEMPLATE | Yes | `` | The container path to the input template, you will need to bind mount the host folder/file. |
KILT_OUT_TEMPLATE | Yes | `` | The container’s path to the output template, you will need to bind mount the host folder/file. |
SYSDIG_ORCHESTRATOR_HOST | No | `` | The Orchestrator Agent Host. |
SYSDIG_ORCHESTRATOR_PORT | No | `` | The Orchestrator Agent’s port, the Sysdig default value is 6667 . |
SYSDIG_WORKLOAD_AGENT_IMAGE | No | quay.io/sysdig/workload-agent:X.Y.Z | The Workload Agent image to instrument workload containers. Each release defines the proper X.Y.Z version. |
SYSDIG_LOGGING | No | info | The Sysdig Instrumentation login level. The supported values are silent , fatal , critical , error , warning , info , debug , trace . |
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.
Environment Variable | Required | Default | Description |
---|---|---|---|
KILT_PARAMETERIZE_ENVARS | No | false | Use true to enable 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.
Environment Variable | Required | Default | Description |
---|---|---|---|
KILT_LOG_GROUP | No | `` | The AWS CloudWatch Log Group to store the Instrumentation logs. |
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:
Environment Variable | Required | Default | Description |
---|---|---|---|
KILT_OPT_IN | No | `` | Use true to enable the OptIn mode. |
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>
preventsserverless-patcher
from instrumenting all the containers in theTaskDefinition
;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>
configuresserverless-patcher
to instrument all the containers in theTaskDefinition
;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 containerA
and 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
...
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.