From 87c2378ed2f3635de3109987a25928fcdb60c174 Mon Sep 17 00:00:00 2001 From: Gabe Alford Date: Thu, 5 Oct 2023 16:39:47 -0600 Subject: [PATCH] feat: add Admission Controller docs --- docs/src/resources/admission.md.tmpl | 185 +++++++++++++++++++++++++++ docs/src/resources/container.md.tmpl | 2 - 2 files changed, 185 insertions(+), 2 deletions(-) create mode 100644 docs/src/resources/admission.md.tmpl diff --git a/docs/src/resources/admission.md.tmpl b/docs/src/resources/admission.md.tmpl new file mode 100644 index 00000000..692e15bc --- /dev/null +++ b/docs/src/resources/admission.md.tmpl @@ -0,0 +1,185 @@ +# Falcon Admission Controller + +## About FalconAdmission Custom Resource (CR) +Falcon Operator introduces the FalconAdmission Custom Resource (CR) to the cluster. The resource is meant to install, configure, and uninstall the Falcon Admission Controller on the cluster. + +### FalconAdmission CR Configuration using CrowdStrike API Keys +To start the FalconAdmission installation using CrowdStrike API Keys to allow the operator to determine your Falcon Customer ID (CID) as well as pull down the CrowdStrike Falcon Admisison Controller image, please create the following FalconAdmission resource to your cluster. You will need to provide CrowdStrike API Keys and CrowdStrike cloud region for the installation. It is recommended to establish new API credentials for the installation at https://falcon.crowdstrike.com/support/api-clients-and-keys, required permissions are: + * Falcon Images Download: Read + * Sensor Download: Read + +Example: + +```yaml +apiVersion: falcon.crowdstrike.com/v1alpha1 +kind: FalconAdmission +metadata: + name: falcon-admission +spec: + falcon: + tags: 'test-cluster,dev' + falcon_api: + client_id: PLEASE_FILL_IN + client_secret: PLEASE_FILL_IN + cloud_region: autodiscover + registry: + type: crowdstrike +``` + +### FalconAdmission Reference Manual + +#### Falcon API Settings +| Spec | Description | +| :------------------------- | :------------------------------------------------------------------------------------------------------- | +| falcon_api.client_id | CrowdStrike API Client ID | +| falcon_api.client_secret | CrowdStrike API Client Secret | +| falcon_api.cloud_region | CrowdStrike cloud region (allowed values: autodiscover, us-1, us-2, eu-1, us-gov-1) | +| falcon_api.cid | (optional) CrowdStrike Falcon CID API override | + +#### Admission Controller Configuration Settings +| Spec | Description | +| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | +| installNamespace | (optional) Override the default namespace of falcon-kac | +| image | (optional) Leverage a Falcon Admission Controller Sensor image that is not managed by the operator; typically used with custom repositories; overrides all registry settings; might require admissionConfig.imagePullSecrets to be set | +| version | (optional) Enforce particular Falcon Admission Controller version to be installed (example: "6.31", "6.31.0", "6.31.0-1409") | +| registry.type | Registry to mirror Falcon Admission Controller (allowed values: acr, ecr, crowdstrike, gcr, openshift) | +| registry.tls.insecure_skip_verify | (optional) Skip TLS check when pushing Falcon Admission to target registry (only for demoing purposes on self-signed openshift clusters) | +| registry.tls.caCertificate | (optional) A string containing an optionally base64-encoded Certificate Authority Chain for self-signed TLS Registry Certificates | +| registry.tls.caCertificateConfigMap | (optional) The name of a ConfigMap containing CA Certificate Authority Chains under keys ending in ".tls" for self-signed TLS Registry Certificates (ignored when registry.tls.caCertificate is set) | +| registry.acr_name | (optional) Name of ACR for the Falcon Admission push. Only applicable to Azure cloud. (`registry.type="acr"`) | +| resourcequota.pods | (optional) Configure the maximum number of pods that can be created in the falcon-kac namespace | +| admissionConfig.serviceAccount.annotations| (optional) Configure annotations for the falcon-kac service account (e.g. for IAM role association) | +| admissionConfig.port | (optional) Configure the port the Falcon Admission Controller Service listens on | +| admissionConfig.containerPort | (optional) Configure the port the Falcon Admission Controller container listens on | +| admissionConfig.tls.validity | (optional) Configure the validity of the TLS certificate used by the Falcon Admission Controller | +| admissionConfig.failurePolicy | (optional) Configure the failure policy of the Falcon Admission Controller | +| admissionConfig.disabledNamespaces | (optional) Configure the list of namespaces the Falcon Admission Controller validating webhook should ignore | +| admissionConfig.replicas | (optional) Configure the number of replicas of the Falcon Admission Controller | +| admissionConfig.imagePullPolicy | (optional) Configure the image pull policy of the Falcon Admission Controller | +| admissionConfig.imagePullSecrets | (optional) Configure the image pull secrets of the Falcon Admission Controller | +| admissionConfig.resourcesClient | (optional) Configure the resources client of the Falcon Admission Controller | +| admissionConfig.resources | (optional) Configure the resources of the Falcon Admission Controller | +| admissionConfig.updateStrategy | (optional) Configure the deployment update strategy of the Falcon Admission Controller | + + +#### Falcon Sensor Settings +| Spec | Description | +| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | +| falcon.apd | (optional) Configure Falcon Sensor to leverage a proxy host | +| falcon.aph | (optional) Configure the host Falcon Sensor should leverage for proxying | +| falcon.app | (optional) Configure the port Falcon Sensor should leverage for proxying | +| falcon.billing | (optional) Configure Pay-as-You-Go (metered) billing rather than default billing | +| falcon.provisioning_token | (optional) Configure a Provisioning Token for CIDs with restricted AID provisioning enabled | +| falcon.tags | (optional) Configure Falcon Sensor Grouping Tags; comma-delimited | +| falcon.trace | (optional) Configure Falcon Sensor Trace Logging Level (none, err, warn, info, debug) | + +All arguments are optional, but successful deployment requires either falcon_id and falcon_secret **or** cid and image. When deploying using the CrowdStrike Falcon API, the container image and CID will be fetched from CrowdStrike Falcon API. While in the latter case, the CID and image location is explicitly specified by the user. + +### Auto Proxy Configuration + +The operator will automatically configure the sensor's proxy configuration when the cluster proxy is configured on OpenShift via OLM. When not running on OpenShift, adding the proxy configuration via environment variables to the operator's deployment spec will also configure the sensor's proxy information. These settings can be overridden by configuring the [sensor's proxy settings](#falcon-sensor-settings) + +### Image Registry considerations + +Falcon Admission Image is distributed by CrowdStrike through CrowdStrike Falcon registry. Operator supports two modes of deployment: + +#### (Option 1) Use CrowdStrike registry directly + +Does not require any advanced setup. Users are advised to use the following except in their FalconAdmission custom resource definition. + +```yaml +registry: + type: crowdstrike +``` + +Falcon Admission product will then be installed directly from CrowdStrike registry. Any new deployment to the cluster may contact CrowdStrike registry for the image download. + +#### (Option 2) Let operator mirror Falcon Admission Controller image to your local registry + +Requires advanced setup to grant the operator push access to your local registry. The operator will then mirror the Falcon Admission image from CrowdStrike registry to your local registry of choice. +Supported registries are: acr, ecr, gcr, and openshift. Each registry type requires advanced setup enable image push. + +Consult specific deployment guides to learn about the steps needed for image mirroring. + +{{- if ne .Distro "openshift" }} + + - [Deployment Guide for AKS/ACR](../../deployment/azure/README.md) + - [Deployment Guide for EKS/ECR](../../deployment/eks/README.md) + - [Deployment Guide for EKS Fargate](../../deployment/eks-fargate/README.md) + - [Deployment Guide for GKE/GCR](../../deployment/gke/README.md) + - [Deployment Guide for OpenShift](../../deployment/openshift/README.md) +{{- else if eq .Distro "openshift" }} + +- [Deployment Guide for OpenShift](../../README.md) +{{- end }} + +#### (Option 3) Use a custom Image URI + +Image must be available at the specified URI; setting the image attribute will cause registry settings to be ignored. No image mirroring will be leveraged. + +Example: +```yaml +image: myprivateregistry.internal.lan/falcon-admission/falcon-sensor:6.47.0-3003.container.x86_64.Release.US-1 +``` + +### Install Steps +To install Falcon Admission Controler, run the following command to install the FalconAdmission CR: +```sh +{{ .KubeCmd }} create -f https://raw.githubusercontent.com/crowdstrike/falcon-operator/main/config/samples/falcon_v1alpha1_falconadmission.yaml --edit=true +``` + +### Uninstall Steps +To uninstall Falcon Admission Controller simply remove the FalconAdmission resource. The operator will uninstall the Falcon Admission Controller from the cluster. + +```sh +{{ .KubeCmd }} delete falconadmission --all +``` + +### Troubleshooting + +- Falcon Operator modifies the FalconAdmission CR based on what is happening in the cluster. You can get list the CR, Operator Version, and Sensor version by running the following: + + ```sh + $ {{ .KubeCmd }} get falconadmission + NAME OPERATOR VERSION FALCON SENSOR + falcon-admission 0.8.0 6.51.0-3401.container.x86_64.Release.US-1 + ``` + + This is helpful information to use as a starting point for troubleshooting. + You can get more insight by viewing the FalconAdmission CRD in full detail by running the following command: + + ```sh + {{ .KubeCmd }} get falconadmission -o yaml + ``` + +- To review the logs of Falcon Operator: + ```sh + {{ .KubeCmd }} -n falcon-operator logs -f deploy/falcon-operator-controller-manager -c manager + ``` + +- To review the logs of Falcon Admission controller service: + ```sh + {{ .KubeCmd }} logs -n falcon-kac -l "crowdstrike.com/provider=crowdstrike" + ``` + +- To review the currently deployed version of the operator: + ```sh + {{ .KubeCmd }} get falconadmission -A -o=jsonpath='{.items[].status.version}' + ``` + + +### Additional Documentation +End-to-end guide(s) to install Falcon-operator together with FalconAdmission resource. + +{{- if ne .Distro "openshift" }} + - [Deployment Guide for AKS/ACR](../../deployment/azure/README.md) + - [Deployment Guide for EKS/ECR](../../deployment/eks/README.md) + - [Deployment Guide for EKS Fargate](../../deployment/eks-fargate/README.md) + - [Deployment Guide for GKE/GCR](../../deployment/gke/README.md) + - [Deployment Guide for OpenShift](../../deployment/openshift/README.md) +{{- else if eq .Distro "openshift" }} + - [Deployment Guide for OpenShift](../../README.md) +{{- end }} + + + diff --git a/docs/src/resources/container.md.tmpl b/docs/src/resources/container.md.tmpl index 2e9a69ee..47dd7e22 100644 --- a/docs/src/resources/container.md.tmpl +++ b/docs/src/resources/container.md.tmpl @@ -1,6 +1,5 @@ # Falcon Container Sensor - ## About Falcon Container Sensor The Falcon Container sensor for Linux extends runtime security to container workloads in Kubernetes clusters that don’t allow you to deploy the kernel-based Falcon sensor for Linux. The Falcon Container sensor runs as an unprivileged container in user space with no code running in the kernel of the worker node OS. This allows it to secure Kubernetes pods in clusters where it isn’t possible to deploy the kernel-based Falcon sensor for Linux on the worker node, as with AWS Fargate where organizations don’t have access to the kernel and where privileged containers are disallowed. The Falcon Container sensor can also secure container workloads on clusters where worker node security is managed separately. @@ -60,7 +59,6 @@ spec: | registry.tls.caCertificate | (optional) A string containing an optionally base64-encoded Certificate Authority Chain for self-signed TLS Registry Certificates | registry.tls.caCertificateConfigMap | (optional) The name of a ConfigMap containing CA Certificate Authority Chains under keys ending in ".tls" for self-signed TLS Registry Certificates (ignored when registry.tls.caCertificate is set) | registry.acr_name | (optional) Name of ACR for the Falcon Container push. Only applicable to Azure cloud. (`registry.type="acr"`) | -| registry.ecr_iam_role_arn | (optional) ARN of AWS IAM Role to be assigned to the Injector (only needed when injector runs on EKS Fargate) | | injector.serviceAccount.annotations | (optional) Annotations that should be added to the Service Account (e.g. for IAM role association) | | injector.listenPort | (optional) Override the default Injector Listen Port of 4433 | | injector.replicas | (optional) Override the default Injector Replica count of 2 |