Add aks example

Author: Arnas Navašinskas

examples/aks/aks_cluster_with_security_runtime_rules/README.MD

@@ -0,0 +1,49 @@
+# Example of AKS cluster connected to CAST AI with enabled Kvisor security agent and customized runtime security rules
+Following example creates AKS cluster and its supporting resources.\
+After AKS cluster is created it is onboarded to CAST AI.\
+[Kvisor security agent](https://docs.cast.ai/docs/kvisor) is deployed to the cluster and security policies are enabled.\
+See `install_security_agent` and `kvisor_values` variables in `castai.tf` file enabling Kvisor.\
+See `castai_security_runtime_rule` resource defining example [Runtime security rule](https://docs.cast.ai/docs/anomaly-rules-engine) in `castai_runtime_rules.tf` file.\
+Example configuration should be analysed in the following order:
+1. Create Virtual network - `vnet.tf`
+2. Create AKS cluster - `aks.tf`
+3. Create CAST AI related resources to connect GKE cluster to CAST AI with [Kvisor security agent](https://docs.cast.ai/docs/kvisor) enabled - `castai.tf`
+4. Create CAST AI Runtime security rules - `castai_runtime_rules.tf`
+5. If needed - import existing CAST AI runtime rules with `fetch_castai_runtime_rules.sh` script.\
+   Script will generate terraform resources and will print terraform import commands to the console.\
+   \
+   In order to import - set your API key and optionally the base URL:
+   ```
+   export CASTAI_API_KEY="your-api-key-here"
+   export CASTAI_BASE_URL="https://api.cast.ai"  # Optional, default is https://api.cast.ai
+   ```
+   Run the script (it requires jq installed):
+   ```
+   # Fetch all rules
+   ./fetch_castai_runtime_rules.sh
+   
+   # Fetch only already enabled rules
+   ./fetch_castai_runtime_rules.sh --enabled-only
+   ```
+   Output:\
+   Terraform resources are saved to `castai_runtime_rules.tf.example`\
+   Copy wanted runtime rules from `castai_runtime_rules.tf.example` to `castai_runtime_rules.tf` file.\
+   Terraform import commands are printed to console, you need to import newly added resources to terraform state before running any other commands.
+
+# Terraform Usage
+1. Rename `tf.vars.example` to `tf.vars`
+2. Update `tf.vars` file with your cluster name, cluster region and CAST AI API token.
+3. Initialize Terraform. Under example root folder run:
+```
+terraform init
+```
+4. Run Terraform apply:
+```
+terraform apply -var-file=tf.vars
+```
+5. To destroy resources created by this example:
+```
+terraform destroy -var-file=tf.vars
+```
+
+Please refer to this guide if you run into any issues https://docs.cast.ai/docs/terraform-troubleshooting

examples/aks/aks_cluster_with_security_runtime_rules/aks.tf

@@ -0,0 +1,25 @@
+# 2. Create AKS cluster.
+
+resource "azurerm_kubernetes_cluster" "this" {
+  name                = var.cluster_name
+  resource_group_name = azurerm_resource_group.this.name
+  location            = azurerm_resource_group.this.location
+  dns_prefix          = var.cluster_name
+  node_resource_group = "${var.cluster_name}-ng"
+
+  default_node_pool {
+    name = "default"
+    # Node count has to be > 2 to successfully deploy CAST AI controller.
+    node_count     = 2
+    vm_size        = "Standard_D2_v2"
+    vnet_subnet_id = azurerm_subnet.internal.id
+  }
+
+  identity {
+    type = "SystemAssigned"
+  }
+
+  tags = {
+    Environment = "Test"
+  }
+}

examples/aks/aks_cluster_with_security_runtime_rules/castai.tf

@@ -0,0 +1,87 @@
+# 3. Connect AKS cluster to CAST AI with enabled Kvisor security agent.
+
+# Configure Data sources and providers required for CAST AI connection.
+data "azurerm_subscription" "current" {}
+
+# Configure AKS cluster connection to CAST AI using CAST AI aks-cluster module with enabled Kvisor security agent.
+module "castai-aks-cluster" {
+  source = "castai/aks/castai"
+
+  kvisor_grpc_addr = var.kvisor_grpc_addr
+
+  # Kvisor is an open-source security agent from CAST AI.
+  # install_security_agent by default installs Kvisor controller (k8s: deployment)
+  # https://docs.cast.ai/docs/kvisor
+  install_security_agent = true
+
+  # Kvisor configuration examples, enable certain features:
+  kvisor_values = [
+    yamlencode({
+      controller = {
+        extraArgs = {
+          # UI: Vulnerability management configuration = API: IMAGE_SCANNING
+          "image-scan-enabled" = true
+          # UI: Compliance configuration = API: CONFIGURATION_SCANNING
+          "kube-bench-enabled"  = true
+          "kube-linter-enabled" = true
+        }
+      }
+
+      # UI: Runtime Security = API: RUNTIME_SECURITY
+      agent = {
+        # In order to enable Runtime security set agent.enabled to true.
+        # This will install Kvisor agent (k8s: daemonset)
+        # https://docs.cast.ai/docs/sec-runtime-security
+        "enabled" = true
+
+        extraArgs = {
+          # Runtime security configuration examples:
+          # By default, most users enable the eBPF events and file hash enricher.
+          # For all flag explanations and code, see: https://github.com/castai/kvisor/blob/main/cmd/agent/daemon/daemon.go
+          "ebpf-events-enabled"        = true
+          "file-hash-enricher-enabled" = true
+          # other examples
+          "netflow-enabled"              = false
+          "netflow-export-interval"      = "30s"
+          "ebpf-program-metrics-enabled" = false
+          "prom-metrics-export-enabled"  = false
+          "prom-metrics-export-interval" = "30s"
+          "process-tree-enabled"         = false
+        }
+      }
+    })
+  ]
+
+  # Deprecated, leave this empty, to prevent setting defaults.
+  kvisor_controller_extra_args = {}
+
+  # Everything else...
+
+  wait_for_cluster_ready = false
+
+  install_workload_autoscaler = false
+  install_pod_mutator         = false
+  delete_nodes_on_disconnect  = var.delete_nodes_on_disconnect
+
+  api_url          = var.castai_api_url
+  castai_api_token = var.castai_api_token
+  grpc_url         = var.castai_grpc_url
+
+  aks_cluster_name    = var.cluster_name
+  aks_cluster_region  = var.cluster_region
+  node_resource_group = azurerm_kubernetes_cluster.this.node_resource_group
+  resource_group      = azurerm_kubernetes_cluster.this.resource_group_name
+
+  subscription_id = data.azurerm_subscription.current.subscription_id
+  tenant_id       = data.azurerm_subscription.current.tenant_id
+
+  default_node_configuration = module.castai-aks-cluster.castai_node_configurations["default"]
+
+  node_configurations = {
+    default = {
+      disk_cpu_ratio = 25
+      subnets        = [azurerm_subnet.internal.id]
+      tags           = var.tags
+    }
+  }
+}

examples/aks/aks_cluster_with_security_runtime_rules/castai_runtime_rules.tf

@@ -0,0 +1,21 @@
+# 4. Import Runtime security rules.
+# Below is example security runtime rule, you can import existing rules from cast ai using fetch_castai_runtime_rules.sh script
+
+resource "castai_security_runtime_rule" "example_rule__dns_to_crypto_mining_" {
+  name              = "Example rule AKS: DNS to crypto mining"
+  category          = "event"
+  severity          = "SEVERITY_LOW"
+  enabled           = false
+  rule_text         = <<EOT
+event.type == event_dns && event.dns.network_details.category == category_crypto
+EOT
+  rule_engine_type  = "RULE_ENGINE_TYPE_CEL"
+  resource_selector = <<EOT
+resource.namespace == "default"
+EOT
+  labels = {
+    environment = "dev"
+    team        = "security"
+  }
+  depends_on = [module.castai-aks-cluster]
+}

examples/aks/aks_cluster_with_security_runtime_rules/fetch_castai_runtime_rules.sh

@@ -0,0 +1,134 @@
+#!/bin/bash
+
+set -euo pipefail
+
+if ! command -v jq &> /dev/null; then
+  echo "❌ 'jq' is required but not installed."
+  exit 1
+fi
+
+# Configuration
+BASE_URL=${CASTAI_BASE_URL:-"https://api.cast.ai"}
+API_KEY=${CASTAI_API_KEY:-""}
+TF_OUTPUT_FILE="castai_runtime_rules.tf.example"
+ENABLED_ONLY=false
+DEPENDENCY_MODULE="module.castai-aks-cluster"
+
+# Parse optional arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --enabled-only)
+      ENABLED_ONLY=true
+      shift
+      ;;
+    *)
+      echo "❌ Unknown option: $1"
+      echo "Usage: $0 [--enabled-only]"
+      exit 1
+      ;;
+  esac
+done
+
+# Check for API key
+if [ -z "$API_KEY" ]; then
+  echo "❌ Error: CASTAI_API_KEY environment variable not set."
+  exit 1
+fi
+
+# Full API endpoint
+ENDPOINT="$BASE_URL/v1/security/runtime/rules?search=&page.limit=5000&sort.field=severity&sort.order=desc"
+
+echo "🔍 Fetching CAST AI Runtime Rules from: $ENDPOINT"
+
+# Fetch data
+response=$(curl -s "$ENDPOINT" \
+  -H "Accept: application/json" \
+  -H "X-API-Key: $API_KEY" \
+  --fail -v)
+
+if [ -z "$response" ]; then
+  echo "❌ Failed to fetch data from CAST AI."
+  exit 1
+fi
+
+if [ "$ENABLED_ONLY" = true ]; then
+  rules=$(echo "$response" | jq '.rules | map(select(.enabled == true))')
+else
+  rules=$(echo "$response" | jq '.rules')
+fi
+
+# Count and print number of enabled rules
+RULE_COUNT=$(echo "$rules" | jq 'length')
+echo "✅ Found $RULE_COUNT rule(s)."
+
+# Start new TF file
+echo "# This file is autogenerated by fetch_castai_runtime_rules.sh" > "$TF_OUTPUT_FILE"
+
+# Escape double quotes
+escape_quotes() {
+  echo "$1" | sed 's/"/\\"/g'
+}
+
+echo "$rules" | jq -c '.[]' | while read -r rule_json; do
+  name=$(echo "$rule_json" | jq -r '.name')
+  name_escaped=$(escape_quotes "$name")
+  safe_name=$(echo "$name" | iconv -c -t ascii | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_' '_' | sed 's/^_*//')
+
+  category=$(echo "$rule_json" | jq -r '.category')
+  severity=$(echo "$rule_json" | jq -r '.severity')
+  enabled=$(echo "$rule_json" | jq -r '.enabled')
+  rule_text=$(echo "$rule_json" | jq -r '.ruleText // ""')
+  resource_selector=$(echo "$rule_json" | jq -r '.resourceSelector // ""' | sed 's/[[:space:]]*$//')
+  rule_engine_type=$(echo "$rule_json" | jq -r '.ruleEngineType')
+  labels=$(echo "$rule_json" | jq -c '.labels // {}')
+
+  cat >> "$TF_OUTPUT_FILE" <<EOF
+
+resource "castai_security_runtime_rule" "$safe_name" {
+  name              = "$name_escaped"
+  category          = "$category"
+  severity          = "$severity"
+  enabled           = $enabled
+  rule_text         = <<EOT
+$rule_text
+EOT
+  rule_engine_type  = "$rule_engine_type"
+EOF
+
+  if [ -n "$resource_selector" ]; then
+    cat >> "$TF_OUTPUT_FILE" <<EOF
+  resource_selector = <<EOT
+$resource_selector
+EOT
+EOF
+  fi
+
+  if [ "$labels" != "{}" ]; then
+    echo "  labels = {" >> "$TF_OUTPUT_FILE"
+    echo "$labels" | jq -r 'to_entries[] | "    \(.key) = \"\(.value | gsub("\""; "\\\""))\""' >> "$TF_OUTPUT_FILE"
+    echo "  }" >> "$TF_OUTPUT_FILE"
+  fi
+
+  echo "  depends_on = [${DEPENDENCY_MODULE}]" >> "$TF_OUTPUT_FILE"
+  echo "}" >> "$TF_OUTPUT_FILE"
+done
+
+# Print import commands
+echo ""
+echo "📝 Terraform resources written to: $TF_OUTPUT_FILE"
+echo ""
+echo "📦 Suggested Terraform import commands:"
+
+rules_list=$(echo "$rules" | jq -r '.[].name')
+count=$(echo "$rules_list" | wc -l | tr -d ' ')
+current=0
+
+echo "$rules_list" | while read -r name; do
+  current=$((current + 1))
+  safe_name=$(echo "$name" | iconv -c -t ascii | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_' '_' | sed 's/^_*//')
+  if [ "$current" -lt "$count" ]; then
+    echo "terraform import -var-file=tf.vars castai_security_runtime_rule.$safe_name \"$name\" &&"
+  else
+    echo "terraform import -var-file=tf.vars castai_security_runtime_rule.$safe_name \"$name\""
+  fi
+done

examples/aks/aks_cluster_with_security_runtime_rules/providers.tf

@@ -0,0 +1,23 @@
+# Following providers required by AKS and Vnet resources.
+provider "azurerm" {
+  features {}
+  subscription_id = var.subscription_id
+}
+
+provider "castai" {
+  api_token = var.castai_api_token
+  api_url   = var.castai_api_url
+}
+
+provider "azuread" {
+  tenant_id = data.azurerm_subscription.current.tenant_id
+}
+
+provider "helm" {
+  kubernetes {
+    host                   = azurerm_kubernetes_cluster.this.kube_config.0.host
+    client_certificate     = base64decode(azurerm_kubernetes_cluster.this.kube_config.0.client_certificate)
+    client_key             = base64decode(azurerm_kubernetes_cluster.this.kube_config.0.client_key)
+    cluster_ca_certificate = base64decode(azurerm_kubernetes_cluster.this.kube_config.0.cluster_ca_certificate)
+  }
+}

examples/aks/aks_cluster_with_security_runtime_rules/tf.vars.example

@@ -0,0 +1,4 @@
+cluster_name     = "<place-holder>"
+cluster_region   = "<place-holder>"
+castai_api_token = "<place-holder>"
+subscription_id  = "<place-holder>"