PO Box support in Azure - Deployment playbook

Overview

This playbook provides step-by-step instructions for setting up an Azure deployment for the PO Box. It includes creating an App Registration, setting up a storage account and file share, and deploying an Azure Container Instance (ACI) with necessary configurations.

Prerequisites

Azure CLI installed and configured on your machine.
Azure subscription and resource group inside the subscription
Necessary permissions in the Azure subscription to create resources.
Zilla token provided by Customer Success team
Azure container registry login server and image name provided by Customer Success team

Deployment Options

Zilla provides the following mechanisms to allow you to deploy PO BOX to your Azure environment

Option 1: Using Azure portal

This option provides a step by step guide on how to use the Azure Portal to set up the resources required to deploy PO BOX to your environment

Step 1: Create App Registration

Login to Azure portal with admin user and click on create a resource and search of App Registration -> New registration

Fill the above details and click Register

Store Application (client) ID for later use. You will also need to share this Application (client) ID with Customer Success team of Zilla so that they can allow the app to pull the image automatically later.

Step 2: Add Client Secret

Navigate to Manage-> Certificates & secrets and click on New client secret
Add Description and set Expires and click on Add

Keep clientSecret secret secure, as it will be used to authenticate the application.

You will not be able to retrieve this secret again after this step.Step 3: Create Storage Account

Step 3: Create Storage Account

Create an Azure Storage Account to store the Zilla token provided by CS team

Login to Azure portal with admin user and click on create a resource and search of `Storage accounts`and click on Create

Fill the required details and click on Review + create

Review the details and click on Create

Once deployment is done. Click on Go to reosurce

Step 4: Create File Share

Navigate to Data storage → File shares

Click on + File share to add new file share

Add New file share name and details and click on Review + create

Step 5: Create Zilla Directory and Upload Token

Once create, navigate to Browse → Add dirctory named Zilla

Create two directories named pobox-config and pobox-output under Zilla and upload Zilla API key provided by Customer Support team inside pobox-config folder

Step 6: Create Azure Container Instance

Above created app registration should be authenticated as per step 4 https://zilla.atlassian.net/wiki/spaces/ZILLA/pages/3225681948/PoBox+ZINC+support+in+Azure+-+Azure+Container+Registry+ACR+Setup+Guide#Step-4%3A-Obtain-Access-Token and given AcrPull access to repository by Customer Success team

Deploy an Azure Container Instance and mount the file share created earlier.

Login to Azure portal with admin user and click on create a resource and search of Container Instance and click on Create

Fill the details as above and select Image source as Other registry

Image: zillapobox.azurecr.io/zinc:latest

Image registry login server: zillapobox.azurecr.io

Image registry user name : Application Id noted in step 1 https://zilla.atlassian.net/wiki/spaces/ZILLA/pages/edit-v2/3225354263#Step-1%3A-Create-App-Registration.1

Image registry password : Secret noted in step 2 https://zilla.atlassian.net/wiki/spaces/ZILLA/pages/edit-v2/3225354263#Step-2%3A-Add-Client-Secret.1

Navigate to Advance tab and add environment variables as below

                        ZILLA_URL='https://app.zillasecurity.com' \
                        TENANT_DOMAIN='<tenant domain name>' \ #tenant domain
                        POLLING_INTERVAL='30' \
                        SEND_LOGS_TO_BACKEND='true' \
                        USE_FILE_SYSTEM='true' \
                        SECRETS_DIRECTORY_PATH='/mnt/Zilla/pobox-config' \
                        STORAGE_DIRECTORY_PATH='/mnt/Zilla/pobox-output' \

Click on Review + Create

Step 7: Create Logic app to restart container

Create a logic app to restart a container every 24 hours to pull latest zinc image

Login to Azure portal with admin user and click on create a resource and search of Logic Apps and click on Add

Select hosting option and proceed

Fill the details and click Review and create

Once deployed click on Go to resource

Navigate to Development Tools → Logic app designer → Add a trigger and search for Recurrence
Click on Trigger

Fill the details as per daily ACI restart time

Add and action against the trigger

Search for Container instance and select action Start containers in a container group

Sign in and fill the details of container instance

Save the trigger and action.
Run history can be monitored to check the logs

Option 2: Execute CLI commands

This option requires you to execute the following commands (in order) to set up the resources required to deploy PO BOX to your environment

Step 1: Create App Registration

Create a new App Registration in your Azure Active Directory. This will enable authentication for your application. This app will be given acrPull role to pull latest ZINC image

az ad app create --display-name "zilla-pobox-<tenant name>" \
    --sign-in-audience "AzureADMultipleOrgs" \
    --web-redirect-uris "https://app.zillasecurity.com"
    --query "appId" --output tsv

Replace <tenant-name> with your actual tenant name or domain.

Store Application (client) ID for later use. You will also need to share this Application (client) ID with Customer Success team of Zilla so that they can allow the app to pull the image automatically later.

Step 2: Add Client Secret

Generate a client secret (password) for the App Registration. This secret will be used for authentication.

clientSecret=$(az ad app credential reset --id "$appId" \
    --append --display-name "password" \
    --query "password" --output tsv)
echo "Client Secret: $clientSecret"

Keep clientSecret secret secure, as it will be used to authenticate the application.

You will not be able to retrieve this secret again after this step.

Step 3: Create Storage Account

Create an Azure Storage Account to store the Zilla token provided by CS team

az storage account create \ --name zillapoboxstorage \ --resource-group <resource group name> \ --location eastus \ --sku Standard_GRS \ --kind StorageV2 \ --default-action Allow

Replace <resource group name> with your actual resource group name
Make sure it exists or create it if necessary.

Step 4: Create File Share

Create a file share within the storage account to store the Zilla token.

— Create fileShare 
az storage share create \
    --name zilla-pobox-volume \
    --account-name zillapoboxstorage

File Share Name: This name will be used to mount the file share later.

Step 5: Create Zilla Directory and Upload Token

Create a directory in the file share and upload the Zilla token provided by the Customer Success team.

# Create the Zilla directory
az storage directory create \
    --name "Zilla" \
    --share-name "zilla-pobox-volume" \
    --account-name "zillapoboxstorage"

# Create the pobox-config directory inside Zilla
az storage directory create \
    --name "Zilla/pobox-config" \
    --share-name "zilla-pobox-volume" \
    --account-name "zillapoboxstorage"

# Create the pobox-output directory inside Zilla
az storage directory create \
    --name "Zilla/pobox-ouput" \
    --share-name "zilla-pobox-volume" \
    --account-name "zillapoboxstorage"

Step 6: Create Azure Container Instance

Above created app registration should be authenticated as per step 4 https://zilla.atlassian.net/wiki/spaces/ZILLA/pages/3225681948/PoBox+ZINC+support+in+Azure+-+Azure+Container+Registry+ACR+Setup+Guide#Step-4%3A-Obtain-Access-Token and given AcrPull access to repository by CS team

Deploy an Azure Container Instance and mount the file share created earlier.

  --resource-group test_resource_group \
  --name zillapobox \
  --image <Image name provided by zilla> \ 
  --restart-policy OnFailure \
  --environment-variables ZILLA_URL='https://app.zillasecurity.com' \
                        TENANT_DOMAIN='<tenant domain name>' \ #tenant domain
                        POLLING_INTERVAL='30' \
                        SEND_LOGS_TO_BACKEND='true' \
                        USE_FILE_SYSTEM='true' \
                        SECRETS_DIRECTORY_PATH='/mnt/Zilla/pobox-config' \
                        STORAGE_DIRECTORY_PATH='/mnt/Zilla/pobox-output' \
  --registry-login-server <registry name provided by zilla> \ 
  --registry-username <App registration Id> \ 
  --registry-password <App registration password> \ 
  --azure-file-volume-share-name zilla-pobox-volume \
  --azure-file-volume-account-name zillapoboxstorage \
  --azure-file-volume-account-key <Access key for storage account >
  --azure-file-volume-mount-path /mnt/Zilla

registry-username: Use the App registration Id from Step 1.

registry-password: Use the App registration password from Step 2.

Step 7: Create Logic app to restart container

This step needs to be done manually. Refer https://zilla.atlassian.net/wiki/spaces/ZILLA/pages/edit-v2/3225354263#Step-6%3A-Create-Logic-app-to-restart-container

Option 3: Execute Power-shell script

This option allows you to use the Powershell scripts supplied by Zilla to quickly set up the resources required to deploy PO BOX to your environment

Prerequisite: Powershell must be installed in the instance

Powershell must be installed in your instance to execute Powershell scripts. You can download it from the official Microsoft site.

Step 1: Login to Azure

Login to Azure using command: az login

Step 2: Select the subscription

You will be prompted to select the subscription in which want to create resources. Here is a sample screenshot

Step 3: Run createAppRegistration.ps1 (attached)

Before running the createAppRegistration.ps1 script, ensure the config_createAappRegistration.json (attached) file is set up with the necessary values. This file should include any parameters required for the App Registration process.

{
    "resourceGroupName": "<Resource group name>",
    "storageAccountName": "zillapoboxstorage",
    "fileShareName": "zilla-pobox-volume",
    "appRegistrationName": "zillapobox-<Renant name>",
    "location": "<Location>"  
}

Open PowerShell and navigate to the directory where the createAppRegistration.ps1 script is located.
Execute the script by running the following command: .\createAppRegistration.ps1

The script will create an App Registration in Azure and mount the necessary storage.

Once the createAppRegistration.ps1 script has completed, you will need to update the config_aci.json file (attached) to include the app registration Id and secret generated in this previous step.

Also, the Customer Success team needs to Authorise the application created above so that it can access Zilla’s Azure Container Registry for which they will need the app registration id

Refer to readme.txt file under the folder azure share by Customer Success team and execute Powershell script as guided

Step 4: Run createACI.ps1 (attached)

Before running the createACI.ps1 script, ensure the config_createACI.json (attached) file is set up with the necessary values.

{
    "tenantName": "<Tenant name>",
    "resourceGroupName": "<Resource group name>",
    "storageAccountName": "zillapoboxstorage",
    "fileShareName": "zilla-pobox-volume",
    "containerInstanceName": "zillapobox",
    "imageName": "<Registry name provided by CS team>/zinc",
    "registryLoginServer": "<Registry name provided by CS team>",
    "appRegistrationName": "zillapobox-<Tenant name>",
    "appId": "<App Id from above step>",
    "clientSecret": "<secret from above step>",
    "location": "<Location>",
    "subscriptionId": "<Subscription Id>"
}

Open PowerShell and navigate to the directory where the createACI.ps1 script is located.
Execute the script by running the following command: .\createACI.ps1

After following the above steps, you should have successfully created an Azure App Registration and an Azure Container Instance.

Make sure to check the Azure portal for confirmation of above created resources.

Step 5: Create Logic app to restart container

This step needs to be done manually. Refer https://zilla.atlassian.net/wiki/spaces/ZILLA/pages/edit-v2/3225354263#Step-6%3A-Create-Logic-app-to-restart-container

PO Box support in Azure - Deployment playbook

Overview

Prerequisites

Deployment Options

Option 1: Using Azure portal

Step 1: Create App Registration

Step 2: Add Client Secret

Step 3: Create Storage Account

Step 4: Create File Share

Step 5: Create Zilla Directory and Upload Token

Step 6: Create Azure Container Instance

Step 7: Create Logic app to restart container

Option 2: Execute CLI commands

Step 1: Create App Registration

Step 2: Add Client Secret

Step 3: Create Storage Account

Step 4: Create File Share

Step 5: Create Zilla Directory and Upload Token

Step 6: Create Azure Container Instance

Step 7: Create Logic app to restart container

Option 3: Execute Power-shell script

Prerequisite: Powershell must be installed in the instance

Step 1: Login to Azure

Step 2: Select the subscription

Step 3: Run createAppRegistration.ps1 (attached)

Step 4: Run createACI.ps1 (attached)

Step 5: Create Logic app to restart container

Attachments