Draft: Remove Azure pipeline task. Support protected files and remove need for rg permissions for service principal #39
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,32 +1,200 @@ | ||
| # NGINXaaS for Azure Deployment Action | ||
|
|
||
| This action supports managing the configuration of an [NGINXaaS for Azure](https://docs.nginx.com/nginxaas/azure/quickstart/overview/) 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. | ||
|
|
||
| ## Connecting to Azure | ||
|
|
||
| This action leverages the [Azure Login](https://github.com/marketplace/actions/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](https://docs.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#use-the-azure-login-action-with-a-service-principal-secret) | ||
| - [OpenID Connect](https://docs.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#use-the-azure-login-action-with-openid-connect) (OIDC) with an Azure service principal using a Federated Identity Credential | ||
|
|
||
| ### Sample workflow that authenticates with Azure using an Azure service principal with a secret | ||
|
|
||
| ```yaml | ||
| # 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/nginx-for-azure-deploy-action/github-action@v0.4.0 | ||
| 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 | ||
| ``` | ||
|
|
||
| ### Sample workflow that authenticates with Azure using OIDC | ||
|
|
||
| ```yaml | ||
| # 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/nginx-for-azure-deploy-action/github-action@v0.4.0 | ||
| 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 | ||
| ``` | ||
|
|
||
| > **Note:** | ||
| 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 `Contributor` role to manage the deployment. Refer [prerequisites](https://docs.nginx.com/nginxaas/azure/getting-started/prerequisites/) for details. | ||
|
|
||
| ## Handling NGINX configuration file paths | ||
|
|
||
| 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](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/). The file path used in an `include` directive can either be an absolute path or a relative path to the [prefix path](https://www.nginx.com/resources/wiki/start/topics/tutorials/installoptions/). | ||
|
|
||
| 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`. | ||
|
|
||
| ```yaml | ||
| - name: 'Sync the NGINX configuration from the GitHub repository to the NGINXaaS for Azure deployment' | ||
| uses: nginxinc/nginx-for-azure-deploy-action/github-action@v0.4.0 | ||
| 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: false | ||
| ``` | ||
|
|
||
| By 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. | ||
|
|
||
| ```yaml | ||
| - name: 'Sync the NGINX configuration from the Git repository to the NGINXaaS for Azure deployment' | ||
| uses: nginxinc/nginx-for-azure-deploy-action/github-action@v0.4.0 | ||
| 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 | ||
| ``` | ||
| The 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 | | ||
|
|
||
| ## Handling NGINX certificates | ||
|
|
||
| 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 | ||
|
|
||
| ```yaml | ||
| - name: "Sync NGINX certificates to NGINXaaS for Azure" | ||
| uses: nginxinc/nginx-for-azure-deploy-action/github-action@v0.4.0 | ||
| 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 | ||
| ``` | ||
|
|
||
| ## Handling NGINX configuration and certificates | ||
|
|
||
| ```yaml | ||
| - name: "Sync NGINX configuration- multi file and certificate to NGINXaaS for Azure" | ||
| uses: nginxinc/nginx-for-azure-deploy-action/github-action@v0.4.0 | ||
| 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 | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -24,14 +24,19 @@ inputs: | |
| default: "nginx.conf" | ||
| transformed-nginx-config-directory-path: | ||
| description: > | ||
| 'The absolute directory path in the NGINXaaS for Azure deployment where your configuration files will be placed. | ||
| All files found in the nginx-config-directory-path will be copied to this location in the deployment. | ||
| For example, use "/etc/nginx/" to match the standard NGINX directory structure on Azure. | ||
|
There was a problem hiding this comment.
|
||
| If your NGINX configuration files use absolute paths in "include" directives, this setting ensures those paths are correctly mapped in the deployment by prepending the specified directory.' | ||
| required: false | ||
| default: "" | ||
| nginx-certificates: | ||
| description: 'An array of JSON objects each with keys nginx_cert_name, keyvault_secret, certificate_virtual_path and key_virtual_path. Example: [{"certificateName": "server1", "keyvaultSecret": "https://...", "certificateVirtualPath": "/etc/ssl/certs/server1.crt", "keyVirtualPath": "/etc/ssl/certs/server1.key" }, {"name": "server2", "keyvaultSecret": "https://...", "certificateVirtualPath": "/etc/ssl/certs/server2.crt", "keyVirtualPath": "/etc/ssl/certs/server2.key" }] ' | ||
| required: false | ||
| protected-files: | ||
|
There was a problem hiding this comment. From an Actions perspective, this is a new feature in that it was not there earlier on and now we have added support for handling protected files via the action:
|
||
| description: "Comma-separated list of file paths relative to nginx-config-directory-path that should be marked as protected. Example: 'ssl/private.key,conf.d/secrets.conf'" | ||
| required: false | ||
| default: "" | ||
| debug: | ||
| description: "Enable/Disable debug output." | ||
| required: false | ||
|
|
@@ -40,10 +45,10 @@ runs: | |
| using: "composite" | ||
| steps: | ||
| - name: "Synchronize NGINX certificate(s) from the Git repository to an NGINXaaS for Azure deployment" | ||
| run: ${{github.action_path}}/src/deploy-certificate.sh --subscription-id=${{ inputs.subscription-id }} --resource-group-name=${{ inputs.resource-group-name }} --nginx-deployment-name=${{ inputs.nginx-deployment-name }} --nginx-resource-location=${{ inputs.nginx-deployment-location }} --certificates=${{ toJSON(inputs.nginx-certificates) }} --debug=${{ inputs.debug }} | ||
|
There was a problem hiding this comment. https://github.com/kuthiala/nginx-for-azure-deploy-action/blob/f9dbec3c93f58bd3634762d4b2de1f2f0193a4d7/src/deploy-certificate.sh The input handling here needs to be fixed. I am okay if you want to preserve both but in that separate MR, I think you can safely consider refactoring configs and certs both as separate commits. Folks may have a preference in splitting that up further as the changeset will be a bit large but 👍 |
||
| if: ${{ inputs.nginx-deployment-location != '' && inputs.nginx-certificates != '' }} | ||
| shell: bash | ||
| - name: "Synchronize NGINX configuration from the Git repository to an NGINXaaS for Azure deployment" | ||
| run: ${{github.action_path}}/src/deploy-config.sh --subscription-id=${{ inputs.subscription-id }} --resource-group-name=${{ inputs.resource-group-name }} --nginx-deployment-name=${{ inputs.nginx-deployment-name }} --nginx-config-directory-path=${{ inputs.nginx-config-directory-path }} --nginx-root-config-file=${{ inputs.nginx-root-config-file }} --transformed-nginx-config-directory-path=${{ inputs.transformed-nginx-config-directory-path }} --protected-files=${{ inputs.protected-files }} --debug=${{ inputs.debug }} | ||
|
There was a problem hiding this comment. here's a quick suggestion: I agree with what you are doing here but:
I'd recommend the following:
|
||
| if: ${{ inputs.nginx-config-directory-path != '' }} | ||
| shell: bash | ||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a move in the right direction to come inline with Github Actions documentation 👍