chore(docs): Add Serverless Agent examples (#547)

examples/serverless-agent/fargate/orchestrator/README.md

@@ -0,0 +1,27 @@
+# Serverless Orchestrator Agent
+
+This example deploys an AWS ECS Fargate cluster to run the Serverless Orchestrator Agent. This Agent acts as a proxy between the Collector and many Serverless Workload Agents.
+
+## Prerequisites
+
+The following AWS prerequisites are required to deploy this cluster:
+- VPC
+- 2 subnets
+
+## Components
+
+The cluster will be called `<prefix>-cluster` and will deploy the following:
+- 1 Service (called `OrchestratorAgent`)
+  - 1 Task (with the latest version of the Serverless Orchestrator Agent)
+- Network Load balancer
+- Cloudwatch log group
+- Security group
+
+## Layout
+| **File** | **Purpose** |
+| --- | --- |
+| `main.tf` | AWS provider configuration |
+| `orchestrator.tf` | Orchestrator cluster definition |
+| `output.tf` | Defines the output variables |
+| `variables.tf` | AWS and Agent configuration |
+| `versions.tf` | Defines TF provider versions |

examples/serverless-agent/fargate/orchestrator/orchestrator.tf

@@ -0,0 +1,36 @@
+module "fargate-orchestrator-agent" {
+  source  = "sysdiglabs/fargate-orchestrator-agent/aws"
+  version = "0.5.0"
+
+  vpc_id  = var.vpc_id
+  subnets = [var.subnet_1, var.subnet_2]
+
+  access_key = var.access_key
+
+  collector_host = var.collector_host
+  collector_port = var.collector_port
+
+  name        = var.prefix
+  agent_image = var.agent_orchestrator_image
+
+  # True if the VPC uses an InternetGateway, false otherwise
+  assign_public_ip = true
+
+  tags = var.tags
+}
+
+
+data "aws_ecs_cluster" "fargate-orchestrator" {
+  depends_on = [
+    module.fargate-orchestrator-agent
+  ]
+  cluster_name = "${var.prefix}-cluster"
+}
+
+data "aws_ecs_service" "orchestrator-service" {
+  depends_on = [
+    module.fargate-orchestrator-agent
+  ]
+  service_name = "OrchestratorAgent"
+  cluster_arn  = data.aws_ecs_cluster.fargate-orchestrator.arn
+}

examples/serverless-agent/fargate/orchestrator/output.tf

@@ -0,0 +1,11 @@
+output "orchestrator_cluster_name" {
+  value = data.aws_ecs_cluster.fargate-orchestrator.cluster_name
+}
+
+output "orchestrator_cluster_arn" {
+  value = data.aws_ecs_cluster.fargate-orchestrator.arn
+}
+
+output "orchestrator_service_arn" {
+  value = data.aws_ecs_service.orchestrator-service.arn
+}

examples/serverless-agent/fargate/orchestrator/providers.tf

@@ -0,0 +1,4 @@
+provider "aws" {
+  region  = var.region
+  profile = var.profile
+}

examples/serverless-agent/fargate/orchestrator/variables.tf

@@ -0,0 +1,51 @@
+# AWS configuration
+variable "prefix" {
+  description = "All resources created by Terraform have this prefix prepended to them"
+}
+
+variable "profile" {
+  description = "AWS profile name"
+  type        = string
+}
+
+variable "region" {
+  description = "AWS Region for deployment"
+  default     = "us-east-1"
+}
+
+variable "subnet_1" {
+  description = "Subnet-1 Id"
+}
+
+variable "subnet_2" {
+  description = "Subnet-2 Id"
+}
+
+variable "vpc_id" {
+  description = "VPC Id"
+}
+
+variable "tags" {
+  type        = map(string)
+  description = "Tags to assign to resources in module"
+  default     = {}
+}
+
+# Serverless Agent Configuration
+variable "access_key" {
+  description = "Sysdig Agent access key"
+}
+
+variable "agent_orchestrator_image" {
+  description = "Orchestrator Agent image to use"
+  default     = "quay.io/sysdig/orchestrator-agent:latest"
+}
+
+variable "collector_host" {
+  description = "Collector host where agent will send the data"
+}
+
+variable "collector_port" {
+  description = "Collector port where agent will send the data"
+  default     = "6443"
+}

examples/serverless-agent/fargate/orchestrator/versions.tf

@@ -0,0 +1,18 @@
+terraform {
+  required_version = ">=1.7.2"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.35.0"
+    }
+    local = {
+      source  = "hashicorp/local"
+      version = "~> 2.4.1"
+    }
+    sysdig = {
+      source  = "sysdiglabs/sysdig"
+      version = "~> 1.24.5"
+    }
+  }
+}

examples/serverless-agent/fargate/workload/README.md

@@ -0,0 +1,28 @@
+# Workload with Serverless Workload Agent
+
+This example deploys a cluster with a workload and the Serverless Workload Agent as a sidecar to secure the workload.
+
+## Prerequisites
+
+The following prerequisites are required to deploy this cluster:
+- Orchestrator Agent deployed
+- VPC
+- 2 subnets
+
+## Components
+
+The cluster will be called `<prefix>-instrumented-workload` and will deploy the following:
+- 1 Service (called `<prefix-instrumented-service`)
+  - 1 Task (with the latest version of the Serverless Orchestrator Agent)
+    - 1 container named `event-gen-1` running `falcosecurity/event-generator`
+    - 1 container named `event-gen-2` also running `falcosecurity/event-generator`
+    - 1 container named `SysdigInstrumentation` running the Workload Agent which will secure both workload containers
+
+## Layout
+| **File** | **Purpose** |
+| --- | --- |
+| `instrumented_load.tf` | Workload definition. By default it instruments `falcosecurity/event-generator` |
+| `main.tf` | AWS provider configuration |
+| `output.tf` | Defines the output variables |
+| `variables.tf` | AWS and Agent configuration |
+| `versions.tf` | Defines TF provider versions |

examples/serverless-agent/fargate/workload/instrumented_load.tf

@@ -0,0 +1,145 @@
+data "sysdig_fargate_workload_agent" "containers_instrumented" {
+  container_definitions = jsonencode([
+    {
+      "name" : "event-gen-1",
+      "image" : "falcosecurity/event-generator",
+      "command" : ["run", "syscall", "--all", "--loop"],
+      "logConfiguration" : {
+        "logDriver" : "awslogs",
+        "options" : {
+          "awslogs-group" : aws_cloudwatch_log_group.instrumented_logs.name,
+          "awslogs-region" : var.region,
+          "awslogs-stream-prefix" : "task"
+        },
+      }
+    },
+    {
+      "name" : "event-gen-2",
+      "image" : "falcosecurity/event-generator",
+      "command" : ["run", "syscall", "--all", "--loop"],
+      "logConfiguration" : {
+        "logDriver" : "awslogs",
+        "options" : {
+          "awslogs-group" : aws_cloudwatch_log_group.instrumented_logs.name,
+          "awslogs-region" : var.region,
+          "awslogs-stream-prefix" : "task"
+        },
+      }
+    }
+  ])
+
+  workload_agent_image = var.agent_workload_image
+
+  sysdig_access_key = var.access_key
+  orchestrator_host = var.orchestrator_host
+  orchestrator_port = var.orchestrator_port
+
+  log_configuration {
+    group         = aws_cloudwatch_log_group.instrumented_logs.name
+    stream_prefix = "instrumentation"
+    region        = var.region
+  }
+}
+
+resource "aws_ecs_task_definition" "task_definition" {
+  family             = "${var.prefix}-instrumented-task-definition"
+  task_role_arn      = aws_iam_role.task_role.arn
+  execution_role_arn = aws_iam_role.execution_role.arn
+
+  cpu                      = "256"
+  memory                   = "512"
+  network_mode             = "awsvpc"
+  requires_compatibilities = ["FARGATE"]
+  pid_mode                 = "task"
+
+  container_definitions = data.sysdig_fargate_workload_agent.containers_instrumented.output_container_definitions
+}
+
+
+resource "aws_ecs_cluster" "cluster" {
+  name = "${var.prefix}-instrumented-workload"
+}
+
+resource "aws_cloudwatch_log_group" "instrumented_logs" {
+}
+
+data "aws_iam_policy_document" "assume_role_policy" {
+  statement {
+    actions = ["sts:AssumeRole"]
+
+    principals {
+      type        = "Service"
+      identifiers = ["ecs-tasks.amazonaws.com"]
+    }
+  }
+}
+
+resource "aws_iam_role" "execution_role" {
+  assume_role_policy = data.aws_iam_policy_document.assume_role_policy.json
+
+  managed_policy_arns = ["arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"]
+}
+
+resource "aws_iam_role" "task_role" {
+  assume_role_policy = data.aws_iam_policy_document.assume_role_policy.json
+
+  inline_policy {
+    name   = "root"
+    policy = data.aws_iam_policy_document.task_policy.json
+  }
+}
+
+data "aws_iam_policy_document" "task_policy" {
+  statement {
+    actions = [
+      "ecr:GetAuthorizationToken",
+      "ecr:BatchCheckLayerAvailability",
+      "ecr:GetDownloadUrlForLayer",
+      "ecr:BatchGetImage",
+      "logs:CreateLogGroup",
+      "logs:CreateLogStream",
+      "logs:PutLogEvents",
+    ]
+
+    resources = ["*"]
+  }
+}
+
+resource "aws_ecs_service" "service" {
+  name = "${var.prefix}-instrumented-service"
+
+  cluster          = aws_ecs_cluster.cluster.id
+  task_definition  = aws_ecs_task_definition.task_definition.arn
+  desired_count    = var.replicas
+  launch_type      = "FARGATE"
+  platform_version = "1.4.0"
+
+  network_configuration {
+    subnets          = [var.subnet_1, var.subnet_2]
+    security_groups  = [aws_security_group.security_group.id]
+    assign_public_ip = true
+  }
+}
+
+resource "aws_security_group" "security_group" {
+  description = "${var.prefix}-security-group"
+  vpc_id      = var.vpc_id
+}
+
+resource "aws_security_group_rule" "orchestrator_agent_ingress_rule" {
+  type              = "ingress"
+  protocol          = "tcp"
+  from_port         = 0
+  to_port           = 0
+  cidr_blocks       = ["0.0.0.0/0"]
+  security_group_id = aws_security_group.security_group.id
+}
+
+resource "aws_security_group_rule" "orchestrator_agent_egress_rule" {
+  type              = "egress"
+  protocol          = "all"
+  from_port         = 0
+  to_port           = 0
+  cidr_blocks       = ["0.0.0.0/0"]
+  security_group_id = aws_security_group.security_group.id
+}

examples/serverless-agent/fargate/workload/output.tf

@@ -0,0 +1,15 @@
+output "workload_cluster_name" {
+  value = aws_ecs_cluster.cluster.name
+}
+
+output "workload_cluster_arn" {
+  value = aws_ecs_cluster.cluster.arn
+}
+
+output "service_arn" {
+  value = aws_ecs_service.service.id
+}
+
+output "task_revision" {
+  value = aws_ecs_task_definition.task_definition.revision
+}

examples/serverless-agent/fargate/workload/providers.tf

@@ -0,0 +1,4 @@
+provider "aws" {
+  region = var.region
+  profile = var.profile
+}