Add a vSphere NGINX Instance

Learn how to deploy a vSphere NGINX instance using NGINX Controller.

Overview

You can use NGINX Controller to deploy and manage NGINX instances on VMware vSphere.

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

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

 


Before You Begin

Before you can create a vSphere Integration in NGINX Controller, you need to have an account in the vSphere instance you are using with privileges to create and delete a VM. You’ll need the following information when creating a vSphere Integration:

  • vSphere hostname or IP
  • vSphere account username
  • vSphere account password
  • NGINX Plus VM template

Create an NGINX Plus VM template

Select a suitable base OS from the NGINX Plus release docs for the version of NGINX Plus that will be installed.

Install the following prerequisites:

Note: For Ubuntu distributions, please apply the workaround described here which prevents cloned VMs from being assigned the same IP address.

Install NGINX Plus as described.

A template created from a VM that has the prerequisites mentioned above can be used in the vSphere integration.

Important:
You are responsible for securing the connection between the vSphere cloud and any VMs that are created. NGINX Controller can’t secure those connections.

 


Create a vSphere Integration

Integrations allow NGINX Controller to deploy and manage NGINX instances on external systems (cloud providers like vSphere).

To create an Integration for vSphere using the NGINX Controller API, send a POST request similar to the following example to the Integrations API endpoint.

In the JSON request, provide the hostname or IP, username, and password for the vSphere instance as mentioned in this section.

{
    "metadata": {
        "name": "my-v-integration"
    },
    "desiredState": {
        "type": "VSPHERE_INTEGRATION",
        "hostname": "xx.xx.xx.xx",
        "credential": {
            "type": "USER_PASS",
            "username": "vsphereUser",
            "password": "*****"
        }
    }
}

 


Create a Location

Locations are a way to logically group your NGINX Plus instances by their physical locations. After you have created an Integration for vSphere, take the following steps to create a Location.

Prerequisites

To create a Location, you’ll need your vSphere datacenter name and a vSphere VM folder(optional):

Create a Location by using the REST API

To create a Location using the NGINX Controller API, send a POST request similar to the following example to the Locations API endpoint.

In the JSON request, provide the datacenter name, and folder name.

{
  "metadata": {
    "name": "my-v-location"
  },
  "desiredState": {
    "type": "VSPHERE_LOCATION",
    "datacenter": "dc1",
    "folder": "v_test",
    "integrationRef": {
      "ref": "/api/v1/platform/integrations/my-v-integration"
    }
  }
}

 


Create an Instance Template for vSphere 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.

For the Instance Template, you need to provide a VM template with NGINX Plus, cloud-init and cloud-init-vmware-guestinfo installed. Refer to this to create a NGINX Plus VM template. Use this NGINX Controller Technical Specifications guide for the NGINX Plus requirements.

  • To create an Instance Template using the NGINX Controller REST API, send a POST request similar to the following example to the Instance Templates API endpoint. You can find descriptions of the instance parameters in the API Reference documentation.

 

{
  "metadata": {
    "name": "my-v-template"
  },
  "desiredState": {
    "type": "VSPHERE_INSTANCE_TEMPLATE",
    "image": "v_orch_test/nginxplus-template",
    "computeResource": "cluster1",
    "datastore": ["vsanDatastore"],
    "network": ["VLAN-1234"],
    "numCPUs": 1,
    "memoryMB": 4096
  }
}

 


Add a vSphere NGINX Instance to NGINX Controller

Now that you’ve defined a Location and created an Instance Template for an NGINX instance on vSphere, you are ready to add the instance to NGINX Controller.

To add a vSphere NGINX instance to NGINX Controller using the NGINX Controller REST API, send a POST request as shown below to the Instances API endpoint. For the templateRef parameter, use the Instance Template that you created in the previous procedure.

{
  "metadata": {
    "name": "v-inst"
  },
  "desiredState": {
    "type": "VSPHERE_INSTANCE",
    "templateRef": {
      "ref": "/infrastructure/locations/my-v-location/instance-templates/my-v-template"
    }
    }
}

 


What’s Next

​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​

This documentation applies to the following versions of NGINX Controller: 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17 and 3.18.