Guides
Home

Edge Deployment

Introduction to the Identiq Edge Server, including a detailed installation and deployment guide

Suggest Edits

Introduction

The Edge has 3 primary roles:

  • Storage of hashed data in a dedicated, hardened DB. Also, logs and technical metadata are stored locally. The data is loaded to the edge via a secure ETL process based on an export done by the member. The Edge itself doesn’t have access to the member’s databases.

  • Asker - The member is using the edge to query the network. This can be done via a web user interface or directly via REST API as described here.

  • Vouching - When another member on the network sends a query, Identiq sends this query to all the other members, and the Edge answers this query using the Identiq Protocol with complete anonymity and without sharing any data as described in the Identiq protocol description.

For security and privacy considerations, the Edge server is installed in the company’s VPC or on-premise. The Identiq team does not have access to the Edge server, and the installation process is designed in a way to ensure that the installation remains fully secure.

The installation process takes several hours and requires a joint effort with the Identiq team.

Edge overview and high-level concepts

Ingress Controllers - consists of one controller for the internal-facing endpoint and another for the Identiq cloud-facing endpoint.

  • Internal Endpoint - this is only exposed to the internal company network. It is used to generate verification requests by the company-backed systems to the Identiq network.

  • Identiq Endpoint - an external endpoint that is exposed outside the company’s network. The endpoint should be accessible only by the Identiq cloud network.

Database - a normalized and hashed version of the company’s user database.
In memory-caching - a highly optimized in-memory version of the fingerprint DB that allows the Edge server to vouch requests in milliseconds.

Installation Process

Setting up the prerequisite tools (for the IT/DevOps Team)

Before you start installing the Identiq Edge server, you will have to make a few decisions and make sure that you have the proper tools available. These include:

  1. Working with Identiq to choose the proper cloud region/zone for the Edge deployment.
  2. Providing Identiq with the external IP addresses that the Edge service will use, in order to whitelist the IP on the Identiq network side.
  3. Make sure you have the following software installed on your workstation.
    • Kubectl (see https://kubernetes.io/docs/tasks/tools/install-kubectl/)
    • Terraform (see https://www.terraform.io/downloads.html)
    • Cloud CLI - AWS / GCP / Azure
    • The Identiq staff will provide you with login information for the Identiq SaaS application.
    • For the AWS installation:
      • Please make sure the user who runs the actual deployment has permission to create EKS, EC2 instances, VPC, and internet gateway.
      • Make sure that the AWS, GCP, or Azure account has at least 50 vCPU available (under limits - general instances).

Infrastructure Setup - Provisioning the Kubernetes Cluster

To install a new Edge infrastructure, do the following:

% git clone https://github.com/identiq-protocol/edge-infrastructure.git
% cd edge-infrastructure
% cd examples
Choose the relevant cloud provider (aws/azure/gcp)

% git clone https://github.com/identiq-protocol/edge-infrastructure.git
% cd edge-infrastructure
% cd gcp

% git clone https://github.com/identiq-protocol/edge-infrastructure.git
% cd edge-infrastructure
% cd azure

terraform.tfvars

The file includes the relevant cluster settings.
Before deploying the infrastructure, take into consideration changing the tfvars file based on your cluster size details for the AWS region. Additional IAM roles to administer the cluster and EKS cluster name.

Note: Make sure not to modify the instance type and instance count.

% cat terraform.tfvars
  
eks_cluster_name = "edge-cluster"
region           = "us-east-1"

# Elasticache Redis
external_redis      = true         # Create an external redis using elasticache
external_redis_name = "edge-redis" # Name of the elasticache instance

### uncomment the following lines to enable elasticache cluster mode
#ec_cluster_mode_creation_fix_enabled = true
#ec_cluster_mode_enabled              = true
#ec_cluster_mode_num_node_groups      = 2
#cluster_autoscaler_enabled = true

# RDS Postgres
external_db = true # Create an external postgres using RDS
external_db_name = "edge-db" # Name of the RDS instance

# For configuring additional IAM roles to administer the cluster
# uncomment the variable below and set the correct IAM roles ARN.
# eks_map_roles = [{ rolearn = "arn:aws:iam::012345678901:role/edge-admin", username = "admin", groups = ["system:masters"] }]
# eks_map_users = [{ userarn = "arn:aws:iam::012345678901:user/username", username = "admin", groups = ["system:masters"] }]
# For cloudwatch logs in edge uncomment the following line
# eks_additional_policies = ["arn:aws:iam::aws:policy/CloudWatchLogsFullAccess"]

Apply Changes

Run the following command to create a new edge cluster with the correct size. 

% terraform init
% terraform apply

The cluster creation phase will take approximately 30-60 minutes. Once it's done, a connect command will be printed on the screen, run it:

...

Apply complete! Resources: 83 added, 0 changed, 0 destroyed.

Outputs:


connect = aws eks --region us-east-1 update-kubeconfig --name edge-cluster

nat_ips = [
"107.22.244.123",
 "54.197.237.218",
 "54.166.19.62",
]

Connect to the cluster:

% aws eks --region us-east-1 update-kubeconfig --name edge-cluster

Send the value of the certs to the Identiq contact person for certificate approval.

Apply the SSD Storage Class, Only Azure

Azure (No need for GCP, AWS) has a default storage class name. To simplify the process, the following steps allow for overriding the default name. The name SSD is then used by applying the file ssd.yaml directly, without the need to edit it with the name of the storage class.

ssd.yaml has the necessary definitions to create an SSD storage class - which is automatically assigned to the Kubernetes cluster that was just created.

``` Azure
% kubectl patch storageclass default -p '"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}'
% kubectl drain -l agentpool=default
% kubectl apply -f ssd.yaml

Deploy CRDs

AWS

kubectl apply -f ../../crds/aws-load-balancer-controller.yaml

All Cloud Providers

kubectl apply -f ../../crds/helm-operator.yaml

Set Up SSL Connectivity and Network Authentication

In order to obtain your client configurations, log in to the Identiq SaaS application at https://app.identiq.com, and do the following:

  1. Click the "Admin" menu, located in the top right corner, and then click on the bottom right icon.
  2. On the menu at the bottom right, click on the “Download First Installation YAML” (all.yaml) file, which includes the following document entries:
    • “Client Certificates” (client-cert) - includes the company certificate.
    • “Member Secret” (network-auth) - includes the username and password of the company for network access to the cluster.
    • “Artifacts Secret” (flux-helm-repositories, identiq-docker-key) - includes the secret for the Identiq Docker and Helm repositories.
    • Additional edge config
  3. After obtaining this file from the Identiq application, you can apply it to the cluster:
kubectl apply -f ~/Downloads/all.yml

output:

secret/client-cert created
secret/network-auth created                                                                                                                                                                
secret/identiq-docker-key created
secret/flux-helm-repositories created

Deploy Helm Operator

The Helm Operator is used to deploy the necessary Docker apps, and later to auto-update them when needed. The file crd.yaml (for custom resource definition) defines a new Helm term called “helm releases” that installs helm.
Helm-operator.yaml does all the rest so that the Helm Operator can service the infrastructure automatically.

  1. Install Helm Operator:
kubectl apply -f ../../helm-operator/helm-operator.yaml

output:

serviceaccount/helm-operator created
secret/helm-operator-git-deploy created
configmap/helm-operator-kube-config created
clusterrole.rbac.authorization.k8s.io/helm-operator created
clusterrolebinding.rbac.authorization.k8s.io/helm-operator created
service/helm-operator created
  1. Verify that Helm Operator is successfully installed, by typing:
kubectl logs deployment/helm-operator -f

output:

W0329 15:19:53.028908       6 client_config.go:541] Neither --kubeconfig nor --master was specified.  Using the inClusterConfig.  This might not work.
ts=2020-03-29T15:19:53.827085247Z caller=repository.go:118 component=helm version=v3 info="successfully imported repository" name=identiq url=https://identiq.jfrog.io/identiq/helm
ts=2020-03-29T15:19:53.827498753Z caller=operator.go:98 component=operator info="setting up event handlers"

Deploy Identiq Edge Application

  1. We install the Edge application by applying the following file:
% kubectl apply -f edge.yml
helmrelease.helm.fluxcd.io/edge created

The installation takes around 10 minutes until all resources are successfully deployed.

Ingress Controller Addresses

  1. For AWS Installation, run the following commands and send their output to your Identiq contact person:
% kubectl get svc edge-ingress-controller -o jsonpath='EXTERNAL INGRESS: { .status.loadBalancer.ingress[0].hostname}{"\n"}'
EXTERNAL INGRESS: abcdefghi123123.us-east-1.elb.amazonaws.com
% kubectl get svc edge-ingress-internal-controller -o jsonpath='INTERNAL INGRESS: { .status.loadBalancer.ingress[0].hostname}{"\n"}'           
INTERNAL INGRESS: abcdefghi123123.us-east-1.elb.amazonaws.com

% kubectl get svc edge-ingress-controller -o jsonpath='EXTERNAL INGRESS: { .status.loadBalancer.ingress[0].ip}{"\n"}'
EXTERNAL INGRESS: 1.2.3.4
% kubectl get svc edge-ingress-internal-controller -o jsonpath='INTERNAL INGRESS: { .status.loadBalancer.ingress[0].ip}{"\n"}'           
INTERNAL INGRESS: 1.2.3.5

Troubleshooting

  1. Delete the deployment and redeploy the Identiq Edge application:
% kubectl delete hr/edge
helmrelease.helm.fluxcd.io "edge" deleted
% kubectl delete pvc data-edge-mariadb-0 edge-elasticsearch-master-edge-elasticsearch-master-0 redis-data-edge-redis-master-0
persistentvolumeclaim "data-edge-mariadb-0" deleted
  1. Make sure Helm Operator can interact with Tweety:
kubectl exec -i -t $(kubectl get pod -l "app=helm-operator" -o name) -- curl  http://edge-tweety/v1/values
image:
  tag: 1.0.7

global: &global
  hosts: &hosts
    - edge-example.identiq.cloud
  tls:
    - secretName
...
  1. Check that all pods are in the “Running” status. 
% kubectl get pods | grep -Ev "Running|NAME"
% # Should return failed pods

Updated about 2 months ago