Installation

Install Otterize without Otterize Cloud (OSS only)

You'll need Helm installed on your machine to install Otterize as follows:

helm repo add otterize https://helm.otterize.com
helm repo update
helm install otterize otterize/otterize-kubernetes -n otterize-system --create-namespace

This chart is a bundle of the Otterize intents operator, Otterize credentials operator, Otterize network mapper, and SPIRE. Initial deployment may take a couple of minutes. You can add the --wait flag for Helm to wait for deployment to complete and all pods to be Ready, or manually watch for all pods to be Ready using kubectl get pods -n otterize-system -w.

After all the pods are ready you should see the following (or similar) in your terminal when you run kubectl get pods -n otterize-system:

NAME                                                       READY  STATUS  RESTARTS AGE
credentials-operator-controller-manager-6c56fcfcfb-vg6m9   2/2    Running   0     9s
intents-operator-controller-manager-65bb6d4b88-bp9pf       2/2    Running   0     9s
otterize-network-mapper-779fffd959-twjqd                   1/1    Running   0     9s
otterize-network-sniffer-65mjt                             1/1    Running   0     9s
otterize-spire-agent-lcbq2                                 1/1    Running   0     9s
otterize-spire-server-0                                    2/2    Running   0     9s
otterize-watcher-b9bf87bcd-276nt                           1/1    Running   0     9s

Upgrade Otterize

Use Helm to upgrade to the latest version of Otterize:

helm repo update
helm upgrade --install otterize otterize/otterize-kubernetes -n otterize-system

Install Otterize with Otterize Cloud

To connect Otterize OSS to Otterize Cloud you will need to log in, create an integration, and follow the instructions which generates unique credentials for your cluster to communicate to Otterize Cloud.

Install just the Otterize network mapper

helm repo add otterize https://helm.otterize.com
helm repo update
helm install network-mapper otterize/network-mapper -n otterize-system --create-namespace

You can add the --wait flag for Helm to wait for deployment to complete and all pods to be Ready, or manually watch for all pods to be Ready using kubectl get pods -n otterize-system -w.

Create a cluster with support for network policies

Before you start, you need to have a Kubernetes cluster with a CNI that supports NetworkPolicies.

Below are instructions for setting up a Kubernetes cluster with network policies. If you don't have a cluster already, we recommend starting out with a Minikube cluster.

Minikube

If you don't have the Minikube CLI, first install it.

Then start your Minikube cluster with Calico, in order to enforce network policies.

minikube start --cpus=4 --memory 4096 --disk-size 32g --cni=calico

The increased CPU, memory and disk resource allocations are required to be able to deploy the ecommerce app used in the visual tutorials successfully.

Google GKE

Visit the official documentation, or follow the instructions below:

gcloud CLI

To use the gcloud CLI for this tutorial, first install and then initialize it.

To enable network policy enforcement when creating a new cluster:

Run the following command:

gcloud container clusters create CLUSTER_NAME --enable-network-policy --zone=ZONE

(Replace CLUSTER_NAME with the name of the new cluster and ZONE with your zone.)

To enable network policy enforcement for an existing cluster, perform the following tasks:

Run the following command to enable the add-on:

gcloud container clusters update CLUSTER_NAME --update-addons=NetworkPolicy=ENABLED

(Replace CLUSTER_NAME with the name of the cluster.)

Then enable network policy enforcement on your cluster, re-creating your cluster's node pools with network policy enforcement enabled:

gcloud container clusters update CLUSTER_NAME --enable-network-policy

(Replace CLUSTER_NAME with the name of the cluster.)

Console

To enable network policy enforcement when creating a new cluster:

1. Go to the Google Kubernetes Engine page in the Google Cloud console. The remaining steps will appear automatically in the Google Cloud console.

2. On the Google Kubernetes Engine page, click Create.

3. Configure your cluster as desired.

4. From the navigation pane, under Cluster, click Networking.

5. Select the checkbox to Enable network policy.

6. Click Create.

To enable network policy enforcement for an existing cluster:

1. Go to the Google Kubernetes Engine page in the Google Cloud console. The remaining steps will appear automatically in the Google Cloud console.

2. In the cluster list, click the name of the cluster you want to modify.

3. Under Networking, in the Network policy field, click Edit network policy.

4. Select the checkbox to Enable network policy for master and click Save Changes.

5. Wait for your changes to apply, and then click Edit network policy again.

6. Select the checkbox to Enable network policy for nodes.

7. Click Save Changes.

AWS EKS

Starting August 29, 2023, you can configure the built-in VPC CNI add-on to enable network policy support. To spin up a new cluster, use the following eksctl ClusterConfig, and save it to a file called cluster.yaml.

Spin up the cluster using eksctl create cluster -f cluster.yaml. This will spin up a cluster called network-policy-demo in us-west-2.

The important bit is the configuration for the VPC CNI addon:

    configurationValues: |-
      enableNetworkPolicy: "true"

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: network-policy-demo
  version: "1.27"
  region: us-west-2

iam:
  withOIDC: true

vpc:
  clusterEndpoints:
    publicAccess: true
    privateAccess: true

addons:
  - name: vpc-cni
    version: 1.14.0
    attachPolicyARNs: #optional
    - arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy 
    configurationValues: |-
      enableNetworkPolicy: "true"
  - name: coredns
  - name: kube-proxy

managedNodeGroups:
  - name: x86-al2-on-demand
    amiFamily: AmazonLinux2
    instanceTypes: [ "m6i.xlarge", "m6a.xlarge" ]
    minSize: 0
    desiredCapacity: 2
    maxSize: 6
    privateNetworking: true
    disableIMDSv1: true
    volumeSize: 100
    volumeType: gp3
    volumeEncrypted: true
    tags:
      team: "eks"

For guides that deploy the larger set of services, Kafka and ZooKeeper are also deployed, and you will also need the EBS CSI driver to accommodate their storage needs. Follow the AWS guide for the EBS CSI add-on to do so. If you're not using the VPC CNI, you can set up the Calico network policy controller using the following instructions:

Visit the official documentation, or follow the instructions below:

1. Spin up an EKS cluster using the console, AWS CLI or eksctl.
2. Install Calico for network policy enforcement, without replacing the CNI:

kubectl apply -f https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/v1.12.6/config/master/calico-operator.yaml
kubectl apply -f https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/v1.12.6/config/master/calico-crs.yaml

Azure AKS

You can set up an AKS cluster using this guide.

For network policy support, no setup is required: Azure AKS comes with a built-in network policy implementation called Azure Network Policy Manager. You can choose whether you'd like to use this option or Calico when you create a cluster.

Read more at the official documentation site.

---

Install the Otterize CLI

The Otterize CLI is a command-line utility used to control and interact with the Otterize network mapper, manipulate local intents files, and interact with Otterize Cloud.

To install the CLI:

Mac

Brew

brew install otterize/otterize/otterize-cli

Apple Silicon

curl -LJO https://get.otterize.com/otterize-cli/v1.0.13/otterize_macOS_arm64_notarized.zip
tar xf otterize_macOS_arm64_notarized.zip
sudo cp otterize /usr/local/bin  # optionally move to PATH

Intel 64-bit

curl -LJO https://get.otterize.com/otterize-cli/v1.0.13/otterize_macOS_x86_64_notarized.zip
tar xf otterize_macOS_x86_64_notarized.zip
sudo cp otterize /usr/local/bin  # optionally move to PATH

Windows

Scoop

scoop bucket add otterize-cli https://github.com/otterize/scoop-otterize-cli
scoop update
scoop install otterize-cli

64-bit

Invoke-WebRequest -Uri https://get.otterize.com/otterize-cli/v1.0.13/otterize_windows_x86_64.zip -OutFile otterize_Windows_x86_64.zip
Expand-Archive otterize_Windows_x86_64.zip -DestinationPath .
# optionally move to PATH

Linux

64-bit

wget https://get.otterize.com/otterize-cli/v1.0.13/otterize_linux_x86_64.tar.gz
tar xf otterize_linux_x86_64.tar.gz
sudo cp otterize /usr/local/bin  # optionally move to PATH

More variants are available at the GitHub Releases page.

Uninstall Otterize

Before uninstalling

Before uninstalling Otterize, you should make sure to delete any resources created by users: ClientIntents and KafkaServerConfigs.

When you remove these resources, the intents operator will clean up network policies and Kafka ACLs it created. If you remove the operator before doing so, it will not be able to clean up.

If, however, you want the network policies and ACLs to stay in place (because you're redeploying with different configuration, for example), don't remove them.

1. First check if any ClientIntents exist: kubectl get clientintents --all-namespaces
2. If so, remove them.
3. Check if any KafkaServerConfigs exist: kubectl get kafkaserverconfig --all-namespaces
4. If so, remove them.

It's important to remove ClientIntents before removing KafkaServerConfigs, as once you remove the KafkaServerConfig for a Kafka cluster, the intents operator will no longer know how to connect to it and perform cleanup.

Uninstallation

helm uninstall otterize -n otterize-system