Managing clusters

Search…
Managing clusters
Simulate simulations are deployed to infrastructure that is provisioned with the Hadean Platform. Simulate currently supports deployment to Microsoft Azure and Amazon Web Services, provisioning can be done via the Aether CLI or via the Hadean portal.
The setup guide below shows you how to setup a cluster with default options. Be sure to read through this whole article before continuing, in particular the customising infrastructure with Terraform section, you may want to specify Terraform options or Tags for your cluster before starting the process.
Create a new cluster in the cloud
Microsoft Azure
Amazon Web Services
Prerequisites
You will need the following to create a remote deployment target:
Access to Azure Cloud Shell (bash)
An Azure AD account linked to an Azure Subscription that can create Azure resources. Azure account terminology​
An Azure subscription that provides enough quota to run the cluster you require
Step 1: Download a copy of the Hadean Provisioning Bundle
1.To get started go to the Hadean portal and within your company, click Create project.
2.Making sure you have selected Microsoft Azure as the cloud provider, click Download Cluster Provision Bundle.
You will return to this web page later in the setup so it is useful to keep it open
The zip file that is downloaded contains a Terraform script that will prepare your cluster for installation of the Hadean Platform.
Step 2: Upload the Provisioning Bundle to Azure
Open an Azure Cloud Shell and select the bash environment, as specified in Microsoft Azure Cloud Shell overview.
1.Upload the zip file in the Azure Cloud Shell by clicking on the Upload/Download Files icon and selecting Upload
2.Unzip the file into a new directory and navigate to that directory, replacing example-environment with your chosen project name:
unzip -d example-environment hadean-azure-terraform-scripts.zip
cd example-environment
​
Step 3: Run the Terraform script to create the cluster
The following instructions provide the necessary steps to create a Simulate cluster within Azure, using the default options. For further customisations please read the customising infrastructure with Terraform section below.
Before beginning it is best to ensure that you are logged in correctly to your Azure shell. To do this run the following command in the shell and follow the on screen instructions.
az login
Execute the following sequence of commands to create a cluster with the default options:
1.Initialise Environment
make init
make init will configure terraform, and ensure that you are using the correct version and have a valid set of terraform scripts.
2. Plan your Infrastructure
ENVIRONMENT_NAME=example-environment make plan
make plan will run your terraform scripts to decide which infrastructure needs provisioning, the data centres it will use, and the names to give the infrastructure. This stage just creates a plan, no changes will be applied.
Set ENVIRONMENT_NAME to something useful and recognisable for future reference. The name provided can only contain lowercase alphanumeric symbols or hyphens
3. Apply the changes in the cloud:
make apply
At this point the cloud infrastructure will be created, and a 'cluster bundle' zip file will be generated inside a new directory named out-bundle, this file contains the details and connection information for the Hadean provisioning service to install the Hadean Platform to the newly created cluster. Download the file by clicking Upload/Download files. Save it somewhere accessible, you'll upload it to the Hadean Portal in the next step.
When you want to destroy the environment you have just created follow the instructions given further down Delete A Cluster​
Prerequisites
You will need the following to create a remote deployment target:
Access to AWS CloudShell (bash)
An AWS account that has enough quota to run the cluster you require
Step 1: Download a copy of the Hadean Provisioning Bundle
1.To get started go to the Hadean portal and within your company, click Create project.
2.Making sure you have selected Amazon Web Services as the cloud provider, click Download Cluster Provision Bundle.
You will return to this web page later in the setup so it is useful to keep it open
The zip file that is downloaded contains a Terraform script that will prepare your cluster for installation of the Hadean Platform.
Step 2: Upload the Provisioning Bundle to AWS & Install Terraform
1.Open an AWS CloudShell. You may have to select a different region if your default region is unsupported currently. Make sure you're in a bash environment, as specified in AWS Cloud Shell overview.
2.Upload the zip file in the AWS CloudShell by pressing Actions > Upload file
3.Unzip the file into a new directory and navigate to that directory, replacing example-environment with your chosen project name:
unzip -d example-environment hadean-aws-terraform-scripts.zip
cd example-environment
​
4. Download Terraform
The AWS CloudShell doesn't automatically include Terraform which is required to provision an Simulate cluster. To download Terraform run:
$ wget https://releases.hashicorp.com/terraform/1.0.4/terraform_1.0.4_linux_amd64.zip
$ unzip terraform_1.0.4_linux_amd64.zip
$ export PATH="$PWD:$PATH"
​
Step 3: Run the Terraform script to create the cluster
The following instructions provide the necessary steps to create an Simulate cluster within AWS, using the default options. For further customisations please read the customising infrastructure with Terraform section below.
Execute the following sequence of commands to create a cluster with the default options:
1.Initialise Environment
make init
make init will configure terraform, and ensure that you are using the correct version and have a valid set of terraform scripts.
2. Plan your Infrastructure
ENVIRONMENT_NAME=example-environment make plan
make plan will run your terraform scripts to decide which infrastructure needs provisioning, the data centres it will use, and the names to give the infrastructure. This stage just creates a plan, no changes will be applied
Set ENVIRONMENT_NAME to something useful and recognisable for future reference. The name provided can only contain lowercase alphanumeric symbols or hyphens
3. Apply the changes in the cloud:
make apply
After this the infrastructure will get created, and a 'cluster bundle' file will be generated inside a new directory named out-bundle, this file contains the details and connection information for the Hadean provisioning service to install the Hadean Platform to the newly created cluster. Download the file by clicking Actions > Download file. Provide the path to the cluster bundle inside out-bundle for example: $HOME/hadean-aws-terraform-scripts/out-bundle/hadean-cluster-bundle.zip, click Download and this will be downloaded to your machine. Save it somewhere accessible, you'll upload it to the Hadean Portal in the next step.
Step 4: Provision your cluster with the Hadean Platform
Return to the new project form on the Hadean portal from step 1.
Complete the form by providing:
Project name: A short recognisable name for you to identify the project in your list
Hadean Simulate version: The version of Simulate that you want to have installed on the cluster, this should match the version used to develop your simulation
Project bundle: Upload the cluster bundle that was downloaded from the cloud resource
Clicking Create will start the provisioning process. After a few seconds you will be be redirected to the projects page where you will be able to see the status of your new project. This will initially be flagged as PROVISIONING
The provisioning will take some time. You will be alerted by email when the cluster is ready or if there are problems with provisioning. You can refresh the page to check the status. When ready, get started using your new cluster by running your simulation on it.
Delete a cluster
When you are done with your cluster you can delete it and all the corresponding resources on the cloud by returning to the azure cloud shell, navigating to the directory from which you built your cluster and executing:
make destroy
This command will destroy the environment created from the plan in the current working directory. This looks at config such as environment name to know which remote infrastructure to clean up so be sure to check that you are about to destroy the cluster you intend to. It is good practise to create separate directories for each of your clusters. If you have deleted the directory you used to make the plan you can simply re-run the make plan step providing the same environment name and configuration as you used before and this will generate the files you need to destroy the cluster.
When a cluster is temporarily not needed you can suspend it to reduce costs rather than destroying it, When using azure from the shell the following two commands will respectively stop and start resources in your resource group.
Note that the resource name will be your environment name with a hdn-env- prefix
az vm stop --ids $(az vm list -g hdn-env-example-environment --query "[].id" -o tsv)
az vm start --ids $(az vm list -g hdn-env-example-environment --query "[].id" -o tsv)
Customising infrastructure with Terraform
Reducing client latency with Connect nodes in multiple regions
When connecting clients to Connect, the connection will be via the public internet. As a result, the quality and latency of the connection can be very variable. The latency of the connection is correlated with the distance the client is from the node, and so to help reduce the effect of this you can deploy Connect nodes into multiple edge data centers around the world, allowing each client to connect to the one that is closest to them. The nodes can take advantage of the high-quality inter-data center networking provided by the cloud providers to provide a better experience than a client connecting over the public internet could achieve.
Configuration for Connect locations is specified in terraform.edgeconfig.auto.tfvars.json. This file dictates where Connect nodes should be deployed, how many, and what machine size they should have. The information required by each cloud provider differs slightly so please refer to the correct tab for the cloud provider you are using. By default the Terraform scripts are configured to create a node in the default simulation location.
Microsoft Azure
Amazon Web Services
Example Edge Config
The edge config is specified as a list of objects which map a location to a list of machine instance sizes. In the following config the result will be one Connect node in uksouth, two in eastus and one in ukwest. They all share the same machine size of Standard_D8s_v3.
{
    "edge_network": [
        { 
            "location": "uksouth", 
            "instances": [
                { "size": "Standard_D8s_v3" }
            ] 
        },
        { 
            "location": "eastus", 
            "instances": [
                { "size": "Standard_D8s_v3" },
                { "size": "Standard_D8s_v3" }
            ] 
        },
        { 
            "location": "ukwest", 
            "instances": [
                { "size": "Standard_D8s_v3" }
            ] 
        }
    ]
}
Helpful Azure CLI commands
From a shell that has the Azure CLI installed:
az account list-locations -o table for a list of available locations.
az vm list-sizes -o table --location uksouth for a list of available machine sizes in a given location. Note: replace uksouth with the location you need machine size information from.
The edge config is specified as a list of objects which map a region to a list of machine instance sizes and availability zones. In the following config the result will be a Muxer in eu-west-2a, two Muxers in us-east-2a, one in eu-west-1a and one in eu-west-1b. They all share the same machine size of m5.2xlarge.
{
    "edge_network": [ 
        { 
            "region": "eu-west-2", 
            "instances": [
                { "size": "m5.2xlarge", "zone": "eu-west-2a" }
            ] 
        },
        { 
            "region": "us-east-2", 
            "instances": [
                { "size": "m5.2xlarge", "zone": "us-east-2a" },
                { "size": "m5.2xlarge", "zone": "us-east-2a" }
            ] 
        },
        { 
            "region": "eu-west-1", 
            "instances": [
                { "size": "m5.2xlarge", "zone": "eu-west-1a" },
                { "size": "m5.2xlarge", "zone": "eu-west-1b" },
            ] 
        }
    ]
}
Helpful AWS CLI commands
From a shell that has the AWS CLI installed:
aws ec2 describe-regions --query "Regions[].{Name:RegionName}" --output text for a list of available regions.
aws ec2 describe-instance-types --query 'InstanceTypes[].InstanceType | sort(@)' --output text --region eu-west-2 for a list of available machine sizes in a given region. Note: replace eu-west-2 with the region you need machine size information from.
aws ec2 describe-availability-zones --query 'AvailabilityZones[*].[ZoneName]' --output text --region eu-west-2 for a list of availablity zones in a given region. Note: replace eu-west-2 with the region you need availability zone information from.
Specifying a Terraform Back-End
Please use the provided template as reference on how to configure a backend for Microsoft Azure.
For more information on Terraform backends: Terraform backend overview.
Terraform template example:
terraform {  
    backend "azurerm" {    
        container_name       = "blobcontainername"    
        storage_account_name = "storageaccountname"    
        resource_group_name  = "resource-group-name"    
        key                  = "hdne-envs/state"  
    }
}
Specifying Tags
Please use the provided template file tags.tfvars and fill out accordingly.
############################################################
# Example of tags. The limit in Azure is 15 tags.
#  We use 2 mandatory tags, therefore only 13 are left
#  Characters that are not supported by Azure: < > % & / ?
#  Tag value limit: 256 characters
############################################################
​
tags = {  
    purpose          = "",  
    environment      = "",  
    application_id   = "",  
    working_schedule = "",  
    protection       = "",  
    department       = "",  
    dev_unit         = "",  
    product          = "",  
    customer         = "hadean",  
    project          = "",  
    env_name         = "",  
    initiator        = "",  
    lifetime         = ""
}
Specifying the Simulation Location
Make sure you specify the desired location of your components via the terraform.tfvars file. It's recommended that your components are in a close proximity with regards to locale. This will enable components to take advantage of higher bandwidth and lower latency connections.
Specifying Extra Terraform Arguments
Simply set the environment variable EXTRA_TF_ARGS. For example:
EXTRA_TF_ARGS="-no-color" ENVIRONMENT_NAME=my-env make plan
​