Deployment issues for new customers

Currently, all new-customer deployments are non-functional. Existing customers deploying into a new region are also affected. See Known Issues for updates.

NGINX Configuration

Learn how to configure NGINX as a Service 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 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 NGINX configuration

  1. Go to your NGINXaaS 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 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.
    Add NGINX Configuration
    Note:
    When you create a new deployment, it is expected that the default NGINX configuration isn’t visible in this step.
    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.
  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.

Note:
We currently only support servers listening on ports 80 and 443. We have future work to extend these to other ports.

NGINX Configuration Validation

NGINXaaS 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>hello 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

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;
   # ...
}
  1. Go to your NGINXaaS 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
Warning:
The configuration will fail to upload if any files in the tarball are not referenced in the NGINX configuration. Make sure to exclude any OS specific files from the tarball, for example, files starting with ._.

Update NGINX Configuration

  1. Go to your NGINXaaS 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.

Delete NGINX Configuration

  1. Go to your NGINXaaS 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 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.

Configuration Directives List

Alphabetical index of directives

NGINXaaS for Azure supports a limited set of NGINX directives.

absolute_redirect
accept_mutex
accept_mutex_delay
access_log (ngx_http_log_module)
add_after_body
add_before_body
add_header
add_trailer
allow (ngx_http_access_module)
ancient_browser
ancient_browser_value
auth_basic
auth_basic_user_file
auth_delay
auth_jwt
auth_jwt_claim_set
auth_jwt_header_set
auth_jwt_key_cache
auth_jwt_key_request
auth_jwt_leeway
auth_jwt_type
auth_request
auth_request_set
break
charset
charset_map
charset_types
chunked_transfer_encoding
client_body_buffer_size
client_body_in_file_only
client_body_in_single_buffer
client_body_timeout
client_header_buffer_size
client_header_timeout
client_max_body_size
connection_pool_size
create_full_put_path
dav_access
dav_methods
debug_connection
default_type
deny (ngx_http_access_module)
empty_gif
error_log
error_page
expires
f4f
f4f_buffer_size
fastcgi_index
fastcgi_keep_conn
fastcgi_pass
flv
geo (ngx_http_geo_module)
geoip_city (ngx_http_geoip_module)
geoip_country (ngx_http_geoip_module)
geoip_org (ngx_http_geoip_module)
geoip_proxy
geoip_proxy_recursive
google_perftools_profiles
grpc_bind
grpc_buffer_size
grpc_connect_timeout
grpc_hide_header
grpc_ignore_headers
grpc_intercept_errors
grpc_next_upstream
grpc_next_upstream_timeout
grpc_next_upstream_tries
grpc_pass
grpc_pass_header
grpc_read_timeout
grpc_send_timeout
grpc_set_header
grpc_socket_keepalive
grpc_ssl_certificate
grpc_ssl_certificate_key
grpc_ssl_ciphers
grpc_ssl_conf_command
grpc_ssl_crl
grpc_ssl_name
grpc_ssl_password_file
grpc_ssl_protocols
grpc_ssl_server_name
grpc_ssl_session_reuse
grpc_ssl_trusted_certificate
grpc_ssl_verify
grpc_ssl_verify_depth
gunzip
gunzip_buffers
gzip
gzip_buffers
gzip_comp_level
gzip_disable
gzip_http_version
gzip_min_length
gzip_proxied
gzip_static
gzip_types
gzip_vary
hash (ngx_http_upstream_module)
health_check (ngx_http_upstream_hc_module)
hls
hls_buffers
hls_forward_args
hls_fragment
hls_mp4_buffer_size
hls_mp4_max_buffer_size
http
http2_body_preread_size
http2_chunk_size
http2_idle_timeout
http2_max_concurrent_pushes
http2_max_concurrent_streams
http2_max_field_size
http2_max_header_size
http2_max_requests
http2_push
http2_push_preload
http2_recv_buffer_size
http2_recv_timeout
if
if_modified_since
ignore_invalid_headers
image_filter
image_filter_buffer
image_filter_interlace
image_filter_jpeg_quality
image_filter_sharpen
image_filter_transparency
image_filter_webp_quality
include
internal
ip_hash
js_body_filter
js_content
js_fetch_ciphers (ngx_http_js_module)
js_fetch_protocols (ngx_http_js_module)
js_fetch_verify_depth (ngx_http_js_module)
js_header_filter
js_import (ngx_http_js_module)
js_include (ngx_http_js_module)
js_path (ngx_http_js_module)
js_set (ngx_http_js_module)
js_var (ngx_http_js_module)
keepalive
keepalive_disable
keepalive_requests (ngx_http_core_module)
keepalive_time (ngx_http_core_module)
keepalive_timeout (ngx_http_core_module)
keyval (ngx_http_keyval_module)
keyval_zone (ngx_http_keyval_module)
large_client_header_buffers
least_conn (ngx_http_upstream_module)
least_time (ngx_http_upstream_module)
limit_conn (ngx_http_limit_conn_module)
limit_conn_dry_run (ngx_http_limit_conn_module)
limit_conn_log_level (ngx_http_limit_conn_module)
limit_conn_status
limit_conn_zone (ngx_http_limit_conn_module)
limit_except
limit_rate
limit_rate_after
limit_req
limit_req_dry_run
limit_req_log_level
limit_req_status
limit_req_zone
limit_zone
lingering_close
lingering_time
lingering_timeout
listen (ngx_http_core_module)
load_module
location
log_format (ngx_http_log_module)
log_subrequest
map (ngx_http_map_module)
map_hash_bucket_size (ngx_http_map_module)
map_hash_max_size
match (ngx_http_upstream_hc_module)
max_ranges
merge_slashes
min_delete_depth
mirror
mirror_request_body
modern_browser
modern_browser_value
mp4
mp4_buffer_size
mp4_limit_rate
mp4_limit_rate_after
mp4_max_buffer_size
mp4_start_key_frame
msie_padding
msie_refresh
ntlm
open_log_file_cache (ngx_http_log_module)
override_charset
port_in_redirect
postpone_output
proxy_buffer_size (ngx_http_proxy_module)
proxy_buffering
proxy_buffers
proxy_busy_buffers_size
proxy_cache
proxy_cache_background_update
proxy_cache_bypass
proxy_cache_convert_head
proxy_cache_key
proxy_cache_lock
proxy_cache_lock_age
proxy_cache_lock_timeout
proxy_cache_max_range_offset
proxy_cache_methods
proxy_cache_min_uses
proxy_cache_path
proxy_cache_revalidate
proxy_cache_use_stale
proxy_cache_valid
proxy_connect_timeout (ngx_http_proxy_module)
proxy_cookie_domain
proxy_cookie_flags
proxy_cookie_path
proxy_force_ranges
proxy_headers_hash_bucket_size
proxy_headers_hash_max_size
proxy_hide_header
proxy_http_version
proxy_ignore_client_abort
proxy_ignore_headers
proxy_intercept_errors
proxy_limit_rate
proxy_max_temp_file_size
proxy_method
proxy_next_upstream (ngx_http_proxy_module)
proxy_next_upstream_timeout (ngx_http_proxy_module)
proxy_next_upstream_tries
proxy_no_cache
proxy_pass (ngx_http_proxy_module)
proxy_pass_header
proxy_pass_request_body
proxy_pass_request_headers
proxy_read_timeout
proxy_redirect
proxy_request_buffering
proxy_send_lowat
proxy_send_timeout
proxy_set_body
proxy_set_header
proxy_socket_keepalive (ngx_http_proxy_module)
proxy_ssl_certificate (ngx_http_proxy_module)
proxy_ssl_certificate_key (ngx_http_proxy_module)
proxy_ssl_ciphers (ngx_http_proxy_module)
proxy_ssl_conf_command (ngx_http_proxy_module)
proxy_ssl_name (ngx_http_proxy_module)
proxy_ssl_protocols (ngx_http_proxy_module)
proxy_ssl_server_name (ngx_http_proxy_module)
proxy_ssl_session_reuse (ngx_http_proxy_module)
proxy_ssl_verify (ngx_http_proxy_module)
proxy_ssl_verify_depth (ngx_http_proxy_module)
proxy_temp_file_write_size
queue
random (ngx_http_upstream_module)
random_index
read_ahead
real_ip_header
real_ip_recursive
recursive_error_pages
referer_hash_bucket_size
referer_hash_max_size
reset_timedout_connection
resolver (ngx_http_core_module)
resolver_timeout (ngx_http_core_module)
return (ngx_http_rewrite_module)
rewrite
rewrite_log
satisfy
secure_link
secure_link_md5
secure_link_secret
send_lowat
send_timeout
server (ngx_http_core_module)
server_name (ngx_http_core_module)
server_name_in_redirect
server_tokens
session_log
session_log_format
session_log_zone
set (ngx_http_rewrite_module)
set_real_ip_from (ngx_http_realip_module)
slice
source_charset spdy_chunk_size
spdy_headers_comp
split_clients (ngx_http_split_clients_module)
ssi
ssi_last_modified
ssi_min_file_chunk
ssi_silent_errors
ssi_types
ssi_value_length
ssl (ngx_http_ssl_module)
ssl_buffer_size
ssl_certificate (ngx_http_ssl_module)
ssl_certificate_key (ngx_http_ssl_module)
ssl_ciphers (ngx_http_ssl_module)
ssl_conf_command (ngx_http_ssl_module)
ssl_early_data
ssl_ecdh_curve (ngx_http_ssl_module)
ssl_ocsp
ssl_ocsp_cache
ssl_ocsp_responder
ssl_prefer_server_ciphers (ngx_http_ssl_module)
ssl_protocols (ngx_http_ssl_module)
ssl_reject_handshake
ssl_session_cache (ngx_http_ssl_module)
ssl_session_ticket_key (ngx_http_ssl_module)
ssl_session_tickets (ngx_http_ssl_module)
ssl_session_timeout (ngx_http_ssl_module)
ssl_stapling
ssl_stapling_responder
ssl_stapling_verify
ssl_verify_client (ngx_http_ssl_module)
ssl_verify_depth (ngx_http_ssl_module)
status
status_zone (ngx_http_api_module)
sticky
sticky_cookie_insert
stub_status
sub_filter
sub_filter_last_modified
sub_filter_once
sub_filter_types
subrequest_output_buffer_size
tcp_nodelay (ngx_http_core_module)
tcp_nopush
try_files
types
types_hash_bucket_size
types_hash_max_size
underscores_in_headers
uninitialized_variable_warn
upstream (ngx_http_upstream_module)
upstream_conf
userid
userid_domain
userid_expires
userid_flags
userid_mark
userid_name
userid_p3p
userid_path
userid_service
valid_referers
variables_hash_bucket_size (ngx_http_core_module)
variables_hash_max_size (ngx_http_core_module)
worker_aio_requests
worker_connections
xml_entities
xslt_last_modified
xslt_param
xslt_string_param
xslt_stylesheet
xslt_types
zone (ngx_http_upstream_module)

What’s Next

NJS Support.