--- title: "Quickstart: Deploy Geneos using Terraform" description: "Learn how to quickly deploy a Geneos demo environment using Terraform on AWS, Azure, or Google Cloud with minimal setup and easy steps." url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/quickstart/terraform-quickstart/index.html" --- This page provides step-by-step instructions for deploying a demo environment using Terraform. This approach is useful for running an initial deployment in AWS, Azure, or Google Cloud with minimal configuration. **Note** For demo environment deployments, the required network and security services are already provisioned, along with a Gateway instance. ## File structure The Terraform deployment package contains the following file structure: ```plaintext scripts/ └── terraform/ ├── environments/ │ ├── demo/ │ │ ├── aws.tf.template │ │ ├── azure.tf.template │ │ ├── gateway.yml │ │ ├── gcp.tf.template │ │ ├── main.tf │ │ ├── netprobe.yml │ │ ├── outputs.tf │ │ ├── terraform.tfvars │ │ ├── variables.tf │ │ └── scripts/ │ │ └── upload_key_if_missing.sh │ │ │ └── dev/ │ ├── aws/ │ │ ├── main.tf │ │ ├── netprobe.yml │ │ ├── outputs.tf │ │ ├── providers.tf │ │ ├── terraform.tfvars.example │ │ ├── terraform.tfvars.rhel8.example │ │ ├── terraform.tfvars.rhel9.example │ │ ├── terraform.tfvars.ubuntu24.example │ │ ├── variables.tf │ │ └── versions.tf │ │ │ ├── azure/ │ │ ├── main.tf │ │ ├── netprobe.yml │ │ ├── outputs.tf │ │ ├── providers.tf │ │ ├── terraform.tfvars.example │ │ ├── terraform.tfvars.rhel8.example │ │ ├── terraform.tfvars.rhel9.example │ │ ├── terraform.tfvars.ubuntu24.example │ │ ├── variables.tf │ │ └── versions.tf │ │ │ └── gcp/ │ ├── main.tf │ ├── netprobe.yml │ ├── outputs.tf │ ├── providers.tf │ ├── terraform.tfvars.example │ ├── terraform.tfvars.rhel8.example │ ├── terraform.tfvars.rhel9.example │ ├── terraform.tfvars.ubuntu24.example │ ├── variables.tf │ └── versions.tf │ └── modules/ ├── aws/ │ ├── default-vpc/ │ │ ├── main.tf │ │ ├── outputs.tf │ │ └── variables.tf │ │ │ ├── instance/ │ │ ├── main.tf │ │ ├── outputs.tf │ │ └── variables.tf │ │ │ └── security_group/ │ ├── main.tf │ ├── outputs.tf │ └── variables.tf │ ├── azure/ │ ├── nic/ │ │ ├── main.tf │ │ ├── outputs.tf │ │ └── variables.tf │ │ │ ├── nsg/ │ │ ├── main.tf │ │ ├── outputs.tf │ │ └── variables.tf │ │ │ ├── public_ip/ │ │ ├── main.tf │ │ ├── outputs.tf │ │ └── variables.tf │ │ │ ├── virtual_machine/ │ │ ├── main.tf │ │ ├── outputs.tf │ │ └── variables.tf │ │ │ └── vnet/ │ ├── main.tf │ └── variables.tf │ ├── common/ │ └── deploy/ │ ├── main.tf │ ├── outputs.tf │ ├── variables.tf │ └── scripts/ │ └── deploy.sh │ └── gcp/ ├── firewall/ │ ├── main.tf │ ├── outputs.tf │ └── variables.tf │ └── instance/ ├── main.tf ├── outputs.tf └── variables.tf ``` Refer to the following sections for details on the purpose of each file: - [Demo environment files](#deployment-steps) **Note** The demo 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. - [AWS development environment files](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/instance-provisioning/aws-instance-provisioning/index.html#template-files) - [Azure development environment files](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/instance-provisioning/azure-instance-provisioning/index.html#template-files) - [Google Cloud development environment files](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/instance-provisioning/google-cloud-instance-provisioning/index.html#template-files) ## Prerequisites 1. [Terraform](https://www.terraform.io/downloads) version 1.0 or higher installed 2. [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) version 2.15 or higher installed. The installation should automatically include `ansible-core`. 3. SSH key pair for Ansible deployment ```bash # Generate SSH key pair if not already available ssh-keygen -t rsa -b 4096 -f ../../../../../resources/id_rsa ``` 4. Access to your selected cloud provider - For AWS: - [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) version 2.0 or higher installed - [AWS permissions and authentication](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/ansible-configuration/index.html#aws) - For Azure: - [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) version 2.0 or higher installed - Azure subscription and resource group - [Azure permissions and authentication](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/ansible-configuration/index.html#azure) - For Google Cloud: - [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) installed - Google Cloud project - [Google Cloud permissions and authentication](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/ansible-configuration/index.html#google-cloud-platform-gcp) 5. Geneos resources - The Netprobe and Gateway packages should be available in their respective cloud storages. - The Netprobe and Gateway setup template files from `/resources` folder should be available in their respective cloud storages. ## Deployment steps **Tip** Watch this [step-by-step demo](https://app.storylane.io/share/elmwimloyrg9) in full screen to learn how to deploy a demo environment. https://app.storylane.io/demo/elmwimloyrg9 1. Activate your preferred [cloud provider](#activate-a-cloud-provider). 2. Configure the [required permissions](#set-up-cloud-provider-authentication). 3. Update the [Terraform configuration file](#update-the-terraform-configuration-file). 4. Update the [Ansible configuration files](#update-the-ansible-configuration-file). 5. [Deploy](#deploy-the-terraform-configuration) the Terraform configuration. 6. [Clean up](#clean-up-resources) the resources created. The following configuration files are provided: | File | Description | |------|-------------| | `terraform.tfvars` | Main configuration file. This must be updated before deployment. | | `netprobe.yml` | Netprobe configuration file for Ansible deployment | | `gateway.yml` | Gateway configuration file for Ansible deployment | | `variables.tf` | Variable definitions | | `main.tf` | Common logic and deployment orchestration | | `providers.tf` | Provider configurations | | `outputs.tf` | Deployment outputs | | `.tf.template` | Cloud-specific resource templates | | `.tf` | Active cloud provider resources (after renaming) | ### Activate a cloud provider The demo environment includes template files for each cloud provider. Before running Terraform, activate your chosen cloud provider by renaming the appropriate template file. **Important** Ensure to select only one cloud provider to avoid conflicts between multiple `.tf` files. - `aws.tf.template` — for AWS-specific resources ```bash mv aws.tf.template aws.tf ``` - `gcp.tf.template` — for Google Cloud-specific resources ```bash mv gcp.tf.template gcp.tf ``` - `azure.tf.template` — for Azure-specific resources ```bash mv azure.tf.template azure.tf ``` The Gateway virtual machine and service will always be deployed when you activate a cloud template by renaming the `*.tf.template` file to `*.tf`. Virtual machine configurations are based on the [Netprobe system requirements](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/installation/quickstart-linux-and-other-platforms/index.html#system-requirements). For complete details on the default virtual machine configuration, refer to [virtual machine defaults](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/quickstart/virtual-machine-defaults/index.html). #### AWS The default instance type is `t3.large`, following the [ITRS AWS AMI](https://aws.amazon.com/marketplace/pp/prodview-vsgileoae4w5w) specifications. #### Azure The following defaults for VM size and OS disk type follow the [ITRS Azure virtual machine image](https://portal.azure.com/#view/Microsoft_Azure_Compute/VmSmartDefaultsBlade/marketplaceId/itrsgroupltd1620310702149.itrs-geneos-azure-monitoringitrs-geneos-azuremon-byol/telemetryId/3ee0a00b-a9c1-4ae2-93f1-8be0cff0fd16) specifications. - Virtual machine size: `Standard_D2s_v3` - Virtual machine OS disk type: `Premium_LRS` #### GCP The default machine type and boot OS disk type and size follow the [Netprobe system requirements](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/installation/quickstart-linux-and-other-platforms/index.html#system-requirements). - Machine type: `n2-standard-2` - Boot disk type: `pd-ssd` - Boot disk size: 50GB ### Set up cloud provider authentication This deployment requires two types of authentication: 1. Terraform authentication (infrastructure creation) to allow Terraform to create virtual machines, networks, and cloud resources. - AWS: Configure AWS CLI profiles or environment variables. - Azure: Configure Azure CLI or service principal. - Google Cloud: Configure `gcloud auth` or service account credentials. 2. Application authentication (cloud storage access) to allow applications running on virtual machines to download the deployment resources from the respective cloud storage. This is configured in the `netprobe.yml` file for each environment. Refer to the following sections for detailed authentication configuration for all cloud providers: - [AWS](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/quickstart/aws-cloudformation-quickstart/index.html#create-an-instance-profile-with-an-iam-role) - [Azure](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/ansible-configuration/index.html#azure) - [Google Cloud Platform](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/ansible-configuration/index.html#google-cloud-platform-gcp) ### Update the Terraform configuration file After activating your cloud provider, update `terraform.tfvars` with your specific values: #### Deployment parameters ```hcl # Deployment Control ansible_operation = "install" # Ansible operation - see ansible/README.md#valid-operations # Common Configuration deployment_count = 2 # Number of Netprobe instances ssh_public_key_path = "../../../../resources/id_rsa.pub" ``` #### Cloud provider configuration Configure only the section for your selected cloud provider. ##### Basic configuration examples ```hcl # AWS - Basic Required Parameters aws_region = "us-east-1" aws_instance_profile = "your-instance-profile-name" # GCP - Basic Required Parameters gcp_project_id = "your-project-id" gcp_service_account_email = "your-service-account@your-project-id.iam.gserviceaccount.com" # Azure - Basic Required Parameters azure_resource_group_name = "your-resource-group" azure_subscription_id = "your-subscription-id" azure_identity_ids = ["/subscriptions/your-subscription-id/resourceGroups/your-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/your-managed-identity"] ``` ### Update the Ansible configuration file The `netprobe.yml` and `gateway.yml` files contain the Ansible configurations for their respective component deployments. Ensure to configure the minimum required fields outlined in [demo configuration](#demo-configuration) and [resources configuration](#resources-configuration). For the general configuration structure and available parameters, refer to [Ansible configuration](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/ansible-configuration/index.html). #### SSH configuration ```yaml # SSH connection configuration (required) ansible_ssh_private_key_file: "../../../resources/id_rsa" ansible_ssh_common_args: "-o ControlMaster=no -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" ``` #### Demo configuration **Note** These settings only exist in the demo environment and are not used in the development environments. These demo-specific keys are intended to simplify switching clouds in the demo. Development environments manage per-cloud configuration in their respective directories and variables. | Parameter | Description | |-----------|-------------| | `demo_configurations` | Hold per-cloud values used by the playbook, currently:- `bootstrap`: per-cloud additional bootstrap command - `source`: per-cloud `resources.source` fields consumed by Ansible download tasks | Example (`netprobe.yml` configuration excerpt): ```yaml demo_configurations: aws: bootstrap: "" source: {} azure: bootstrap: "{{ python_path }} -m pip install --upgrade msrestazure && ansible-galaxy collection install azure.azcollection --force && {{ python_path }} -m pip install -r ~/.ansible/collections/ansible_collections/azure/azcollection/requirements.txt" source: resource_group: Eng-Geneos-Cloud-Resources storage_account_name: geneoscloudresources gcp: bootstrap: "{{ python_path }} -m pip install --upgrade google-cloud-storage" source: auth_kind: machineaccount ``` How these are applied: - `additional_bootstrap: "{{ demo_configurations[cloud_provider].bootstrap }}"` - `resources.source` becomes a map keyed by the chosen provider: - For `aws`: `resources.source = { aws: {} }` - For `azure`: `resources.source = { azure: { resource_group: ..., storage_account_name: ... } }` - For `gcp`: `resources.source = { gcp: { auth_kind: machineaccount } }` #### Resources configuration Update the `resources` block in the Gateway (`gateway.yml`) and Netprobe (`netprobe.yml`) configuration files in `scripts/terraform/environments/demo`. Ensure you specify the correct cloud storage location for your binaries. ```yaml resources: # Remove or empty source to use localhost as default source: "{{ { cloud_provider: demo_configurations[cloud_provider].source } }}" container: path: executable: # Optional per-component extras: setupfile: { path: } # netprobe and gateway only ``` ### Deploy the Terraform configuration Initialize Terraform: ```bash terraform init ``` Preview the planned deployment: ```bash terraform plan ``` Apply the configuration: ```bash terraform apply ``` The Terraform demo environment deploys: | Component | Deployment condition | |-----------|---------------------| | One Gateway instance (management server) | Always deployed when template is activated. | | Configurable number of Netprobe instances (monitoring agents) | Deployed based on `deployment_count`. | | Required networking and security configurations | Always deployed when template is activated. | | Automated Gateway service deployment | Always deployed. | | Automated Netprobe service deployment | Always deployed. | ### Clean up resources To clean up and remove all resources created, run the following command: ```bash terraform destroy ``` ## 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 Terraform](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/cloud-native-deployments/deploying-via-terraform/terraform-deployment-overview-and-prerequisites/index.html).