This guide is supplementary to the reference documentation of Composable Architecture Platform, specifically to help AWS customers with installation, setup, and production considerations when deploying the software to Amazon Web Services (AWS) with a subscription to any of the available TomorrowX platforms on AWS Marketplace aws.amazon.com/marketplace.
An active AWS Marketplace subscription to a TomorrowX Platform license, in this guide we will refer to the Delivery Innovation Platform (PREMIUM) subscription.
To check if your organisation has an active subscription, go to AWS Marketplace > Manage subscriptions in the AWS Console. If not, proceed to subscribe to an Amazon Machine Image (AMI) licensed distribution for AWS via the AWS Marketplace.
Specific AWS account IAM user permissions will be required to interact with AWS services and the software installation, examples of IAM policies are detailed later in this guide.
At the time of writing, this guide has used the installation with the official CentOS 7 (x86_64) - with Updates HVM by Amazon Web Services AMI. Basic Linux commands are required to connect to your instance and perform operational tasks such as server updates, restarts, and SSH key rotation.
Knowledge of the following AWS services:
Amazon Elastic Compute Cloud (Amazon EC2) - required
AWS Marketplace – required
AWS Identity and Access Management (IAM) - required
AWS Service Quotas - optional
Amazon Simple Email Service (Amazon SES) - optional
Delivery Innovation Platform architecture diagram (Marketplace default)
The installation is shipped as single instance combining the console and server components. This ensures all available architectural deployment options can be considered as and when solutions are created and released through the development lifecycle into production. The instance may need to connect to various on-premise, hybrid, or external integration points (e.g., databases, CSV data files for processing, or 3rd party API services). Refer to the section Architectural Scenarios for more details for architecting these scenarios.
In this guide we are referencing the initial installation components as made available from the launch from AWS marketplace. From there, you will quickly adapt the architectural scenario for scale and most appropriate business use case.
For a better security posture, we provide a sample high availability example for high availability deployed within private subnet behind a load balancer for failover and administration access whereby the Console instance is physically separated to Runtime (n) number of servers to be auto-scaled relative to anticipated traffic load, and availability requirements.
For any advanced, or new scenarios not listed here, contact us directly for guidance as detailed on the AWS Marketplace listing https://aws.amazon.com/marketplace/pp/prodview-hmasfes2o4jna#pdp-support
The launch of the TomorrowX Platform from the AWS Marketplace involves a single component. A running Amazon Machine Image (AMI) running in EC2 as detailed in the architecture diagram for running in AWS Marketplace. Both console and server components of the installation are accessed via public internet (http/https), and the console connects to the server via a specific administration management port directly on the host server as detailed in the architecture diagram.
Default configuration example for AWS Marketplace Launch from Website
Please refer to the product reference section - Essential things to do first in order to manage the default accounts and change passwords.
First time users can launch the console at http://{Instance IP/DNS}/console
e.g. http://12.34.56.78/console
If you are new to AWS Identity and Access Management, then reference getting started reference documentation here: https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started.html .
To support multiple users in your AWS account, you must delegate permission to allow other people to perform only the actions you want to allow. To do this, create an IAM user group with the permissions those people need and then add IAM users to the necessary user groups as you create them. You can use this process to set up the user groups, users, and permissions for your entire AWS account.
An IAM user with the following policies attached have been selected to launch the platform from AWS Marketplace in this guide. Please adjust IAM policies appropriately for your AWS account. Select either Launch from Website, or Launch through EC2 option.
Where AWS Managed Policies provide the IAM User with access across EC2 and Marketplace services, you will need to restrict services where appropriate if your organisation enforces finer grained security policies to services or regions.
Refer to documentation about AWS Managed policies here https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html
To set up a user group, you need to create the group. Then give the group permissions based on the type of work that you expect the users in the group to do. Finally, add users to the group.
Once the user group has been created or during creation, you may attach the following policies.
AmazonEC2ReadOnlyAccess
Policy ARN arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess
Provides read only access to Amazon EC2 via the AWS Management Console.
SupportUser
Policy ARN arn:aws:iam::aws:policy/job-function/SupportUser
This policy grants permissions to troubleshoot and resolve issues in an AWS account. This policy also enables the user to contact AWS support to create and manage cases.
https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html#jf_support-user
EC2InstanceConnect
Policy ARN arn:aws:iam::aws:policy/EC2InstanceConnect Allows customers to call EC2 Instance Connect to publish ephemeral keys to their EC2 instances and connect via ssh or the EC2 Instance Connect CLI.
An IAM Policy must be set for users working with instance metadata to require the use of IMDSv2 as detailed here. The policy specifies that you can’t call the RunInstances API unless the instance is also opted in to require the use of IMDSv2
AmazonEC2FullAccess
AWSMarketplaceFullAccess
ComputeOptimizerReadOnlyAccess
To access AWS Marketplace software licences granted with your organisation, you can create and set the following policy.
LicenseManager-List-Read
The recommended method is for the user within the IAM User Group to assume the required role using STS. AWS provides AWS Security Token Service (AWS STS) as a web service that enables you to request temporary, limited-privilege credentials for AWS Identity and Access Management (IAM) users or for users you authenticate (federated users). Reference documentation about the AssumeRole action which returns a set of temporary security credentials that you can use to access AWS resources that you might not normally have access to. These temporary credentials consist of an access key ID, a secret access key, and a security token. Typically, you use AssumeRole within your account or for cross-account access.
https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html
Where you are using AWS IAM or other federated identity management across the account, you may create specific roles in order to utilise the AssumeRole action when using the recommended method of AWS STS. You can use the roles as detailed below to implement segregation of user roles to perform specific operation tasks such as support user role, advanced user role, marketplace licenses role, and so on.
An IAM role is an identity you can create that has specific permissions with credentials that are valid for short durations. Roles can be assumed by entities that you trust.
Create the following roles basic and advanced support along with read only access to view AWS Marketplace software licences across the organisation.
Here are the steps for an IAM user or IAM users in a group to assume a segregated role within your account or there is a full tutorial for further explanation here.
https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html
Create a role (the role to be assumed) and related policy with privileges. Copy ARN of the role.
Example: Create the following User Role called SupportUser and attach the appropriate policies.
Role name: SupportUser
Attached Policies: SupportUser
AmazonEC2ReadOnlyAccess
EC2InstanceConnect
Grant access to the role by creating a new policy to assume a role and assigning to the user or group.
This can be an in-line policy or an attached policy to the user or group. Example to assume SupportUser role, ARN will also require your account ID.
Add an IAM user to the user group.
Switch role
Login as the IAM user to AWS console and switch roles using the top right menu item.
Select Switch role
Finally, login as the IAM user using your Account ID, role name that you wish to assume, and select a display name. In this example Role is SupportUser, and Account is account ID.
When third parties require access to your organization's AWS resources, you can use roles to delegate access to them. For example, a third party might provide a service for managing your AWS resources. With IAM roles, you can grant these third parties’ access to your AWS resources without sharing your AWS security credentials. Instead, the third party can access your AWS resources by assuming a role that you create in your AWS account.
More details can be referenced here. https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html
When you select either Launch from Website, or Launch through EC2 option from AWS Marketplace, the user has the option to use an existing key pair or to create a new key pair to connect via SSH to the new EC2 instance running the TomorrowX Platform.
For other Linux installations the public keys are typically located in the .ssh/authorized_keys file on the instance.
For more details about Amazon EC2 key pairs and Linux instances refer to https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html
It is strongly recommended as a minimum requirement to set and enforce an operational policy to rotate SSH keys at least every 90 days to allow IAM users who require access to connect directly with TomorrowX Platform instance(s). Set the rotation schedule according to the key and credentials rotation policy in force for your organisation.
Create a new key pair in the EC2 console, type RSA, format .pem. This is a private key that you must download to your local machine.
If you are launching a NEW TomorrowX platform instance, and have been assigned EC2 access permissions, you can select this key pair to SSH connect to the instance when it has launched successfully.
To add or replace a key pair, you must be able to connect to your instance. If you've lost your existing private key or you launched your instance without a key pair, you won't be able to connect to your instance and therefore won't be able to add or replace a key pair.
Generate Public Key from Private Key (e.g., TomorrowX-Platform.pem)
Execute the command ssh-keygen -y
Note: your key file must not be publicly viewable for SSH to work. Use this command if needed: chmod 400 TomorrowX-Platform.pem
400 protects it by making it read only and only for the owner.
You will be prompted to Enter file in which the key is and provide the path for the private key. Where (TomorrowX-Platform.pem) is the new private key.
For centOS installations append the above generated public key to /home/centos/.ssh/authorized_keys
Remove the old key from ~/.ssh/authorized_keys & /home/centos/.ssh/authorized_keys
Now re-connect to the instance using your SSH client command and the new private key, e.g. ssh -i "TomorrowX-Platform.pem" root@[Public IPv4 address]
No other programmatic system credentials or cryptographic keys are required.
AWS Key Management Service (AWS KMS) is a managed service that makes it easy for you to create and control the cryptographic keys that are used to protect your data. https://docs.aws.amazon.com/kms/latest/developerguide/overview.html
Where customer sensitive data is being stored you can choose to use KMS as your encryption solution for your EBS resources associated with your EC2 instances or other data, ensure you utilise and enable automatic key rotation for an existing KMS key.
When you enable automatic key rotation for a KMS key, AWS KMS generates new cryptographic material for the KMS key every year. For more information about KMS key rotation refer to https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html
Customer Sensitive Data
When the instance has launched, the only sensitive data within the installation is the ec2-user password, that is initially set as the instance ID of the new EC2 Instance as detailed in AWS Marketplace launch usage instructions. There is no customer sensitive data stored upon initial deployment.
Where PII or PHI sensitive data could be present you should always encrypt the relevant AWS datastore.
All 3rd party or external services that are utilised to store PII or PHI sensitive data should be encrypted.
A common AWS Service is Amazon Relational Database Service (RDS) where you can encrypt your Amazon RDS DB instances. Data that is encrypted at rest includes the underlying storage for DB instances, its automated backups, read replicas, and snapshots. You need to enable encryption at DB level or table level or field level wherever customer data is stored.
https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html
Use Amazon EBS encryption as a straight-forward encryption solution for your EBS resources associated with your EC2 instances. With Amazon EBS encryption, you aren't required to build, maintain, and secure your own key management infrastructure. Amazon EBS encryption uses AWS KMS keys when creating encrypted volumes and snapshots.
Encryption operations occur on the servers that host EC2 instances, ensuring the security of both data-at-rest and data-in-transit between an instance and its attached EBS storage.
You can attach both encrypted and unencrypted volumes to an instance simultaneously.
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html
Where customer sensitive data is being stored then you should encrypt the EBS data volume attached to the EC2 instance. You will need to create a snapshot of the existing EBS volume and then create a new EBS volume using the newly created Snapshot ID ensuring you check the Encrypt this volume option and selecting the appropriate Key Management Service (KMS) key.
With a new encrypted EBS volume available you can detach the existing unencrypted EBS volume and attach the encrypted EBS volume.
The instance launches with administrator access only. NOTE: There is no back door access to the console application. Loss of administrator credentials will result in access denied without user recovery.
A fully encrypted application database is used for the application and user credentials. Console configuration is available for user SSO access to the console.
There are no AWS services data encryption configuration required as part of the deployment of the software. For the initial installation, any sensitive data such as API keys, passwords etc utilise a credential vault designed to be substantially better than keeping passwords in text file or hard-coded yet still reside within the self-contained instance environment of the TomorrowX Platform.
Please refer to the product reference section - Credential Vault if you require further details.
Administrator users only can access the credential vault values through the console, and obfuscated values (such as passwords) in the web page are never exposed. Instead, the HTML (if you were to view the source) simply contains the value “*SAME*” in all password fields that can be edited.
Every time an administrator changes a password value, the action is logged in the TomorrowX Platform audit log.
For general information about the AWS Instance Metadata Service refer to https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html
Instance Metadata Service Version 1 (IMDSv1) and Instance Metadata Service Version 2 (IMDSv2) are enabled by default when using the Launch from Website AWS Marketplace. You can verify this using the AWS CLI modify-instance-metadata-options command.
Example:
Response:
After the instance successfully launches in EC2, the TomorrowX Platform will then start as a running service. When running, it will immediately invoke a token authenticated API GET request to retrieve the metadata instance-id using IMDSv2 as follows: http://169.254.169.254/latest/meta-data/instance-id This is the only request made to the Instance Metadata Service, initiated from the new instance itself, not externally.
The instance-id value is used as the unique password to then auto-create the ec2-user credentials, which provides software console access only to the AWS customer launching the instance. The AWS Marketplace usage instructions then guide the user to the Essential things to do first section, such as changing user password and setting user access roles.
With initial ec2-user credentials created for the software console, you should turn off access to your instance metadata by disabling the HTTP endpoint of the instance metadata service using the AWS CLI command for the instance. You can reverse this change at any time by enabling the HTTP endpoint.
Example:
Response:
You are advised to use of IMDSv2 if the instance will require access to the Instance Metadata Service. Use the modify-instance-metadata-options CLI command and set the http-tokens parameter to required. When you specify a value for http-tokens, you must also set http-endpoint to enabled.
Example:
Response:
List the available CloudWatch metrics for your instance reference documentation is provided here.
A prerequisite for setting Cloudwatch alarms is to create an Amazon Simple Notification Service (SNS) topic - aws.amazon.com/sns, and then creating a suitable subscription to that topic in order to receive alerts via the alert delivery method preference option. E.g., email, SMS, http(s) web server endpoint, and other options are available.
You are recommended as a minimum to Create status check alarm using AWS Cloudwatch - aws.amazon.com/cloudwatch, to monitor Status check failure:either at appropriate intervals which will be dependent on the application or service being created, and assigned service level as to whether it’s a development, test, or production instance. This alarm will monitor both instance and system status. The AWS/EC2 namespace includes the following status check metrics. By default, status check metrics are available at a 1-minute frequency at no charge. Refer to Status check metrics reference documentation here https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/viewing_metrics_with_cloudwatch.html#status-check-metrics
MetadataNoToken - The number of times the instance metadata service was successfully accessed using a method that does not use a token.
This metric is used to determine if there are any processes accessing instance metadata that are using Instance Metadata Service Version 1, which does not use a token. If all requests use token-backed sessions, i.e., Instance Metadata Service Version 2, the value is 0.
Cloudwatch alarm on this metric will ensure you are notified if the instance is incorrectly using IMDSv1 without a token and can also be visually displayed by browsing for the MetadataNoToken metric in Cloudwatch for all instances.
Other data type Cloudwatch alarms with notifications for production environments are available to monitor CPU utilization when thresholds are above expected limits, and http(s) listeners for web applications monitoring in combination with EC2 load balancer configuration when instances are deployed as a target group behind a load balancer for scaling the platform, if and when required.
Access to the console is via the URL https://{ip address}/console, where {ip address} is the public or Elastic IP address allocated to the EC2 Instance. If you can log in, then the Platform’s Console is working correctly, and all other issues can be resolved from within the Console.
If the console log in window does not load or does not log you in, you can check the platform’s log files by accessing the EC2 instance via SSH and navigating to the following location: opt/local/Tomorrow/server/logs - the logs will provide information about the issue preventing proper function of the Console.
If you can successfully log in to the Console, use the Servers window to check the health of your server, which is where your solutions are deployed to and run from.
Navigate to Administration -> Server Definitions area to rectify Server definition and reachability issues such as port definition, host name, and Server Encryption Key.
TomorrowX Platform service restarts will also help restore the service application of both the console and server. You need to SSH connect to the instance to perform service restarts.
To stop the service use: # service tomorrowstart stop
To start the service use: # service tomorrowstart start
It is good practice, and highly recommended to routinely update the instance with available packages. For example, run the # sudo yum update command as root user for centOS or RHEL every month.
The TomorrowX Platform contains its own internal data store for storing user data, preferences, and the created solutions. There is no specific backup strategy in place as part of the AWS Marketplace deployment. After launch AWS customers are highly encouraged to create Elastic Block Store (EBS) Snapshots of running instance volumes using Lifecycle Manager within the EC2 console.
Tag the instance volume with name Backup and value set to true
Create new lifecycle policy, with policy type EBS snapshot policy
Set Target resources to Volume with Target resource tags Key to Backup with value true
Set the desired backup schedule to create the volume snapshot, for example daily every 24 hours. Select the desired backup and retention policy for your organisation.
To restore a volume snapshot as a new instance, select Create image from snapshot from the Actions menu. A new Amazon Machine Image (AMI) will then be created, from which you can Launch instance from AMI from the Images > AMIs to restore your instance. Please note that user credentials will be those of the instance volume from which the backup was created, new ec2-user credentials are not created with the new instance ID using this method.
If you wish to take a manual backup of the TomorrowX Platform installation:
SSH connect to the instance
Stop the TomorrowX Platform service using the command:
Zip the entire contents of the TomorrowX Platform installation directory. Default installation path is opt/local/Tomorrow where Tomorrow is the installation directory
Copy the zip file to the backup target location of choice
Start the TomorrowX service using the command:
You can restore this folder to your new instance location, ensuring startup service is reinstated to the new instance whilst respecting hardware configuration of the original installation from where the backup has been taken
The following pages describe the service endpoints and service quotas for AWS services. To connect programmatically to an AWS service, you use an endpoint.
https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html
Service quotas, also referred to as limits, are the maximum number of service resources or operations for your AWS account.
With Service Quotas, you can view and manage your anticipated quotas for AWS services from a central location. Quotas, also referred to as limits in AWS services, are the maximum values for the resources, actions, and items in your AWS account. Each AWS service defines its quotas and establishes default values for those quotas. Depending on your business needs, you might need to increase your service quota values. For adjustable quotas, you can request a quota increase. Smaller increases are automatically approved, and larger requests are submitted to AWS Support. You can track your request case in the AWS Support console. Requests to increase service quotas don't receive priority support. If you have an urgent request, contact AWS Support. AWS Support might approve, deny, or partially approve your requests.
To request a service quota increase:
https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html
Sign in to the AWS Management Console and open the Service Quotas console at https://console.aws.amazon.com/servicequotas/home.
In the navigation pane, choose AWS services.
Choose an AWS service from the list or type the name of the service in the search box.
If the quota is adjustable, you can choose the button or the name, and then choose Request quota increase.
For Change quota value, enter the new value. The new value must be greater than the current value.
Choose Request.
If you are expecting to scale your application or service or create multiple public internet facing instances you should proactively Request a quota increase for the EC2-VPC Elastic IPs as the default quota value is set to “5”.
Similarly, if you are using Amazon’s Simple Email Service (Amazon SES) aws.amazon.com/ses/, for console set up user credential reminders, server fail notifications, or the application is using email alerts then you should adjust the default quota to the anticipated sending volume and rate. Typically, AWS will increase the default quota sending limit from 200 to 50,000 upon request approval.
In a high availability deployment scenario, ensure you check and adjust default service quotas for application load balancers and RDS services appropriately.
Elastic Load Balancing endpoints and quotas
https://docs.aws.amazon.com/general/latest/gr/elb.html
Amazon Relational Database Service endpoints and quotas
https://docs.aws.amazon.com/general/latest/gr/rds-service.html
Ensure you review your architectural diagram to check all AWS services used and quotas applied to your account.
AWS Customers are strongly recommended to subscribe to AWS Business support plan, or greater to receive appropriate support from AWS for all production deployments and related AWS services used.
See price plans https://aws.amazon.com/premiumsupport/plans/
VPC
Parameter
Value
Tenancy
Default
Default VPC
Yes
IPv4 CIDR
e.g.172.31.0.0/16
DNS hostnames
Enabled
DNS resolution
Enabled
Subnet
Parameter
Value
Available IPv4 addresses
4090
Default subnet
Yes
Auto-assign public IPv4 address
Yes
IPv4 CIDR
e.g.172.31.64.0/20
Auto-assign public IPv4 address
Yes
Hostname type
IP name
Auto-assign IPv6 address
No
Auto-assign customer-owned IPv4 address
No
Resource name DNS A record
Disabled
Resource name DNS AAAA record
Disabled
Route table
Destination
Target
Propagated
0.0.0.0/0
e.g. igw-ae0737cb
(internet gateway ID)
No
172.31.0.0/16
local
No
Network ACL
Type
Protocol
Port range
Source
Inbound rules (allow)
All traffic
All
All
0.0.0.0/0
Outbound rules (allow)
All traffic
All
All
0.0.0.0/0
Security Group
Type
Protocol
Port range
Inbound rules (IPv4)
HTTP
HTTPS SSH
TCP
TCP TCP
80 443 22
Outbound rules (IPv4)
All traffic
All
All
Role Name
Description
Attached policies
SupportUser
Users who need to SSH connect to instances to perform routine maintenance and server reboots.
SupportUser
AmazonEC2ReadOnlyAccess
EC2InstanceConnect
Add inline policy to Require IMDSv2 (refer to Customer Managed Policies)
AdvancedSupport
Users who require EC2 and Marketplace full access to launch and configure instances. Deploy and advanced technical support.
AmazonEC2FullAccess
AWSMarketplaceFullAccess
ComputeOptimizerReadOnlyAccess
MarketplaceLicences
Users who require access to list software licence subscriptions across the organisation.
LicenseManager-List-Read
