This action supports managing the configuration and certificates of an NGINXaaS for Azure deployment in a GitHub repository. It enables continuous deployment through GitHub workflows to automatically update the NGINXaaS for Azure deployment when changes are made to the NGINX configuration files stored in the repository. Additionally, one can update NGINX certificates that are already present in Azure key vault.
This action leverages the Azure Login action for authenticating with Azure and performing update to an NGINXaaS for Azure deployment. Two different ways of authentication are supported:
- Service principal with secrets
- OpenID Connect (OIDC) with an Azure service principal using a Federated Identity Credential
# File: .github/workflows/nginxForAzureDeploy.yml
name: Sync the NGINX configuration from the GitHub repository to an NGINXaaS for Azure deployment
on:
push:
branches:
- main
paths:
- config/**
jobs:
Deploy-NGINX-Configuration:
runs-on: ubuntu-latest
steps:
- name: 'Checkout repository'
uses: actions/checkout@v2
- name: 'Run Azure Login using an Azure service principal with a secret'
uses: azure/login@v2
with:
creds: ${{ secrets.AZURE_CREDENTIALS }}
- name: 'Sync the NGINX configuration from the GitHub repository to the NGINXaaS for Azure deployment'
uses: nginxinc/[email protected]
with:
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
resource-group-name: ${{ secrets.AZURE_RESOURCE_GROUP_NAME }}
nginx-deployment-name: ${{ secrets.NGINX_DEPLOYMENT_NAME }}
nginx-config-directory-path: config/
nginx-root-config-file: nginx.conf
transformed-nginx-config-directory-path: /etc/nginx/
debug: false# File: .github/workflows/nginxForAzureDeploy.yml
name: Sync the NGINX configuration from the GitHub repository to an NGINXaaS for Azure deployment
on:
push:
branches:
- main
paths:
- config/**
permissions:
id-token: write
contents: read
jobs:
Deploy-NGINX-Configuration:
runs-on: ubuntu-latest
steps:
- name: 'Checkout repository'
uses: actions/checkout@v2
- name: 'Run Azure Login using OIDC'
uses: azure/login@v2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
- name: 'Sync the NGINX configuration from the GitHub repository to the NGINXaaS for Azure deployment'
uses: nginxinc/[email protected]
with:
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
resource-group-name: ${{ secrets.AZURE_RESOURCE_GROUP_NAME }}
nginx-deployment-name: ${{ secrets.NGINX_DEPLOYMENT_NAME }}
nginx-config-directory-path: config/
nginx-root-config-file: nginx.conf
transformed-nginx-config-directory-path: /etc/nginx/
debug: falseNote: The service principal being used for authenticating with Azure should have access to manage the NGINXaaS deployment. For simplicity, this guide assumes that the service principal has
Contributorrole to manage the deployment. Refer prerequisites for details.
To facilitate the migration of the existing NGINX configuration, NGINXaaS for Azure supports multiple-files configuration with each file uniquely identified by a file path, just like how NGINX configuration files are created and used in a self-hosting machine. An NGINX configuration file can include another file using the include directive. The file path used in an include directive can either be an absolute path or a relative path to the prefix path.
The following example shows two NGINX configuration files inside the /etc/nginx directory on disk are copied and stored in a GitHub repository under its config directory.
| File path on disk | File path in the repository |
|---|---|
| /etc/nginx/nginx.conf | /config/nginx.conf |
| /etc/nginx/sites-enabled/mysite.conf | /config/sites-enabled/mysite.conf |
To use this action to sync the configuration files from this example, the directory path relative to the GitHub repository root config/ is set to the action's input nginx-config-directory-path for the action to find and package the configuration files. The root file nginx.conf is set to the input nginx-root-config-file.
- name: 'Sync the NGINX configuration from the GitHub repository to the NGINXaaS for Azure deployment'
uses: nginxinc/[email protected]
with:
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
resource-group-name: ${{ secrets.AZURE_RESOURCE_GROUP_NAME }}
nginx-deployment-name: ${{ secrets.NGINX_DEPLOYMENT_NAME }}
nginx-config-directory-path: config/
nginx-root-config-file: nginx.conf
debug: falseBy default, the action uses a file's relative path to nginx-config-directory-path in the repository as the file path in the NGINXaaS for Azure deployment.
| File path on disk | File path in the repository | File path in the NGINXaaS for Azure deployment |
|---|---|---|
| /etc/nginx/nginx.conf | /config/nginx.conf | nginx.conf |
| /etc/nginx/sites-enabled/mysite.conf | /config/sites-enabled/mysite.conf | sites-enabled/mysite.conf |
The default file path handling works for the case of using relative paths in include directives, for example, if the root nginx.conf references mysite.conf using:
include sites-enabled/mysite.conf;
For the case of using absolute paths in include directives, for example, if the root nginx.conf references mysite.conf using:
include /etc/nginx/sites-enabled/mysite.conf;
The action supports an optional input transformed-nginx-config-directory-path to transform the absolute path of the configuration directory in the NGINXaaS for Azure deployment. The absolute configuration directory path on disk /etc/nginx/ can be set to transformed-nginx-config-directory-path as follows to ensure the configuration files using absolute paths in include directives work as expected in the NGINXaaS for Azure deployment.
- name: 'Sync the NGINX configuration from the Git repository to the NGINXaaS for Azure deployment'
uses: nginxinc/[email protected]
with:
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
resource-group-name: ${{ secrets.AZURE_RESOURCE_GROUP_NAME }}
nginx-deployment-name: ${{ secrets.NGINX_DEPLOYMENT_NAME }}
nginx-config-directory-path: config/
nginx-root-config-file: nginx.conf
transformed-nginx-config-directory-path: /etc/nginx/
debug: falseThe transformed paths of the two configuration files in the NGINXaaS for Azure deployment are summarized in the following table
| File path on disk | File path in the repository | File path in the NGINXaaS for Azure deployment |
|---|---|---|
| /etc/nginx/nginx.conf | /config/nginx.conf | /etc/nginx/nginx.conf |
| /etc/nginx/sites-enabled/mysite.conf | /config/sites-enabled/mysite.conf | /etc/nginx/sites-enabled/mysite.conf |
Since certificates are secrets, it is assumed they are stored in Azure key vault. One can provide multiple certificate entries to the github action as an array of JSON objects with keys:
certificateName- A unique name for the certificate entry
keyvaultSecret- The secret ID for the certificate on Azure key vault
certificateVirtualPath- This path must match one or more ssl_certificate directive file arguments in your Nginx configuration; and must be unique between certificates within the same deployment
keyVirtualPath- This path must match one or more ssl_certificate_key directive file arguments in your Nginx configuration; and must be unique between certificates within the same deployment
See the example below
- name: "Sync NGINX certificates to NGINXaaS for Azure"
uses: nginxinc/[email protected]
with:
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
resource-group-name: ${{ secrets.AZURE_RESOURCE_GROUP_NAME }}
nginx-deployment-name: ${{ secrets.NGINX_DEPLOYMENT_NAME }}
nginx-deployment-location: ${{ secrets.NGINX_DEPLOYMENT_LOCATION }}
nginx-certificates: '[{"certificateName": "$NGINX_CERT_NAME", "keyvaultSecret": "https://$NGINX_VAULT_NAME.vault.azure.net/secrets/$NGINX_CERT_NAME", "certificateVirtualPath": "/etc/nginx/ssl/my-cert.crt", "keyVirtualPath": "/etc/nginx/ssl/my-cert.key" } ]'
debug: false - name: "Sync NGINX configuration- multi file and certificate to NGINXaaS for Azure"
uses: nginxinc/[email protected]
with:
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
resource-group-name: ${{ secrets.AZURE_RESOURCE_GROUP_NAME }}
nginx-deployment-name: ${{ secrets.NGINX_DEPLOYMENT_NAME }}
nginx-deployment-location: ${{ secrets.NGINX_DEPLOYMENT_LOCATION }}
nginx-config-directory-path: config/
nginx-root-config-file: nginx.conf
transformed-nginx-config-directory-path: /etc/nginx/
nginx-certificates: '[{"certificateName": "$NGINX_CERT_NAME", "keyvaultSecret": "https://$NGINX_VAULT_NAME.vault.azure.net/secrets/$NGINX_CERT_NAME", "certificateVirtualPath": "/etc/nginx/ssl/my-cert.crt", "keyVirtualPath": "/etc/nginx/ssl/my-cert.key" } ]'
debug: false