helm-azure-tpl

Helm plugin for Azure template processing

Plugin for Helm to inject Azure information (subscriptions, resources, msgraph) and Azure KeyVault secrets. Also works as standalone executable outside of Helm.

Installation

requires sed and curl for installation

#################################################
# Github workflows

# Installation of latest version
- uses: webdevops/setup-helm-azure-tpl@v1

# Installation of specific version
- uses: webdevops/setup-helm-azure-tpl@v1
  with:
    version: 0.63.9

#################################################
# Helm 4.x

# Installation of latest version
helm plugin install "https://github.com/webdevops/helm-azure-tpl/releases/latest/download/azure-tpl-cli.tgz" --verify=false
helm plugin install "https://github.com/webdevops/helm-azure-tpl/releases/latest/download/azure-tpl-getter.tgz" --verify=false

# Installation of specific version
helm plugin install "https://github.com/webdevops/helm-azure-tpl/releases/download/0.63.9/azure-tpl-cli.tgz" --verify=false
helm plugin install "https://github.com/webdevops/helm-azure-tpl/releases/download/0.63.9/azure-tpl-getter.tgz" --verify=false

# Update
# please do uninstall and install again, for now

# Uninstall
helm plugin uninstall azure-tpl-cli
helm plugin uninstall azure-tpl-getter

#################################################
# Helm 3.x (legacy support)

# Installation of latest version
helm plugin install https://github.com/webdevops/helm-azure-tpl.git

# Installation of specific version
helm plugin install https://github.com/webdevops/helm-azure-tpl.git --version=0.63.9

# Update to latest version
helm plugin update azure-tpl

# Uninstall
helm plugin uninstall azure-tpl

Usage

Helm (downloader mode)

you can use helm in "downloader" mode to process files eg:

[!CAUTION] DO NOT use azure-tpl functions in values.yaml files as these files are read again by helm without azure-tpl processing! Use different file names and paths.

helm upgrade foobar123 -f azuretpl://config/values.yaml .

for additional values files for azure-tpl you can use environment variabels:

AZURETPL_VALUES=./path/to/azuretpl.yaml helm upgrade foobar123 -f azuretpl://config/values.yaml .

File processing (only Helm v3)

helm azure-tpl uses AzureCLI authentication to talk to Azure

Process one file and overwrite it:

helm azure-tpl apply template.tpl

Process one file and saves generated content as another file:

helm azure-tpl apply template.tpl:template.yaml

Processes all .tpl files and saves them as .yaml files

helm azure-tpl apply --target.fileext=.yaml *.tpl

General usage:

Usage:
  helm-azure-tpl [OPTIONS] command [files...]

Application Options:
      --log.level=[trace|debug|info|warning|error] Log level (default: info) [$AZURETPL_LOG_LEVEL]
      --log.format=[logfmt|json]                   Log format (default: logfmt) [$AZURETPL_LOG_FORMAT]
      --log.source=[|short|file|full]              Show source for every log message (useful for debugging and bug reports)
                                                   [$AZURETPL_LOG_SOURCE]
      --log.color=[|auto|yes|no]                   Enable color for logs [$AZURETPL_LOG_COLOR]
      --log.time                                   Show log time [$AZURETPL_LOG_TIME]
      --dry-run                                    dry run, do not write any files [$AZURETPL_DRY_RUN]
      --debug                                      debug run, print generated content to stdout (WARNING: can expose secrets!)
                                                   [$HELMHELM_DEBUG_DEBUG]
      --stdout                                     Print parsed content to stdout instead of file (logs will be written to stderr)
                                                   [$AZURETPL_STDOUT]
      --template.basepath=                         sets custom base path (if empty, base path is set by base directory for each file. will
                                                   be appended to all root paths inside templates) [$AZURETPL_TEMPLATE_BASEPATH]
      --target.prefix=                             adds this value as prefix to filename on save (not used if targetfile is specified in
                                                   argument) [$AZURETPL_TARGET_PREFIX]
      --target.suffix=                             adds this value as suffix to filename on save (not used if targetfile is specified in
                                                   argument) [$AZURETPL_TARGET_SUFFIX]
      --target.fileext=                            replaces file extension (or adds if empty) with this value (eg. '.yaml')
                                                   [$AZURETPL_TARGET_FILEEXT]
      --keyvault.expiry.warningduration=           warn before soon expiring Azure KeyVault entries (default: 168h)
                                                   [$AZURETPL_KEYVAULT_EXPIRY_WARNING_DURATION]
      --keyvault.expiry.ignore                     ignore expiry date of Azure KeyVault entries and don't fail'
                                                   [$AZURETPL_KEYVAULT_EXPIRY_IGNORE]
      --values=                                    path to yaml files for .Values [$AZURETPL_VALUES]
      --set-json=                                  set JSON values on the command line (can specify multiple or separate values with
                                                   commas: key1=jsonval1,key2=jsonval2)
      --set=                                       set values on the command line (can specify multiple or separate values with commas:
                                                   key1=val1,key2=val2)
      --set-string=                                set STRING values on the command line (can specify multiple or separate values with
                                                   commas: key1=val1,key2=val2)
      --set-file=                                  set values from respective files specified via the command line (can specify multiple or
                                                   separate values with commas: key1=path1,key2=path2)

Help Options:
  -h, --help                                       Show this help message

Arguments:
  command:                                         specifies what to do (help, version, lint, apply)
  files:                                           list of files to process (will overwrite files, different target file can be specified
                                                   as sourcefile:targetfile)

Build-in objects

Template functions

Azure template functions

[!NOTE] Functions can also be used starting with azure prefix instead of az

Azure KeyVault functions

response format:

{
  "attributes": {
    "created": 1620236104,
    "enabled": true,
    "exp": 1724593377,
    "nbf": 1661362977,
    "recoverableDays": 0,
    "recoveryLevel": "Purgeable",
    "updated": 1661449616
  },
  "contentType": "...",
  "id": "https://xxx.vault.azure.net/secrets/xxx/xxxxxxxxxx",
  "managed": false,
  "name": "xxx",
  "tags": {},
  "value": "...",
  "version": "xxxxxxxxxx"
}

Azure ManagedCluster functions

Azure Redis cache functions

Azure StorageAccount functions

Azure EventHub functions

Azure AppConfig functions

response format:

{
  "contentType": "...",
  "eTag": "...",
  "isReadOnly": false,
  "key":" ...",
  "label": null,
  "lastModified": null,
  "syncToken": "...",
  "tags": {},
  "value": "..."
}

Azure RBAC functions

Azure ResourceGraph functions

[!NOTE] ManagementGroups must be defined with their resource ID /providers/microsoft.management/managementgroups/{MANAGEMENT_GROUP_ID}. Subscriptions must either be defined by the subscription id or their resource id /subscriptions/{SUBSCRIPTION_ID}.

MsGraph (AzureAD) functions

[!NOTE] Functions can also be used starting with msGraph prefix instead of mg

Time template functions

Misc template functions

{{
azResource
"/subscriptions/d86bcf13-ddf7-45ea-82f1-6f656767a318/resourcegroups/k8s/providers/Microsoft.ContainerService/managedClusters/mblaschke"
"2022-01-01"
| jsonPath "$.properties.aadProfile"
| toYaml
}}

Helm template functions (borrowed from helm project)

Sprig template functions

Sprig template functions are also available

Examples

## Fetch resource as object and convert to yaml
{{ azResource
"/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourcegroups/example-rg/providers/Microsoft.ContainerService/managedClusters/k8scluster"
"2022-01-01"
| toYaml
}}

## Fetch resource as object, select .properties.aadProfile via jsonPath and convert to yaml
{{ azResource
"/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourcegroups/example-rg/providers/Microsoft.ContainerService/managedClusters/k8scluster"
"2022-01-01"
| jsonPath "$.properties.aadProfile"
| toYaml
}}

## Fetches all resources from subscription
{{ (azResourceList "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx") | toYaml }}

## Fetches all virtualNetwork resources from subscription
{{ (azResourceList "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx" "resourceType eq 'Microsoft.Network/virtualNetworks'") | toYaml }}

## Fetches all resources from resourceGroup
{{ (azResourceList "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourcegroups/example-rg") | toYaml }}

## Fetch Azure VirtualNetwork address prefixes
{{ azVirtualNetworkAddressPrefixes
"/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourcegroups/example-rg/providers/Microsoft.Network/virtualNetworks/k8s-vnet"
}}xxx/resourcegroups/example-rg/providers/Microsoft.Network/virtualNetworks/k8s-vnet"
"default2"
| join ","
}}

## Fetch first storageaccount key
{{ (index (azStorageAccountAccessKeys "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/example-rg/providers/Microsoft.Storage/storageAccounts/foobar") 0).value }}

## fetch blob from storageaccount container
{{ azureStorageAccountContainerBlob "https://foobar.blob.core.windows.net/examplecontainer/file.json" }}

## Fetch secret value from Azure KeyVault (using only name; only AzurePublicCloud, AzureChinaCloud and AzureGovernmentCloud)
{{ (azKeyVaultSecret "examplevault" "secretname").value }}
{{ (azKeyVaultSecret "examplevault" "secretname").attributes.exp | fromUnixtime | toRFC3339 }}

## Fetch secret value from Azure KeyVault (using full url)
{{ (azKeyVaultSecret "https://examplevault.vault.azure.net/" "secretname").value }}

## Fetch current environmentName
{{ azAccountInfo.environmentName }}

## Fetch current tenantId
{{ azAccountInfo.tenantId }}

## Fetch current selected subscription displayName
{{ azSubscription.displayName }}

## Fetch RoleDefinition id for "owner" role
{{ (azRoleDefinition "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx" "Owner").name }}

## Executes ResourceGraph query and returns result as yaml
{{ azResourceGraphQuery "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx" `resources | where resourceGroup contains "xxxx"` | toYaml }}
or
{{ `resources | where resourceGroup contains "xxxx"` | azResourceGraphQuery "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"   | toYaml }}

## Executes ResourceGraph query for Management Group and returns result as yaml
{{ azResourceGraphQuery "/providers/microsoft.management/managementgroups/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx" `resources | where resourceGroup contains "xxxx"` | toYaml }}
or
{{ `resources | where resourceGroup contains "xxxx"` | azResourceGraphQuery "/providers/microsoft.management/managementgroups/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"   | toYaml }}

## Fetch kubeconfig from AKS managed cluster
{{ (index (azManagedClusterUserCredentials "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourcegroups/example-rg/providers/Microsoft.ContainerService/managedClusters/foobar").kubeconfigs 0).value | b64dec }}

Experimental features

PS: some code is borrowed from Helm