General Requirements

Welcome to the foundation-building phase of your AlphaSense Enterprise Intelligence deployment. To ensure a smooth and efficient installation, this section outlines the essential prerequisites you must fulfill to create a robust and high-performing environment for seamless installation. The preflight check at the beginning of the installation verifies these prerequisites.

Domain Name

Choose a domain name to provide a human-readable and easily accessible address for your AlphaSense Enterprise Intelligence product. It is also required during the installation process.

Network

See overview for a reference network architecture diagram.

Customers have full control of the network infrastructure and configure it to meet compliance. We only require the following:

Virtual Network CIDR

A CIDR block of at least /22 (recommended /16).

SMTP Firewall Rule

The outbound connection should be allowed for the SMTP host and port which were configured in the SMTP credential configuration.

SCIM Firewall Rule

In case you plan to use SCIM to provision users from your existing IAM providers, the inbound connection to the endpoint https://{domain_name}/services/scim/v2 should be allowed. The {domain_name} should be the one defined when setting up the domain name.

Enterprise Gateway Firewall Rule

Enterprise Gateway ensures secure network communication between the Kubernetes cluster and AlphaSense SaaS mothership. It is required for core functionalities such as cross-cluster search, document viewing, and license management, etc.

The outbound connection should be allowed for the domain enterprise-gateway.research.alpha-sense.org with port 443.

Kubernetes Cluster

Note

We recommend maintaining or upgrading the cluster outside the working or peak hours in order to ensure the stability of the product.

Cluster Name

warning

Kubernetes cluster name must not exceed 20 characters.

Cluster Version

We currently support versions v1.30 and v1.31. You may select any of these versions to comply with your organization’s policy.

CNI

Choose a CNI supporting network policies. The Kubernetes project recommends using a plugin that is compatible with the V1.0.0 CNI specification.

Cluster Autoscaling

Make sure Kubernetes autoscaling or the node autoscaler provided by your Kubernetes distribution is installed and working.

Metrics Server

Metrics server needs to be installed for HPA to work correctly.

Persistent Volumes

Make sure to have your cloud of choice persistent volume CSI driver installed and configured. Make sure to set a default storage class, AlphaSense will provision persistent block storage volume (PVC) from the default storage class. You can change the default storageclass encryption settings to meet your compliance.

Starting from Kubernetes 1.30, cluster might not have the default storage class annotation. You can add the needed annotation with this command:

kubectl patch storageclass <storage class name> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Node Groups Configuration

All node groups must be amd64 architecture.

The minimum root volume storage size is 64GB.

Cluster autoscaler can autoscale these node groups.

Public subnets should be limited to bastion or public Internet-facing load balancer only.

VMs (k8s nodes) of the node group should run on private subnets only.

Object Storages

AlphaSense uses Crossplane to create and manage S3 and GCS blob storages.

Pods must have connectivity to the cloud object storage service.

Messaging Layer

AlphaSense uses Crossplane to create and manage AWS (SNS, SQS) and GCP (Pub/Sub) messages resources.

Pods must have connectivity to the cloud messaging services.

MySQL Database Cluster

A relational database cluster is needed to store data and serve the needs of the applications. It should have optimal performance, scalability, and reliability. All k8s pods must have connectivity to the SQL cluster. AlphaSense will create fine-grained databases, grants, and users within the DB cluster with Crossplane automatically.

Select one of the reference architectures and configure the MySQL cluster resources accordingly.

Engine

It requires the MySQL 5.7 engine.

Parameters

Fine-tune database parameters for optimal performance, including timeouts, encryption settings, and table name conventions.

• connect_timeout: 20
• wait_timeout: 1800
• net_read_timeout: 60
• net_write_timeout: 120
• lower_case_table_names: 1
• explicit_defaults_for_timestamp: 1
• innodb_print_all_deadlocks: 1
• require_secure_transport: 0
  • If you use GCP Cloud SQL, this parameter is already disabled by default.

Check the parameters in your MySQL cluster

mysql> SHOW VARIABLES WHERE Variable_name IN ('connect_timeout', 'wait_timeout', 'net_read_timeout', 'net_write_timeout', 'innodb_print_all_deadlocks', 'require_secure_transport', 'lower_case_table_names', 'explicit_defaults_for_timestamp');

Variable_name	Value
connect_timeout	20
explicit_defaults_for_timestamp	ON
innodb_print_all_deadlocks	ON
lower_case_table_names	1
net_read_timeout	60
net_write_timeout	120
require_secure_transport	OFF
wait_timeout	1800

PostgreSQL Database Cluster

A relational database cluster is needed to store data and serve the needs of the applications. It should have optimal performance, scalability, and reliability. All k8s pods must have connectivity to the SQL cluster. AlphaSense will create fine-grained databases, grants, and users within the DB cluster with Crossplane automatically.

Select one of the reference architectures and configure the PostgreSQL cluster resources accordingly.

Engine

It requires the PostgreSQL 16 engine.

Kubernetes Secrets

warning

Make sure you have selected the right Kubernetes cluster to receive your secrets.

Our applications will reference your provided secrets for needed features.

MySQL Secrets

Secrets for a MySQL admin user, password, endpoint, and port need to be set in your mysql Kubernetes namespace to enable the databases to be created/modified on installation and upgrade.

These can be set manually using the example below or can be synced with your secret store.

Example:

export database variables

export DATABASE_CLUSTER_ADMIN_USERNAME=<database cluster admin username>
export DATABASE_CLUSTER_PASSWORD=<database cluster admin password>
export DATABASE_CLUSTER_PORT=<database cluster port>
export DATABASE_CLUSTER_ENDPOINT=<database cluster endpoint>

mysql secret

kubectl create ns mysql
kubectl -n mysql create secret generic default-creds \
    --from-literal=username="${DATABASE_CLUSTER_ADMIN_USERNAME}"\
    --from-literal=password="${DATABASE_CLUSTER_PASSWORD}" \
    --from-literal=port="${DATABASE_CLUSTER_PORT}" \
    --from-literal=endpoint="${DATABASE_CLUSTER_ENDPOINT}"

PostgreSQL Secrets

Secrets for a PostgreSQL admin user, password, endpoint, and port need to be set in your postgres Kubernetes namespace to enable the databases to be created/modified on installation and upgrade.

These can be set manually using the example below or can be synced with your secret store.

Example:

export postgresql database variables

export POSTGRESQL_DATABASE_CLUSTER_ADMIN_USERNAME=<postgresql database cluster admin username>
export POSTGRESQL_DATABASE_CLUSTER_PASSWORD=<postgresql database cluster admin password>
export POSTGRESQL_DATABASE_CLUSTER_PORT=<postgresql database cluster port>
export POSTGRESQL_DATABASE_CLUSTER_ENDPOINT=<postgresql database cluster endpoint>

postgresql secret

kubectl create ns postgres
kubectl -n postgres create secret generic spicedb-creds \
        --from-literal=username="${POSTGRESQL_DATABASE_CLUSTER_ADMIN_USERNAME}" \
        --from-literal=password="${POSTGRESQL_DATABASE_CLUSTER_PASSWORD}" \
        --from-literal=port="${POSTGRESQL_DATABASE_CLUSTER_PORT}" \
        --from-literal=endpoint="${POSTGRESQL_DATABASE_CLUSTER_ENDPOINT}"

TLS Secrets

We use NGINX ingress for HTTPS communication. A Kubernetes secret with the full certificate chain and private key is required.

tls secret

kubectl create ns alphasense
kubectl -n alphasense create secret tls default-tls \
    --cert=<path/to/full-chain-certificate/file> \
    --key=<path/to/private-key/file>

To obtain the certificate, you can use your own certificate authority, your certificate supplier, or Let's Encrypt.

If the fully qualified domain name for the product is private-cloud.alpha-sense.com, then the certificate should be issued with:

Subject Alternative Name

X509v3 Subject Alternative Name:
    DNS:*.private-cloud.alpha-sense.com, DNS:private-cloud.alpha-sense.com

SMTP Credentials for Email Sending

We require SMTP credentials for sending emails (reset password, alerts, etc.). We need the SMTP username, password, host, port, and sender email address information:

smtp secret

kubectl create ns alphasense
kubectl -n alphasense create secret generic sender-smtp \
    --from-literal=username=<username> \
    --from-literal=password=<password> \
    --from-literal=address=<sender email address> \
    --from-literal=host=<smtp host> \
    --from-literal=port=<smtp port>

By default, it is expected that a secure SMTP server will be used. If you prefer to use a non-secure SMTP server, you must create the secret as follows:

non secure smtp secret

kubectl create ns alphasense
kubectl -n alphasense create secret generic sender-smtp \
    --from-literal=username=<username> \
    --from-literal=password=<password> \
    --from-literal=address=<sender email address> \
    --from-literal=host=<smtp host> \
    --from-literal=port=<smtp port> \
    --from-literal=secure="false" \
    --from-literal=requireTLS="false"

SSO Secret

Due to technical limitations, we require an unique saml entity id for SSO, even when SSO

is not configured. This secret is required even for username and password login method at the moment.

sso-config secret for sso-ws

kubectl create ns platform
kubectl -n platform create secret generic sso-config \
        --from-literal=saml-entityid="<unique id, e.g your cluster fqdn>"

See SSO configuration for more details.

Per-Cloud Provider Requirements

Make sure to check the technical requirements for your specific cloud provider, as the general requirements do not cover all the details for each cloud provider.

• AWS Technical Requirements
• GCP Technical Requirements