Install Using Helm - new flow (beta)
The steps described here to deploy open-appsec on Kubernetes are currently in beta.
The installation flow as described here has changed from the previous one in the way that deployment of the open-appsec helm chart, CRDs and default configuration are now separate steps. This allows more flexibility and custom selection of the preferred CRD version by the user.
Prerequisites
Kubernetes 1.16.0+ cluster with RBAC enabled with Cluster admin permissions
Helm 3 Package Manager installed on your local machine
kubectl
andwget
command-line tools installed on the system that you use to access the Kubernetes clusterYou have understanding of Kubernetes Ingress and either have an already deployed Ingress or know how to configure one.
(Optional, Recommended) Sign-Up and Login to WebUI Portal If you want to centrally manage your open-appsec WAF deployment via WebUI (SaaS) OR if you want to locally manage your open-appsec WAF deployment but still connect to central WebUI for viewing the local configuration (in read-only), central monitoring, logging and reporting: Follow the instructions below to sign-up and login to the WebUI available at https://my.openappsec.io:
(Optional, Recommended) Create deployment profile for the open-appsec deployment in WebUI Portal If you signed-up and logged in to the WebUI Portal (see prerequisite above), now follow the instructions below to create a new deployment profile for your open-appsec deployment. Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below.
Installation
Step 1: Add the Helm Repo
helm repo add openappsec https://charts.openappsec.io
helm repo update
Step 2: Install open-appsec Helm Chart
Run the following command to install open-appsec together with Ingress NGINX Ingress Controller, Kong API Gateway, or Apache APISIX API Gateway.
helm install open-appsec-nginx openappsec/open-appsec-nginx-ingress \
--set controller.ingressClass=appsec-nginx \
--set controller.ingressClassResource.name=appsec-nginx \
--set controller.ingressClassResource.controllerValue="k8s.io/appsec-nginx" \
--set appsec.persistence.enabled=false \
--set controller.service.externalTrafficPolicy=Local \
--set appsec.userEmail="<your-email-address>" \
--set appsec.agentToken= \
--namespace appsec --create-namespace
Your deployment of open-appsec and the selected proxy solution for integration will be done into a new namespace appsec
.
If you have created a deployment profile in the WebUI (see prerequisites section above) to connect your deployment to the central WebUI please specify this token as value for the appsec.agentToken
parameter (for standalone deployments leave parameter empty).
Replace the value <your-email-address>
for the appsec.userEmail
parameter with your own email address, for more details on this see below.
Optional open-appsec helm install
parameters
helm install
parameters-n <namespace>
: select a namespace name that will include the open-appsec and NGINX ingress controller resources, please use theappsec
namespace.--create-namespace
: create namespace if it doesn't exist--name-template
: name of your deployment, used for pod naming (optional)--set appsec.userEmail
: allows you to associate your email address with your specific deployment by replacing<your-email-address>
with your own email address.This allows us to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future.
--set appsec.persistence.enabled
: persistent volume includes machine learning information, if this is set to false then machine learning information is lost when the appsec container is stopped/restarted.true
: default is truefalse
If this value is set to true (default, when not overriding with
false
) you must also specifyappsec.persistence.learning.storageClass
--set appsec.persistence.learning.storageClass
: Specify storage class to be used for the learning pod. Note: storageClass name specified here must support ReadWriteMany (like AWS EFS or Azure Files).--set appsec.mode
: Configure if the deployment is connected to the central management WebUI (SaaS)standalone
: use this only for standalone deployment (locally managed via CRDs with no connection to central management WebUI (SaaS))managed
: use this for connection to central management WebUI (SaaS), when this is setappsec.agentToken
must be provided as well.
--set appsec.agentToken
: set the deployment profile token from central management WebUI (SaaS) to connect your open-appsec deployment to the central WebUI (SaaS), also make sure to setappsec.mode
tomanaged
when you provide the token, see here how to get the token: create a profile in web UI.--set controller.ingressClassResource.name
: specify unique ingress class name, default is 'appsec-nginx'--set controller.ingressClassResource.controllerValue
: default is 'k8s.io/appsec-nginx'--set controller.service.externalTrafficPolicy=Local
required for preserving original IP address in conjunction with LoadBalancer in e.g. Azure AKS (Standard Load Balancer) or AWS EKS (Network Load Balancer).
For additional available configuration values please check the values.yaml within the downloaded Helm chart and the Ingress NGINX documentation available here.
Step 3: Validate that open-appsec is installed and running
kubectl get pods -n appsec
The READY column should show 2/2 for the ingress controller pod and 1/1 for the learning deployment and shared storage deployment pods.
Step 4: If you connected to central WebUI AND configured your deployment profile in the WebUI to "This management" mode for centrally managing open-appsec configuration:
Create one or more assets in the WebUI which represent web applications and/or Web APIs which you want to be protected by open-appsec WAF and allows you to adjust the open-appsec configuration specifically for each of them. Make sure to link your assets to the specific WebUI Profile which you created earlier (General -> Profiles) and adjust the Threat Prevention mode to Detect-Learn or Prevent (Threat Prevention -> Mode), the steps are described here: Protect Additional Assets
Don't forget to Enforce policy in the WebUI after you did any changes for those changes to become effective!
The following steps 5-10 are only relevant if you want to locally manage this open-appsec deployment in Kubernetes using a declarative configuration using custom resources.
They apply to the following two cases:
You do not want to connect to central WebUI at all (you didn't provide a deployment profile token earlier)
You provided deployment profile token earlier for a WebUI profile set to mode "Declarative Management"
Step 5: (only for locally-managed deployments) Download the yaml file for open-appsec CRD installation
Run the following command to obtain the yaml file containing the open-appsec CRD definitions, chose the CRD version you want to use. v1beta1 CRDs:
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/crds/open-appsec-crd-v1beta1.yaml
v1beta2 CRDs (beta):
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/crds/open-appsec-crd-v1beta2.yaml
Step 6: (only for locally-managed deployments) Create the open-appsec CRDs which add new K8s resource-types that will be used later for defining the protection policies, log settings, exceptions, user response and more.
Deploy the CRDs using the following command: If you downloaded v1beta1 CRDs:
kubectl apply -f ./open-appsec-crd-v1beta1.yaml
If you downloaded v1beta2 CRDs:
kubectl apply -f ./open-appsec-crd-v1beta2.yaml
Step 7: (only for locally-managed deployments) Download a default configuration for the open-appsec custom resources
Run the following command to obtain the yaml file containing the open-appsec default configuration custom resources, chose the CRD version which you have deployed in the steps above on your cluster. Default configuration for v1beta1 in detect-learn mode:
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/k8s/v1beta1/open-appsec-k8s-default-config-v1beta1.yaml
Default configuration for v1beta2 (beta) in detect-learn mode:
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/k8s/v1beta2/open-appsec-k8s-default-config-v1beta2.yaml
Step 8: (only for locally-managed deployments) Deploy default configuration for the open-appsec custom resources
To deploy the default configuration for the open-appsec custom resources perform the step below: Apply default configuration for v1beta1:
kubectl apply -f ./open-appsec-k8s-default-config-v1beta1.yaml
Default configuration for v1beta2 (beta):
kubectl apply -f ./open-appsec-k8s-default-config-v1beta2.yaml
Step 9: Setup options (only for locally-managed deployments)
Here's the available options:
NGINX Ingress Controller Option 1: Add protection to existing running Ingress
open-appsec implements K8s ingress resources serving as an NGINX ingress controller with multi-layered Web App & API protection functionalities.
If you use today an NGINX Ingress, you can easily update your existing K8S ingress resource to use open-appsec ingress. Once you apply the change, the ingress will reload and traffic will be protected.
This is a good approach for a lab, staging or non critical production environments. For production deployments we suggest to first run a new Ingress protected with open-appsec WAF in parallel, see instructions "NGINX Ingress Controller (2)" (next tab).
a. Make sure to have an open-appsec policy resource
If you followed the steps above you should now have an open-appsec-best-practice-policy custom resource deployed on your K8s cluster. You can check this with the following command which will list all open-appsec policy custom resources:
kubectl get policies.openappsec.io
If you want to check if it's set to detect-learn
(default) or prevent-learn
mode you can use this command:
When using v1beta1 CRDs:
kubectl get policies.openappsec.io open-appsec-best-practice-policy -o yaml
When using v1beta2 CRDs:
kubectl get policies.openappsec.io default-policy -o yaml
If you want to create your own custom policy, you find all details here:
For v1beta1 CRDs: Configuration Using CRDs
For v1beta2 CRDs: Configuration Using CRDs - v1beta2
b. Find out the name of your relevant ingress resource:
kubectl get ing -A
c. Edit the ingress resource:
kubectl edit ing/<ingress name> -n <ingress namespace>
d. Change the ingressClassname to the ingress class name used by open-appsec:
spec:
ingressClassName: appsec-nginx
The default ingress class name used by open-appsec is appsec-nginx
. In case you configured another ingress class name, please adjust the setting accordingly.
e. Add this annotation to activate the desired open-appsec policy custom resource:
openappsec.io/policy: default-policy
Make sure to use the correct name for the open-appsec policy resource which you created above.
Step 10: Validate that open-appsec works
Your existing or new Ingress is now running and you can try it out!
Generate some traffic to one of the services defined in your ingress.
Run this command to see logs:
Note the name of the ingress nginx pod by running:
kubectl get pods -n appsec
Show the logs of the open-appsec agent container by running:
kubectl logs [ingress nginx pod name] -c open-appsec -n appsec
Step 10: Point your DNS to the New Ingress
After testing that your services are reachable, you can point your public DNS record to the new ingress.
In case of a problem, at any time, you can either switch open-appsec off while running the same ingress code, or change your DNS back.
Last updated
Was this helpful?