Skip to content

Commit 870c17a

Browse files
yitzhaktalyitzhaktal
authored
DEVOPS-2509-added-documentation-for-system-diagnostics-k8s-api-enablement (#44)
1 parent a9c23ea commit 870c17a

File tree

2 files changed

+163
-0
lines changed

2 files changed

+163
-0
lines changed

‎docs/advanced/k8s_api_access.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# System Diagnostics: Kubernetes API Integration
2+
3+
This document describes how to enable and configure the System Diagnostics feature to access the Kubernetes API from the backend pod. This integration allows the System Diagnostics feature to collect detailed information about the Lightrun deployment's Kubernetes environment.
4+
5+
## Overview
6+
7+
The System Diagnostics feature can be configured to access the Kubernetes API from the backend pod to enhance its diagnostic capabilities. This integration provides valuable insights into the Kubernetes environment where Lightrun is deployed, enabling more comprehensive system monitoring and troubleshooting.
8+
9+
## Prerequisites
10+
11+
Before enabling this feature, ensure that:
12+
13+
1. The `serviceAccount.create` setting is set to `true` in your values.yaml
14+
2. Your Kubernetes cluster allows service account token mounting
15+
3. You have the necessary permissions to create Roles and RoleBindings in the namespace where Lightrun is deployed
16+
17+
## Configuration
18+
19+
To enable Kubernetes API access, set the following in your values.yaml:
20+
21+
```yaml
22+
general:
23+
system_diagnostics_k8s_api:
24+
enabled: true
25+
```
26+
27+
## How It Works
28+
29+
When enabled, this feature:
30+
31+
1. Creates a Role and RoleBinding that grant the backend pod permission to:
32+
- List and get resources in the Lightrun namespace
33+
- Access basic cluster information
34+
35+
2. Mounts the service account token to the backend pod, allowing it to authenticate with the Kubernetes API
36+
37+
3. Enables the backend to collect system diagnostics data about:
38+
- Pod status and resource usage
39+
- Node information
40+
- Cluster events
41+
- Resource limits and requests
42+
43+
## Security Considerations
44+
45+
⚠️ **Important Security Notes:**
46+
47+
- This feature requires mounting a service account token inside the pod, which may not be allowed in all environments
48+
- The service account token provides access to Kubernetes API resources within the namespace
49+
- Consider the security implications before enabling this feature in production environments
50+
- Review your cluster's security policies regarding service account token mounting
51+
52+
## Troubleshooting
53+
54+
If the feature is not working as expected:
55+
56+
1. Verify that `serviceAccount.create` is set to `true`
57+
2. Check that the service account token is properly mounted in the backend pod
58+
3. Ensure the Role and RoleBinding were created successfully
59+
4. Review the backend pod logs for any authentication or authorization errors
60+
61+
## Disabling the Feature
62+
63+
To disable Kubernetes API access:
64+
65+
```yaml
66+
general:
67+
system_diagnostics_k8s_api:
68+
enabled: false
69+
```
70+
71+
Note: Disabling this feature only affects the Kubernetes API data collection. Other system diagnostics features will continue to work as normal.

‎docs/advanced/system_diagnostics_k8s_api.md

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# System Diagnostics: Kubernetes API Integration
2+
3+
This document describes how to enable and configure the System Diagnostics feature to access the Kubernetes API from the backend pod. This integration allows the System Diagnostics feature to collect detailed information about the Lightrun deployment's Kubernetes environment.
4+
5+
## Overview
6+
7+
The System Diagnostics feature can be configured to access the Kubernetes API from the backend pod to enhance its diagnostic capabilities. This integration provides valuable insights into the Kubernetes environment where Lightrun is deployed, enabling more comprehensive system monitoring and troubleshooting.
8+
9+
## Prerequisites
10+
11+
Before enabling this feature, ensure that:
12+
13+
1. The `serviceAccount.create` setting is set to `true` in your values.yaml
14+
2. Your Kubernetes cluster allows service account token mounting
15+
3. You have the necessary permissions to create Roles and RoleBindings in the target namespace
16+
17+
## Configuration
18+
19+
To enable Kubernetes API access, set the following in your values.yaml:
20+
21+
```yaml
22+
general:
23+
system_diagnostics_k8s_api:
24+
enabled: true
25+
26+
serviceAccount:
27+
create: true
28+
```
29+
30+
Note: When `system_diagnostics_k8s_api.enabled` is set to `true`, the feature will automatically override `serviceAccount.automountServiceAccountToken` to `true` for the backend pod, regardless of its global setting.
31+
32+
## How It Works
33+
34+
When enabled, this feature:
35+
36+
1. Creates a Role and RoleBinding that grant the backend pod permission to get and list the following Kubernetes resources in the Lightrun namespace:
37+
- Deployments
38+
- DaemonSets
39+
- StatefulSets
40+
- ReplicaSets
41+
- Ingresses
42+
- NetworkPolicies
43+
- Pods and Pod logs
44+
- Services
45+
- ConfigMaps
46+
- PersistentVolumeClaims
47+
- Endpoints
48+
- ResourceQuotas
49+
- LimitRanges
50+
- Events
51+
52+
2. Automatically enables service account token mounting for the backend pod by overriding `automountServiceAccountToken` to `true`, allowing it to authenticate with the Kubernetes API.
53+
54+
3. Enables the backend to collect system diagnostics data about:
55+
- Deployment, DaemonSet, StatefulSet, and ReplicaSet configurations and status
56+
- Pod status, resource usage, and logs
57+
- Service and Endpoint configurations
58+
- Ingress and NetworkPolicy configurations
59+
- ConfigMap contents
60+
- PersistentVolumeClaim status and configurations
61+
- ResourceQuota and LimitRange settings
62+
- Cluster events and their details
63+
64+
## Security Considerations
65+
66+
⚠️ **Important Security Notes:**
67+
68+
- This feature automatically enables service account token mounting for the backend pod by setting `automountServiceAccountToken` to `true`
69+
- The service account token provides access to Kubernetes API resources within the namespace
70+
- Consider the security implications before enabling this feature in production environments
71+
- Review your cluster's security policies regarding service account token mounting
72+
73+
## Troubleshooting
74+
75+
If the feature is not working as expected:
76+
77+
1. Verify that `serviceAccount.create` is set to `true`
78+
2. Check that the service account token is properly mounted in the backend pod
79+
3. Ensure the Role and RoleBinding were created successfully
80+
4. Review the backend pod logs for any authentication or authorization errors
81+
82+
## Disabling the Feature
83+
84+
To disable Kubernetes API access:
85+
86+
```yaml
87+
general:
88+
system_diagnostics_k8s_api:
89+
enabled: false
90+
```
91+
92+
Note: Disabling this feature only affects the Kubernetes API data collection. Other system diagnostics features will continue to work as normal.

0 commit comments

Comments
 (0)