From 2f6c8234112f28449aff6e5a0e276beea4f02a54 Mon Sep 17 00:00:00 2001 From: Piotr Zaniewski Date: Tue, 15 Oct 2024 18:47:05 +0200 Subject: [PATCH] feat: improve enable audit logging section Signed-off-by: Piotr Zaniewski --- .../guides/configure-audit-levels-helm.mdx | 6 +- platform/configure/advanced/audit.mdx | 120 +++++++++--------- 2 files changed, 65 insertions(+), 61 deletions(-) diff --git a/platform/_partials/guides/configure-audit-levels-helm.mdx b/platform/_partials/guides/configure-audit-levels-helm.mdx index b49891d9c..ba333ed2c 100644 --- a/platform/_partials/guides/configure-audit-levels-helm.mdx +++ b/platform/_partials/guides/configure-audit-levels-helm.mdx @@ -1,15 +1,15 @@ Create a new file `vcluster.yaml`: -```yaml +```yaml title="vcluster.yaml" config: audit: enabled: true level: 1 ``` -Then apply these values with helm (make sure to specify the correct vCluster Platform version): +Then apply these values with helm (make sure to specify the correct platform version): -``` +```bash title="Apply helm values" helm upgrade loft vcluster-platform --namespace vcluster-platform \ --repo https://charts.loft.sh \ --version $LOFT_VERSION \ diff --git a/platform/configure/advanced/audit.mdx b/platform/configure/advanced/audit.mdx index 2a71f78ed..6dc569833 100644 --- a/platform/configure/advanced/audit.mdx +++ b/platform/configure/advanced/audit.mdx @@ -1,8 +1,8 @@ --- title: Enabling Audit Logging sidebar_label: Enable Audit Logging -description: Learn how to enable auditing to log activities such as management instance changes. sidebar_position: 2 +description: Learn how to enable and configure audit logging to track activities in the platform, including management instance changes and cluster operations. --- import Tabs from "@theme/Tabs"; @@ -14,58 +14,58 @@ import AuditConfiguration from "../../api/_partials/resources/config/status/audi ## Overview -vCluster Platform auditing provides a security-relevant, chronological set of records documenting the sequence of actions in vCluster Platform. vCluster Platform audits the activities generated by users and by applications that use the vCluster Platform API. +Audit logging in the platform provides a security-relevant, chronological set of records documenting the sequence of actions. It audits activities generated by users and applications that use the platform API. -vCluster Platform is able to log activities related to: +The platform can log activities related to: -- Management Instance changes, such as creation of new virtual clusters, spaces etc. +- Management instance changes, such as creation of new virtual clusters, spaces, etc. - Changes within a virtual cluster or space - Changes within a connected cluster -Auditing in vCluster Platform is very similar to [auditing Kubernetes clusters](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/) in general. +Auditing in the platform is similar to [auditing Kubernetes clusters](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/) in general. -## Enable Auditing +## Enable auditing -vCluster Platform auditing is configured through the vCluster Platform config in the vCluster Platform UI (Admin -> Config). +Configure auditing through the platform config in the platform UI (`Admin -> Config`). An example configuration could look like: -```yaml +```yaml title="Example audit configuration" audit: enabled: true level: 1 ``` -:::warning vCluster Platform Restart Required -Changing the vCluster Platform auditing configuration requires a restart to take effect. You can restart vCluster Platform either through the vCluster Platform UI or via kubectl: `kubectl rollout restart deploy/loft -n loft` +:::warning Platform restart required +Changing the platform auditing configuration requires a restart to take effect. Restart the platform either through the platform UI or via kubectl: `kubectl rollout restart deploy/loft -n loft` ::: Each request on each stage of its execution generates an audit event, which is then pre-processed according to a certain policy and written to a backend (currently only log backends are supported). The policy determines what's recorded and the backends persist the records. Each request can be recorded with an associated stage. The defined stages are: -- `RequestReceived` - The stage for events generated as soon as the audit handler receives the request, and before it is delegated down the handler chain. -- `ResponseComplete` - The response body has been completed and no more bytes will be sent. -- `Panic` - Events generated when a panic occurred. +- `RequestReceived`: The stage for events generated as soon as the audit handler receives the request, and before it is delegated down the handler chain. +- `ResponseComplete`: The response body has been completed and no more bytes are sent. +- `Panic`: Events generated when a panic occurred. :::info -The audit logging feature increases the memory consumption of vCluster Platform because some context required for auditing is stored for each request. Memory consumption depends on the audit logging configuration. +The audit logging feature increases the memory consumption of the platform because some context required for auditing is stored for each request. Memory consumption depends on the audit logging configuration. ::: -## Audit Levels +## Audit levels -For easier configuration, vCluster Platform provides audit levels, that are preconfigured audit policies for the most common use cases. These levels range from 1 to 4 where 1 logs the fewest requests, while 4 logs the most. A more detailed description can be found below: +The platform provides audit levels, which are preconfigured audit policies for the most common use cases. These levels range from 1 to 4 where 1 logs the fewest requests, while 4 logs the most: -- **Level 1**: will log modifying requests such as creation / modification or deletion of any objects -- **Level 2**: like Level 1 but will also log the metadata of reading requests, such as listing pods inside a virtual cluster or space. It won't log the response or request payload and instead only the metadata such as request origin, target etc. -- **Level 3**: like Level 2 but instead of only logging the request metadata will also log the complete request payload sent to vCluster Platform -- **Level 4**: like Level 3 but instead of only logging metadata and request payload, will also log the response vCluster Platform has sent to the requester +- **Level 1**: Logs modifying requests such as creation / modification or deletion of any objects +- **Level 2**: Like Level 1 but also logs the metadata of reading requests, such as listing pods inside a virtual cluster or space. It won't log the response or request payload and instead only the metadata such as request origin, target, etc. +- **Level 3**: Like Level 2 but instead of only logging the request metadata also logs the complete request payload sent to the platform +- **Level 4**: Like Level 3 but instead of only logging metadata and request payload, also logs the response the platform has sent to the requester :::info -For all of these levels certain internal read-only apis are not logged since those might pollute the log and drastically increase log size. If you also want to log these, please create a custom audit policy as described below. +For all of these levels certain internal read-only APIs are not logged since those might pollute the log and drastically increase log size. To log these, create a custom audit policy as described below. ::: -You can configure the audit level through the vCluster Platform config, that can be modified either through the vCluster Platform UI or helm: +Configure the audit level through the platform config, which can be modified either through the platform UI or helm: -## Optional: Audit Policy +## Optional: Audit policy :::warning It is recommended to use audit levels instead of audit policy directly, because a policy is much more complex to define. ::: -As an alternative to Audit levels, policy allows you to define exact rules about what events should be recorded and what data they should include. When an event is processed, it's compared against the list of rules in order. The first matching rule sets the audit granularity of the event. The defined audit granularity options are: +As an alternative to audit levels, policy allows you to define exact rules about what events should be recorded and what data they should include. When an event is processed, it's compared against the list of rules in order. The first matching rule sets the audit granularity of the event. The defined audit granularity options are: -- `None` - don't log events that match this rule. -- `Metadata` - log request metadata (requesting user, timestamp, resource, verb, etc.) but not request or response body. -- `Request` - log event metadata and request body but not response body. This does not apply for non-resource requests. -- `RequestResponse` - log event metadata, request and response bodies. This does not apply for non-resource requests. +- `None`: Don't log events that match this rule. +- `Metadata`: Log request metadata (requesting user, timestamp, resource, verb, etc.) but not request or response body. +- `Request`: Log event metadata and request body but not response body. This does not apply for non-resource requests. +- `RequestResponse`: Log event metadata, request and response bodies. This does not apply for non-resource requests. -An example policy that catches all requests would look like this: +An example policy that catches all requests: -```yaml +```yaml title="Example audit policy" audit: enabled: true policy: @@ -111,73 +111,77 @@ Below you can find a complete policy reference: -## Persisting Audit Logs +## Persisting audit logs -There are 2 ways how to persist vCluster Platform audit logs. Either you can deploy vCluster Platform with a persistent volume claim or let vCluster Platform connect to a persistent database. The PVC approach does not work for HA mode for vCluster Platform. +There are two ways to persist platform audit logs: deploying the platform with a persistent volume claim (PVC) or connecting the platform to a persistent database. The PVC approach does not work for HA mode for the platform. -### Deploy vCluster Platform with a PVC to save Audit Logs +### Deploy the platform with a PVC to save audit logs Create a new `values.yaml` with the following values: -```yaml +```yaml title="values.yaml for PVC" audit: persistence: enabled: true # size: 30Gi ``` -Then apply the values via helm: +Apply the values via helm: -```yaml +```bash title="Apply helm values" helm upgrade vcluster-platform vcluster-platform -n vcluster-platform --version 4.0.0-alpha.12 \ --repo https://charts.loft.sh \ --reuse-values \ -f values.yaml ``` -### Use a persistent database as vCluster Platform audit backend +### Use a persistent database as platform audit backend -Go to Admin > Config and specify the following vCluster Platform config setting: +Go to `Admin > Config` and specify the following platform config setting: -```yaml +```yaml title="Platform config for persistent database" audit: dataStoreEndpoint: mysql://username:password@tcp(hostname:3306)/database-name ``` -Then press Apply and wait until vCluster Platform is restarted. +Apply the changes and wait until the platform is restarted. -## Viewing and Exporting Audit Logs +## Viewing and exporting audit logs -By default, vCluster Platform will log audit events to the following locations: +By default, the platform logs audit events to the following locations: -- To a log file in json format located at `/var/log/loft/audit.log` inside the vCluster Platform container. Each line inside the log represents a single audit event. -- To an internal sqlite storage located at `/var/log/loft/audit.db` inside the vCluster Platform container. This sqlite database is used to display audit log events in the vCluster Platform UI. By default audit events in the sqlite are not persisted, so restarting vCluster Platform will clear the database. Instead of using a sqlite database, vCluster Platform is also able to write those events to a persistent mysql database that can be configured through the vCluster Platform config. E.g.: +- To a log file in JSON format located at `/var/log/loft/audit.log` inside the platform container. Each line inside the log represents a single audit event. +- To an internal sqlite storage located at `/var/log/loft/audit.db` inside the +platform container. This sqlite database is used to display audit log events in +the platform UI. By default audit events in the sqlite are not persisted, so +restarting the platform clears the database. Instead of using a sqlite database, the platform can write those events to a persistent mysql database configured through the platform config: -```yaml +```yaml title="Platform config for MySQL database" audit: enabled: true dataStoreEndpoint: mysql://username:password@tcp(hostname:3306)/database-name ``` -### Enable Audit SideCar +### Enable audit sidecar -To easily export the audit events to third party systems, we recommend to enable the audit log sidecar that will print all the audit events onto stdout in a separate container which then can be easily watched and exported. +To easily export the audit events to third party systems, enable the audit log +sidecar that prints all the audit events onto stdout in a separate container which can then be easily watched and exported. Enabling the sidecar is only possible through helm values. Create a `values.yaml` with the following contents: -```yaml +```yaml title="values.yaml for audit sidecar" audit: enableSideCar: true ``` :::warning -You cannot configure this under Admin > Config, since this requires a change in the vCluster Platform deployment itself, which is why this is a helm option only +You cannot configure this under `Admin > Config`, since this requires a change in the platform deployment itself, which is why this is a helm option only ::: -Then update the helm release via: +Update the helm release: -``` +```bash title="Update helm release" helm upgrade vcluster-platform vcluster-platform --namespace vcluster-platform \ --repo https://charts.loft.sh \ --version 4.0.0-alpha.12 \ @@ -185,20 +189,20 @@ helm upgrade vcluster-platform vcluster-platform --namespace vcluster-platform \ --values values.yaml ``` -Wait until vCluster Platform has restarted, then you can view the audit logs via: +Wait until the platform has restarted, then view the audit logs: -``` +```bash title="View audit logs" kubectl logs -n vcluster-platform -l app=loft -c audit -f ``` -### Audit Config Reference +### Audit config reference -## How does Audit Logging work for Direct Cluster Endpoints? +## Audit logging for direct cluster endpoints -If the direct cluster endpoint feature is enabled, vCluster Platform audit configuration is synced to each agent and each vCluster Platform agent will propagate audit events that it receives back to the central vCluster Platform instance, which then logs it as a regular audit event. Such "propagated" events can be identified through the `annotations.audit.loft.sh/sent-by-agent` identifier in an audit event. +Direct cluster endpoints allow direct communication between users and clusters, bypassing the central platform instance. When this feature is enabled, the platform audit configuration is synced to each agent. Each platform agent propagates audit events it receives back to the central platform instance, which then logs it as a regular audit event. These "propagated" events can be identified by the `annotations.audit.loft.sh/sent-by-agent` identifier in an audit event. -:::info Disable Agent Sync Back -You can disable event sync back from the agent to the central vCluster Platform instance via the audit config option `disableAgentSyncBack`. +:::info Disable agent sync back +Disable event sync back from the agent to the central platform instance via the audit config option `disableAgentSyncBack`. :::