Prerequisites

Overview

This guide discusses the prerequisites that must be met before the Kinetic Platform can be installed.

Application Servers

The Kinetic Platform is typically deployed to one or more servers which we refer to as a "cluster" throughout this documentation.Depending on the environment configuration chosen, either 1 or 3+ servers need to be provisioned with the following minimum requirements:

Supported Operating Systems

Hardware Requirements

• 32GB RAM
• 8 Cores
• 250GB ext4 Storage, application (NAS, SAN or attached) mounted to /var/lib/gravity
• 250GB ext4 Storage, etcd (attached, dedicated SSD) mounted to /var/lib/gravity/planet/etcd

If you're running in the cloud we recommend using AWS t3.2xlarge or equivalent instances and for the etcd disk, io1 class EBS volumes with at least 1500 provisioned IOPS.

Etcd Disk Performance Requirements

Prior to installation, a check will be performed to assess performance characteristics of the disk used for etcd data on each master node.

The check uses fio tool and looks at the following benchmarks:

• Sequential write IOPS:
  • If the detected IOPS is below 50, a warning is triggered.
  • If the detected IOPS is below 10, a failure is triggered
• Fsync latency:
  • If the detected latency is higher than 50ms, a warning is triggered.
  • If the detected latency is higher than 150ms, a failure is triggered.

Networking Requirements

Installation Only Ports

The following ports are required during initial installation:
| Port | Protocol | Description |
| ------------------------- | --------- | ------------------------- |
| 61008-61010, 61022-61024 | HTTPS | Installer agent ports |
| 4242 | TCP | Bandwidth checker utility |

These ports can be closed after the install has been completed.

Required Port Configuration

The following ports are required for normal cluster operation:

SOURCE/DESTINATION LEGEND

• all - Any node which is a member of the cluster
• ext - Any source outside the cluster
• lb - The Kinetic Platform Load Balancer
• localhost - The port is only used within the host where the request started
• controllers - Nodes which are designated "controller" role (these are commonly referred to as master nodes and by default will be the first 3 nodes added to your cluster)

Networking

Load Balancer

A layer seven load balancer, commonly referred to as an application load balancer, is required for running the Kinetic Platform.

Sticky Sessions / Persistence

The Kinetic Platform leverages sticky sessions to route users to the same server. When configuring the load balancer, sticky sessions need to be enabled with INGRESSCOOKIE as the session cookie name. If the sticky sessions are not configured, users will get prompted for their credentials as requests are transferred between application servers.

Target Configuration

End users connect to the Kinetic Platform from a web browser. In order to secure this connection, the load balancer is responsible for accepting HTTPS requests and routing them to the Kinetic Platform cluster nodes.

The load balancer can be configured to terminate HTTPS and internally route to an unencrypted HTTP port, or it can be configured as a reverse proxy when end-to-end encryption is desired. When being used as a reverse proxy, the load balancer should be configured to decrypt the traffic, apply any applicable layer 7 actions (such as introspecting the INGRESSCOOKIE), and then re-encrypt the traffic before routing it to the encrypted HTTPS port.

Because the Kinetic Platform requires persistent sessions, it is not possible to support SSL/HTTPS passthrough configurations

The load balancer target pool should contain the IP addresses of all the nodes in the cluster. Each node in the cluster contains an ingress listening on ports 30080 for HTTP traffic, 30443 for HTTPS traffic, and 10248 for HTTP health checks. The load balancers target HTTP health check should point to HTTP:10248/healthz.

When using cloud providers such as AWS, this could either be configured using a pool of Elastic IPs or by configuring a load balancer to point to a target group

End to End SSL Target Configuration
| Load Balancer Port | Instance Port | Instance Protocol | Internal Usage |
|--------------------|---------------|-------------------|------------------------------------------|
| 80 | 30080 | HTTP | Redirect to 443 when using SSL |
| 443 | 30443 | HTTPS | HTTPS ingress node port for the cluster. |

SSL Termination Target Configuration
| Load Balancer Port | Instance Port | Instance Protocol | Internal Usage |
|--------------------|---------------|-------------------|-----------------------------------------|
| 80 | 30080 | HTTP | Redirect to 443 when using SSL |
| 443 | 30080 | HTTP | HTTP ingress node port for the cluster. |

Header Manipulation

In order to preserve the source IP address of the request for use in security policies and for log file accuracy, the load balancer must be configured to set the following headers:

• X-Forwarded-For
• X-Forwarded-Host
• X-Forwarded-Proto

Most layer 7 load balancers (including AWS ALBs) set these headers by default

DNS Configuration

The Kinetic Platform provides the ability to support multiple tenants (we call tenants "Spaces"). The configuration and management of the system is exposed as the root domain and the environment for each tenant is exposed as a subdomain based upon their tenant identifier (we call tenant identifiers "slugs"). For example, if the Kinetic Platform is exposed via kinetic.mydomain.com then tenants would be exposed via tenant1.kinetic.mydomain.com, tenant2.kinetic.mydomain.com, etc.

Configure the following within your domain registration system:

• A record MYDOMAIN.COM mapped to the IP address of the load balancer
• A record *.MYDOMAIN.COM mapped to the IP address of the load balancer

When using cloud providers such as AWS, we recommend using the DNS registration option supplied by the provider (ie Route 53 for AWS).

The following information will be required during the Kinetic Platform Install related to this prerequisite:

1. Domain Name (ie, kinetic.mydomain.com)

Wildcard TLS Certificate

A wildcard certificate and full certificate chain (root CA and all intermediary certificates) is required to install the Kinetic Platform. Instructions for obtaining a wildcard certificate vary based on signing authority.

IMPORTANT: The wildcard certificate domain name must match the domain name you provide for DNS.

SMTP Server

In order to send email alerts and notifications, the Kinetic Platform should be configured with a SMTP server.

Storage

NFS Device Path

An NFS device is needed for shared filesystem access to facilitate the following platform functions:

• File attachments submitted via Forms and Discussions
• Component Service Discovery
• Web Session Persistance & Replication

When creating or requesting an NFS path, ensure the following:

• All application servers (ie host nodes) have network access to the NFS server(s).
• UUID 55101 has access to creating files within the path.
• Log files (if Elasticsearch is not used)
• 100GB Capacity*

*Space requirements vary based on usage patterns. Implementations that expect many file attachments (via Form submissions or Discussion messages) should provide more space.

Apache Cassandra (3.0+)

The Kinetic Platform uses Apache Cassandra as the primary data storage system. Cassandra is a highly available distributed database with linear scalability and fault tolerance on commodity hardware or cloud infrastructure. Cassandra relies on the concept of "quorum" to provide consistency and subsequently requires at least three database nodes for use with the Kinetic Platform.

Note: For initial development work, a one-node cluster will work. For example, you can set up a one
node cluster on a desktop using products such as Oracle VirtualBox or Docker Desktop.

See the Getting Started page in the Cassandra Documentation for installation and configuration instructions.

Recommended Hardware Requirements (x3)

• 16 GB RAM
• 8 Cores
• 250GB Storage (unshared attached storage required, SSD preferred)

Post-Install Configuration

• Ensure traffic from the application server hosts can access access each Cassandra host on its configured client port (9042 by default).
• Increase the batch_size_fail_threshold_in_kb (cassandra.yaml) value from 50 to 500. This must be applies to each Cassandra servers individually and requires a restart to be applied.
• Ensure each Cassandra node's time is in sync with the Kinetic Request CE web server environment. Clock drift between the Cassandra cluster and the Kinetic Request CE web servers can cause issues when performing batch operations (including kapp or form slug renames). Kinetic recommends using the NTP service to keep the servers in sync.

IMPORTANT: There are a small number of Kinetic Platform operations that will ever exceed the default batch_size_fail_threshold_in_kb, but they are very important. Ensure that all Cassandra servers have had this value updated and the Cassandra process restarted before beginning the Kinetic Platform installation.

The Kinetic Platform does not support using AWS Keyspaces for Cassandra storage

Elasticsearch (7.1+)

Elasticsearch is required to enable console access to aggregated log content, which allows administrators to conveniently search log content (common during production troubleshooting and development). If Elasticsearch is not configured as part of the Kinetic Platform installation, log content will be written to independent log files within the attached NFS path and not available from the Kinetic consoles.

Recommended Hardware Requirements (x2)

• 16 GB RAM
• 8 Cores
• 500GB Storage (unshared attached storage required)

Post-Install Considerations

• Ensure traffic from the application server hosts can access access each Elasticsearch host on its configured client port (9200 by default).
• Ensure an acceptable rotation strategy is in place based on your companies compliance policies for log file retention. During installation you will be asked to provide a base Elasticsearch index prefix (kinetic-platform-logs by default). Log content will be written to Elasticsearch indexes using the provided prefix and the suffix -YYYY-MM-DD (ie kinetic-platform-logs-2020.01.01).

SQL Database Server

The Kinetic Platform requires a SQL database for the Workflow (Task) component and supports MS SQL 2012+, Oracle 11+ and Postgres 9.5+. Each tenant (space) within the Kinetic Platform will need its own database/schema. When using Postgres, this database can (optionally) be automatically created, however if using MS SQL or Oracle the database needs to be created by a DBA before the new tenant is provisioned.

When adding a new tenant, the necessary database tables and data will be automatically created. Additionally, when the Kinetic Platform is upgraded, the Workflow component may also create or update the schema. Therefore, the database user used to configure the tenant must have permissions to create/modify the schema.

Recommended Hardware Requirements (x1)

• 8 Cores
• 16 GB RAM
• 400GB Storage

Post-Install Considerations

• Ensure an acceptable backup strategy a is implemented.
• Ensure appropriate database maintenance tasks are schedule.

---

Installation Checklist

The following information will be required during the Kinetic Platform installation process.

DNS

1. Domain Name (ie, kinetic.mydomain.com)

Ingress Certificates

1. Ingress TLS Certificate (PEM Format -- full certificated chain)
2. Ingress TLS Key (PEM Format)

NFS

1. NFS Server Hostname / IP
2. NFS Path

Cassandra

1. Datacenter Name (this can be obtained by running nodetool status)
2. Hosts (a comma separated list of cassandra hosts, ex; 10.10.10.5:9042)
3. Username/Password (if required by cluster)
4. Root Certificate in PEM format (if required by cluster)

Elastic Search

1. Endpoint
2. Username/Password (if required by cluster)
3. Index Base Pattern (we recommend kinetic-platform-logs)

Configuration Checklist

The following information will be required during post-install configuration.

SMTP

The following information will be required during the Kinetic Platform post-installation configuration:

1. Host
2. Port
3. Username and Password (if applicable)
4. TLS Enabled?
5. From Address and Name

SQL Database

The following information will be required after the Kinetic Platform is installed to provision a space (some databases, namely Oracle require some additional connection information):

1. Host (ie: 10.10.10.13)
2. Port (ie: 5432)
3. Database/Service Name
4. Username/Password (if required)
5. SSL Certificates in PEM format (Root and Client if required)

This same information can be used to set the default template to be used when creating a new space. If you are using PostgreSQL, it can also be used to define the user that is used to automatically create new tenant database schemas.