githubEdit

AWS Terraform Script

Instructions for deploying MikoPBX in AWS via Terraform script

This guide describes deploying MikoPBX in AWS using the Infrastructure as Code (IaC) approach with Terraform. The entire infrastructure — EC2 instance, network rules, disks, and IP address — is declared in code, ensuring reproducibility, versioning, and the ability to quickly redeploy in any environment.

General process:

Download .raw  →  Upload to S3  →  Import as AMI  →  Deploy via Terraform
circle-info

Note: AMI image import cannot be performed directly via Terraform — AWS does not support this process through the Terraform provider. A separate bash script is used for the import, after which Terraform uses the created AMI.


Prerequisites

  • Terraform >= 1.3.0

  • AWS CLI configured with access keys (aws configure)

  • Bash (macOS / Linux)

  • IAM permissions: ec2:*, s3:*, iam:CreateRole, iam:PutRolePolicy

Configuring AWS CLI

aws configure
# AWS Access Key ID: your_key
# AWS Secret Access Key: your_secret_key
# Default region name: us-east-1 (your region)
# Default output format: json

Uploading the Image to S3

  1. Go to the MikoPBX releases page: https://github.com/mikopbx/Core/releasesarrow-up-right

    Download the latest image with the .raw extension.

Amazon Web Services Console
  1. Navigate to ServicesStorageS3.

S3 section in AWS Console
  1. Click Create bucket. Enter a unique bucket name in the Bucket name field. Use default values for all other fields.

Confirm by clicking Create bucket.

Creating bucket to store disk image file
  1. Open the created bucket by clicking its name. Click Upload and select the disk image file with the .raw extension.

Click Upload to confirm.

Uploading disk image file

Configuring the IAM Role for Import

AWS requires a special IAM role vmimport for image imports. Perform these steps once per account.

Create a file trust-policy.json with the following content:

Create a file role-policy.json with the following content:

Replace mikopbx-bucket with your S3 bucket name.

Run the following commands to apply the policies:


Importing the Image as an AMI

Save the script below as import-image.sh and edit the variables DEFAULT_BUCKET, DEFAULT_IMAGE, and DEFAULT_NAME.

import-image.sh

Run the script:

Once complete, the script will output the AMI ID — save it, as it will be needed for Terraform.


Deploying via Terraform

Create all of the following files (directory structure):

Below we walk through each file and the content to add to each:

main.tf

The main configuration file describing all AWS resources to be created: EC2 instance, Security Group, EBS disks, and Elastic IP. By default, the Security Group opens only the ports required for MikoPBX to operate: SSH, HTTP/HTTPS, SIP, and RTP.

Warning: Be sure to configure the Firewall in MikoPBX after your first login!


variables.tf

Declares variables with their types, descriptions, and default values. Does not contain specific values on its own — only the schema.


outputs.tf

Defines what data Terraform will output after a successful apply: the web interface URL, and the login and password for the first login. Convenient for quickly retrieving credentials without opening the AWS Console.


terraform.tfvars

Contains the specific variable values for your environment: region, AMI ID, instance type, etc. This is the file that changes when moving between environments (dev/staging/prod).

Note: Specify your own parameters in this file — replace aws_region, instance_name, instance_type, storage_disk_size, allowed_ssh_cidr, create_key_pair, and public_key_path as needed. Be sure to replace custom_ami_id with the ID of the AMI you created earlier.


Running Terraform

Make sure all 4 files are created, then run the following commands:

You will see the following output:

Run the following command to preview the configuration:

You will see the configuration that Terraform has parsed and plans to create. Review all parameters, then run:

Enter yes to confirm. Upon successful creation of the MikoPBX instance, the required credentials will be displayed:


Connecting to MikoPBX

After a successful terraform apply:

  1. Copy the URL from the output values.

  2. Open it in your browser: https://<URL>

Use the credentials displayed during infrastructure creation to log in.

MikoPBX Web-Interface (Deployed using terraform in AWS)

⚠️ After logging in, be sure to configure the Firewall in MikoPBX.


Destroying Resources

⚠️ The AMI and the S3 bucket containing the image are not deleted automatically — they must be removed manually via the AWS Console or CLI if no longer needed.


Common Errors

Error: InvalidAMIID.NotFound

Cause: The AMI exists in a different region. Solution: Make sure the region in terraform.tfvars matches the region where the import script was run.

Error: OptInRequired during import

Cause: The vmimport role has not been created or lacks the required permissions. Solution: Repeat the IAM role configuration step.

Error: import status error

Cause: Corrupted .raw file or incorrect format. Solution: Verify that the original image was downloaded correctly and that the filename in DEFAULT_IMAGE is accurate.

Slow snapshot import

Importing a large image can take 10–30 minutes. The script automatically waits for completion, polling the status every 30 seconds.

Last updated

Was this helpful?