CloudFormation

Sysdig provides the following YAML template for the Serverless Workload Agent:

• instrumentation.yaml: Deploys the instrumentation service that instruments your workload template.

The instrumentation service leverages serverless-patcher, a Sysdig containerized tool that automates the instrumentation CloudFormation templates.

Run the template instrumentation service either in the cloud or locally and integrate it into your CI/CD pipeline.

Prerequisites

Review the Installation Requirements before getting started.

Deploy the Instrumentation Stack

1. Push the latest image of serverless-patcher to a private ECR repository within the same region where the deployment will take place.

2. Log in to the AWS Console, select CloudFormation, and create a stack with new resources.

3. Specify the instrumentation.yaml as the Template source.

   • The name of the Macro must be unique in your account.
   • The serverless-patcher image must be hosted in an ECR private repo within the same region in which the deployment takes place.

4. Provide the stack details to deploy the Instrumentation Service:

   • Instrumentation Priority: Supported options are availability (by default) or security.
     • In security mode, the Workload Agent aims to process every syscall event and will prevent the workloads from running unsecured. Consequently, secured applications will not execute until the Workload Agent receives the runtime policies.
     • The availability mode instead facilitates resource sharing between the Workload Agent and the workload containers, enabling the Workload Agent to detect when resource pressure exceeds configurable limits and pause event processing to reduce pressure.
   • Sidecar Essential Flag: If marked as essential, ECS will stop all containers in the task if the sidecar exits. The sidecar container is marked as essential in security mode by default to prevent secured workloads from running unsecured.
   • Sidecar CPU Units and Memory Limit/Reservation: The settings can be adjusted to allocate dedicated CPU units and memory resources/limits to the sidecar container.

5. Complete the stack creation and wait for the deployment to complete.

6. When complete, note the SysdigInstrumentationMacro from the Stack outputs tab.

Instrument the Workload Stack

The instrumentation process includes inspecting the images of the containers in the TaskDefinition to patch the entrypoint and command of them. If your workload containers are using images from private registries, you must explicitly provide the original entrypoint and command for each container.

1. Copy and paste the Transformation Macro string from the Sysdig Instrumentation stack output to the root level of your workload stack template.
2. Deploy your instrumented workload template. The Sysdig instrumentation service will go over the workload template to instrument it.

Upgrade the Workload Agent

The Workload Agent version can be upgraded by updating the Instrumentation Stack with the latest image of serverless-patcher specified as Sysdig Serverless Patcher Image and Workload Agent specified as Sysdig Workload Agent Image. These versions do not need to match but it is recommended to use consistent versions.

Once the Instrumentation Stack has been updated, the Workload Stack should be deleted and recreated.

Next Steps

After the deployment is completed, security-related events will be visible in the Sysdig Secure Events feed.

Optionally, you can perform advanced Configuration steps.

Use the Serverless Patcher

The Sysdig serverless-patcher tool lets you instrument your CloudFormation templates when installing the Sysdig Serverless Agent for ECS on Fargate. You can run serverless-patcher both in the cloud and locally, and it can be integrated with your CI/CD pipeline or automation tools to instrument templates automatically before deploying them to your staging environment.

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

Instrument your CloudFormation Templates

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
   

   The above command runs serverless-patcher locally and instruments your CloudFormation template.

   You need to replace:

   • /path/to/src/template with the path to your original CloudFormation template
   • /path/to/out/template with the path to the output instrumented template.
   • /host/path/template with the path to the folder containing the original template on your local machine.

   Additionally, you can pass the following environment variables to the command to configure serverless-patcher:

   • SYSDIG_COLLECTOR: The Collector Host.
   • SYSDIG_COLLECTOR_PORT: The Collector port. The default value is 6443.
   • SYSDIG_ACCESS_KEY: Sysdig Agent access key
   • SYSDIG_WORKLOAD_AGENT_IMAGE: The Workload Agent image to instrument workload containers. Each release defines the proper version.
   • SYSDIG_LOGGING: The Sysdig Instrumentation login level. The supported values are silent, fatal, critical, error, warning, info, debug, trace.

   Once the command finishes executing, you should have a new CloudFormation template with the same name as the original but with _instrumented appended to it. You can use this instrumented template to deploy your workload to AWS.

   You can use this to instrument your CloudFormation templates as part of your CI/CD pipeline.

Legacy Support

The Orchestrator Agent will be deprecated in an upcoming release. However, you can use it as a proxy connection between the Workload Agent and the Sysdig Collector in Agent version 5.3.0.

Sysdig providess the following YAML template for the Serverless Orchestrator and Workload Agents:

• orchestrator-agent.yaml: Use this file to deploy the stack running the Orchestrator Agent.
• instrumentation.yaml: Use this file to deploy the instrumentation service that instruments your workload template with the Orchestrator Agent as a proxy.

Deploy the Orchestrator Agent

1. Log in to the AWS Console.

2. Open CloudFormation and create a new stack.

3. Upload the orchestrator-agent.yaml file as the template.

4. Provide the required parameters, such as the VPC where your service runs.

5. Complete the stack creation and wait for the deployment to complete.

   

6. When the deployment is complete, note the orchestrator host and port values in the stack outputs.

Configure the Workload Agent

To configure the Workload Agent to use the Orchestrator Agent, set the following environment variables when running the serverless patcher command:

• SYSDIG_ORCHESTRATOR_HOST: The Orchestrator Agent Host.
• SYSDIG_ORCHESTRATOR_PORT: The Orchestrator Agent’s port. The default value is 6667.

These variables replace SYSDIG_COLLECTOR and SYSDIG_COLLECTOR_PORT.