Amazon AWS Specific Information
Please note--this section is organized in the form of a quick-start guide. If all the steps performed are done in-order, it will help to ensure success for an AWS deployment.
Creating an IAM Role
In order to simplify the configuration for Amazon Web Services, the system supports reading the RDS and Elasticache configuration directly. In order to use this feature, one must configure an IAM role with access to the appropriate rights, as shown, then the option for "AWS Configuration" will become available in the Wizard. Without the IAM credentials, a manual configuration is still possible.
The permissions are for:
- AmazonEC2ReadOnlyAccess: To detect the local region being run in, and the security groups to validate proxy configurations
- CloudWatchFullAccess: When using cloudwatch monitoring, to build log groups and to report data (recommended, but not required)
- AmazonElastiCacheReadOnlyAccess: To populate the available caches
- AmazonRDSReadOnlyAccess: To populate database configurations
Configuring an Elasticache for Redis Instance
If Elasticache will be used, it is recommended that the instance be setup before configuring Heimdall, as this allows the Elasticache configuration to be auto-detected. When configuring Elasticache, ensure it is set to "clustered mode enabled". While Heimdall can work in non-clustered mode, it will not be detected in the AWS Wizard if it is not configured with this option. After configuring either a single or multi-node instance, it is important to configure a parameter group, and set the parameter "notify-keyspace-events" to the value "AE". This will allow the system to track objects that are added and removed from the cache automatically, which helps prevent L2 cache misses. In other Redis types, this parameter can be set dynamically at runtime, but in ElastiCache, this can only be set via the parameter group. Failure to do this will simply reduce the performance of the system when there are cache misses. The configuration should appear as below:
Configure the RDS/Aurora Database
Heimdall supports detecting of MySQL, Postgres and SQL Server types (Aurora included). If configured before Heimdall along with the IAM role (above), then the configurations can be populated using the configuration wizard once the Heimdall instance is started. For Redshift installs, autodetection is not yet supported, but can be manually configured in the wizard.
AWS Marketplace Install
Heimdall can be be easily started using the AWS marketplace. During this startup, the image will download the newest release version of Heimdall. If the security groups are such that the download can not complete, then an older version of Heimdall will be used (from the instance creation time).
First, in the EC2, select launch instance, select the aws marketplace option on the left, and search for "Heimdall", then select:
Then, continue with the Heimdall Data Premium Edition:
Select the desired instance types--The marketplace offering supports a variety of appropriate instances with up to 8 cores (please contact Heimdall sales for larger instances):
Continue through the screens, ensuring that the security group configuration opens ports as needed for proxy ports:
Finally, review and launch:
Once the instance is online, please configure the instance using the wizard for the best results. Nearly every manual configuration will have a fault, often resulting in support calls.
Advanced Marketplace Install
As Heimdall can run on multiple servers, at initilization, an instance can accept as user-data configuration options that will control how the instance runs, and if it should operate as a proxy or server (only). When set to such a mode, the instance will attempt to tune itself for the role in question, i.e. use the entire instance's memory vs. allowing memory to be used
- hdHost=hostname of management server
- hdPort=port of the management server, generally 8087
- vdbName=exact name of the vdb to service
- hdUser=login username for the management server, can be admin
- hdPassword=login password for the management server
- javaOptions=Any arbitrary options desired to be set
Once initialized, this configuration can be adjusted in the file /etc/heimdall.conf manually if necessary. Note, if the hdRole is set, then the instance will automatically allocate 80% of instance memory for the process (server or proxy). This can be tuned in the /etc/heimdall.conf as needed as well.
These settings will effectively allow auto-scaling groups of proxies to be configured.
Note: If building an AMI for auto-scaling, which may be used by multiple scaling groups with different configurations, it is suggested that after doing initial testing, the heimdall.conf be deleted so that user-data will be re-read to build the heimdall configuration. This will leverage the user-data on each new initialization to build the configuration at startup.
Cloudwatch Metrics and Logs
In each VDB, under logging, an option is available for AWS Cloudwatch. If enabled and Cloudwatch access is enabled in the system's IAM role, it will start logging a variety of metrics into Cloudwatch under the "Heimdall" namespace, and the vdb logs will also be logged into Cloudwatch. The metrics include:
- DB Query Rate
- DB Query Time
- Avg Response Time
- DB Read Percent
- DB Transaction Percent
- Cache Hit Percent
Please note that additional charges may be incurred due to metrics and logging, in particular if debug logs under high volume are logged into Cloudwatch.