Quickstart: Deploy Geneos using AWS CloudFormation

This page provides step-by-step guides to get started with an initial deployment of a demo environment using AWS CloudFormation and the templates provided. This is useful if you want to run an initial deployment in your AWS environment with minimal configuration requirements.

Note

For demo environment deployments, the required network and security services are already provisioned, along with instances for the Gateway.

File structure Copied

The AWS native deployment package contains the following file structure:

scripts/
└── native/
    └── AWS/
        ├── resources/
        │   ├── gateway.service
        │   └── netprobe.service
        │
        ├── DemoDependencies.yml
        ├── EC2withNetprobe.yml
        ├── ExistingEC2withNetprobe.yml
        ├── RollbackNetprobe.yml
        ├── UninstallNetprobe.yml
        └── UpdateNetprobe.yml

See CloudFormation templates for details on the purpose of each template file.

The DemoDependencies.yml template is deployed in this quickstart guide. It sets up a demo Gateway with flexible networking options. You can either create new AWS resources such as VPC, subnet, and security group, or use the AWS defaults. The template also automates the setup of an EC2 instance with a Gateway installation and configuration as a systemd service.

Note

The DemoDependencies.yml template deploys the Gateway in demo mode, limiting you to two Netprobe instances. Refer to Gateway demo mode for more information.

Prerequisites Copied

• An AWS account with permissions to create EC2 instances and networking resources
• When using defaults (CreateNewResources=false), ensure that your account already has a default VPC. Most AWS accounts should automatically have this.
• An IAM instance profile with the required permissions:
  • S3 read access to the Gateway artifacts bucket
  • EC2 and VPC permissions, if creating new resources
• The Gateway installation package and files should be located in an accessible S3 bucket:
  • The Gateway executable should be named gateway2.linux_64.
  • The setup file should be named gateway.setup.xml.

Deployment steps Copied

1. Create an S3 bucket where the following Geneos artifacts and templates will be stored:

   • Gateway binary tarball (for example, geneos-gateway-7.5.0-linux-x64.tar.gz)
   • Gateway setup XML (for example, gateway.setup_template.xml located in /resources)
   • Netprobe binary tarball (for example, geneos-netprobe-standard-7.5.0-linux-x64.tar.gz)
   • Netprobe setup XML (for example, netprobe.setup_template.xml located in /resources)
   • Service files (for example, files located in scripts/native/AWS/resources)

2. Create an instance profile with an IAM role.

3. Deploy the EC2 instances.

Note

Commands are provided for each deployment step. Update the parameters as needed.

Create an S3 bucket and upload artifacts Copied

Create an S3 bucket by running:

aws s3api create-bucket --bucket <your-unique-bucket-name> --region <region> --create-bucket-configuration LocationConstraint=<region>

Upload the Geneos artifacts and configuration templates in the S3 bucket created by running:

aws s3 cp /local/file/path s3://<your-unique-bucket-name>/

Create an instance profile with an IAM role Copied

You must have an instance profile with an IAM role granting read permissions on the S3 bucket.

Refer to the following AWS documentation for more information:

• Create new IAM role
• Add or update inline policy document within the IAM role
• Create new instance profile
• Add an IAM role to the instance profile

For example:

  aws iam create-role --role-name <roleName> --assume-role-policy-document '{
    "Version":"2012-10-17",
    "Statement":[{"Effect":"Allow","Principal":{"Service":"ec2.amazonaws.com"},"Action":"sts:AssumeRole"}]
  }'

  aws iam put-role-policy --role-name <roleName> --policy-name S3Read-MyBucket --policy-document '{
    "Version":"2012-10-17",
    "Statement":[
      {"Effect":"Allow","Action":["s3:GetObject"],"Resource":"arn:aws:s3:::<your-unique-bucket-name>/*"},
      {"Effect":"Allow","Action":["s3:ListBucket"],"Resource":"arn:aws:s3:::<your-unique-bucket-name>"}
    ]
  }'

  aws iam create-instance-profile --instance-profile-name <instanceProfileName>
  aws iam add-role-to-instance-profile --instance-profile-name <instanceProfileName> --role-name <roleName>

Deploy EC2 Instances Copied

Deploy an EC2 instance with the Gateway installed Copied

You can deploy EC2 instances running the Gateway using either new network resources or existing network infrastructure. The default instance type is t3.large, following the ITRS AWS AMI specifications.

For complete details on the default virtual machine configuration, refer to AWS virtual machine defaults.

The following scripts will download and install these components from your S3 bucket and configure them as services.

Using new network resources Copied

aws cloudformation deploy --stack-name DemoDepsNewNet --template-file scripts/native/AWS/DemoDependencies.yaml --parameter-overrides CreateNewResources=true AMIImageId=ami-0123456789abcdef0 IamInstanceProfile=MyEc2InstanceProfile KeyName=my-keypair S3GatewayURL=s3://my-bucket/gateway.tar.gz S3GatewaySetupURL=s3://my-bucket/gateway.setup.xml S3GatewayServiceURL=s3://my-bucket/gateway.service

Using default network resources Copied

aws cloudformation deploy --stack-name DemoDepsDefNet --template-file scripts/native/AWS/DemoDependencies.yaml --parameter-overrides CreateNewResources=false AMIImageId=ami-0123456789abcdef0 IamInstanceProfile=MyEc2InstanceProfile KeyName=my-keypair S3GatewayURL=s3://my-bucket/gateway.tar.gz S3GatewaySetupURL=s3://my-bucket/gateway.setup.xml S3GatewayServiceURL=s3://my-bucket/gateway.service

Deploy an EC2 Fleet with the Netprobe installed Copied

The following script will deploy an EC2 fleet that runs the Netprobe and connects to an existing Gateway. Use the same VPC and subnet as the Gateway EC2 instance to ensure proper connectivity between the Netprobe and the Gateway.

aws cloudformation deploy --stack-name MyNetprobeFleet --template-file scripts/native/AWS/EC2withNetprobe.yaml --parameter-overrides AMIImageId=ami-0123456789abcdef0 KeyName=my-keypair IamInstanceProfile=MyEc2InstanceProfile VpcId=my-vpc SubnetId=my-subnet SecurityGroupIds=my-security-group S3NetprobeURL=s3://my-bucket/netprobe.tar.gz S3NetprobeSetupURL=s3://my-bucket/netprobe.setup.xml S3NetprobeServiceURL=s3://my-bucket/netprobe.service GatewayHost=my-gateway-host NumberOfInstances=3

Verification and debugging Copied

Run the following commands if you need to verify or debug your deployment.

View template execution logs Copied

ssh -i <privatekey> <user>@<host> "sudo cat /var/log/cloud-init-output.log"

Check the service status Copied

ssh -i <privatekey> <user>@<host> "systemctl is-active <service>.service"

Download the logs Copied

ssh -i <privatekey> <user>@<host> "sudo tar -cvz -C "cd <install_dir> && find <service> -type f -name '*.log' -print0 | sudo tar --null -czf - --files-from -" > <service>-logs.tar.gz

Next steps Copied

After successfully deploying to the demo environment, you may proceed to the development environment. The demo environment automatically provisions network and security resources for demonstration purposes and must be destroyed afterwards. The development environment, however, requires you to provision your own network and security resources.

For detailed instructions, see Deploying via AWS CloudFormation.