On this page

Get Involved

Importing a Kubernetes Cluster into Guardrails

Kubernetes clusters can be imported into Guardrails with the use of an agent that reports resource data within the cluster. The agent runs in a StatefulSet alongside the other components in the cluster and always runs in a single pod.

Prerequisites

The following must be installed in order to run the enrollment steps:

Turbot Guardrails Workspace Setup

Mods

The following mods need to be installed:

If using the ServiceNow integration to sync Kubernetes data into ServiceNow, the following mods need to be installed:

turbot/servicenow
turbot/servicenow-kubernetes (if using the ServiceNow integration)

For ServiceNow integration, a ServiceNow instance should be imported into Guardrails as well.

Policies

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.

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.

Set Kubernetes Context

Before running the install script, set your kubeconfig context to the correct Kubernetes cluster.

For more information on setting context for cloud providers:

Persistent Storage

By default, the Helm chart attempts to use the cluster's default StorageClass to dynamically provision a PersistentVolumeClaim (PVC) for the StatefulSet.

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, Azure CSI driver, or GCE PD CSI driver in order for the agent to install successfully.

We recommend leaving persistence enabled when installing the agent to avoid disruptions to the osquery database; however, you can disable it by modifying guardrails-values.yaml before running helm install:

persistence:
  enabled: false

For additional values related to persistence, please see Helm chart values.

Install Agent

Ensure your kubectl config context is set properly.
Login to your Guardrails workspace as a Turbot/Owner or Turbot/Admin.
Click the purple Connect card in the top right of the landing page.
Click Kubernetes Cluster.
Select the Parent Resource (resources from the Kubernetes cluster will be automatically imported and managed under this resource).
Download or copy the generated script and then run it to install the Helm chart containing the agent.

Verify Agent Deployment

After installing the agent, if enrollment is successful, a Kubernetes cluster resource and its related resources will be created under the parent resource.

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.

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.

Update Agent

To update an installed agent with a new Helm chart version, run the following commands:

helm repo update
helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values

To update the values for an existing release, pass in the new values with the -f flag:

helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values -f guardrails-values.yaml

Only values included in guardrails-values.yaml will be updated, with priority being given to new values.

Cluster Name

Guardrails will attempt to use a friendly name as the cluster name.

These are the current defaults for clusters by cloud provider:

AWS EKS: The EKS cluster name from the aws:eks:cluster-name tag
GCP GKE: The cluster-name from instance metadata

You can also set the title, which will override the defaults above, by adding an annotation to the StatefulSet containing the agent in guardrails-values.yaml:

statefulSet:
  annotations:
    guardrails.turbot.com/cluster-name: "my-kube-cluster"

And then upgrade the release:

helm upgrade guardrails-agent-kubernetes turbot/guardrails-agent-kubernetes --namespace guardrails --reuse-values -f guardrails-values.yaml

Troubleshooting

If you do not see the Kubernetes cluster in Guardrails, this most likely means enrollment failed.

Enrollment can fail for a number of reasons:

The agent isn't running, which can be verified with kubectl:
```
kubectl get sts --namespace guardrails
```
The agent is running but has encountered an error while making the enroll request. To view the logs with kubectl:
```
kubectl logs sts/guardrails-agent-kubernetes -f --namespace guardrails
```

The enroll secret is expired. To verify you have the latest enroll secret, run this GraphQL query:

{
  osquery(resource: "[FOLDER_RESOURCE_ID]" resourceTypeUri:"tmod:@turbot/kubernetes#/resource/types/cluster") {
    enrollSecret
  }
}

An old enroll secret exists in the cluster. To delete the previous secret:

kubectl delete secret guardrails-agent-kubernetes-secret --namespace guardrails

Next Steps

Configure queries for resources.
Setup the sync from cloud resources with Turbot Guardrails to ServiceNow.