Enable secrets for robusta (#1557)

* Updated docs regarding secrets * Simplified syntax usage in docs for secret triggers * Updated playbook-track-secrets docs * Updated track secrets tutorial * Fixed secret triggers section * Fixed triggers markdown * Fixed import of render_generic_trigger * Removed custom description for secrets * Fix for _k8s-wildcard-triggers.jinja * Added custom description for Secrets * Updated Secret in kubernetes.rst * Changed secrets inline-ctx in kubernetes.rst * Checking if custom description works * Added escaping to secrets triggers * block scalar for inline-ctx * context instead of inline-context for secrets * _k8s-generic-triggers.jinja custom_description fix * Trying inline rst * Moved secret triggers to separate jijna file * Fixed usage of playbook-reference/triggers/_k8s-secrets-triggers.jinja * Removed sample image from playbook-track-secrets.rst * Fixed secret triggers display --------- Co-authored-by: arik <[email protected]>
robusta-dev · Sep 24, 2024 · 5769f1e · 5769f1e
1 parent 8a5f478
commit 5769f1e
Show file tree

Hide file tree

Showing 4 changed files with 156 additions and 0 deletions.
diff --git a/docs/playbook-reference/triggers/_k8s-secrets-triggers.jinja b/docs/playbook-reference/triggers/_k8s-secrets-triggers.jinja
@@ -0,0 +1,5 @@
+{% from "playbook-reference//triggers/_k8s-generic-macro.jinja" import render_generic_trigger %}
+{{ render_generic_trigger("Secret", "on_secret_create", 'Fires when a Secret is created.', 'created', related_actions ) }}
+{{ render_generic_trigger("Secret", "on_secret_update", 'Fires when a Secret is updated.', 'updated', related_actions ) }}
+{{ render_generic_trigger("Secret", "on_secret_delete", 'Fires when a Secret is deleted.', 'deleted', related_actions ) }}
+{{ render_generic_trigger("Secret", "on_secret_all_changes", 'Fires when a Secret is created, updated, or deleted.', 'modified', related_actions ) }}
diff --git a/docs/playbook-reference/triggers/kubernetes.rst b/docs/playbook-reference/triggers/kubernetes.rst
@@ -336,6 +336,16 @@ For triggers that fire only on Pod errors, see :ref:`Crashing Pod Triggers`.
   :header_update_levels:
   :file: playbook-reference/triggers/_k8s-generic-triggers.jinja
 
+
+Secret triggers
+*********************
+Secret triggers fire when secret resource changes. *By default Robusta does not support tracking secrets*, but you can enable it by :ref:`configuring kubewatch to monitor secrets<track-secrets-overview>`.
+
+.. jinja::
+  :header_update_levels:
+  :file: playbook-reference/triggers/_k8s-secrets-triggers.jinja
+
+
 Wildcard triggers
 *********************
 

diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -34,6 +34,7 @@ Define your own alerts. Customize the data shown in alert notifications.
    playbook-failed-liveness
    alert-custom-prometheus
    alert-custom-enrichment
+   playbook-track-secrets.rst
 
 .. _tutorials-notification-routing:
 

diff --git a/docs/tutorials/playbook-track-secrets.rst b/docs/tutorials/playbook-track-secrets.rst
@@ -0,0 +1,140 @@
+.. _track-secrets-overview:
+Track Kubernetes Secret Changes
+############################################
+
+By default Robusta is not configured to track secret changes, but it is possible to configure it
+by giving permissions to Robusta to read secrets and configuring kubewatch.
+
+How to Track Changes in Kubernetes Secrets
+------------------------------------------------
+
+1. **Grant Permissions to Robusta**: By default, Robusta does not have permission to read Secrets. You'll need to grant it the necessary permissions.
+2. **Configure Kubewatch**: Set up Kubewatch to monitor Secret resources.
+3. **Create Custom Playbook**: Define a playbook that specifies when you should be notified and what data you'd like to see.
+4. **Route Alerts (Optional)**: If needed, direct these notifications to specific destinations, also known as 'Sinks', by adding this information to your custom playbook.
+
+Updating Configurations to track Secret Changes
+*******************************************************
+**Scenario**: You want to be notified whenever a Secret in your cluster is created, updated, or deleted.
+
+**Implementation**:
+
+Add the following configurations to your `generated_values.yaml` file and apply the necessary permissions.
+
+**1. Grant Permissions to Robusta**
+
+Create a YAML file named `kubewatch-secret-permissions.yaml` with the following content:
+
+.. code-block:: yaml
+
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: ClusterRole
+    metadata:
+      namespace: your-namespace
+      name: read-secrets-role
+    rules:
+    - apiGroups: [""]
+      resources: ["secrets"]
+      verbs: ["get", "list", "watch"]
+    ---
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: ClusterRoleBinding
+    metadata:
+      name: read-secrets-role-binding
+    subjects:
+    - kind: ServiceAccount
+      name: robusta-forwarder-service-account
+      namespace: your-namespace
+    roleRef:
+      kind: ClusterRole
+      name: read-secrets-role
+      apiGroup: rbac.authorization.k8s.io
+
+Apply the permissions:
+
+.. code-block:: shell
+
+    kubectl apply -f kubewatch-secret-permissions.yaml
+
+**2. Configure Kubewatch to Monitor Secrets**
+
+Add the following to the `kubewatch` section in your `generated_values.yaml`:
+
+.. code-block:: yaml
+
+    kubewatch:
+      config:
+        namespace: your-namespace
+        resource:
+          secret: true
+
+**3. Create Custom Playbook**
+
+Add the following to the `customPlaybooks` section in your `generated_values.yaml`:
+
+.. code-block:: yaml
+
+    customPlaybooks:
+    - triggers:
+        - on_secret_all_changes: {}
+      actions:
+        - create_finding:
+            title: "Secret $name in namespace $namespace was changed"
+            aggregation_key: SecretModified
+
+.. details:: How does it work?
+
+  1. **Grant Permissions**: The first YAML grants Robusta the necessary permissions to read Secrets.
+  2. **Configure Kubewatch**: The `kubewatch` configuration tells Robusta to monitor Secret resources.
+  3. **Set Up the Trigger**: The `on_secret_all_changes` trigger ensures you'll receive notifications for all Secret changes.
+  4. **Create the Notification**: The `create_finding` action generates a notification with a custom title.
+
+Then perform a :ref:`Helm Upgrade <Simple Upgrade>`.
+
+**Note**: You can also use the :ref:`Sink Matchers<sink-matchers>` to route notifications instead of explicitly specifying a sink in the playbook.
+
+**Testing**:
+
+1. **Create a Test Secret**:
+
+   .. code-block:: shell
+
+       kubectl create secret generic test-secret --from-literal=key1=value1
+
+2. **Modify the Secret**:
+
+   .. code-block:: shell
+
+       kubectl patch secret test-secret -p '{"stringData":{"key1":"newvalue"}}'
+
+3. **Delete the Secret**:
+
+   .. code-block:: shell
+
+       kubectl delete secret test-secret
+
+A Robusta notification will arrive in your configured :ref:`sinks <Sinks Reference>`, indicating that the Secret was created, modified, or deleted.
+
+
+Cleanup
+------------------------------
+
+To stop monitoring Secret changes:
+
+1. Remove the playbook you added from the `customPlaybooks` in your `generated_values.yaml` file.
+2. Remove the Secret monitoring configuration:
+
+   .. code-block:: yaml
+
+       kubewatch:
+         config:
+           resource:
+             secret: false
+
+3. Delete the permissions:
+
+   .. code-block:: shell
+
+       kubectl delete -f kubewatch-secret-permissions.yaml
+
+Then, perform a :ref:`Helm Upgrade <Simple Upgrade>`.