Quickstart: Deploy Geneos using Terraform

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 Copied

The Terraform deployment package contains the following file structure:

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

  Note

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

• AWS development environment files
• Azure development environment files
• Google Cloud development environment files

Prerequisites Copied

1. Terraform version 1.0 or higher installed

2. Ansible version 2.15 or higher installed. The installation should automatically include ansible-core.

3. SSH key pair for Ansible deployment

   # 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 version 2.0 or higher installed
     • AWS permissions and authentication
   • For Azure:
     • Azure CLI version 2.0 or higher installed
     • Azure subscription and resource group
     • Azure permissions and authentication
   • For Google Cloud:
     • Google Cloud CLI installed
     • Google Cloud project
     • Google Cloud permissions and authentication

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 Copied

1. Activate your preferred cloud provider.
2. Configure the required permissions.
3. Update the Terraform configuration file.
4. Update the Ansible configuration files.
5. Deploy the Terraform configuration.
6. Clean up the resources created.

The following configuration files are provided:

Activate a cloud provider Copied

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

  mv aws.tf.template aws.tf
  

• gcp.tf.template — for Google Cloud-specific resources

  mv gcp.tf.template gcp.tf
  

• azure.tf.template — for Azure-specific resources

  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. For complete details on the default virtual machine configuration, refer to virtual machine defaults.

AWS Copied

The default instance type is t3.large, following the ITRS AWS AMI specifications.

Azure Copied

The following defaults for VM size and OS disk type follow the ITRS Azure virtual machine image specifications.

• Virtual machine size: Standard_D2s_v3
• Virtual machine OS disk type: Premium_LRS

GCP Copied

The default machine type and boot OS disk type and size follow the Netprobe system requirements.

• Machine type: n2-standard-2
• Boot disk type: pd-ssd
• Boot disk size: 50GB

Set up cloud provider authentication Copied

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
• Azure
• Google Cloud Platform

Update the Terraform configuration file Copied

After activating your cloud provider, update terraform.tfvars with your specific values:

Deployment parameters Copied

# 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 Copied

Configure only the section for your selected cloud provider.

Basic configuration examples Copied

# 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 Copied

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 and resources configuration.

For the general configuration structure and available parameters, refer to Ansible configuration.

SSH configuration Copied

# 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 Copied

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.

Example (netprobe.yml configuration excerpt):

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 Copied

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.

resources:
  # Remove or empty source to use localhost as default
  source: "{{ { cloud_provider: demo_configurations[cloud_provider].source } }}"
  container: <cloud-storage-container>
  path: <archive-file>
  executable: <binary-name>
  # Optional per-component extras:
  setupfile: { path: <setup-xml> }     # netprobe and gateway only

Deploy the Terraform configuration Copied

Initialize Terraform:

terraform init

Preview the planned deployment:

terraform plan

Apply the configuration:

terraform apply

The Terraform demo environment deploys:

Clean up resources Copied

To clean up and remove all resources created, run the following command:

terraform destroy

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 Terraform.