Istio via Helm
Introduction
The instructions below show how to install Curiefense on a Kubernetes cluster, embedded in an Istio service mesh.
The following tasks, each described below in sequence, should be performed:
At the bottom of this page is a Reference section describing the charts and configuration variables.
During this process, you might find it helpful to read the descriptions (which include the purpose, secrets, and network/port details) of the services and their containers: Services and Container Images
Clone the Helm Repository
Clone the repository, if you have not already done so:
This documentation assumes it has been cloned to ~/curiefense-helm
.
Create a Kubernetes Cluster
Access to a Kubernetes cluster is required. Dynamic provisioning of persistent volumes must be supported. To set a StorageClass other than the default, change or override variable storage_class_name
in ~/curiefense-helm/curiefense-helm/curiefense/values.yaml
.
Below are instructions for several ways to achieve this:
Using minikube, Kubernetes 1.23.3
Using Google GKE, Kubernetes 1.23
Using Amazon EKS, Kubernetes 1.23
You will need to install the following clients:
Install kubectl (https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- use the same version as your cluster.
Install Helm v3 (https://helm.sh/docs/intro/install/)
Option 1: Using minikube
This section describes the install for a single-node test setup (which is generally not useful for production).
Install minikube
Starting from a fresh ubuntu 21.04 VM:
Install docker (https://docs.docker.com/engine/install/ubuntu/), and allow your user to interact with docker with
sudo usermod -aG docker $USER && newgrp docker
Install minikube (https://minikube.sigs.k8s.io/docs/start/)
Start a screen
or tmux
, and keep the following command running:
Option 2: Using Google GKE
Create a cluster
Option 3: Using Amazon EKS
Create a cluster
Reset State
If you have a clean machine where Curiefense has never been installed, skip this step and go to the next.
Otherwise, run these commands:
Ensure that helm ls -a --all-namespaces
outputs nothing.
Create Namespaces
Run the following commands:
Setup storage
Curiefense's confserver exports configurations to object storage services, from which they are retrieved by curieproxy. Four backends are currently supported: AWS S3, Google Cloud Storage, minio (which can be self-hosted), or local storage (for single-node test deployments). To use curiefense, you must pick one, and define Secrets that allow interacting with the chosen storage service (except for local storage).
Option 1: AWS credentials
Encode the AWS S3 credentials that have r/w access to the S3 bucket. This yields a base64 string:
Create a local file called s3cfg.yaml
, with the contents below, replacing both occurrences of BASE64_S3CFG
with the previously obtained base64 string:
Deploy this secret to the cluster:
Option 2: Google Cloud Storage credentials
Create a bucket, and a service account that has read/write access to the bucket. Obtain a private key for this account, which should look like this:
Create a local file called gs.yaml
, with the contents below, replacing both occurrences of BASE64_GS_PRIVATE_KEY
with the previously obtained base64 string:
Deploy this secret to the cluster:
Set the curieconf_manifest_url
variables in curiefense-helm/curiefense/values.yaml
and istio-helm/charts/gateways/istio-ingress/values.yaml
to the following URL: gs://BUCKET_NAME/prod/manifest.json
(replace BUCKET_NAME with the actual name of the bucket).
Also set the curiefense_bucket_type
variables in the same values.yaml files to gs
.
Option 3: minio credentials
Install a minio server, create a bucket and a Service Account that has read/write permissions to that bucket. The curiefense helm charts may be used to deploy such a minio server (single-node, default credentials, for testing).
Encode the minio credentials that have r/w access to the bucket. This yields a base64 string:
Create a local file called miniocfg.yaml
, with the contents below, replacing both occurrences of BASE64_MINIOCFG
with the previously obtained base64 string:
Deploy this secret to the cluster:
An example miniocfg.yaml file is provided in ~/curiefense-helm/curiefense-helm/example-miniocfg.yaml
. It contains default credentials for minio, that will work with the minio installation that is provided in the curiefense helm charts.
Set the curieconf_manifest_url
variables in curiefense-helm/curiefense/values.yaml
and istio-helm/charts/gateways/istio-ingress/values.yaml
to the following URL: minio://BUCKET_NAME/prod/manifest.json
(replace BUCKET_NAME with the actual name of the bucket; use curiefense-minio-bucket
with the minio installation that is provided in the curiefense helm charts).
Also set the curiefense_bucket_type
variables in the same values.yaml files to minio
.
Option 4: local bucket
For clusters where all istio ingress proxies as well as the confserver run on the same kubernetes node (typically test environments), a simple hostPath
volume can be used. It is mounted to /bucket
on the host machine, as well as in relevant containers.
Set the curieconf_manifest_url
variables in curiefense-helm/curiefense/values.yaml
and istio-helm/charts/gateways/istio-ingress/values.yaml
to the following URL: file:///bucket/prod/manifest.json
.
Also set the curiefense_bucket_type
variables in the same values.yaml files to local-bucket
.
Setup TLS for the UI server
Using TLS is optional. Follow these steps if only if you want to use TLS for communicating with the UI server, and you do not rely on istio to manage TLS.
The UIServer can be made to be reachable over HTTPS. To do that, two secrets have to be created to hold the TLS certificate and TLS key.
Create a local file called uiserver-tls.yaml
, replacing TLS_CERT_BASE64
with the base64-encoded PEM X509 TLS certificate, and TLS_KEY_BASE64
with the base64-encoded TLS key.
Deploy this secret to the cluster:
An example file with self-signed certificates is provided at ~/curiefense-helm/curiefense-helm/example-uiserver-tls.yaml
.
Deploy Istio and Curiefense Images
Deploy the Istio service mesh:
And then the Curiefense components:
Deploy the (Sample) App
The application to be protected by Curiefense should now be deployed. These instructions are for the sample application bookinfo
which is deployed in the default
kubernetes namespace. Installation instructions are summarized below. More detailed instruction are available on the istio website.
Enable Istio injection
Add the istio-injection=enabled
label that will make Istio automatically inject necessary sidecars to applications that are deployed in the default
namespace.
Install the application
Test bookinfo
Check that bookinfo
Pods are running (wait a bit if they are not):
Sample output example:
Check that the application is working by querying its API directly without going through the Istio service mesh:
Expected output:
Test access to bookinfo through Istio
Set the GATEWAY_URL variable by following instructions on the Istio website.
Alternatively, with minikube, this command can be used instead:
Check that bookinfo is reachable through Istio:
Expected output:
If this error occurs: Could not resolve host: a6fdxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx.us-west-2.elb.amazonaws.com
...the ELB is not ready yet. Wait and retry until it becomes available (typically a few minutes).
Check that logs are emitted by the ingress gateway
Run this query to access the protected website, bookinfo, and thus generate an access log entry:
Run this to ensure that the logs have been emitted:
Expected output:.
Expose Curiefense Services Using NodePorts
Run the following commands to expose Curiefense services through NodePorts. Warning: if the machine has a public IP, the services will be exposed on the Internet.
Start with this command:
The following command can be used to determine the IP address of your cluster nodes on which services will be exposed:
For minikube only:
If you are using minikube, also run the following commands on the host in order to expose services on the Internet (ex. if you are running this on a cloud VM):
For Amazon EKS only:
If you are using Amazon EKS, you will also need to allow inbound connections for port range 30000-30500 from your IP. Go to the EC2 page in the AWS console, select the EC2 instance for the cluster (named curiefense-eks-...-Node
), select the "Security" pane, select the security group (named eks-cluster-sg-curiefense-eks-[0-9]+
), then add the incoming rule.
Access Curiefense Services
Services are now available on the IP address of any of the Kubernetes nodes, through a Node Port.
Service | Node Port | Notes |
---|---|---|
Curiefense UI over HTTP | 30080 | |
Curiefense UI over HTTPS | 30443 | |
Grafana over HTTP | 30300 | |
Kibana over HTTP | 30601 | |
Configuration API | 30000 | swagger at http://IP:30000/api/v1 |
Elasticsearch | 30200 |
For a full list of ports used by Curiefense containers, see the Reference page on services and containers.
Reference: Description of Helm Charts
Curiefense charts
Helm charts are divided as follows:
curiefense-admin
- confserver, and UIServer.curiefense-dashboards
- Grafana and Prometheus.curiefense-log
- elasticsearch, filebeat, fluentd, kibana, logstash.curiefense-proxy
- curielogger and redis.
Chart configuration variables
Configuration variables in ~/curiefense-helm/curiefense-helm/curiefense/values.yaml
can be modified or overridden to fit your deployment needs:
Variables in the
images
section define the Docker image names for each component. Override this if you want to host images on your own private registry.storage_class_name
is the StorageClass that is used for dynamic provisioning of Persistent Volumes. It defaults tonull
(default storage class, which works by default on EKS, GKE and minikube)...._storage_size
variables define the size of persistent volumes. The defaults are fine for a test or small-scale deployment.curieconf_manifest_url
is the URL of the AWS S3 or Google Cloud Storage bucket that is used to synchronize configurations between theconfserver
and the Curiefense Istio sidecars.docker_tag
defines the image tag versions that should be used.deploy.sh
will override this to deploy a version that matches the current working directory, unless theDOCKER_TAG
environment variable is set.
Istio chart
Components added or modified by Curiefense are defined in ~/curiefense-helm/istio-helm/charts/gateways/istio-ingress/
. Compared to the upstream Istio Kubernetes distribution, we add or change the following Pods:
An
initContainer
calledcuriesync-initialpull
has been added. It synchronizes configuration before running Envoy.A container called
curiesync
has been added. It periodically fetches the configuration that should be applied from an S3 or GS bucket (configurable with thecurieconf_manifest_url
variable), and makes it available to Envoy. This configuration is used by the LUA code that inspects traffic.The container called
istio-proxy
now uses our custom Docker image, embedding our HTTP Filter, written in Lua.An
EnvoyFilter
has been added. It forwards access logs tocurielogger
(seecuriefense_access_logs_filter.yaml
).An
EnvoyFilter
has been added. It runs Curiefense's Lua code to inspect incoming traffic on the Ingress Gateways (seecuriefense_lua_filter.yaml
).
Chart configuration variables
Configuration variables in ~/curiefense-helm/istio-helm/charts/gateways/istio-ingress/values.yaml
can be modified or overridden to fit your deployment needs:
gw_image
defines the name of the image that contains our filtering code and modified Envoy binary.curiesync_image
defines the name of the image that contains scripts that synchronize local Envoy configuration with the AWS S3 bucket defined incurieconf_manifest_url
.curieconf_manifest_url
is the URL of the AWS S3 bucket that is used to synchronize configurations between theconfserver
and the Curiefense Istio sidecars.curiefense_namespace
should contain the name of the namespace where Curiefense components defined in~/curiefense-helm/curiefense-helm/
are running.redis_host
defines the hostname of the redis server that will be used bycurieproxy
. Defaults to the provided redis StatefulSet. Override this to replace the redis instance with one you supply.initial_curieconf_pull
defines whether a configuration should be pulled from the AWS S3 bucket before running Envoy (true
), or if traffic should be allowed to flow with a default configuration until the next synchronization (typically every 10s).
Last updated