Deploying with Microsoft Azure

This document shows you how to deploy the WhatsApp Business Platform API on Microsoft Azure.

Get Started

Before you start you will need to:

• Set up an Azure Account
• Create an SSH Key Pair
• Install Azure CLI
• Install Terraform
• Install Kubernetes (kubectl) and create a kubeconfig file in ~/.kube/config if the file doesn't exist.

Deployment

1. From your development machine, in the terminal application, login to Azure using az login. Successful login should return a result similar to the following:

   
   {
       "cloudName": "AzureCloud",
       "homeTenantId": "home-Tenant-Id",
       "id": "Subscription-Id",
       "isDefault": true,
       "managedByTenants": [],
       "name": "Subscription-Name",
       "state": "Enabled",
       "tenantId": "Tenant-Id",
       "user": {
         "name": "your-username@domain.com",
         "type": "user"
       }
   }
   
           

2. Download all Azure Terraform files from the deployment templates GitHub repository and put them in a directory, e.g.: ~/biz/azure.
3. Configure parameters in the _variables.tf_ file by updating the default value of each parameter. See Deployment Parameters.
4. Based on the configured throughput value, map it to its corresponding database machine type by referring to the map_db_class variable in variables.tf. For instance, if you configure the throughput value to be 120, it should map to the DB machine type Standard_E8as_v4.
5. Based on the DB machine type identified in step 4, comment / uncomment the corresponding innodb_buffer_pool_size, innodb_buffer_pool_instances, query_cache_size values in the scripts/my.cnf file. For instance, if you configure the throughput value to be 120, its DB machine type is Standard_E8as_v4, then you should comment out the default settings (based on Standard_E8as_v4) and uncomment the settings for Standard_E8as_v4 as shown in the following script code:

   # current value is based on Standard_E16as_v4 (16vCPU,128GB)
   # innodb_buffer_pool_size      = 103079215104
   # innodb_buffer_pool_instances = 32
   # query_cache_size             = 8589934592
   
   # Standard_E8as_v4 (8vCPU,64GB)
   innodb_buffer_pool_size        = 51539607552
   innodb_buffer_pool_instances   = 16
   query_cache_size               = 4294967296
           
           

6. After all configurations are set. From the root directory created in step 2, for instance: ~/biz/azure, run terraform init to install external dependencies required by the template. Optionally, you can also run terraform validate to validate if the template syntax is correct.
7. In the root directory, run terraform plan to generate a plan and check if all required variables are properly set. Make sure there is no error shown in this step.
8. In the root directory, run terraform apply and you need to approve the deployment by typing yes upon prompt. Alternatively, you could run terraform apply -auto-approve to skip interactive approval of the plan before applying.

     Do you want to perform these actions?
     Terraform will perform the actions described above.
     Only 'yes' will be accepted to approve.
   
     Enter a value: yes
   
           
           

9. All services will be deployed automatically.

Deployment Parameters

General Configuration

Throughput Configuration

WhatsApp Business API Configuration

Database Configuration

Grafana Configuration

Output after Deployment

Upon successful creation of stack, the following parameters are displayed:

• web_server_name: The host name to access the WA Business API endpoints. The API endpoint root URL can be accessed through https://<web_server_name>.
• monitor_server_name: The host name to access the Grafana dashboard. The Grafana dashboard can be accessed through http://<monitor_server_name>:3000.
• number_of_shards: Number of shards to configure for the WhatsApp Business API.

WhatsApp Business Platform API Client Configuration

After the WhatsApp Business Platform API client is successfully deployed, it needs to be configured to bring it into operation.

Step 1: Phone Registration

For more in-depth information about phone number registration, see Phone Number guide.

Download the base64-encoded certificate from your WhatsApp account in the Facebook Business Manager under the Phone Numbers tab of the WhatsApp Manager. Once you have the correct phone number selected and have the base64-encoded certificate, you need to register the WhatsApp Business API client through the account node. For more information, see the Registration documentation.

Step 2: Set Shards

You need to use the shards endpoint to increase the number of active Coreapp instances to achieve the desired throughput. The number of shards can be found in the Output section of the stack.

Step 3: Update Application Settings

The configuration of WhatsApp Business Platform API web callbacks and other parameters is described in the Application Settings documentation. To achieve stable throughput, the following application settings are recommended.

{
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 3000,
            "callback_persist": true,
            "db_garbagecollector_enable": false, # change this to true when there are no ongoing messaging campaigns
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 900000,
            "media": {
                "auto_download": [
                    "document",
                    "image",
                    "video",
                    "voice",
                    "sticker",
                    "audio"
                ]
            },
            "notify_user_change_number": true,
            "pass_through": false,
            "sent_status": true,
            "show_security_notifications": false,
            "skip_referral_media_download": false,
            "unhealthy_interval": 30,
            "wa_id": "12245552741",
            "webhooks": {
                "max_concurrent_requests": 24,
                "message": {
                    "delivered": true,
                    "read": true,
                    "sent": true
                },
                "url": "<YOUR_WEBHOOK_SERVER_URL>"
            }
        }
    },
    "meta": {
        "api_status": "stable",
        "version": "2.41.3"
    }
}
    
    

You will need to restart all CoreApp pods after configuring the highlighted parameters above for them to take effect. You can do this, use the following command:

kubectl rollout restart deployment coreapp

Wait until all CoreApp pods are back in RUNNING status.

Step 4: Validation of the Setup

Once the configuration and registration steps are successful, a message can be sent and received to validate the basic functionality of WhatsApp Business API client. For more information, see Messages.

Upon successful receipt of a message, the WhatsApp Business API client will POST the message status/details to the Webhook configured in Step 3.

If your message was successfully received, you have successfully completed the configuration set up. For more information on the available API endpoints, see the Reference documentation.

Updating

If you need to upgrade to a newer API version or update the template with any adjusted parameters, follow these steps:

1. Update the API version as followed in the variables.tf file and run terraform validate to validate if the template syntax is correct.

   variable "api-version" {
     default = "v2.43.1"
   }
       

2. From the root directory, run terraform apply and all changes are automatically updated.

Destroying

You can use terraform destroy to destroy all resources created by the Terraform plan. At the prompt, enter yes.

  Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes
    

Troubleshooting

Terraform preserves already-deployed services even if the plan fails halfway. After you make a change in the same plan, run terraform apply to resume from the failed resources.

1. How do I connect to the Kubernetes cluster that I created?

1. Go to the Azure Portal - Resource groups console: Resource groups - Microsoft Azure
2. Select the resource group with the name:
   rg-<name_prefix>-<owner>
3. Select the Kubernetes service from the Resources tab with the name:
   aks-<name_prefix>-<owner>-xxxx
4. Click the Connect button, the right pane will slide out with instructions on how to connect to the Kubernetes cluster.
   

   Connect to Kubernetes cluster
5. Once you are connected to the cluster, you can run kubectl commands to manage the cluster. For instance:
   1. To list all pods: kubectl get pod
   2. To get a pod log: kubectl logs <pod_name>
   3. To get the log of a pod container: kubectl logs <pod_name> -c <container_name>

2. How do I resolve the "Cannot create more than 1 network watchers for this subscription in this region" error?

Reason for Error: This error is generated because your Azure subscription does not allow multiple network watchers to be created. This error is thrown when you already have a network watcher in your Azure subscription.

Mitigation:

1. Comment out the following section in the following sample network.tf file, so that no new network watcher is created.

# resource "azurerm_network_watcher" "waNet" {
#   name                = "production-nwwatcher"
#   location            = azurerm_resource_group.waNet.location
#   resource_group_name = azurerm_resource_group.waNet.name
# }      
      

2. Then run terraform apply.
3. The error should resolve and the deployment will proceed.

3. Issue: Machine Overview Grafana dashboard shows No Data for all charts.

Reason: This is a known issue and further work is required to fix this.

Mitigation: You can check machine specific metrics from the Azure portal instead. To check CoreApp / Web / DB machine metrics:

1. Go to the Azure Portal - Virtual machine scale set console.
2. Filter the virtual machine scale sets (VMSS) by the resource group name:
   rg-<name_prefix>-<owner>-xxxx-aks-node
   
3. Select the VMSS that you want to check machine metrics of. For example, coreapp machine metrics can be viewed by selecting the VMSS with the name aks-coreapp-xxx-vmss and switch to the Monitoring tab.
   
4. To view DB machine metrics, select the VMSS with the name aks-db-xxx-vmss.
   

To check media file share metrics:

1. Go to the Azure Portal - Storage accounts console.
2. Select the storage account filtered by the resource group name:
   rg-<name_prefix>-<owner>-xxxx-aks-node
   
3. Switch to the Monitoring tab: