Upload using the Azure portal

An 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 NGINXaaS for Azure. The use of certain directives and parameters is not allowed to ensure the NGINX configuration’s compatibility with IaaS 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 an NGINX configuration

Go to your NGINXaaS for Azure deployment.
Select NGINX configuration in the left menu and you will see the default configuration that NGINXaaS provides.

Note:
If you don’t see the default configuration, it’s likely the deployment was created through a client tool other than the portal (For example, Terraform), or the “Apply default NGINX configuration” was unchecked during the deployment creation process in the portal. You can still proceed with the steps below to provide your own NGINX configuration for the deployment.

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 the 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.
Protected File	Indicates the file may contain sensitive data such as passwords. Protected files are saved to the NGINX Configuration, but cannot be retrieved later.

Warning:
Protected files cannot be read after being applied. This means a new copy of the protected file must be included when making changes to the NGINX configuration.

Provide your NGINX configuration.
Create additional configurations as needed following the same steps above.
Select Submit to apply the new configuration.

Note:
We currently only support up to 5 unique listen ports. NGINX configurations that specify more than 5 ports will be rejected. For more information on listen port limitations, see our FAQ.

NGINX configuration validation

NGINX configuration is validated real-time to check for syntax and compatibility with the service. Validation errors are reported in the editor for you to correct.

For example, if you create/update an NGINX config with a particular directive that is not allowed, the service will analyse your NGINX config and provide real-time feedback.

The editing experience consists of a single view for both editing and validation

If the config is invalid, then any errors are highlighted in-place in the config editor. Hover over the highlighted errors to learn more about them or check the problems section at the bottom. Corrections can be made in the same panel.
If the config is valid, then a green check mark appears next to NGINXaaS Analyzer at the bottom indicating that you can submit the config to deploy it.

Upload a GZIP NGINX configuration

Given the example gzipped archive,

$ tar -czf nginx.tar.gz nginx
$ tar -tzf nginx.tar.gz
nginx/
nginx/nginx.conf
nginx/njs.js
nginx/servers
nginx/servers/
nginx/servers/server1.conf
nginx/servers/server2.conf

where nginx is a directory with the following structure,

$ tree nginx
nginx
├── nginx.conf
├── njs.js
└── servers
    ├── server1.conf
    └── server2.conf

1 directory, 4 files

nginx.tar.gz can be uploaded via the following portal workflow.

Before continuing, ensure the file paths in the archive match the includes in the NGINX config. For example,

http {
   include nginx/servers/server1.conf;
   js_import nginx/njs.js;
   # ...
}

Go to your NGINXaaS for Azure deployment.
Select NGINX configuration from the left menu.
Select Upload config package.
Drag and drop or browse for the new gzip compressed archive file to upload.
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.
Select Upload.

Update an NGINX configuration

Go to your NGINXaaS for Azure deployment.
Select NGINX configuration in the left menu.
Select the configuration file you want to update from the File path list.
Make the necessary updates to the configuration.
- You can also update the file path and/or assign the file as root.
(Optional) Select any other configuration files to make additional updates.
Submit your changes.

Delete NGINX configuration Files

Go to your NGINXaaS for Azure deployment.
Select NGINX configuration in the left menu.
Select the configuration file you want to delete from the File path list.
Select the delete icon .
Confirm your action to delete the configuration file.

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

NGINX configuration automation workflows

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

NGINX filesystem restrictions

NGINXaaS for Azure places restrictions on the instance’s filesystem; only a specific set of directories are allowed to be read from and written to. Below is a table describing what directories the NGINX worker process can read and write to and what directories auxiliary files can be written to. Aux files include certificate files and any files uploaded to the deployment, excluding NGINX configuration files.

Allowed Directory	NGINX worker process can read/write to	Aux files can be written to
/etc/nginx		✓
/opt	✓	✓
/srv	✓	✓
/tmp	✓
/var/cache/nginx	✓
/var/www	✓	✓

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

Disallowed configuration directives

Some directives are not supported because of specific limitations. If you include one of these directives in your NGINX configuration, you’ll get an error.

Disallowed Directive	Reason
ssl_engine	No hardware SSL accelerator is available.
debug_points	NGINXaaS does not provide access to NGINX processes for debugging.
fastcgi_bind grpc_bind memcached_bind proxy_bind scgi_bind uwsgi_bind	Source IP specification for active-active deployments is not allowed.
quic_bpf	QUIC connection migration is not currently supported for active-active deployments.

You may find that a few directives are not listed here as either allowed or disallowed. Our team is working on getting these directives supported soon.

Configuration directives list

Alphabetical index of directives

NGINXaaS for Azure supports a limited set of NGINX directives.