Skip to content

Commit 4e864e7

Browse files
luisffcluisffc
committed
Update guide - Update Kubernetes / EKS integration instructions. closes #213
Signed-off-by: Luis Cavalcante <[email protected]>
1 parent e1a277c commit 4e864e7

File tree

1 file changed

+176
-165
lines changed
  • docs/guides/kubernetes/import-kubernetes-cluster

1 file changed

+176
-165
lines changed

‎docs/guides/kubernetes/import-kubernetes-cluster/index.md

+176-165
Original file line numberDiff line numberDiff line change
@@ -1,165 +1,176 @@
1-
---
2-
title: "Importing a Kubernetes Cluster into Guardrails"
3-
template: Documentation
4-
nav:
5-
title: "Importing Clusters"
6-
order: 10
7-
---
8-
9-
# Importing a Kubernetes Cluster into Guardrails
10-
11-
Kubernetes clusters can be imported into Guardrails with the use of an agent
12-
that reports resource data within the cluster. The agent runs in a StatefulSet
13-
alongside the other components in the cluster and always runs in a single pod.
14-
15-
## Prerequisites
16-
17-
The following must be installed in order to run the enrollment steps:
18-
19-
- [Helm](https://helm.sh/docs/intro/install/)
20-
- [kubectl](https://kubernetes.io/docs/tasks/tools/)
21-
22-
## Turbot Guardrails Workspace Setup
23-
24-
### Mods
25-
26-
The following [mods](https://turbot.com/guardrails/docs/mods) need to be installed:
27-
- [turbot/osquery](https://turbot.com/guardrails/docs/mods/turbot/osquery)
28-
- [turbot/kubernetes](https://turbot.com/guardrails/docs/mods/kubernetes/kubernetes)
29-
30-
If using the [ServiceNow integration](https://turbot.com/guardrails/docs/guides/servicenow) to sync Kubernetes data into ServiceNow, the following mods need to be installed:
31-
- [turbot/servicenow](https://turbot.com/guardrails/docs/mods/servicenow/servicenow)
32-
- [turbot/servicenow-kubernetes](https://turbot.com/guardrails/docs/mods/servicenow/servicenow-kubernetes) (if using the ServiceNow integration)
33-
34-
For ServiceNow integration, a [ServiceNow instance should be imported into Guardrails](https://turbot.com/guardrails/docs/guides/servicenow/import-servicenow-instance) as well.
35-
36-
### Policies
37-
38-
After installing the osquery mod, the `Turbot > Workspace > osquery` policy is set to `Enabled` by default. If set to `Enabled`, the osquery APIs are also enabled, so we recommend setting this policy as `Enabled`.
39-
40-
By default, the enroll secret returned by Guardrails expires every hour, but you can change this expiration period in the `Turbot > Workspace > osquery > Enroll Secret Expiration`. This is helpful if you want to reuse the same enroll secret over time in automated deployments.
41-
42-
### Set Kubernetes Context
43-
44-
Before running the install script, set your kubeconfig context to the correct Kubernetes cluster.
45-
46-
For more information on setting context for cloud providers:
47-
48-
- AWS: https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html
49-
- Azure: https://learn.microsoft.com/en-us/azure/aks/learn/quick-kubernetes-deploy-cli#connect-to-the-cluster
50-
- GCP: https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#interact_kubectl
51-
52-
### Persistent Storage
53-
54-
By default, the Helm chart attempts to use the cluster's default StorageClass to dynamically provision a PersistentVolumeClaim (PVC) for the StatefulSet.
55-
56-
Many Kubernetes clusters from cloud providers no longer include in-tree storage provisioners by default, so you will need to install drivers like the [AWS EBS CSI driver](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html), [Azure CSI driver](https://learn.microsoft.com/en-us/azure/aks/csi-storage-drivers), or [GCE PD CSI driver](https://cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/gce-pd-csi-driver) in order for the agent to install successfully.
57-
58-
We recommend leaving persistence enabled when installing the agent to avoid
59-
disruptions to the osquery database; however, you can disable it by modifying
60-
`guardrails-values.yaml` before running `helm install`:
61-
62-
```yml
63-
persistence:
64-
enabled: false
65-
```
66-
67-
For additional values related to persistence, please see [Helm chart values](https://github.com/turbot/helm-charts/tree/main/charts/guardrails-agent-kubernetes#values).
68-
69-
### Install Agent
70-
71-
1. Ensure your kubectl config context is set properly.
72-
2. Login to your Guardrails workspace as a **Turbot/Owner** or **Turbot/Admin**.
73-
3. Click the purple **Connect** card in the top right of the landing page.
74-
4. Click **Kubernetes Cluster**.
75-
5. Select the **Parent Resource** (resources from the Kubernetes cluster will be automatically imported and managed under this resource).
76-
6. Download or copy the generated script and then run it to install the Helm chart containing the agent.
77-
78-
#### Verify Agent Deployment
79-
80-
After installing the agent, if enrollment is successful, a Kubernetes cluster resource and its related resources will be created under the parent resource.
81-
82-
The `Turbot > osquery > Configuration` calculated policy contains the configuration osquery uses, including the queries, so this will need to finish calculating before any resources will be created for that cluster in Guardrails.
83-
84-
If you still do not see any resources for that cluster being created, please check if the value for the `Turbot > osquery > Configuration` policy is available.
85-
86-
### Update Agent
87-
88-
To update an installed agent with a new Helm chart version, run the following commands:
89-
90-
```sh
91-
helm repo update
92-
helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values
93-
```
94-
95-
To update the values for an existing release, pass in the new values with the `-f` flag:
96-
97-
```sh
98-
helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values -f guardrails-values.yaml
99-
```
100-
101-
Only values included in `guardrails-values.yaml` will be updated, with priority being given to new values.
102-
103-
### Cluster Name
104-
105-
Guardrails will attempt to use a friendly name as the cluster name.
106-
107-
These are the current defaults for clusters by cloud provider:
108-
- AWS EKS: The EKS cluster name from the `aws:eks:cluster-name` tag
109-
- GCP GKE: The `cluster-name` from instance metadata
110-
111-
You can also set the title, which will override the defaults above, by adding
112-
an annotation to the StatefulSet containing the agent in
113-
`guardrails-values.yaml`:
114-
115-
```yml
116-
statefulSet:
117-
annotations:
118-
guardrails.turbot.com/cluster-name: "my-kube-cluster"
119-
```
120-
121-
And then upgrade the release:
122-
123-
```sh
124-
helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values -f guardrails-values.yaml
125-
```
126-
127-
### Troubleshooting
128-
129-
If you do not see the Kubernetes cluster in Guardrails, this most likely means enrollment failed.
130-
131-
Enrollment can fail for a number of reasons:
132-
133-
- The agent isn't running, which can be verified with `kubectl`:
134-
```sh
135-
kubectl get sts --namespace guardrails
136-
```
137-
- The agent is running but has encountered an error while making the enroll request. To view the logs with `kubectl`:
138-
```sh
139-
kubectl logs sts/guardrails-agent-kubernetes -f --namespace guardrails
140-
```
141-
- The enroll secret is expired. To verify you have the latest enroll secret, run this GraphQL query:
142-
```graphql
143-
{
144-
osquery(resource: "[FOLDER_RESOURCE_ID]" resourceTypeUri:"tmod:@turbot/kubernetes#/resource/types/cluster") {
145-
enrollSecret
146-
}
147-
}
148-
```
149-
- An old enroll secret exists in the cluster. To delete the previous secret:
150-
```sh
151-
kubectl delete secret guardrails-agent-kubernetes-secret --namespace guardrails
152-
```
153-
154-
## Next Steps
155-
156-
1. [Configure queries](guides/kubernetes/configure-queries) for resources.
157-
2. Setup the [sync from cloud resources with Turbot Guardrails to ServiceNow](/guardrails/docs/guides/servicenow/guardrails-to-servicenow-sync).
158-
159-
## Further Reading
160-
161-
Additional context and demos about these features:
162-
- [Kubernetes Security Posture Management](https://turbot.com/guardrails/blog/2024/05/kubernetes-security-posture-management)
163-
- [Real-time Kubernetes discovery for ServiceNow CMDB](https://turbot.com/guardrails/blog/2024/05/servicenow-kubernetes-discovery)
164-
165-
We want to hear from you! Join our [Slack Community](https://turbot.com/community/join) `#guardrails` channel to ask questions and share feedback.
1+
---
2+
title: "Importing a Kubernetes Cluster into Guardrails"
3+
template: Documentation
4+
nav:
5+
title: "Importing Clusters"
6+
order: 10
7+
---
8+
9+
# Importing a Kubernetes Cluster into Guardrails
10+
11+
Kubernetes clusters can be imported into Guardrails with the use of an agent
12+
that reports resource data within the cluster. The agent runs in a StatefulSet
13+
alongside the other components in the cluster and always runs in a single pod.
14+
15+
## Prerequisites
16+
17+
The following must be installed in order to run the enrollment steps:
18+
19+
- [Helm](https://helm.sh/docs/intro/install/)
20+
- [kubectl](https://kubernetes.io/docs/tasks/tools/)
21+
22+
## Turbot Guardrails Workspace Setup
23+
24+
### Mods
25+
26+
The following [mods](https://turbot.com/guardrails/docs/mods) need to be installed:
27+
- [turbot/osquery](https://turbot.com/guardrails/docs/mods/turbot/osquery)
28+
- [turbot/kubernetes](https://turbot.com/guardrails/docs/mods/kubernetes/kubernetes)
29+
30+
If using the [ServiceNow integration](https://turbot.com/guardrails/docs/guides/servicenow) to sync Kubernetes data into ServiceNow, the following mods need to be installed:
31+
- [turbot/servicenow](https://turbot.com/guardrails/docs/mods/servicenow/servicenow)
32+
- [turbot/servicenow-kubernetes](https://turbot.com/guardrails/docs/mods/servicenow/servicenow-kubernetes) (if using the ServiceNow integration)
33+
34+
For ServiceNow integration, a [ServiceNow instance should be imported into Guardrails](https://turbot.com/guardrails/docs/guides/servicenow/import-servicenow-instance) as well.
35+
36+
### Policies
37+
38+
After installing the osquery mod, the `Turbot > Workspace > osquery` policy is set to `Enabled` by default. If set to `Enabled`, the osquery APIs are also enabled, so we recommend setting this policy as `Enabled`.
39+
40+
By default, the enroll secret returned by Guardrails expires every hour, but you can change this expiration period in the `Turbot > Workspace > osquery > Enroll Secret Expiration`. This is helpful if you want to reuse the same enroll secret over time in automated deployments.
41+
42+
### Set Kubernetes Context
43+
44+
Before running the install script, set your kubeconfig context to the correct Kubernetes cluster.
45+
46+
For more information on setting context for cloud providers:
47+
48+
- AWS: https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html
49+
- Azure: https://learn.microsoft.com/en-us/azure/aks/learn/quick-kubernetes-deploy-cli#connect-to-the-cluster
50+
- GCP: https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#interact_kubectl
51+
52+
### Persistent Storage
53+
54+
By default, the Helm chart attempts to use the cluster's default StorageClass to dynamically provision a PersistentVolumeClaim (PVC) for the StatefulSet.
55+
56+
Many Kubernetes clusters from cloud providers no longer include in-tree storage provisioners by default, so you will need to install drivers like the [AWS EBS CSI driver](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html), [Azure CSI driver](https://learn.microsoft.com/en-us/azure/aks/csi-storage-drivers), or [GCE PD CSI driver](https://cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/gce-pd-csi-driver) in order for the agent to install successfully.
57+
58+
We recommend leaving persistence enabled when installing the agent to avoid
59+
disruptions to the osquery database; however, you can disable it by modifying
60+
`guardrails-values.yaml` before running `helm install`:
61+
62+
```yml
63+
persistence:
64+
enabled: false
65+
```
66+
67+
For additional values related to persistence, please see [Helm chart values](https://github.com/turbot/helm-charts/tree/main/charts/guardrails-agent-kubernetes#values).
68+
69+
### Install Agent
70+
71+
1. Ensure your kubectl config context is set properly.
72+
2. Login to your Guardrails workspace as a **Turbot/Owner** or **Turbot/Admin**.
73+
3. Click the purple **Connect** card in the top right of the landing page.
74+
4. Click **Kubernetes Cluster**.
75+
5. Select the **Parent Resource** (resources from the Kubernetes cluster will be automatically imported and managed under this resource).
76+
6. Download or copy the generated script and then run it to install the Helm chart containing the agent.
77+
78+
#### Verify Agent Deployment
79+
80+
After installing the agent, if enrollment is successful, a Kubernetes cluster resource and its related resources will be created under the parent resource.
81+
82+
The `Turbot > osquery > Configuration` calculated policy contains the configuration osquery uses, including the queries, so this will need to finish calculating before any resources will be created for that cluster in Guardrails.
83+
84+
If you still do not see any resources for that cluster being created, please check if the value for the `Turbot > osquery > Configuration` policy is available.
85+
86+
### Update Agent
87+
88+
To update an installed agent with a new Helm chart version, run the following commands:
89+
90+
```sh
91+
helm repo update
92+
helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values
93+
```
94+
95+
To update the values for an existing release, pass in the new values with the `-f` flag:
96+
97+
```sh
98+
helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values -f guardrails-values.yaml
99+
```
100+
101+
Only values included in `guardrails-values.yaml` will be updated, with priority being given to new values.
102+
103+
### Cluster Name
104+
105+
Guardrails will attempt to use a friendly name as the cluster name.
106+
107+
These are the current defaults for clusters by cloud provider:
108+
- AWS EKS: The EKS cluster name from the `aws:eks:cluster-name` tag
109+
110+
Important: The guardrails agent retrieves the tag above from the [instance metadata service (IMDS)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). Therefore, the number of IMDSv2 token hops (`HttpPutResponseHopLimit`) set on instance metadata should be 2 or higher.
111+
112+
You can set the number of hops with the following command, where `<instance-id>` is the ID of the node instance where the agent is running:
113+
114+
```
115+
aws ec2 modify-instance-metadata-options \
116+
--instance-id <instance-id> \
117+
--http-put-response-hop-limit 2
118+
```
119+
120+
- GCP GKE: The `cluster-name` from instance metadata
121+
122+
You can also set the title, which will override the defaults above, by adding
123+
an annotation to the StatefulSet containing the agent in
124+
`guardrails-values.yaml`:
125+
126+
```yml
127+
statefulSet:
128+
annotations:
129+
guardrails.turbot.com/cluster-name: "my-kube-cluster"
130+
```
131+
132+
And then upgrade the release:
133+
134+
```sh
135+
helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values -f guardrails-values.yaml
136+
```
137+
138+
### Troubleshooting
139+
140+
If you do not see the Kubernetes cluster in Guardrails, this most likely means enrollment failed.
141+
142+
Enrollment can fail for a number of reasons:
143+
144+
- The agent isn't running, which can be verified with `kubectl`:
145+
```sh
146+
kubectl get sts --namespace guardrails
147+
```
148+
- The agent is running but has encountered an error while making the enroll request. To view the logs with `kubectl`:
149+
```sh
150+
kubectl logs sts/guardrails-agent-kubernetes -f --namespace guardrails
151+
```
152+
- The enroll secret is expired. To verify you have the latest enroll secret, run this GraphQL query:
153+
```graphql
154+
{
155+
osquery(resource: "[FOLDER_RESOURCE_ID]" resourceTypeUri:"tmod:@turbot/kubernetes#/resource/types/cluster") {
156+
enrollSecret
157+
}
158+
}
159+
```
160+
- An old enroll secret exists in the cluster. To delete the previous secret:
161+
```sh
162+
kubectl delete secret guardrails-agent-kubernetes-secret --namespace guardrails
163+
```
164+
165+
## Next Steps
166+
167+
1. [Configure queries](guides/kubernetes/configure-queries) for resources.
168+
2. Setup the [sync from cloud resources with Turbot Guardrails to ServiceNow](/guardrails/docs/guides/servicenow/guardrails-to-servicenow-sync).
169+
170+
## Further Reading
171+
172+
Additional context and demos about these features:
173+
- [Kubernetes Security Posture Management](https://turbot.com/guardrails/blog/2024/05/kubernetes-security-posture-management)
174+
- [Real-time Kubernetes discovery for ServiceNow CMDB](https://turbot.com/guardrails/blog/2024/05/servicenow-kubernetes-discovery)
175+
176+
We want to hear from you! Join our [Slack Community](https://turbot.com/community/join) `#guardrails` channel to ask questions and share feedback.

0 commit comments

Comments
 (0)