---
title: "Quickstart: Deploy Geneos using AWS CloudFormation"
description: "Quickly set up a demo environment for Geneos using AWS CloudFormation with minimal configuration. Follow our detailed step-by-step guide for deployment."
url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/quickstart/aws-cloudformation-quickstart/index.html"
---
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

The AWS native deployment package contains the following file structure:

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

See [CloudFormation templates](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-aws-cloudformation/aws-cloudformation-templates/index.html#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](https://docs.itrsgroup.com/docs/geneos/7.11.0/administration/gateway_licensing/index.html#demo-mode) for more information. 


## Prerequisites

- 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


**Tip**


Watch this [step-by-step demo](https://app.storylane.io/share/asna6pszg2jy) in full screen to learn how to deploy a demo environment. 


https://app.storylane.io/demo/asna6pszg2jy

1. Create an [S3 bucket](#create-an-s3-bucket-and-upload-artifacts) 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](#create-an-instance-profile-with-an-iam-role).
3. Deploy the [EC2 instances](#deploy-ec2-instances).


**Note**

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


### Create an S3 bucket and upload artifacts

Create an S3 bucket by running:

```bash
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:

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

### Create an instance profile with an IAM role

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](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html)
- [Add or update inline policy document within the IAM role](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html)
- [Create new instance profile](https://docs.aws.amazon.com/cli/latest/reference/iam/create-instance-profile.html)
- [Add an IAM role to the instance profile](https://docs.aws.amazon.com/cli/latest/reference/iam/add-role-to-instance-profile.html)

For example:

  ```bash
    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

#### Deploy an EC2 instance with the Gateway installed

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](https://aws.amazon.com/marketplace/pp/prodview-vsgileoae4w5w) specifications.

For complete details on the default virtual machine configuration, refer to [AWS virtual machine defaults](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/quickstart/virtual-machine-defaults/index.html).

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

##### Using new network resources

```bash
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

```bash
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

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.

```bash
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

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

### View template execution logs

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

### Check the service status

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

### Download the logs

```bash
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

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](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-aws-cloudformation/aws-cloudformation-templates/index.html).