Add an AWS NGINX Instance

Learn how to deploy an AWS NGINX instance using NGINX Controller.

Overview

You can use NGINX Controller to deploy and manage NGINX instances on Amazon Web Services (AWS).

This tutorial explains how to deploy NGINX Plus on AWS by defining an AWS Integration, a Location, and an Instance Template in NGINX Controller.

Important:
You are responsible for applying software and security updates on your data plane Instances. NGINX Controller does not manage these updates for you.

 

Create an AWS Integration

Integrations give NGINX Controller permission to deploy and manage NGINX instances on external systems, such as cloud providers like AWS.

Prerequisites

To create an Integration for AWS, you need to configure an AWS IAM user with the following roles:

"ec2:*Instance*",
"ec2:*Tags*"

In addition, you’ll need to copy and save the following AWS security credentials to use when creating an AWS Integration:

  • access key ID
  • secret access key ID

Steps

To create an AWS Integration, take the following steps:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select the Create Integration quick action.
  5. Add a name.
  6. (Optional) Add a display name.
  7. (Optional) Add a description.
  8. (Optional) Add tags.
  9. In the Integration Type list, select AWS_INTEGRATION.
  10. (Optional) Add the service endpoint URI.
  11. In the Credential Type list, select AWS_ACCESS_KEY.
  12. Add the access key ID.
  13. Add the secret access key ID.
  14. Select Submit.

 

Create a Location

After you’ve created an Integration for AWS, the next step is to create a Location. Locations are a way to logically group your NGINX Plus instances by their physical locations.

To create a Location, take the following steps:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Infrastructure.
  3. On the Infrastructure Menu, select Locations.
  4. Select Create.
  5. Add a name for the Location.
  6. (Optional) Add a display name.
  7. In the Type list, select AWS_LOCATION.
  8. In the Integration References list, select the AWS Integration(s) to associate with the Location.
  9. Add the AWS VPC ID.
  10. Add the AWS region.
  11. (Optional) Add a description.
  12. (Optional) Add tags.
  13. (Optional) Add a description.
  14. (Optional) Add tags.
  15. Select Submit.

 

Create an Instance Template for AWS NGINX Instances

An Instance Template defines the parameters to use when creating an NGINX instance. Instance templates are ideal for cloud orchestration and make managing your cloud resources easy and quick.

Prerequisites

You’ll need to gather the following AWS information to create an Instance Template for AWS NGINX instances. You may need to look up this information in your AWS account.

  • Amazon Machine Image ID

    The AMI that you select should be secure and hardened. We recommend closing ports that are not needed and updating the AMI to include the latest security patches. NGINX Controller will not secure or update this Instance for you.

    The AMI must be an operating system that is supported by the NGINX Controller Agent. For the list of supported OSes, see the NGINX Controller Technical Specifications Guide.

    The AMI image must have the following software packages installed:

    • NGINX Plus (R19, R20, R21, R22, or R23)
    • Python 2.7 (for NGINX Controller 3.6 and earlier)
    • Golang (for NGINX Controller 3.7 and newer)
    • OpenSSL
    • cURL 7.32 or newer
    • libxerces-c3.2
    • Cloud-init

  • EC2 Instance Type

    After you’ve configured the AMI, you need to define the EC2 Instance size. You can find the EC2 Instance sizes that your region supports here: https://aws.amazon.com/ec2/instance-types/.

  • Subnet ID

    The SubnetId identifies the specific subnet contained within your VPC that you want to deploy your Instance into.

  • Security Group IDs

    The security group controls traffic flowing to and from your NGINX Instances. You need to use the GroupId from the security group to configure your Instance Template.

    The GroupId you select must have ports 22, 443, and 8443 opened to allow communication from NGINX Plus to NGINX Controller. We recommend opening only ports 22 and 8443 to the IP address that NGINX Controller is using. The ports that your applications use will require other ports to be open. If your HTTP application is running on this NGINX Plus Instance, you need to open port 80.

    The security group you select should use the same VPC ID that was configured with your Location.

  • AWS Public Key

    The AWS public key is the key that allows NGINX Controller to communicate with your NGINX Plus orchestrated Instance. You need this key so you can install updates. If you do not want to provide your public key, you need to manually install the NGINX Controller agent. You will copy/paste your ssh key name into this field.

Steps

To create an Instance Template for AWS NGINX instances, take the following steps:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Infrastructure > Instance Templates.
  3. Select Create Instance Template.
  4. Add a name.
  5. (Optional) Add a display name.
  6. (Optional) Add a description.
  7. (Optional) Add tags.
  8. Select a Location in the list, or select Create New to create a Location.
  9. In the Type list, select AWS_INSTANCE_TEMPLATE.
  10. Add the Amazon Machine Image ID.
  11. Add the EC2 Instance Type.
  12. Add the Subnet ID.
  13. (Optional) Add the Security Group IDs.
  14. (Optional) Add the AWS Public Key.
  15. Specify whether a public IP address should be assigned to the instance.
  16. Select Submit.
Note:
Enabling WAF via the App Security add-on is not supported when deploying Instances with an Instance Template.

 

Add an AWS NGINX Instance to NGINX Controller

Now that you’ve defined a Location and made an Instance Template for an NGINX instance on AWS, you’re ready to add the instance to NGINX Controller.

To add an AWS Instance to NGINX Controller, take the following steps:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Infrastructure.
  3. On the Infrastructure menu, select Instances.
  4. On the Instances overview page, select Create.
  5. Select Create a new instance using a template.
  6. Add a name.
  7. Select a Location.
  8. Select an Instance Template.
  9. Select Submit.

 

Troubleshooting

When deploying an NGINX Plus instance, the deployment may fail because the Controller Agent install script doesn’t download. When this happens, an error similar to the following is logged to /var/log/agent_install.log: “Failed to download the install script for the agent.”

Take the following steps to troubleshoot the issue:

  • Ensure that ports 443 and 8443 are open between NGINX Controller and the network where the NGINX Plus instance is being deployed.
  • Verify that you can communicate with NGINX Controller from the NGINX Plus instance using the NGINX Controller FQDN that you provided when you installed NGINX Controller.
  • If you’re deploying an NGINX Plus instance on Amazon Web Services using a template, ensure that the Amazon Machine Image (AMI) referenced in the instance_template has a cURL version of 7.32 or newer.

 

What’s Next

This documentation applies to the following versions of NGINX Controller: 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17, 3.18, 3.18.1, 3.18.2 and 3.18.3.

This documentation applies to the following versions of NGINX Controller API Management module: 3.18, 3.18.1, 3.19, 3.19.1, 3.19.2, 3.19.3 and 3.19.4.

This documentation applies to the following versions of NGINX Controller App Delivery module: 3.20, 3.20.1, 3.21, 3.22, 3.22.1, 3.22.2 and 3.22.3.