Upload using the Azure CLI

Overview

An NGINX configuration can be applied to the deployment using 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

• Confirm that you meet the NGINXaaS Prerequisites.

• Install Azure CLI version 2.59.0 or greater: Azure CLI Installation.

• Log into your Azure account through the CLI: Azure CLI Authentication.

• Install the NGINXaaS for Azure extension:

  Note:
  The extension will automatically install the first time you run an az nginx command.

  az extension add --name nginx
  

See Also:
See the NGINXaaS for Azure CLI reference for a complete list of NGINXaaS CLI commands.

• 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.

Create a configuration

Create a configuration for a deployment using a gzipped archive. The archive should contain the NGINX configuration files and any other files required by the configuration, for example:

$ 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

To create a new NGINX configuration, use the az nginx deployment configuration create command:

az nginx deployment configuration create --configuration-name
                                         --deployment-name
                                         --resource-group
                                         [--files]
                                         [--location]
                                         [--no-wait {0, 1, f, false, n, no, t, true, y, yes}]
                                         [--package]
                                         [--protected-files]
                                         [--root-file]

Validate your configuration

You can use the analyze command to validate your configuration before submitting it to the deployment:

az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \
   --resource-group $RESOURCE_GROUP --root-file /etc/nginx/nginx.conf \
   --name default --files "$FILES_CONTENT"

Examples

• Create a single file configuration:

  az nginx deployment configuration create --name default \
     --deployment-name myDeployment --resource-group myResourceGroup \
     --root-file /etc/nginx/nginx.conf \
     --files "[{content:'aHR0cCB7CiAgICB1cHN0cmVhbSBhcHAgewogICAgICAgIHpvbmUgYXBw \
     IDY0azsKICAgICAgICBsZWFzdF9jb25uOwogICAgICAgIHNlcnZlciAxMC4wLjEuNDo4 \
     MDAwOwogICAgfQoKICAgIHNlcnZlciB7CiAgICAgICAgbGlzdGVuIDgwOwogICAgICAg \
     IHNlcnZlcl9uYW1lICouZXhhbXBsZS5jb207CgogICAgICAgIGxvY2F0aW9uIC8gewog \
     ICAgICAgICAgICBwcm94eV9zZXRfaGVhZGVyIEhvc3QgJGhvc3Q7CiAgICAgICAgICAg \
     IHByb3h5X3NldF9oZWFkZXIgWC1SZWFsLUlQICRyZW1vdGVfYWRkcjsKICAgICAgICAg \
     ICAgcHJveHlfc2V0X2hlYWRlciBYLVByb3h5LUFwcCBhcHA7CiAgICAgICAgICAgIHBy \
     b3h5X3NldF9oZWFkZXIgR2l0aHViLVJ1bi1JZCAwMDAwMDA7CiAgICAgICAgICAgIHBy \
     b3h5X2J1ZmZlcmluZyBvbjsKICAgICAgICAgICAgcHJveHlfYnVmZmVyX3NpemUgNGs7 \
     CiAgICAgICAgICAgIHByb3h5X2J1ZmZlcnMgOCA4azsKICAgICAgICAgICAgcHJveHlf \
     cmVhZF90aW1lb3V0IDYwczsKICAgICAgICAgICAgcHJveHlfcGFzcyBodHRwOi8vYXBw \
     OwogICAgICAgICAgICBoZWFsdGhfY2hlY2s7CiAgICAgICAgfQogICAgICAgIAogICAg \
     fQp9',virtual-path:'/etc/nginx/nginx.conf'}]"
  

• Create a multiple file configuration:

  az nginx deployment configuration create --name default \
     --deployment-name myDeployment --resource-group myResourceGroup \
     --root-file /etc/nginx/nginx.conf \
     --files "[{'content':'aHR0cCB7CiAgICB1cHN0cmVhbSBhcHAgewogICAgICAgIHpvbmUg \
     YXBwIDY0azsKICAgICAgICBsZWFzdF9jb25uOwogICAgICAgIHNlcnZlciAxMC4wLjEu \
     NDo4MDAwOwogICAgfQoKICAgIHNlcnZlciB7CiAgICAgICAgbGlzdGVuIDgwOwogICAg \
     ICAgIHNlcnZlcl9uYW1lICouZXhhbXBsZS5jb207CgogICAgICAgIGxvY2F0aW9uIC8g \
     ewogICAgICAgICAgICBpbmNsdWRlIC9ldGMvbmdpbngvY29uZi5kL3Byb3h5LmNvbmY7 \
     CiAgICAgICAgICAgIHByb3h5X3Bhc3MgaHR0cDovL2FwcDsKICAgICAgICAgICAgaGVh \
     bHRoX2NoZWNrOwogICAgICAgIH0KICAgICAgICAKICAgIH0KfQ==', \
     'virtual-path':'/etc/nginx/nginx.conf'}, \
     {'content':'cHJveHlfc2V0X2hlYWRlciBIb3N0ICRob3N0Owpwcm94eV9zZXRfaGVhZGVy \
     IFgtUmVhbC1JUCAkcmVtb3RlX2FkZHI7CnByb3h5X3NldF9oZWFkZXIgWC1Qcm94eS1B \
     cHAgYXBwOwpwcm94eV9zZXRfaGVhZGVyIEdpdGh1Yi1SdW4tSWQgMDAwMDAwOwpwcm94 \
     eV9idWZmZXJpbmcgb247CnByb3h5X2J1ZmZlcl9zaXplIDRrOwpwcm94eV9idWZmZXJz \
     IDggOGs7CnByb3h5X3JlYWRfdGltZW91dCA2MHM7', \
     'virtual-path':'/etc/nginx/conf.d/proxy.conf'}]"
  

• Upload package with config files:

  az nginx deployment configuration create --deployment-name myDeployment \
     --resource-group myResourceGroup --root-file nginx.conf --name default \
     --package data='H4sIAAAAAAAAA+3VbWvbMBAHcL/Op7hCoTCIbckPCU0olG3QvVoog21QMCK+1qGyJGRlpBv57pPXbsla1wkdZS3c70UMdxfxP2wn6mqhVuFcq8vg2cTeKMt+Xb37V56zLGBpwvOYpVkyCmLGspwHED9fpI1l44QFCKzWrm9uV/+Vqpwz8GMA3tI0zqKoQRgzZHfF1net8K6Yp9eTP3WJonGFf3bUptag/YYWWBzGIQvT47G/wb1d1tvlt931w4C8KyB/UsCkt5v2drNHAyZdAZMnBcx7u6Pe7vh3wMHWwCaZXDQOFYwf3KRCiRrhTYgrURuJ/iei3sqt58IttIJo66hWiZdiKV3hbgyCw5WLKlfLyV8zFt3SKuBxDEfTg3cf3376OnsP7dzJtOInZyilhs/ayvJgGvnChTraHLDuyHD/eW0Zq1c3RYOuqFCUfuUz3Tg4rPznpH/wy/AchRx+mMGhxVo7LERZ2p1fmrWl4akxt29K17wRTQPtC3ccRR1D/ijpqmJe4fx698L8ZS3M91mY/8vCyctaONln4WT/hdeD9eB//xkQQgghhBBCCCGEEEIIIYQQQggh5FX6CfCArk8AKAAA'
  

• Multiple file configuration with protected files:

  az nginx deployment configuration create --name default \
     --deployment-name 0102242023test --resource-group azclitest-geo \
     --root-file /etc/nginx/nginx.conf \
     --files "[{'content':'aHR0cCB7CiAgICB1cHN0cmVhbSBhcHAgewogICAgICAgIHpvbmUg \
     YXBwIDY0azsKICAgICAgICBsZWFzdF9jb25uOwogICAgICAgIHNlcnZlciAxMC4wLjEu \
     NDo4MDAwOwogICAgfQoKICAgIHNlcnZlciB7CiAgICAgICAgbGlzdGVuIDgwOwogICAg \
     ICAgIHNlcnZlcl9uYW1lICouZXhhbXBsZS5jb207CgogICAgICAgIGxvY2F0aW9uIC8g \
     ewogICAgICAgICAgICBpbmNsdWRlIC9ldGMvbmdpbngvY29uZi5kL3Byb3h5LmNvbmY7 \
     CiAgICAgICAgICAgIHByb3h5X3Bhc3MgaHR0cDovL2FwcDsKICAgICAgICAgICAgaGVh \
     bHRoX2NoZWNrOwogICAgICAgIH0KICAgICAgICAKICAgIH0KfQ==', \
     'virtual-path':'/etc/nginx/nginx.conf'}, \
     {'content':'cHJveHlfc2V0X2hlYWRlciBIb3N0ICRob3N0Owpwcm94eV9zZXRfaGVhZGVy \
     IFgtUmVhbC1JUCAkcmVtb3RlX2FkZHI7CnByb3h5X3NldF9oZWFkZXIgWC1Qcm94eS1B \
     cHAgYXBwOwpwcm94eV9zZXRfaGVhZGVyIEdpdGh1Yi1SdW4tSWQgMDAwMDAwOwpwcm94 \
     eV9idWZmZXJpbmcgb247CnByb3h5X2J1ZmZlcl9zaXplIDRrOwpwcm94eV9idWZmZXJz \
     IDggOGs7CnByb3h5X3JlYWRfdGltZW91dCA2MHM7', \
     'virtual-path':'/etc/nginx/conf.d/proxy.conf'}]" \
     --protected-files "[{'content':'aHR0cCB7CiAgICB1cHN0cmVhbSBhcHAgewogICAgICAgIHpvbmUg \
     YXBwIDY0azsKICAgICAgICBsZWFzdF9jb25uOwogICAgICAgIHNlcnZlciAxMC4wLjEu \
     NDo4MDAwOwogICAgfQoKICAgIHNlcnZlciB7CiAgICAgICAgbGlzdGVuIDgwOwogICAg \
     ICAgIHNlcnZlcl9uYW1lICouZXhhbXBsZS5jb207CgogICAgICAgIGxvY2F0aW9uIC8g \
     ewogICAgICAgICAgICBpbmNsdWRlIC9ldGMvbmdpbngvY29uZi5kL3Byb3h5LmNvbmY7 \
     CiAgICAgICAgICAgIHByb3h5X3Bhc3MgaHR0cDovL2FwcDsKICAgICAgICAgICAgaGVh \
     bHRoX2NoZWNrOwogICAgICAgIH0KICAgICAgICAKICAgIH0KfQ==', \
     'virtual-path':'/etc/nginx/nginxprot.conf'}, \
     {'content':'cHJveHlfc2V0X2hlYWRlciBIb3N0ICRob3N0Owpwcm94eV9zZXRfaGVhZGVy \
     IFgtUmVhbC1JUCAkcmVtb3RlX2FkZHI7CnByb3h5X3NldF9oZWFkZXIgWC1Qcm94eS1B \
     cHAgYXBwOwpwcm94eV9zZXRfaGVhZGVyIEdpdGh1Yi1SdW4tSWQgMDAwMDAwOwpwcm94 \
     eV9idWZmZXJpbmcgb247CnByb3h5X2J1ZmZlcl9zaXplIDRrOwpwcm94eV9idWZmZXJz \
     IDggOGs7CnByb3h5X3JlYWRfdGltZW91dCA2MHM7', \
     'virtual-path':'/etc/nginx/conf.d/proxyprot.conf'}]"
  

See the Azure CLI Configuration Create Documentation for more details on the available parameters.

Update a configuration

Update a configuration for a deployment using a gzipped archive.

Use the az nginx deployment configuration update command to update an existing NGINX configuration:

az nginx deployment configuration update [--add]
                                         [--configuration-name]
                                         [--deployment-name]
                                         [--files]
                                         [--force-string {0, 1, f, false, n, no, t, true, y, yes}]
                                         [--ids]
                                         [--location]
                                         [--no-wait {0, 1, f, false, n, no, t, true, y, yes}]
                                         [--remove]
                                         [--resource-group]
                                         [--root-file]
                                         [--set]
                                         [--subscription]

Example

• Update content of the first file in a configuration:

  az nginx deployment configuration update --name default \
     --deployment-name myDeployment --resource-group myResourceGroup \
     --files [0].content="aHR0cCB7CiAgICB1cHN0cmVhbSBhcHAgewogICAgICAgIHpvbmUg \
     YXBwIDY0azsKICAgICAgICBsZWFzdF9jb25uOwogICAgICAgIHNlcnZlciAxMC4wLjEu \
     NDo4MDAwOwogICAgfQoKICAgIHNlcnZlciB7CiAgICAgICAgbGlzdGVuIDgwOwogICAg \
     ICAgIHNlcnZlcl9uYW1lICouZXhhbXBsZS5jb207CgogICAgICAgIGxvY2F0aW9uIC8g \
     ewogICAgICAgICAgICBwcm94eV9zZXRfaGVhZGVyIEhvc3QgJGhvc3Q7CiAgICAgICAg \
     ICAgIHByb3h5X3NldF9oZWFkZXIgWC1SZWFsLUlQICRyZW1vdGVfYWRkcjsKICAgICAg \
     ICAgICAgcHJveHlfc2V0X2hlYWRlciBYLVByb3h5LUFwcCBhcHA7CiAgICAgICAgICAg \
     IHByb3h5X3NldF9oZWFkZXIgR2l0aHViLVJ1bi1JZCAwMDAwMDA7CiAgICAgICAgICAg \
     IHByb3h5X2J1ZmZlcmluZyBvbjsKICAgICAgICAgICAgcHJveHlfYnVmZmVyX3NpemUg \
     NGs7CiAgICAgICAgICAgIHByb3h5X2J1ZmZlcnMgOCA4azsKICAgICAgICAgICAgcHJv \
     eHlfcmVhZF90aW1lb3V0IDYwczsKICAgICAgICAgICAgcHJveHlfcGFzcyBodHRwOi8v \
     YXBwOwogICAgICAgICAgICBoZWFsdGhfY2hlY2s7CiAgICAgICAgfQogICAgICAgIAog \
     ICAgfQp9"
  

See the Azure CLI Configuration Update Documentation for more details on the available parameters.