September 2, 2026

Federated Architecture for Amazon Web Services or Deploying Horizon 8 on Amazon WorkSpaces Core: Download and Deploy the Horizon Edge Gateway

You can download and deploy the Horizon Edge Gateway into your Horizon 8 federated deployment in Amazon Web Services (AWS) to pair with Horizon Cloud. You can use this same procedure if you are deploying a Horizon Edge for Horizon 8 on Amazon WorkSpaces Core.

Follow these steps to download and deploy the Horizon Edge Gateway appliance for an Edge deployment that uses the federated architecture with the AWS solution.

Follow these same steps to download and deploy the Horizon Edge Gateway appliance for an Edge deployment for Horizon 8 on Amazon WorkSpaces Core.

In the federated architecture or for deploying a Horizon 8 Edge on Amazon WorkSpaces Core, you must deploy Horizon Edge Gateway into the native Amazon Elastic Computer Cloud (EC2) infrastructure within your edge's environment in Horizon Cloud.

Prerequisites

You must meet the following prerequisites before continuing.

Verify that you meet the Horizon Edge Gateway-related prerequisites described in Getting Started with a Horizon 8 Edge Deployment.
Verify that you meet the conditions described in Make Appropriate Destination URLs Reachable to Deploy a Horizon Edge Gateway in a Horizon 8 Environment for using a Horizon Edge Gateway to pair a Horizon 8 pod with Horizon Cloud.
Verify that you are using the appropriate version of the Horizon Edge Gateway. See the Omnissa Product Interoperability Matrix.
The Horizon Edge Gateway virtual appliance must reach the internet to communicate with the Horizon Control Plane. If your environment requires use of a proxy server and proxy configuration for deployed appliances to reach the Internet, verify that you have reviewed the proxy-related information, known limitations, and known issues when using proxy settings with the Horizon Edge Gateway appliance.

If you intend to use a proxy while pairing edge using configure-edge-gateway.sh script, you must first run the following command, specifying as true when ProxySSL is enabled and otherwise specifying as false:

/opt/horizon/bin/configure-edge-gateway.sh -p 'Pairing_Code' -x -i 'IP_or FQDN_of Proxy' -r 'Proxy_Port' -m 'Proxy_User_Name' -a 'Proxy_Password' -s 'true_or_false'

See the proxy-related information in the following Note.

Note: Update the proxy configuration in the Edge.

/opt/horizon/bin/configure-edge-gateway.sh --configure-proxy --proxy-host 127.0.0.1 --proxy-port 3128 --proxy-username 'exampleUsername' --proxy-password 'examplePassword'

To explore more options run the script with -h option, as shown below.

/opt/horizon/bin/configure-edge-gateway.sh -h

You must use the command-line for many of the steps. However, you can perform some of the deployment steps using either the AWS Management Console or the AWS Command Line Interface (CLI). For detailed information about working with an Amazon EC2 environment, see the Amazon Elastic Compute Cloud documentation at https://docs.aws.amazon.com/ec2/index.html. The steps that follow often suggest the specific type of Amazon Elastic Compute Cloud documentation to reference.

Procedure

Download the Horizon Edge Gateway disk image by using the step to obtain the Horizon Edge Gateway Appliance binary in the middle of the procedure on page Add and Deploy a Horizon 8 Edge. Respond to all onscreen prompts.

The Horizon Edge Gateway disk image/appliance is available as a VMDK file. Download the VMDK file to your local system.

Note: Download the latest version of the Horizon Edge Gateway disk image. We recommend that you use the latest version of the Edge Gateway appliance. For version information, see the Omnissa Product Interoperability Matrix.

Save the downloaded binary to a location from which you will deploy it into the desired virtualization platform and then return to this step sequence to continue the required pairing process.

Before uploading the disk image file to your Amazon EC2 environment, you must first create an Amazon S3 bucket.
Create an Amazon S3 bucket in your Amazon EC2 environment. For detailed instructions, refer to the Amazon Elastic Compute Cloud documentation.
Upload the downloaded VMDK file to your Amazon S3 bucket. You can perform this step using either the AWS Management Console or the AWS command-line interface (CLI).
- (AWS Management Console) Log in to the AWS Management Console for your Amazon EC2 environment. Go to the S3 service, select the bucket that you created earlier, and upload the VMDK file to that bucket.
- (AWS CLI) Access the AWS CLI and run the following command.
```
aws s3 cp <file-path-to-VMDK-file> <S3URI>
```
  See the Amazon Elastic Compute Cloud documentation for details about running the cp command.
In the AWS Management Console, the VMDK file is listed in the Objects tab.
Create a service role and a policy and attach the policy to the role.
1. Create the first of three new JSON files required for this procedure.
  
  The purpose of this JSON file is to store the service-role information. Name the file as you wish. In this procedure, the example filename for this file is trust-policy.json.
  
  The following text is as an example of the contents of the JSON file.
```
{
    "Version":"2022-10-17",
    "Statement":[
        {
            "Sid":"",
            "Effect":"Allow",
            "Principal":{
                "Service":"vmie.amazonaws.com"
            },
            "Action":"sts:AssumeRole",
            "Condition":{
                "StringEquals":{
                    "sts:ExternalId":"vmimport"
                }
            }
        }
    ]
}
```
2. Create a service role with a name of your choice and store the role information in the new JSON file.
  
  For example, using the CLI, run a command such as the following.
  
  The following command is a generic example.
```
aws iam create-role --role-name <role-name> --assume-role-policy-document <file-path>
```
  The following example command replaces the placeholder <role-name> with the specific example vmimport and the placeholder <file-path> with the specific example trust-policy.json.
```
aws iam create-role --role-name vmimport --assume-role-policy-document file://trust-policy.json
```
  See the Amazon Elastic Compute Cloud documentation for details about running the create-role command.
3. Create the second of three new JSON files required for this procedure.
  
  Provide the name of bucket name in which you will upload the VMDK file, such as <bucket-name>, the name used in the example that follows.
  
  The purpose of this JSON file is to attach a new policy with the new role. Name the file as you wish. In this procedure, the example filename for this file is role-policy.json.
  
  The following text is as an example of the contents of the example role-policy.json file.
```
{
    "Version":"2022-10-17",
    "Statement":[
        {
            "Effect":"Allow",
            "Action":[
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource":[
                "arn:aws:s3:::<bucket-name>"
            ]
        },
        {
            "Effect":"Allow",
            "Action":[
                "s3:GetObject"
            ],
            "Resource":[
                "arn:aws:s3:::<bucket-name>/*"
            ]
        },
        {
            "Effect":"Allow",
            "Action":[
                "ec2:ModifySnapshotAttribute",
                "ec2:CopySnapshot",
                "ec2:RegisterImage",
                "ec2:Describe*"
            ],
            "Resource":"*"
        }
    ]
}
```
4. Create a policy, attach it to the new role, and store them in the newly created JSON file.
  
  For example, using the CLI, run a command such as the following.
  
  The following command is a generic example.
```
aws iam put-role-policy --role-name <role-name> --policy-name <policy-name> --policy-document <file-path>
```
  The following example replaces the placeholder role-name with a specific example of a role named x, the placeholder policy-name with the specific example of the previously named policy also named x, and the placeholder file-path with the specific example of the previously named JSON file x.
  
  aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document file://role-policy.json
  
  See the Amazon Elastic Compute Cloud documentation for details about running the put-role-policy command.
Import a snapshot from the imported VMDK file.
1. Create the third of three new JSON files required for this procedure.
  
  Include the following information in the file.
  - The bucket name, such as <bucket-name>, which is used in the example that follows.
  - The filename of the VMDK file that you uploaded to your Amazon S3 bucket, such as <vmdk-file-name-uploaded-to-S3>, which is used in the example that follows.
  The purpose of this JSON file is to store the snapshot of the imported VMDK file. Name the file as you wish. In this procedure, the example filename for this file is container.json.
  
  The following text is an example of the contents of the container.json file.
```
{
    "Description": "Adapter-VM",
    "Format": "vmdk",
    "UserBucket": {
        "S3Bucket": "<bucket-name>",
        "S3Key": "<vmdk-file-name-uploaded-to-S3>"
    }
}
```
2. Run the command to import the snapshot from the imported VMDK file to the newly created JSON file.
  
  Using the CLI, run the following type of command.
```
aws ec2 import-snapshot --role-name <role-name> --description <description> --disk-container <file-path>
```
  See the Amazon Elastic Compute Cloud documentation for details about running the import-snapshot command.
  
  The following command is a specific example of the import-snapshot command, where the role-name parameter is optional and not used, the description is "Adapter-VM", and the container filename is container.json.
```
aws ec2 import-snapshot --description "Adapter-VM" --disk-container file://container.json
```
  The import-snapshot command can take several minutes to complete. However, after you run the command, the command creates output, which includes an ImportTaskId line that you can use to track the progress of the task. The following output is an example.
```
{
    "ImportTaskId": "import-snap-05b4c84af4xxxxxxx",
    "Description": "Adapter-VM",
    "SnapshotTaskDetail": {
        "StatusMessage": "pending",
        "UserBucket": {
              "S3Bucket": "awsbucket",
             "S3Key": "edge-gw-2.3.3.0-22720582.ec2.vmdk"
         },
       "Progress": "0",
       "Status": "active",
        "Description": "Adapter-VM",
        "DiskImageSize": 0.0
    }

}
```
3. Take note of the ImportTaskId value in the import-snapshot command output.
To track the progress of the import-snapshot task and obtain the snapshot ID, run the following command.
```
aws ec2 describe-import-snapshot-tasks --import-task-ids <import-task-id>
```
Replace the <import-task-id> placeholder with the value listed in the import-snapshot command output. The example value listed in the preceding example output is import-snap-05b4c84af4xxxxxxx. See the Amazon Elastic Compute Cloud documentation for details about running the describe-import-snapshot-tasks command.

The describe-import-snapshot-tasks command provides output that indicates the progress of the import-snapshot task and, when the task is complete, provides the snapshot ID, which is required to register the image. For example.
- "Progress": "43". A line in the output such as this line indicates the percentage of progress for the import-snapshot task. In this example, the task is 43% complete.
- "Status": "completed". A line in the output such as this line indicates that the import-snapshot task is complete.
- "SnapshotId": "snap-06d42e043bxxxxxxx". A line in the output such as this line is included when the task is complete. For this example, the snapshot ID is snap-06d42e043bxxxxxxx.
Take note of the snapshot ID from the describe-import-snapshot-tasks command output.
To register the snapshot image, run the register-image command.
```
aws ec2 register-image --region us-west-2 --name <image-name> --architecture x86_64 --root-device-name '/dev/sda1' --virtualization-type hvm --ena-support --block-device-mappings DeviceName=/dev/sda1,Ebs={SnapshotId=<SnapshotId>} 
```
Where you must provide responses specific to your deployment for each option, such as the --region, --architecture, and others. See the Amazon Elastic Compute Cloud documentation for details about running the register-image command.

The following information is specific to the --name option and the SnapshotId parameter.
- --name - provide a name for the image according to the constraints for the string.
- SnapshotId - provide the snapshot ID from the describe-import-snapshot-tasks command output. The register-image command provides output that includes the ID of the Amazon Machine Image (AMI). The following example is a typical register-image output.
```
 {
        "ImageId": "ami-0721ee000321c4685"
    }
```
The AMI indicated in the register-image command output also appears in the AWS Management Console among the list of AMIs.
To support the creation and configuration of the Horizon Edge Gateway AMI instance, prepare a startup script similar to the following example.
```
#!/bin/bash
/opt/horizon/bin/configure-adapter.py --sshEnable
echo -e '<password>\n<password>' | passwd admin
echo -e '<password>\n<password>' | passwd ccadmin
echo 'cs_ip cs_fqdn' >> /etc/hosts
```
In the example, the script supports the following configurations:
- Enablement of SSH access to the Horizon Edge Gateway appliance.
- Creation of an admin user account on the appliance with the defined password (\n). Ensure that you define a strong password. Strong passwords are at least 8 characters and must include one or more numbers, upper and lower case letters, and special characters.
- Creation of a ccadmin user account on the appliance with the defined password (\n). Ensure that you define a strong password. Strong passwords are at least 8 characters and must include one or more numbers, upper and lower case letters, and special characters.
- Resolution of the Connection Server host name (cs_fqdn) to the Connection Server IP address (cs_ip). You must add this script to the user-data in the next step where you launch the Horizon Edge Gateway AMI instance.
Launch the AMI instance for Horizon Edge Gateway.

Note: To ensure that the instance provides sufficient capabilities, use model c5.2xlarge or greater.

You can launch an instance using the AWS Management Console or the CLI. In either case, use the ID of the Amazon Machine Image (AMI) provided in the register-image command output and add the startup script that you prepared in the previous step to the user-data.

Note: You must add the startup script at this time because the user-data is only executed at the first boot sequence of the AMI instance.

To use the CLI, see the Amazon Elastic Compute Cloud documentation for details about running the run-instances command.

To use the AWS Management Console, see the Amazon Elastic Compute Cloud documentation for details, such as for launching an instance using the launch instance wizard.

If you choose to launch the instance using the AWS Management Console, locate the new AMI by the Image ID, select the AMI, and click Launch. You can then continue through the wizard providing the specifics for your deployment.
After the Horizon Edge Gateway AMI starts up, edit the configuration of the AMI instance and remove the startup script.
SSH to the Horizon Edge Gateway VM AWS instance.

To use the CLI or AWS Management Console, see the Amazon Elastic Compute Cloud documentation for details about connecting to your instance. We recommend SSH to allow copy-paste of the pairing key.

For related information, see Enable SSH access for Horizon Edge.

For related information, also see Connect to your Linux instance and Connect to your Linux instance with EC2 Instance Connect in AWS product documentation.
Run a pair edge script using the following command format, where pairing_code is the pairing code that you copied from the Step 9 screenshot described in Add and Deploy a Horizon 8 Edge.
```
sudo su -
/opt/horizon/bin/configure-edge-gateway.sh -p <pairing_code>
```
To improve security, consider deactivating SSH when you have completed these steps.
Go back to the Horizon Universal Console to complete the configuration of the Horizon Connection Server detail. See Add and Deploy a Horizon 8 Edge.

Was this page helpful?

Federated Architecture for Amazon Web Services or Deploying Horizon 8 on Amazon WorkSpaces Core: Download and Deploy the Horizon Edge Gateway

Prerequisites

Procedure

Provide feedback for this topic

Write your review