# Install With Helm using Webhook

{% hint style="warning" %}
The installation steps on this page apply to following supported open-appsec integrations:

* Istio Ingress Controller (currently in beta)
* Kong, new integration using native, Lua-based open-appsec attachment plugin (currently in beta)

For all other open-appsec integrations on Kubernetes see: [install-using-helm-new-flow-beta](https://docs.openappsec.io/getting-started/start-with-kubernetes/install-using-helm-new-flow-beta "mention")

Let us know if you have any feedback regarding these beta programs or require technical assistance: [mailto://info@openappsec.io](mailto:info@openappsec.io)
{% endhint %}

{% hint style="info" %}
The open-appsec integration with Kong as shown on this page is for the newer, more flexible version of the Kong open-appsec integration which is based on using a Lua plugin. This is a more native integration than the traditional plugin (also still available, but will be deprecated in the future) and is following the official Kong plugin guidelines.

As this is a regular Kong plugin, you must make sure to also configure the plugin to apply to your traffic (e.g. all traffic, specific routes, etc.), as otherwise the open-appsec agent will not receive the traffic for inspection. You find all required info below in the documentation
{% endhint %}

The steps described on this page explain how to deploy and integrate open-appsec on Kubernetes:

* with an existing Istio Ingress Gateway already deployed on Kubernetes
* with an existing Kong API Gateway already deployed on Kubernetes

## Prerequisites

* Kubernetes 1.16.0+ cluster with [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) enabled with Cluster admin permissions
* [Helm 3 Package Manager](https://helm.sh/docs/intro/install/) installed on your local machine
* `kubectl` and `wget` command-line tools installed on the system that you use to access the Kubernetes cluster
* For Istio:
  * An existing deployment of Istio Ingress Gateway. Supported versions: 1.23 - 1.26
  * You should have an understanding of Istio Kubernetes CRD types "Virtual Service" and "Gateway"
* For Kong:
  * An existing deployment of Kong API Gateway. 
  * You should have an understanding of Kubernetes "Ingress"

### **Optional (Recommended)**

To use the open-appsec central management web UI for managing your open-appsec WAF deployment — either **centrally** via WebUI (SaaS) or **locally** with optional **read-only WebUI monitoring** — follow these steps (not required if you plan to manage your deployment only locally, declaratively):

* **Sign Up / Log In**\
  Go to <https://my.openappsec.io> and sign up or log in to access the WebUI.

{% content-ref url="../using-the-web-ui-saas/sign-up-and-login-to-portal" %}
[sign-up-and-login-to-portal](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/sign-up-and-login-to-portal)
{% endcontent-ref %}

* **Create a Deployment Profile**\
  Once logged in, create a new deployment profile for your open-appsec setup.\
  **Important:** After completing policy installation, **copy the profile token**—you’ll need it in the installation steps that follow.

{% content-ref url="../using-the-web-ui-saas/create-a-profile" %}
[create-a-profile](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/create-a-profile)
{% endcontent-ref %}

## Installation

#### Step 1: Add the Helm Repo

{% hint style="info" %}
Please note that this new installation flow with helm uses a different helm chart.
{% endhint %}

```bash
helm repo add openappsec https://charts.openappsec.io
helm repo update
```

#### Step 2: Deployment

{% tabs %}
{% tab title="Istio" %}
Run the following command to deploy the open-appsec helm chart into your Istio Ingress Controller namespace:

```bash
helm install open-appsec-webhook openappsec/open-appsec-injector \
--set webhook.objectSelector.labelValue=istio-ingress \
--set webhook.objectSelector.labelName=app \
--set kind=istio \
--set appsec.persistence.enabled=false \
--set gateways.istio-ingressgateway.service.externalTrafficPolicy=Local \
--set appsec.userEmail=<your-email-address> \
--set appsec.agentToken= \
-n [istio ingress gateway namespace]
```

Before running the installation command, make sure to update the placeholders according to your environment:

* **`istio ingress gateway namespace`** - Replace this with the **namespace** of your existing Istio ingress gateway deployment.
* `appsec.agentToken`  - If you are connecting to the central WebUI, add the profile token you received after creating a deployment profile in the WebUI.
  * For standalone deployments leave parameter empty
* `appsec.userEmail` **-** Replace `<your-email-address>` with your own **email address**.

**open-appsec will now be deployed into the existing namespace of your istio ingress gateway.**

{% hint style="info" %}
If you have persistent storage available in your cluster please set the `--set appsec.persistence.enabled=false` parameter in the following command to `true` to allow open-appsec to use persistent storage for the learning. This is only shown for maximum compatibility reasons.
{% endhint %}

<details>

<summary>Optional open-appsec helm install  parameters</summary>

* `-n <istio ingress gateway namespace>`: select the existing namespace name of the istio ingress gateway deployment to which open-appsec should be added and integrated with.

{% hint style="warning" %}
The open-appsec-waf-injector is using a label in the istio ingress gateway deployment to identify those pods, to which the open-appsec agent container should be automatically added (via mutating webhook).\
In addition it adds and loads our attachment module as a filter in the istio ingress gateway container, allowing the open-appsec agent to inspect traffic arriving at the istio ingress gateway.\
\
In case of the default value an open-appsec agent container will e.g. be added to each istio ingress gateway pod which has the following label set: `app: istio-ingress` \
Two parameters are available that allow you to customize the name and value of that label.<br>
{% endhint %}

* `--set kind`: specify the integration you want to deploy, for Istio make sure to select `istio` as value.
* `--set webhook.objectSelector.labelName` : specify the name of the label (default name is `app`) which is used to identify the deployment istio ingress gateway deployment to which the open-appsec attachment should be automatically injected.
* `--set webhook.objectSelector.labelValue` : specify the value of the label (default is `istio-ingress)` which is used to identify the istio ingress gateway deployment to which the open-appsec attachment should be automatically injected.&#x20;
* `--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.&#x20;

  * `true`: default is true
  * `false`

  If this value is set to true (default, when not overriding with `false`) you must also specify `appsec.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.agentToken`: set the deployment profile token from central management WebUI (SaaS) to connect your open-appsec deployment to the central WebUI (SaaS), see here how to get the token: [create a profile in web UI](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/create-a-profile). If you don't set this then your deployment will be in standalone mode.
* `--set gateways.istio-ingressgateway.service.externalTrafficPolicy=Local` recommended for preserving original IP address by making sure that traffic for the loadbalancer service is only routed to pods on the same node.

For additional available configuration values please check the values.yaml within the downloaded Helm chart and the Ingress Ingress Gateways documentation available [here](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/).

</details>
{% endtab %}

{% tab title="Kong" %}

### Kong helm chart adjustment and redeployment

You will continue to use your regular Kong helm chart, but with an adjustment to make the open-appsec Lua-based attachment plugin available:<br>

1. Redeploy your existing helm-based Kong gateway deployment by replacing the kong proxy container with an enhanced kong proxy container provided by open-appsec which already includes the *open-appsec-waf-kong-plugin* (or alternatively build a container yourself which includes the *open-appsec-waf-kong-plugin*). This plugin is required for the open-appsec agent to receive traffic from the Kong gateway for inspection and returning decisions about allowing/preventing http requests.

You can use one of the following parameters with your kong/kong helm chart deployment:\
\
For replacing the Kong Enterprise Gateway container with the enhanced one for open-appsec:

```bash
--set image.repository=ghcr.io/openappsec/kong-gateway-k8s-attachment-plugin
--set image.tag=latest
```

For replacing the Kong OSS container with the enhanced one for open-appsec:

```bash
--set image.repository=ghcr.io/openappsec/kong-k8s-attachment-plugin
--set image.tag=latest
```

2. Now that we have a Kong container deployed that includes the *open-appsec-waf-kong-plugin*, you must make sure to load it by creating and applying a KongPlugin resource as follows:

{% hint style="info" %}
If you use Kong Konnect, then this is not required, as you can enable the plugin centrally using open-appsec's plugin schema for Kong Konnect, find instructions and all details here:

[using-kong-konnect-kong-only](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/using-kong-konnect-kong-only "mention")
{% endhint %}

Create a file `open-appsec-KongPlugin.yaml` with following content:

```yaml
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: open-appsec-waf-kong-plugin
config: {}
plugin: open-appsec-waf-kong-plugin
```

Apply this file using following command:\
(Replace `[add your kong deployment namespace here]` with your kong deployment namespace.)

```bash
kubectl apply -f open-appsec-KongPlugin.yaml -n [add your kong deployment namespace here]
```

### open-appsec deployment

Run the following command to deploy the open-appsec helm chart into your existing Kong namespace.

Before running the installation command below, make sure to update the placeholders according to your environment:

* **`kong gateway namespace`** - Replace this with the **namespace** of your existing Kong gateway deployment.
* `appsec.agentToken`  - If you are connecting to the central WebUI, add the profile token you received after creating a deployment profile in the WebUI.
  * For standalone deployments leave parameter empty
* `appsec.userEmail` **-** Replace `<your-email-address>` with your own **email address**.

```bash
helm install open-appsec-webhook openappsec/open-appsec-injector \
--set webhook.objectSelector.labelName="app.kubernetes.io/name" \
--set webhook.objectSelector.labelValue=kong \
--set kind=kong \
--set appsec.persistence.enabled=false \
--set appsec.userEmail=<your-email-address> \
--set appsec.agentToken= \
-n [kong gateway namespace]
```

**open-appsec will now be deployed into the existing namespace of your Kong gateway.**

{% hint style="info" %}
If you have persistent storage available in your cluster please set the `--set appsec.persistence.enabled=false` parameter in the following command to `true` to allow open-appsec to use persistent storage for the learning. This is only shown for maximum compatibility reasons.
{% endhint %}

<details>

<summary>Optional open-appsec helm install  parameters</summary>

* `-n <kong gateway namespace>`: select the existing namespace name of the Kong gateway deployment to which open-appsec should be added and integrated with.

{% hint style="warning" %}
The open-appsec-waf-injector is using a label in the Kong gateway deployment to identify those pods, to which the open-appsec agent container should be automatically added (via mutating webhook).\
This allows the open-appsec agent to inspect traffic arriving at the Kong gateway (the attachment plugin which is part of the enhanced Kong container will hand over traffic for inspection to the open-appsec agent in the same pod).\
\
In case of the default value an open-appsec agent container will e.g. be added to each pod which has the following label set: `app: istio-ingress` (this helm chart also support istio integration). Make sure to adjust this for Kong, see helm install command above!\
Two parameters are available that allow you to customize the name and value of that label.
{% endhint %}

* `--set kind`: specify the integration you want to deploy, for Kong make sure to select `kong` as value.
* `--set webhook.objectSelector.labelName` : specify the name of the label (default name is `app`) which is used to identify the existing kong gateway to which the open-appsec attachment should be automatically injected.\
  Make sure to adjust this aligned with your kong gateway deployment, e.g. as shown in the helm install command for Kong above!
* `--set webhook.objectSelector.labelValue` : specify the value of the label (default is `istio-ingress`, as this helm chart also supports istio) which is used to identify the existing kong gateway deployment to which the open-appsec attachment should be automatically injected. \
  Make sure to adjust this aligned with your kong gateway deployment, e.g. as shown in the helm install command for Kong above!
* `--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.&#x20;

  * `true`: default is true
  * `false`

  If this value is set to true (default, when not overriding with `false`) you must also specify `appsec.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.agentToken`: set the deployment profile token from central management WebUI (SaaS) to connect your open-appsec deployment to the central WebUI (SaaS), see here how to get the token: [create a profile in web UI](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/create-a-profile). If you don't set this then your deployment will be in standalone mode.

For additional available configuration values please check the values.yaml within the downloaded Helm chart and the Kong gateway's documentation available [here](https://developer.konghq.com/gateway/install/).

</details>
{% endtab %}
{% endtabs %}

#### Step 3: Enable open-appsec Injection to the existing deployment

To allow open-appsec to inspect the traffic through your existing Istio Ingress or Kong gateway, it must be attached to the existing deployment. This happens automatically **if the proper labels are set** and the deployment is restarted.

1. **Label the Namespace**\
   Add the `inject-waf-attachment=true` label to the **namespace** of your existing reverse proxy deployment (e.g. Istio Ingress Gateway or Kong):

   ```bash
   kubectl label namespace [existing reverse proxy deployment namespace] inject-waf-attachment="true" --overwrite
   ```
2. **Label the Deployment**\
   Ensure your current reverse proxy **deployment** has the required labels set as configured in your `webhook.objectSelector`:

   * `webhook.objectSelector.labelName`
   * `webhook.objectSelector.labelValue`

   *(These labels must match what’s configured in the open-appsec Helm chart. Refer to your Helm values or the section above for details.)*
3. **Restart the existing reverse proxy deployment**

Restart your existing deployment by using the following command:

```
kubectl rollout restart deployment [istio ingress gateway deployment name] -n [istio ingress gateway namespace]
```

{% hint style="success" %}
Here's what happens when you restart the deployment:

* The `inject-waf-attachment`  label **enables** open-appsec to patch the existing deployment.
* An open-appsec **agent container** is injected additionally into each pod using a **Kubernetes mutating webhook**.
* *In case of Istio:* During restart, the open-appsec **attachment** is injected into the existing ingress gateway container.
  {% endhint %}

{% hint style="info" %}
If you want to remove the agent (Istio or Kong) and injected attachment (Istio only) later again, you can set `inject-waf-attachment` to `false` and perform another rollout restart of the deployment so it gets removed again.
{% endhint %}

#### Step 4: Validate that open-appsec is installed and running

```
kubectl get pods -n [reverse proxy deployment namespace]
```

The READY column should now show an additional container running in your proxy pod and should show 1/1 for each of the following pods: waf injector, learning deployment (only in standalone deployment), shared storage deployment (only in standalone deployment).&#x20;

**Step 5: 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:&#x20;

{% content-ref url="../using-the-web-ui-saas/protect-additional-assets" %}
[protect-additional-assets](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/protect-additional-assets)
{% endcontent-ref %}

{% hint style="success" %}
Don't forget to Enforce policy in the WebUI after you did any changes for those changes to become effective!
{% endhint %}

{% hint style="danger" %}
The following steps 6-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"

If you are not managing your deployment locally, scroll down to [#validate-that-open-appsec-works](#validate-that-open-appsec-works "mention")
{% endhint %}

#### Step 6: (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, choose the CRD version you want to use.\
\
v1beta2 CRDs:

```bash
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/crds/open-appsec-crd-v1beta2.yaml
```

#### Step 7:  (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.

{% hint style="info" %}
You can skip this step if you skipped the previous step, because you plan to centrally manage open-appsec from central WebUI and not manage it locally using CRDs.
{% endhint %}

Deploy the CRDs using the following command:

For the v1beta2 CRDs:

```bash
kubectl apply -f ./open-appsec-crd-v1beta2.yaml
```

#### Step 8: (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 v1beta2 in detect-learn mode:

```bash
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/k8s/v1beta2/open-appsec-k8s-default-config-v1beta2.yaml
```

{% hint style="info" %}
The default configuration files provided above are set to detect-learn mode, which is recommended for new deployments to allow the machine learning engine sufficient learning before moving to prevent-learn mode. You can then later easily reconfigure the `open-appsec-best-practice-policy` custom policy resource to prevent-learn mode.\
\
If you would like to start in prevent-mode in non-critical environment for testing purposes right away, you can alternatively use these files, which are preconfigured to prevent-learn mode:

Default configuration for v1beta2 (beta) in prevent-mode

`wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/k8s/v1beta2/open-appsec-k8s-prevent-config-v1beta2.yaml`<br>
{% endhint %}

#### Step 9: (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:\
\
Default configuration for v1beta2 (beta):

```bash
kubectl apply -f ./open-appsec-k8s-default-config-v1beta2.yaml
```

#### Step 10: Configure open-appsec protection using custom resources (only relevant for locally-managed deployments)&#x20;

**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:

```bash
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 (the name of the policy created by the default configuration in v1beta2 is `default-policy`):

```bash
kubectl get policies.openappsec.io default-policy -o yaml
```

If you want to create your own custom policy, you find all details here:

For v1beta2 CRDs: [configuration-using-crds-v1beta2](https://docs.openappsec.io/getting-started/start-with-kubernetes/configuration-using-crds-v1beta2 "mention")

**b. Create a `PolicyActivation` resource**\
\
Using a `PolicyActivation` custom resource you can now specify that your existing open-appsec policy (e.g. `default-policy`, see above)  should be applied to all traffic matching the hostname `example.com`. (You can have multiple `Policy` custom resources and also multiple `PolicyActivation` custom resources)

Create a new file `policy-activation.yaml` to specify a new `PolicyActivation` custom resource similar to the below specification (change `example.com` to your own hostname, adjust `default-policy` if you want to reference another `Policy` custom resource instead of the default one):

```yaml
apiVersion: openappsec.io/v1beta2
kind: PolicyActivation
metadata:
  name: policy-activation-example
spec:
  enabledPolicies:
    - name: default-policy
      hosts:
        - "example.com"
```

Then apply it to your Kubernetes cluster using:

```bash
kubectl apply -f policyactivation.yaml
```

If you want to create your own PolicyActivation custom resource, you find all details here:

For v1beta2 CRDs: [configuration-using-crds-v1beta2](https://docs.openappsec.io/getting-started/start-with-kubernetes/configuration-using-crds-v1beta2 "mention")

## Validate the Deployment:

Your reverse proxy is now protected with open-appsec (in detect or prevent mode)!

1. *In case of Istio:* Generate some traffic to one of the services defined by your Istio `Gateway` and `VirtualService` resources\
   \
   \&#xNAN;*In case of Kong:* Generate some traffic to e.g. the web resource specified in your K8s ingress resource.
2. Run this command to see logs:

Note the name of an Istio ingress gateway pod by running:

```
kubectl get pods -n [reverse proxy deployment namespace]
```

Then show the logs of the open-appsec agent container by running:

```
kubectl logs [reverse proxy deployment pod name] -c open-appsec -n [reverse proxy deployment namespace]
```