Installing Hex on a Private Cloud

Prerequisites

Installing Hex in a private cloud requires at a bare minimum:

• Kubernetes 1.16+

• kots - https://kots.io/​

• An S3 bucket and accompanying IAM credentials

• A Postgres 11 database

Optional dependencies

• ALB ingress controller

  • For automatically exposing Hex behind an HTTPS load balancer

• (Highly recommended) Calico or other similar network controller

  • Kubernetes defines the API for specifying Network Security Policies, but by default it has no built-in capability to enforce these.

  • Hex comes out of the box with some network policies to add additional security layers onto kernel security, but these will not work without a network controller

  • Deploying a controller like Calico will make these work

  • ​https://docs.projectcalico.org/security/kubernetes-network-policy​

Terraform Templates

If you are missing any of the above, Hex provides a few getting started templates for AWS that you can mix and match as well as a complete bundled: https://github.com/hex-inc/cloud-templates/tree/master/aws​

An overview of the templates are:

• ​VPC - Provision the VPC, public+private+database subnets, nat gateways and more

• ​EKS - Provision a new EKS cluster with EC2 auto-scaling worker groups of a given number + size

• ​S3 - Create a new encrypted S3 Bucket with corresponding IAM user role to access it stored in AWS SSM

• ​RDS - Create a new encrypted RDS Postgres 11 database and store the credentials in AWS SSM

• ​ALB - Automatically deploy the ALB Ingress Controller into EKS

• ​Calico - Automatically deploy Calico into a kubernetes cluster

• ​Complete Bundle - Combines and automatically deploys all of the above for you

Using the above Terraform templates requires setting up Terraform and AWS to work together. Instructions on how to set them are below:

• Terraform or Terraform Cloud

  • Terraform Cloud is recommended

  • ​https://www.terraform.io/​

  • ​https://learn.hashicorp.com/collections/terraform/aws-get-started​

• Appropriate AWS access keys to provision the resources

  • Hex provides a sample policy that can be used to provision the resources in policy.json

  • ​https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html​

Installation

1. (Optional) Generate and activate the kubeconfig for your kubernetes cluster

   1. aws eks --region us-east-2 update-kubeconfig --name hex-main

   2. Test that it works kubectl get -n kube-system pods

2. Install Hex using Kots​

   kubectl kots install hex

   1. Choose or leave the default namespace of hex

   2. Create a new password and remember it for later

3. Navigate to http://localhost:8800/ and enter the password from the previous step

4. Install license file you received from Hex, this will be a .yaml file

5. Configure the installation

   1. Hex

      1. You can leave replicas at 1, or increase to 2 or 3 to increase redundancy

      2. Choose a name/email/password for the admin account

         1. You can add more Admins in the UI later

      3. (Optional) Choose whether or not you want to use the AWS ALB to expose your app

         1. See Exposing Hex to your Org​

      4. (Optional) Set up custom python kernel images

         1. See Using custom kernel images​

   2. S3

      1. Add the name of the S3 bucket you created for Hex

      2. Add in the IAM access and secret keys that have access to upload/get and delete from the bucket

   3. Postgres

      1. Add in the Postgres connection details of an existing database, or the one you created using the Hex templates

6. Deploy the installation in the "Version History" tab

7. Check that the install worked correctly

   1. Run kubectl get -n hex pods to verify that the pods spun up correctly

8. Initialize and unseal Vault

   1. See Setting up Vault​

9. Set up a port forward to test the install worked

   1. Run kubectl -n hex port-forward [hex-pod-name] 5000

   2. Navigate to https://localhost:5000/ and you should see and be able to log into Hex!

10. Now you are ready to expose Hex to your organization

    1. See Exposing Hex to your Org​