NGINX Configuration

Learn how to configure NGINX for Azure

NGINX configuration can be applied to the deployment via the Azure portal in two different ways:

  • Create a new NGINX configuration from scratch or by pasting it in the Azure portal editor.
  • Upload a gzip compressed tar archive containing your NGINX configuration.

As part of applying your NGINX configuration, the service validates the configuration for syntax and compatibility with NGINX for Azure service. Use of certain directives and parameters is not allowed to ensure the NGINX configuration’s compatibility with SaaS deployment model in Azure. Validation errors are reported in the editor for you to correct. For more information, check the NGINX Configuration Validation section.

Prerequisites

  • If the NGINX configuration requires SSL/TLS certificates, then a managed identity and integration with Azure Key Vault is required.

  • A contributor role is required to apply the configuration to the deployment.

Add NGINX configuration

  1. Go to your NGINX for Azure deployment.

  2. Select NGINX configuration in the left menu.

  3. Select the plus icon to add a file path, then Confirm.

    Property Description
    File path Each NGINX configuration file can be uniquely identified by a file path (for example, nginx.conf or /etc/nginx/nginx.conf) to align with intended NGINX configuration file structure.
    Root file The root file is the main NGINX configuration file. The first file created will be the root file by default.
    You can designate a different root file if you have more than a single configuration file in your deployment. The root file is designated with a bookmark icon on the portal.
    Add NGINX Configuration
    Note:
    When you create a new deployment, it is expected that the default NGINX configuration isn’t visible in this step.
  4. Provide your NGINX configuration.

    NGINX Configuration file
  5. You can create additional configurations as needed following the same steps above.

  6. Select Submit to apply the new configuration.

NGINX Configuration Validation

NGINX for Azure is primarily focused on L7 load balancing such as HTTP reverse proxy use cases. Only HTTP context is allowed (Stream or Mail contexts do not currently work and will be rejected). Configuration provided within the HTTP context guarantees the best experience.

Here is a simple Hello World example of an NGINX configuration added to the deployment, where only the HTTP context is provided

http {
    server {
        listen 80;
        location / {
            default_type text/html;
            return 200 '<!doctype html><html lang="en"><head></head><body>hellow world!</body></html>';
        }
    }
}

NGINX configuration is validated upon submission to check for syntax and compatibility with the service. Validation errors are reported back in the editor for you to correct.

For example, if the NGINX configuration fails validation because a particular directive is not allowed, the service rejects the configuration, and you have an opportunity to correct the errors.

NGINX Configuration validation error

The editing experience provides a split view:

  • The left editor provides a read-only view of the rejected configuration. Hover over the highlighted errors to learn more about them.

  • Make updates and corrections in the editor on the right.

After making any corrections, resubmit the configuration.

Upload GZIP NGINX Configuration

  1. Go to your NGINX for Azure deployment.

  2. Select NGINX configuration from the left menu.

  3. Select Upload config package.

    Upload GZIP NGINX Configuration file
  4. Drag and drop or browse for the new gzip compressed tar archive file to upload.

  5. Specify the root file.

    Warning:
    Uploading a new file will replace all existing NGINX configuration files in your deployment. You must acknowledge this step before you proceed to upload.
  6. Select Upload.

    Confirm Config file upload

Update NGINX Configuration

  1. Go to your NGINX for Azure deployment.

  2. Select NGINX configuration in the left menu.

  3. Select the configuration file you want to update from the File path list.

  4. Make the necessary updates to the configuration.

    • You can also update the file path and/or assign the file as root.
  5. (Optional) Select any other configuration files to make additional updates.

  6. Submit your changes.

Warning:
Uploading a new GZIP compressed tar archive will replace all the existing NGINX configuration files in the deployment.

Delete NGINX Configuration

  1. Go to your NGINX for Azure deployment.

  2. Select NGINX configuration in the left menu.

  3. Select the configuration file you want to delete from the File path list.

  4. Select the delete icon .

  5. Confirm your action to delete the configuration.

Confirm Delete Configuration

Note:
Only non-root configuration files can be deleted.

NGINX Configuration Automation Workflows

NGINX configurations stored in GitHub can be applied to existing NGINX for Azure deployments via custom GitHub Action workflows. See NGINX for Azure Deployment Action for documentation and examples on how to incorporate these workflows in your GitHub Actions CI/CD pipelines.

NGINX Process Restrictions

NGINX for Azure allows the NGINX worker proccess to read and write only from the following directories:

  • /tmp
  • /srv
  • /opt
  • /var/www

Attempts to access other directories will be denied and result in a 5xx error.

What’s Next

NJS Support.