# Upload using the Azure CLI ## Overview F5 NGINXaaS for Azure (NGINXaaS) configurations can be managed using the Azure CLI. This document outlines common Azure CLI workflows to validate, create, and update NGINX configurations. ## Prerequisites - Install [Azure CLI with NGINXaaS extension](/nginxaas-azure/client-tools/cli.md) - 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 To create a new NGINX configuration, use the `az nginx deployment configuration create` command: There are two supported ways to upload your configuration: 1. **Plain file upload** — Upload one or more configuration files directly using the `--files` parameter. 1. **Tarball upload** — Package your configuration files into a `.tar.gz` archive and upload it using the `--package` parameter. Both methods are valid and can be used depending on how your configuration is structured. ```shell 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:
#### Validate plain files If you are uploading individual configuration files, you can pass them as base64-encoded content through the `--files` parameter: ```shell az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ --resource-group $RESOURCE_GROUP --root-file /etc/nginx/nginx.conf \ --name default --files "$FILES_CONTENT" ``` #### Validate a tarball package If you are using a `.tar.gz` archive, encode it and pass it through the `--package` parameter: ```shell TAR_DATA=$(base64 -i nginx.tar.gz) az nginx deployment configuration analyze --deployment-name myDeployment \ --resource-group myResourceGroup --root-file nginx.conf \ --name default --package data="$TAR_DATA" ```
### Upload a configuration #### Upload plain files The following examples show how to upload plain configuration files directly to your deployment: - Create a single file configuration: ```shell 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: ```shell 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'}]" ``` - Multiple file configuration with protected files: ```shell 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'}]" \ --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'}]" ``` #### Upload a tarball package You can bundle your configuration files into a `.tar.gz` archive and upload it as a single package. - **Upload config using a package:** Create a gzip compress tarball package. **Note:** The package must start at the `etc` level. Your tarball must contain the `etc/nginx/` directory structure. ```shell $ tar -czf nginx.tar.gz etc $ tar -tzf nginx.tar.gz etc/ etc/nginx/ etc/nginx/nginx.conf etc/nginx/njs.js etc/nginx/servers/ etc/nginx/servers/server1.conf etc/nginx/servers/server2.conf ``` Where `etc` is a directory with the following structure: ```shell $ tree etc etc └── nginx ├── nginx.conf ├── njs.js └── servers ├── server1.conf └── server2.conf 2 directories, 4 files ``` Encode your tar.gz file and create your NGINXaaS configuration: ```shell TAR_DATA=$(base64 -i nginx.tar.gz) az nginx deployment configuration create --deployment-name myDeployment \ --resource-group myResourceGroup --root-file /etc/nginx/nginx.conf --name default \ --package data="$TAR_DATA" ``` - **Upload config using a package with protected files:** Create a gzip compress tarball package: ```shell $ tar -czf nginx-config.tgz etc $ tar -tzf nginx-config.tgz etc/ etc/nginx/ etc/nginx/nginx.conf etc/nginx/conf.d/ etc/nginx/conf.d/proxy.conf etc/nginx/conf.d/proxyprot.conf etc/nginx/conf.d/nginxprot.conf ``` Where `etc` is a directory with the following structure: ```shell $ tree etc etc └── nginx ├── conf.d │ ├── nginxprot.conf │ ├── proxy.conf │ └── proxyprot.conf └── nginx.conf 2 directories, 4 files ``` Encode your tarball file and create your NGINXaaS configuration with protected files: ```shell TAR_DATA=$(base64 -i nginx-config.tgz) az nginx deployment configuration create \ --deployment-name myDeployment \ --resource-group myResourceGroup \ --root-file /etc/nginx/nginx.conf \ --package data="${TAR_DATA}" protected-files="['/etc/nginx/conf.d/proxyprot.conf','/etc/nginx/conf.d/nginxprot.conf']" \ --name default ``` See the [Azure CLI Configuration Create Documentation](https://learn.microsoft.com/en-us/cli/azure/nginx/deployment/configuration?view=azure-cli-latest#az-nginx-deployment-configuration-create) 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: ```shell 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: ```shell 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](https://learn.microsoft.com/en-us/cli/azure/nginx/deployment/configuration?view=azure-cli-latest#az-nginx-deployment-configuration-update) for more details on the available parameters. **Note:** See the [NGINX connfiguration overview](overview.md) topic to learn more about: - [NGINX configuration automation workflows](overview.md#nginx-configuration-automation-workflows) - [NGINX filesystem restrictions](overview.md#nginx-filesystem-restrictions) - [Disallowed configuration directives](overview.md#disallowed-configuration-directives) - [Directives that cannot be overridden](overview.md#directives-that-cannot-be-overridden) - [Configuration directives list](overview.md#configuration-directives-list)