Customer-Managed Installation Prerequisites

Overview

This guide outlines the prerequisites that must be in place before you begin installing the Kinetic Platform. Review this guide in its entirety before you begin the installation.

Application Server

The Kinetic Platform is typically deployed to one or more servers, also called "clusters". Depending on the environment configuration you choose, you will need to provision either 1 or 3+ servers with the minimum requirements outlined below.

Operating System

The following operating systems are currently supported by their creators and are used by our installation framework for installing the Platform:

The operating systems below are no longer supported by their creators; however, they are currently supported by our installation framework and can be used to install the Platform.

Hardware Requirements

• 32GB RAM
• 8 Cores
• Storage volumes provisioned and mounted to the following locations:
  • Point : /var/lib/rook (20GB minimum)
  • Point : /var/lib/kubelet (50GB minimum)
  • Point : /var/openebs (100GB minimum)
  • Point : /var/lib/containerd (50GB minimum)
  • Point : /var/lib/etcd (100GB minimum)
  • Point : /var/lib/kurl (30GB minimum)
  • Point : /var/tmp (50GB minimum)

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

Networking Requirements

Ports: Ensure the following ports are open:

Browser: The server must run one of the following browsers:

• Chrome (Version 66+)
• Firefox (Version 58+)
• Opera (Version 53+)
• Edge (Version 80+)
• Safari (Mac OS only, Version 13+)

IP forwarding configuration Ensure the following IP forwarding settings are configured:

• net.ipv4.ip_forward = 1
• net.ipv4.conf.all.forwarding=1

Networking

Load Balancer

A layer seven load balancer, also 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 a session cookie name of INGRESSCOOKIE. If the sticky sessions are not configured, users will be prompted to enter 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.

Note: 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 balancer's target HTTP health check should point to HTTP\:10248/healthz.

Note: 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

SSL Termination Target Configuration

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

Note: 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 (which we call "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 (what we call "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, and so on.

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

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

A domain name (for example, kinetic.mydomain.com) will be required during the Kinetic Platform install as part of this prerequisite.

Installer TLS Certificate

At the end of the command line installation process, the installer provides a link to the Kinetic Configuration page along with a password. When you access this link, you will be brought to the "Bypass browser TLS warning" page, which indicates that your browser may warn you that the certificate used for the page is self-signed. You can either continue using the self-signed certificate or follow the instructions provided to continue to the Admin Console and upload a custom certificate. You can add a custom certificate through the Admin Console at a later date if desired.

Wildcard TLS Certificate

A wildcard certificate and full certificate chain (root CA and all intermediary certificates) are required to install the Kinetic Platform. Instructions for obtaining a wildcard certificate vary based on the 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 an SMTP server.

Storage

NFS Device Path

An NFS device is needed for shared file system access to facilitate the following Platform functions:

• File attachments submitted via forms
• Web Session persistence and replication
• Trusted Platform certificate storage

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

• 100GB of free space

  Note: Space requirements vary based on usage patterns. Implementations that expect lots of file attachments (via Form submissions) should provision more space.

• All application servers (host nodes) have network access to the NFS server(s).
• All application servers have the packages required for mounting NFS drives installed (for example, nfs-common for Debian).
• UUID 55101 has access to create files within the path.
• Log files are enabled (if Elasticsearch is not used)

Apache Cassandra (4.1+)

The Kinetic Platform uses 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.

Post-Install Configurations

• Ensure that Cassandra is configured for SSL.
• Ensure traffic from the application server hosts can 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 applied to each Cassandra server individually and requires a restart to be applied.
• Ensure each Cassandra node's time syncs 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 (Version 7.1 or higher)

Elasticsearch enables Platform console access to aggregated log content, which allows administrators to search log content conveniently (common during production troubleshooting and development). While not required, 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 inaccessible from the Kinetic consoles.

For information on installing and implementing Elasticsearch, see Elastic's Elasticsearch Guide.

Recommended Hardware Requirements (x2)

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

Configuration Considerations

• We recommend configuring SSL for Elasticsearch to establish a secure connection between the Kinetic application and Elasticsearch.

Post-Install Considerations

• Ensure traffic from the application server hosts can access each Elasticsearch host on its configured client port (9200 by default).
• Ensure you have established an acceptable rotation strategy based on your company's 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 (for example, kinetic-platform-logs-2020.01.01).
• Ensure an acceptable backup strategy is implemented.
• Ensure appropriate database maintenance tasks are scheduled.

SQL Database Server

The Kinetic Platform requires an SQL database for the Task workflow component. The following databases are supported:

• MS SQL 2012, 2016, and 2019
• Oracle 11 and later
• Postgres 9.5 and later

Important: 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 you're 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 permission to create/modify the schema.

Recommended Hardware Requirements (x1)

• 8 Cores
• 16 GB RAM
• 400GB Storage

Backup and Database Maintenance

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

---

Installation Checklist

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

DNS

• Domain Name (for example, kinetic.mydomain.com)

Ingress Certificates

• Ingress TLS Certificate (PEM Format; full certificated chain)
• Ingress TLS Key (PEM Format)

NFS

• NFS Server Hostname / IP
• NFS Path

Cassandra

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

Elasticsearch

• Endpoint
• Username/Password (if required by cluster)
• 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:

• Host
• Port
• Username and Password (if applicable)
• TLS Enabled?
• 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):

• Host (for example, 10.10.10.13)
• Port (for example, 5432)
• Database/Service Name
• Username/Password (if required)
• SSL Certificates in PEM format (Root and Client if required)

Note: 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.