Azure Functions Hosting
Overview
The Azure provider supports deploying policies into Azure Functions to run them inexpensively in your subscription. Currently, you can deploy timer triggered functions (azure-periodic) or Event Grid triggered functions (azure-event-grid).
The first deployment to an Azure Function will create the following resources in your Azure subscription:
Resource Group: Holds all the resources
Azure Storage: Serves as the backend data store for the Functions
Application Insights: Provides logging and metric tracking for the Functions
App Service Plan: A Linux based consumption plan using the V2 runtime to support Python Functions
Function App: The Function that executes the given policy
Successive policy deployments will only create a new Function App for the policy, because the rest of the infrastructure can be shared.
Note: Ensure you are using at least the minimum actively supported version of Python.
Azure Modes
Custodian can run in numerous modes. The default mode is pull.
- pull:
Default mode, which executes the policy locally to where Custodian is run.
properties: type: enum: - pull required: - type
- azure-periodic:
Creates a timer triggered Azure Function to run the policy in Custodian. The timing is executed based on a user defined cron interval , such as every 15 minutes or every hour on weekdays.
properties: execution-options: type: object provision-options: additionalProperties: false properties: appInsights: oneOf: - type: string - additionalProperties: false properties: location: type: string name: type: string resourceGroupName: type: string type: object identity: additionalProperties: false properties: id: type: string type: enum: - SystemAssigned - UserAssigned - Embedded type: object servicePlan: oneOf: - type: string - additionalProperties: false properties: autoScale: additionalProperties: false properties: defaultCapacity: type: string enabled: type: boolean maxCapacity: type: string minCapacity: type: string type: object location: type: string name: type: string resourceGroupName: type: string skuName: type: string skuTier: type: string type: object storageAccount: oneOf: - type: string - additionalProperties: false properties: location: type: string name: type: string resourceGroupName: type: string type: object type: object schedule: pattern: ^\s?([0-5]?[0-9]|\,|(\*\/)|\-)+ (\*|[0-5]?[0-9]|\,|\/|\-)+ (\*|[0-9]|(1[0-9])|(2[0-3])|\,|\/|\-)+ (\*|[1-9]|([1-2][0-9])|(3[0-1])|\,|\*\/|\-)+ ([Jj](an|anuary)|[Ff](eb|ebruary)|[Mm](ar|arch)|[Aa](pr|pril)|[Mm]ay|[Jj](un|une)|[Jj](ul|uly)|[Aa](ug|ugust)|[Ss](ep|eptember)|[Oo](ct|ctober)|[Nn](ov|ovember)|[Dd](ec|ecember)|\,|\*\/|[1-9]|(1[0-2])|\*)+ ([Mm](on|onday)|[Tt](u|ue|ues|uesday)|[Ww](ed|ednesday)|[Tt](hu|hursday)|[Ff](ri|riday)|[Ss](at|aturday)|[Ss](un|unday)|[0-6]|\,|\*|\-)+\s?$ type: string type: enum: - azure-periodic required: - type
- azure-event-grid:
Creates Event Grid triggered Azure Functions to run the policy in Custodian. This mode allows you to apply your policies when events occur. See Azure Event Grid for more details.
properties: events: items: oneOf: - type: string - properties: event: type: string resourceProvider: type: string required: - resourceProvider - event type: object maxItems: 5 type: array execution-options: type: object provision-options: additionalProperties: false properties: appInsights: oneOf: - type: string - additionalProperties: false properties: location: type: string name: type: string resourceGroupName: type: string type: object identity: additionalProperties: false properties: id: type: string type: enum: - SystemAssigned - UserAssigned - Embedded type: object servicePlan: oneOf: - type: string - additionalProperties: false properties: autoScale: additionalProperties: false properties: defaultCapacity: type: string enabled: type: boolean maxCapacity: type: string minCapacity: type: string type: object location: type: string name: type: string resourceGroupName: type: string skuName: type: string skuTier: type: string type: object storageAccount: oneOf: - type: string - additionalProperties: false properties: location: type: string name: type: string resourceGroupName: type: string type: object type: object type: enum: - azure-event-grid required: - events - type
Provision Options
The following Azure resources are required to support an Azure Function. If they do not exist, Custodian will create them as it creates the Azure Function for the policy.
Storage (shared across functions)
Application Insights (shared across functions)
Application Service Plan (shared across functions with optional default auto scale rule)
Application Service (per function)
Functions can be deployed in either a dedicated Application Service Plan (Basic, Standard or Premium) or in a Consumption plan. More details on the different hosting models offered by Azure Functions can be found in the Azure Functions documentation. By default, Custodian policies are run using the Consumption hosting model. (i.e. skuTier=dynamic)
Note: Linux Consumption plans are not available in all regions. You will get an error when applying the policy if you use an unsupported location.
You can enable auto scaling for your dedicated App Service Plan. The default auto scaling allows you to specify the minimum and maximum number of VMs underlying the Functions. The App Service Plan will be scaled up if the average RAM usage was more than 80% in the past 10 minutes. This option is disabled by default.
The same shared resources from above can be used to service multiple Functions. This is done by specifying the resources names in the policy deployment definition, or by using the default names every time. When deploying a new policy using existing infrastructure, only the new Function will be created.
The default set of parameters for Azure Storage, Application Insights, and Application
Service Plan will deploy the function successfully. To customize the deployment, the defaults
can be overwritten by setting the provision-options object on mode. The following keys are
supported, with their default values shown:
- servicePlan
name (default: cloud-custodian)
location (default: East US)
resourceGroupName (default: cloud-custodian)
skuTier (default: Dynamic) # consumption
skuName (default: Y1)
- autoScale (optional):
enabled (default: False)
minCapacity (default: 1)
maxCapacity (default: 1)
defaultCapacity (default: 1)
- storageAccount
name (default: custodian + sha256(resourceGroupName+subscription_id)[:8])
location (default: servicePlan location)
resourceGroupName (default: servicePlan resource group)
- appInsights
name (default: servicePlan resource group)
location (default: servicePlan location)
resourceGroupName (default: servicePlan name)
The location allows you to choose the region to deploy the resource group and resources that will be provisioned. Application Insights has 20 available locations and thus may not always be in the same region as the other resources. For details, see Application Insights availability by region.
If the specified resources already exist in the subscription, discovered by resource group and resource name, Custodian will not change the existing resource regardless of the parameters set by the policy. If a resource does not exist, it will be provisioned using the provided configuration.
You can provide resource IDs to specify existing infrastructure, rather than matching resource group and resource name. Please see the third example below for the correct formatting. Custodian verifies that the resources defined by the given IDs exist before creating the Function. If the resource is missing, Custodian will return an error.
The following example shows how to deploy a policy to a timer-triggered Function that runs every hour. The defaults are accepted for Storage and Application Insights, and custom values are provided for the Service Plan. This policy deploys a dedicated Basic B1 App Service Plan with the default auto scaling turned on. Based on the RAM consumption in the underlying VMs, the App Service Plan will be backed by 1-3 VMs.
policies:
- name: stopped-vm
mode:
type: azure-periodic
schedule: '0 0 * * * *'
provision-options:
servicePlan:
name: functionshost
skuTier: Basic
skuName: B1
autoScale:
enabled: true
minCapacity: "1"
maxCapacity: "3"
defaultCapacity: "1"
resource: azure.vm
filters:
- type: instance-view
key: statuses[].code
op: not-in
value_type: swap
value: "PowerState/running"
The following example shows how to set the name, size and location of all three components of the supporting infrastructure:
policies:
- name: stopped-vm
mode:
type: azure-periodic
schedule: '0 0 * * * *'
provision-options:
servicePlan:
name: functionshost
location: East US
skuTier: Standard
skuName: S1
appInsights:
location: East US
storageAccount:
name: sampleaccount
location: East US
resource: azure.vm
filters:
- type: instance-view
key: statuses[].code
op: not-in
value_type: swap
value: "PowerState/running"
The final example shows how to use resource ids to specify existing infrastructure:
policies:
- name: stopped-vm
mode:
type: azure-periodic
schedule: '0 0 * * * *'
provision-options:
servicePlan: /subscriptions/<subscription_id>/resourceGroups/cloud-custodian/providers/Microsoft.Web/serverFarms/existingResource
appInsights: /subscriptions/<subscription_id>/resourceGroups/cloud-custodian/providers/microsoft.insights/components/existingResource
storageAccount: /subscriptions/<subscription_id>/resourceGroups/cloud-custodian/providers/Microsoft.Storage/storageAccounts/existingResource
resource: azure.vm
filters:
- type: instance-view
key: statuses[].code
op: not-in
value_type: swap
value: "PowerState/running"
Authentication Options
Custodian function policies support three different authentications modes.
User Assigned Identities
Managed System Identities
Service Principal Credentials (embedded)
Its highly recommended to utilize User Assigned Identities, like Managed System Identities they provide for dynamic automatically rotated credentials, but they also allow for simplicity of managing role assignments to a smaller population of IAM resources, instead of one per policy function.
policies:
- name: stopped-vm
mode:
type: azure-periodic
schedule: '0 0 * * * *'
provision-options:
identity:
type: UserAssigned
id: my-custodian-identity
resource: azure.vm
The identity id can be provided as the user assigned identity’s name or the id, it will be resolved and verified as the policy is provisioned.
Using a Managed System Identity results in the creation of an identity per policy function, which then needs subsequent role assignments before the policy will be able to successfully execute.
policies:
- name: stopped-vm
mode:
type: azure-periodic
schedule: '0 0 * * * *'
provision-options:
identity:
type: SystemAssigned
resource: azure.vm
Execution Options
Execution options are not required, but allow you to override defaults that would normally be provided on the command line in non-serverless scenarios.
Common properties are:
output_dir
cache_period
dryrun
metrics
The default output directory for an Azure Function is /tmp/<random_uuid>. The following
example shows how to save the output of the policy to an Azure Storage Account instead of in
the default Function location.
policies:
- name: stopped-vm
mode:
type: azure-periodic
schedule: '0 0 * * * *'
provision-options:
servicePlan:
name: functionshost
execution-options:
output_dir: azure://yourstorageaccount.blob.core.windows.net/custodian
metrics: azure://<resource_group_name>/<app_insights_name>
resource: azure.vm
filters:
- type: instance-view
key: statuses[].code
op: not-in
value_type: swap
value: "PowerState/running"
More details on Blob Storage output can be found at Writing Custodian Output to Azure Blob Storage
Event Grid Functions
Currently, Event Grid Functions are only supported at the subscription level. You can set the function to be triggered by write and/or delete events. When an Event Grid Function is deployed, Custodian creates an Event Grid Subscription to trigger the new Function when any event occurs in the Subscription. Once triggered, Custodian only executes the policy if the event was caused by the resource provider and event type specified in the policy.
In order to subscribe to an event, you need to provide the resource provider and the action, or provide the string of one of the shortcuts. For a list of all of the resource providers and their actions, see Azure Resource Manager resource provider options.
The following example shows an Event Grid Function that runs when a value is written to Key Vault.
policies:
- name: tag-key-vault-creator
resource: azure.keyvault
mode:
type: azure-event-grid
events:
- resourceProvider: Microsoft.KeyVault/vaults
event: write
filters:
- "tag:CreatorEmail": null
actions:
- type: auto-tag-user
tag: CreatorEmail
Management Groups Support
You can deploy Azure Functions targeting all subscriptions that are part of a specified Management Group.
The following variable allows you to specify Management Group name:
AZURE_FUNCTION_MANAGEMENT_GROUP_NAME
It can be used with Function specific Service Principal credentials described in the previous section. The Management Group environment variable has the highest priority, so AZURE_FUNCTION_SUBSCRIPTION_ID will be ignored.
Timer triggered functions
When the Management Groups option is used with periodic mode, Cloud Custodian deploys a single Azure Function App with multiple Azure Functions following the single-subscription-per-function rule.
Event triggered functions
When the Management Groups option is used with event mode, Cloud Custodian deploys a single Azure Function. It creates an Event Grid subscription for each Subscription in the Management Group delivering events to a single Azure Storage Queue.
Permissions
The Service Principal used at the Functions runtime is required to have an appropriate level of permissions in each target subscription.
The Service Principal used to provision Azure Functions is required to have an appropriate level of permissions to access Management Groups. If the Service Principal doesn’t have MG Reader permissions in any child subscription, these subscriptions won’t be a part of the Cloud Custodian Azure Function deployment process.