The Ops Community ⚙️: Alexandre Nédélec

Create an Azure-Ready GitHub Repository using Pulumi

Alexandre Nédélec — Sun, 30 Jul 2023 00:00:00 +0000

Creating an application and deploying it to Azure is not complicated. You write some code on your machine, do some clicks in the Azure portal, or run some Azure CLI commands from your terminal and that's it: your application is up and running in Azure.

Yet, that's not real life, at least not what you will do when working on a professional project. Your code needs to be versioned and pushed to a location where your colleagues can work on it. The provisioning of Azure resources and deployment to Azure should be carried out using a properly configured CI/CD pipeline with the necessary authorization.

That's a lot of work that would need to be done each time you start a new project. So let's automate that using Pulumi to simplify the process and create an "Azure-Ready GitHub repository".

What's an Azure-Ready GitHub repository?

"Azure-Ready GitHub repository" is not an official term or concept, it's just something I've come up with to describe a Github repository that has everything correctly configured to provision Azure resources or deploy applications to Azure from a GitHub Actions CI/CD pipeline.

The GitHub part

On the GitHub side, to have an Azure-Ready GitHub repository, we need:

the GitHub repository itself (already initialized with a main branch)
the necessary GitHub Actions variables/secrets to authenticate to the correct Azure subscription
a YAML file located in the .github/workflows/ folder that contains the CI/CD pipeline that provisions resources in Azure

The Azure part

On the Azure side, to have an Azure-Ready GitHub repository, we need:

the existing Azure subscription to which resources are deployed
an identity in the Azure Active Directory of the desired tenant so that the GitHub CI/CD pipeline can authenticate to Azure and interact with the subscription

ℹ️ Azure Active Directory has recently been renamed Microsoft Entra ID (as of the time of writing). However, I will continue to use the term Azure Active Directory throughout the rest of the article. Please note that both terms refer to the same service.

The problem with secret credentials

People tend to use secret credentials to authenticate their pipeline to Azure and that's not the best thing to do.

From a security standpoint, depending on secrets always poses a security risk. Even if in that case the secret would be safely stored in a GitHub secret and never exposed publicly, it's still better to avoid secrets when we can.

🔐 That's precisely why when hosting applications in Azure, we use Managed Identities and IAM roles instead of relying on secrets. Yet, here we can't use Managed Identities for GitHub Actions pipelines.

From a practical standpoint, depending on secrets can quickly become problematic as they expire and thus require rotation. Of course, you can set up alerting or automate secret rotation but that's something you would prefer to avoid managing.

💬 I recently encountered a situation in Azure DevOps where a deployment failed due to the expiration of an Azure AD Application secret associated with the Service Connection used in the pipeline, and we were not alerted about it. That's the kind of scenario that can easily happen with secrets and that you want to avoid.

So what can we do about that?

👉 We can stop using secret credentials and use Workload identity federation instead. I suggest you have a look at this GitHub documentation page as well to better understand how it works but basically, you can remember the following:

this mechanism relies on Open ID Connect and trust between Azure and GitHub
the GitHub pipeline does not need an Azure AD application secret anymore to authenticate to Azure
it's not an Azure thing only, it's an open standard that also works with other cloud providers and other platforms than Github

To establish the trust relationship between the Azure AD application and the GitHub repository, a Federated Identity Credential must be created in the Azure Active Directory. You can find how to do that manually from the portal in the documentation but we are going to directly automate that 😉.

The complete solution to implement

Why use Pulumi in that context?

You might wonder why I chose to automate this process using Pulumi instead of writing a Bash or PowerShell script that would execute commands from the GitHub CLI and the Azure CLI.

💡By the way, you should check GitHub CLI if you have not done it yet, it's very handy. And if you have read my article about Azure CLI, you know it's a very convenient tool as well.

I think Pulumi is a better choice here because:

a script is imperative by nature, but declarative infrastructure seems more suitable to avoid dealing with idempotency
Pulumi can interact with both GitHub and Azure using its providers
the code will be easier to write and maintain
the code could be integrated into any application (including a future self-service infrastructure portal) using Pulumi Automation API

In this article, the Pulumi code will be in TypeScript but it would work in any language supported by Pulumi.

Automate the creation of the Azure-Ready GitHub Repository

Create the Pulumi project

Let's start by scaffolding a new Pulumi project using TypeScript:

pulumi new typescript -n AzureOIDC -s dev -d "A program to set up an Azure-Ready GitHub repository"

This command creates a new pulumi project and stack from the TypeScript template:

The name of the project "AzureOIDC" is specified using the -n option
The description of the project "A program to set up an Azure-Ready GitHub repository" is specified using the -d option
The stack of the project "dev" is specified using the -s option

ℹ By default, the pulumi new command installs the dependencies when creating the project. You can prevent this by specifying the -g option, which is useful when you want to use another package manager than the default one (pnpm instead of npm for instance).

This project will need 3 different providers:

So we can add the following packages to our package.json file:

@pulumi/azure-native
@pulumi/azuread
@pulumi/github

Create the repository on GitHub

To use the GitHub provider, we have to provide GitHub credentials. For that, we can create a personal access token (I prefer to create a fine-grained personal access token although a classic personal access token would also work). Next, we simply set the GitHub token in our Pulumi configuration, and the GitHub provider will automatically use it:

pulumi config set github:token XXXXXXXXXXXXXX --secret

🔐 Don't forget to include the --secret option when setting sensitive configurations, as this ensures that Pulumi encrypts the information. By doing so, we can safely commit the configuration files without creating security risks.

Now, it's time to create our GitHub repository!

import * as github from "@pulumi/github";

const repository = new github.Repository("azure-ready-repository", {
  name: "azure-ready-repository",
  visibility: "public",
  autoInit: true
});

export const repositoryCloneUrl = repository.httpCloneUrl;

Pulumi has an auto-naming capability that is very convenient to prevent name collisions or to ensure zero-downtime resource updates. Yet, in this context, I prefer to avoid a random suffix in my GitHub repository name, that's why I am specifying the name property to override the auto-naming behavior.

The last line creates a stack output named repositoryCloneUrl so that we can easily get the URL to clone our newly created repository.

ℹ I wanted the repository to be initialized, that's why I set the autoInit property to true but you should set it to false if you have an existing local git repository that you want to push on this GitHub repository.

Create the identity in Azure Active Directory for the GitHub Actions workflow

Creating an Azure AD application and its service principal is not very complicated:

import * as azuread from "@pulumi/azuread";

const aadApplication = new azuread.Application("AzureReadyApp", { displayName: "Azure Ready App" });
const servicePrincipal = new azuread.ServicePrincipal("AzureReadServicePrincipal", {
  applicationId: aadApplication.applicationId,
});

The OIDC trust thing is a bit more complex. Fortunately, Microsoft's documentation has a detailed page Configuring an app to trust an external identity provider that explains everything and shows how to add a federated identity for GitHub Actions using the Azure Portal, Azure CLI, or Azure PowerShell.

Let's do the same thing using TypeScript and Pulumi Azure AD provider:

new azuread.ApplicationFederatedIdentityCredential("AzureReadyAppFederatedIdentityCredential", {
  applicationObjectId: aadApplication.objectId,
  displayName: "AzureReadyDeploys",
  description: "Deployments for azure-ready-repository",
  audiences: ["api://AzureADTokenExchange"],
  issuer: "https://token.actions.githubusercontent.com",
  subject: pulumi.interpolate`repo:${repository.fullName}:ref:refs/heads/main`,
});

The subject property is what identifies the repository where the GitHub Actions workflow will be authorized to exchange its GitHub token for an Azure access token. It's worth noting that it will only work if the GitHub Actions workflow is run on the git reference (branch or tag) or the environment you specify in subject. You can also specify that only workflows triggered by a pull request should be authorized. Here, I have used the main branch but I could create multiple Federated Identity Credentials with different subjects if needed.

With this configuration, the GitHub Actions workflow we create next will be able to obtain a valid Azure access token.

If you are interested in gaining a better understanding of how all this works, you can refer to this diagram from Microsoft's documentation (with GitHub serving as the external identity provider in our case).

Authorize the Service Principal to provision resources on the subscription

We have created everything we need to get a valid Azure access token, but we still have not authorized the application to provision resources on our subscription.

We can do that by giving the Contributor role to our service principal.

import * as authorization from "@pulumi/azure-native/authorization";
import { azureBuiltInRoles } from "./builtInRoles";

new authorization.RoleAssignment("contributor", {
  principalId: servicePrincipal.id,
  principalType: authorization.PrincipalType.ServicePrincipal,
  roleDefinitionId: azureBuiltInRoles.contributor,
  scope: pulumi.interpolate`/subscriptions/${subscriptionId}`,
});

I intentionally did not declare the variable subscriptionId in the code above. It's because it's up to you to choose how you will provide it. You may want to set it in the configuration and retrieve it from it :

const config = new pulumi.Config();
const subscriptionId = config.get("subscriptionId");

Or your might want to retrieve it from the current configuration of the Azure native provider :

const azureConfig = pulumi.output(authorization.getClientConfig());
const subscriptionId = azureConfig.subscriptionId;

Concerning, the contributor role definition identifier, I could have dynamically retrieved it using Azure APIs (like here). But honestly, as these identifiers don't change it's much easier to hardcode it in a dedicated builtInRoles.ts file.

export const azureBuiltInRoles = {
  contributor : "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c"
};

💡Please note that you don't have to work on the subscription scope. If you prefer to assign the contributor role (or any other role) to an existing resource group rather than the entire subscription, you can certainly do that as well.

Add the configuration for the GitHub Actions workflow

The next step is to correctly set the configuration for the GitHub Actions of our Azure-Ready GitHub repository.

The workflow requires three pieces of information for the OIDC authentication to function properly:

The identifier of the Azure tenant
The identifier of the Azure subscription
The application identifier (also known as client ID) of the previously created Azure AD application

These identifiers are not secrets, they are just identifiers so we could directly set them as GitHub Actions variables like this:

new github.ActionsVariable("tenantId", {
  repository: repository.name,
  variableName: "ARM_TENANT_ID",
  value: azureConfig.tenantId,
});

However, I like to keep my tenant id and my subscription id private so we will store them in GitHub secrets but that's not mandatory at all.

const azureConfig = pulumi.output(authorization.getClientConfig());

new github.ActionsSecret("tenantId", {
  repository: repository.name,
  secretName: "ARM_TENANT_ID",
  plaintextValue: azureConfig.tenantId,
});

new github.ActionsSecret("subscriptionId", {
  repository: repository.name,
  secretName: "ARM_SUBSCRIPTION_ID",
  plaintextValue: azureConfig.subscriptionId,
});

new github.ActionsSecret("clientId", {
  repository: repository.name,
  secretName: "ARM_CLIENT_ID",
  plaintextValue: aadApplication.applicationId,
});

ℹ Please note that could also use environments for deployment and their associated secrets and variables.

Create the GitHub Actions workflow

Everything seems to be properly configured to provision Azure resources from a GitHub Actions workflow in this new repository, except for the workflow itself. The goal here is to have a properly configured pipeline in the repository to get started provisioning Azure infrastructure.

Here is such a pipeline:

name: infra

on:
  workflow_dispatch:

permissions:
      id-token: write
      contents: read
jobs:
  provision-infra:
    runs-on: ubuntu-latest
    steps:
      - name: 'Az CLI login'
        uses: azure/login@v1
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: 'Run az commands'
        run: |
          az account show
          az group list

This workflow first authenticates to Azure using OIDC with the azure/login action and then performs some Azure CLI commands to interact with Azure resources. That's fine and probably enough to get you started but you surely want to provision your infrastructure using a more declarative solution than an Azure CLI script. So let's see a more interesting pipeline still authenticating via Azure OIDC but using Pulumi to provision the Azure resources.

name: infra

on:
  workflow_dispatch:

permissions:
  id-token: write # required for OIDC auth
  contents: read # required to perform a checkout

jobs:
  provision-infra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: latest

      - name: Set node version to 18
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Provision infrastructure
        uses: pulumi/actions@v4.4.0
        id: pulumi
        with:
          command: up
          stack-name: dev
        env:
          ARM_USE_OIDC: true
          PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
          ARM_CLIENT_ID: ${{ secrets.ARM_CLIENT_ID }}
          ARM_TENANT_ID: ${{ secrets.ARM_TENANT_ID }}
          ARM_SUBSCRIPTION_ID: ${{ secrets.ARM_SUBSCRIPTION_ID }}

A permission section is required with 2 settings (more details here):

id-token: write ➡️ needed to request the OIDC token
contents: read ➡️ needed to perform checkout action

ℹ When you start to specify specific permissions, you have to specify all the permissions you need for the job because the default permissions won't apply anymore.

The 3 steps following the checkout step are actions to specify the Node.js version to use, install and correctly configure pnpm. We assume here the infrastructure will be provisioned using TypeScript (and Pulumi of course) but there would have been similar steps with other runtimes/languages (a setup-dotnet and a dotnet retore action for .NET for instance).

The last action is the Pulumi action to provision the infrastructure by running the pulumi up on the dev stack. We can see that this action uses environment variables whose values are based on the GitHub Actions secrets we defined earlier. To tell Pulumi to use OIDC, we just have to set the ARM_USE_OIDC environment variable to true.

        env:
          ARM_USE_OIDC: true
          PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
          ARM_CLIENT_ID: ${{ secrets.ARM_CLIENT_ID }}
          ARM_TENANT_ID: ${{ secrets.ARM_TENANT_ID }}
          ARM_SUBSCRIPTION_ID: ${{ secrets.ARM_SUBSCRIPTION_ID }}

A GitHub Actions secret we did not talk about is PULUMI_ACCESS_TOKEN that is a Pulumi access token to use Pulumi Cloud as our backend to store the infrastructure state and encrypt secrets. This token should be:

Created from Pulumi Cloud (following the documentation here)
Stored in the stack configuration using the following command pulumi config set pulumiTokenForRepository ******* --secret
Stored in a GitHub Actions secret using this code

The last thing to do is to add this workflow file to the GitHub repository:

import { readFileSync } from "fs";

const pipelineContent = readFileSync("main.yml", "utf-8");
new github.RepositoryFile("pipelineRepositoryFile", {
  repository: repository.name,
  branch: "main",
  file: ".github/workflows/main.yml",
  content: pipelineContent,
  commitMessage: "Add preconfigured pipeline file",
  commitAuthor: "Alexandre Nédélec",
  commitEmail: "15186176+TechWatching@users.noreply.github.com",
  overwriteOnCreate: true,
});

This code:

reads the main.yml file that contains the workflow we saw previously
creates a file with this content in the repository in the .github/workflows/ folder for the GitHub Actions workflows
makes a commit when creating the file (or modifying it)

💬 To read the YAML file, I use the readFileSync method from the File System API fs. That's one of the things I love about Pulumi: you use the things you already know and that already exist in your ecosystem. No need to look for a module or wait for someone to write one, there is probably something standard or a popular community library you can use.

Test the Azure-Ready GitHub Repository

Now that the infrastructure code to provision the Azure-Ready GitHub repository is written, let's run it with the pulumi up command and see if it works!

All the resources are correctly created and our new GitHub repository is ready to be used.

Let's clone it.

git clone https://github.com/TechWatching/azure-ready-repository; cd azure-ready-repository

We want to verify that the GitHub project is properly configured and can provision Azure resources from its GitHub Actions workflow.

Let's add some infrastructure code that provisions a few Azure resources to check that:

pulumi new azure-typescript -n "AzureReadyGitHuRepository" -y --force

The --force option allows us to create the code within a non-empty directory.

I used the azure-typescript template that creates a storage account and outputs retrieve its primary access key.

🔒 In the SDK, the outputs of the function that lists the storage access keys are not currently marked as secrets. There is currently an open issue to change that but in the meantime, I have just modified the code to label the stack output as secret ensuring its encryption.

Let's run a pnpm install to install the dependencies and generate the pnpm-lock.yaml file. Then, we can push the code to GitHub and run the pipeline to see how it goes.

That's it, we succeeded to provision a storage account from our new GitHub repository whose creation and configuration were entirely automated using Pulumi.

To conclude

Additional information

There are different platforms you can use to host your Git repositories: GitHub, GitLab, and Azure DevOps to name a few. We use GitHub in this article but you can easily apply the same logic with other platforms (Pulumi has providers for GitLab and Azure DevOps as well).

Even though the Azure-Ready GitHub repository is provisioned using Pulumi, there's nothing stopping you from using another Infrastructure as Code solution that supports Azure OIDC (such as Azure CLI, which was mentioned in the article, Azure Bicep, or even Terraform) in the GitHub Actions workflow of the created repository. You don't even have to provision infrastructure; you can use this workflow to simply deploy an application to an existing Azure resource.

Potential Enhancements

There are many aspects that could be improved in the infrastructure code provisioning the Azure-Ready GitHub repository, but I believe the current solution serves as a good starting point. Nevertheless, here are some ideas for potential enhancements:

make additional items, such as the commit author, configurable
authorize an environment and not only a branch to retrieve an Azure token
use environment variables/secrets instead of variable/secrets at the repository scope

I think it would be interesting as well to put that code behind an API or a Web application using Pulumi Automation API to have a self-service solution to create Azure-Ready GitHub repository on the fly.

Here are some articles on the same topic I wanted to mention:

Stop using static cloud credentials in GitHub Actions by Lee Briggs

➡️ This post provides examples for configuring OIDC authentication with GitHub Actions for AWS, Azure, and GCP. The code for Azure is quite similar to the code I showed here. Yet, it doesn't go so far as to initialize a pipeline ready to deploy resources with Pulumi. Anyway, it's awesome to have the code for all 3 major providers.
Configuring GitHub Actions to Azure authentication with OIDC by Xavier Geerinck

➡️ This post also shows how to configure OIDC authentication with GitHub Actions and Azure but using an Azure CLI script. Although the GitHub repository creation and configuration are done manually, automating the Azure part with a few lines of script is nice.
Getting Rid of Passwords for Deployment with Pulumi OIDC Support by Sam Cogan

➡️ If you don't care about automating everything and simply want to configure OIDC authentication through the Azure portal, that's the post you will want to read. There is also an example of a pipeline to provision Azure infrastructure using a .NET Pulumi program.

Complete code solution

In this article, I aimed to provide a step-by-step explanation of how to automate the creation of a GitHub repository with a properly configured workflow to interact with Azure using OpenID Connect. Consequently, the article turned out to be quite lengthy. I apologize for that, but I didn't want to present the code without adequate explanation.

Anyway, now that we've covered everything, here is the complete code, which is just 75 lines long:

import * as pulumi from "@pulumi/pulumi";
import * as github from "@pulumi/github";
import * as azuread from "@pulumi/azuread";
import * as authorization from "@pulumi/azure-native/authorization";
import { azureBuiltInRoles } from "./builtInRoles";
import { readFileSync } from "fs";

const config = new pulumi.Config();

const repository = new github.Repository("azure-ready-repository", {
  name: "azure-ready-repository",
  visibility: "public",
  autoInit: true
});

export const repositoryCloneUrl = repository.httpCloneUrl;

const aadApplication = new azuread.Application("AzureReadyApp", { displayName: "Azure Ready App" });
const servicePrincipal = new azuread.ServicePrincipal("AzureReadyServicePrincipal", {
  applicationId: aadApplication.applicationId,
});
new azuread.ApplicationFederatedIdentityCredential("AzureReadyAppFederatedIdentityCredential", {
  applicationObjectId: aadApplication.objectId,
  displayName: "AzureReadyDeploys",
  description: "Deployments for azure-ready-repository",
  audiences: ["api://AzureADTokenExchange"],
  issuer: "https://token.actions.githubusercontent.com",
  subject: pulumi.interpolate`repo:${repository.fullName}:ref:refs/heads/main`,
});

const azureConfig = pulumi.output(authorization.getClientConfig());
const subscriptionId = azureConfig.subscriptionId;

new authorization.RoleAssignment("contributor", {
  principalId: servicePrincipal.id,
  principalType: authorization.PrincipalType.ServicePrincipal,
  roleDefinitionId: azureBuiltInRoles.contributor,
  scope: pulumi.interpolate`/subscriptions/${subscriptionId}`,
});

new github.ActionsSecret("tenantId", {
  repository: repository.name,
  secretName: "ARM_TENANT_ID",
  plaintextValue: azureConfig.tenantId,
});

new github.ActionsSecret("subscriptionId", {
  repository: repository.name,
  secretName: "ARM_SUBSCRIPTION_ID",
  plaintextValue: azureConfig.subscriptionId,
});

new github.ActionsSecret("clientId", {
  repository: repository.name,
  secretName: "ARM_CLIENT_ID",
  plaintextValue: aadApplication.applicationId,
});

new github.ActionsSecret("pulumiAccessToken", {
  repository: repository.name,
  secretName: "PULUMI_ACCESS_TOKEN",
  plaintextValue: config.requireSecret("pulumiTokenForRepository"),
});

const pipelineContent = readFileSync("main.yml", "utf-8");
new github.RepositoryFile("pipelineRepositoryFile", {
  repository: repository.name,
  branch: "main",
  file: ".github/workflows/main.yml",
  content: pipelineContent,
  commitMessage: "Add preconfigured pipeline file",
  commitAuthor: "Alexandre Nédélec",
  commitEmail: "15186176+TechWatching@users.noreply.github.com",
  overwriteOnCreate: true,
});

You can find the complete source code used for this article in this GitHub repository.

I hope you enjoyed this article. Please feel free to share your thoughts in the comments, ask questions, or make suggestions. Keep learning.

4 tips about GitHub Actions environment variables and contexts

Alexandre Nédélec — Thu, 02 Feb 2023 09:22:00 +0000

I recently played a bit with GitHub Actions and as I have spent some time running again and again my workflows to understand what what going wrong I thought it could be interesting to share what I have learned especially concerning environment variables and contexts.

🗨 Disclaimer: Although I have some experience with Azure Pipelines, I am still learning GitHub Actions so I do not pretend to know everything about them nor do I never make mistakes when writing about them. Feel free to correct me in the comments if you think I am wrong about something or if something that I show can be done more effectively.

Tip n°1: Environment variables syntax depends on the shell you are using in your job

As you know a GitHub Actions workflow is composed of different jobs where each job is a set of steps that execute on the same runner. As a runner can be hosted Ubuntu, Windows, MacOS or even another operating system (if you host your own runner) the shell that will execute your commands will not be the same by default depending on the runner you choose. For instance if you are on a Ubuntu GitHub-hosted runner, by default the shell will be bash whereas on a Windows GitHub-hosted runner it will be PowerShell (I think we don't say PowerShell Core anymore but I am speaking of pwsh not the old Windows PowerShell of course).

This is really important to know because depending on the shell used, the syntax to use an environment variable in a script is different as you can see on the documentation screenshot below:

🗨 When I am talking about environment variables here I am referring to GitHub default environment variables (for instance GITHUB_EVENT_NAME which the name of the webhook event that triggered the workflow) and to custom variables you set in a workflow. The syntax for environment variables you just create and use in a shell script does not change of course.

The documentation briefly explains the syntax to use depending on the shell here but you can easily miss it like I did. In fact most of the GitHub Actions examples you can find are in bash so if you use them as-is without paying attention to the shell you are using, you will probably get it wrong. I lost a lot of time trying to figure out why my scripts were not working on a Windows runner so I hope knowing that you will avoid to do the same.

Tip n°2: Do not use your repository `GITHUB_TOKEN` in tasks that need to trigger another workflow.

The GITHUB_TOKEN is a secret you can use in your workflow to do some actions on your GitHub repository like pushing a tag, creating a new release, creating an issue... It is very convenient because it allows you to automate in your workflow many things for your GitHub repository using built-in actions or the GitHub REST API.

🗨 Be aware that internally GitHub Actions is a GitHub App that is installed on your repository when you start creating GitHub Actions workflows for this repository. That means the token represented by GITHUB_TOKEN in your workflow is a GitHub App installation token that will only work on your repository workflow and that will have a limited set of permissions (but your can grant more permissions directly in your workflow if you want).

If you want to know about authentication in a workflow, there is dedicated page on the topic in the GitHub documentation. However if you read it quickly you may miss an important piece of information:

"events triggered by the GITHUB_TOKEN will not create a new workflow run"

What does this mean ? It means that if you have 2 workflows and that the first one uses the GITHUB_TOKEN for an action that should trigger the second one, then the second workflow will never be triggered. The aim is to prevent you from making an infinite loop of workflows runs triggering each other.

So imagine you want to implement a workflow that publish a release when a new tag is pushed on a repository, and another workflow that automatically tweet about your new release once it is published, how can you do that? You just have to create a GitHub Personal Access Token, add it as a secret in your repository and use it in your first workflow to create your release. This way, the second workflow will run fine when the release is published.

Tip n°3: Assign information from the event triggering a GitHub Actions workflow to a PowerShell variable.

Sometimes, in a GitHub Actions workflow we want to execute some PowerShell to do specific actions depending on information from the event that triggered the workflow. Hence having a PowerShell variable with this data could be really useful. For instance, if we have a workflow triggered by the publication of a release, maybe we need to retrieve the URLs of the binaries of this release which can be done easily if the event data is in a PowerShell variable.

The webhook payload corresponding to the event that triggered a workflow is part of the properties of the github context.

🗨 If you are not familiar with contexts in GitHub Actions, they are objects that contain information about the current workflow, job, runner or things like that. Contexts are often used in expressions to determine whether or not a step of the workflow should be executed or to set some variables as you can see in the sample below.

As you can read in the documentation, the event property is of type object which makes it difficult to query it and to assign it to a PowerShell variable. Fortunately, there are ways to do that which are based on the fact that GitHub event data is persisted in a json file on the runner file system.

First one is to use the tool jq which is already installed on GitHub's runners and that allows you to process json data. Edward Thomson has a blog post which explains how you can use jq with GitHub Actions to do that: GitHub Actions Day 12: Information about your Workflow.

Second one is to directly use PowerShell to grab the GitHub context like this: $github = Get-Content '${{ github.event_path }}' | ConvertFrom-Json. Thanks a lot Edward Thomson for helping me with this tip 😀.

Edward Thomson

@ethomson

@TechWatching When we spin up a workflow, we'll put the github event data in a file on-disk (in json). We store the filename in the github context itself, as `${{ github.event_path }}`. So you can use `ConvertFrom-Json` on it.

15:39 PM - 20 Jul 2021

To illustrate that, here are a sample of using these two ways to assign the URL of the binary published by a release to a PowerShell variable using the event property of the github context:

using jq:

 $installerUrl = $(jq --raw-output '.release.assets[].browser_download_url | select(contains(\"windows.msi\"))' "${{ github.event_path }}")

using ConvertFrom-Json method in PowerShell:

$github = Get-Content '${{ github.event_path }}' | ConvertFrom-Json
$installerUrl = $github.release.assets | Where-Object -Property name -match 'windows.msi' | Select -ExpandProperty browser_download_url -First 1

I did not know about jq but I find it is a really nice tool although the syntax is not that straightforward. Yet, I prefer the PowerShell way because it allows to directly manipulate an object instead of a json string. It is what I did to automate the upgrade of the Nushell winget package using GitHub Actions when a new release is published (you can read more about it in this article).

Tip n°4: Enable debugging logs to help you understand what is going wrong in your workflow

As many CI / CD platforms, GitHub Actions has the disadvantage of not being testable locally which makes it hard to debug a workflow when something is not working properly. Moreover, by default you won't see how some expressions / contexts are evaluated when the workflow run so logs will not help you figuring out what is wrong in your workflow definition.

Hopefully, you can enable debugging logs for all pipelines in your repository (unfortunately you can't specify it for a specific pipeline only) by setting the secret ACTIONS_STEP_DEBUG to true in your repository. You can read more about it in the documentation but here is what it look likes in a workflow run:

I hope these 4 tips will help you build awesome GitHub Actions workflows.

How to provision an Azure SQL Database with Active Directory authentication

Alexandre Nédélec — Thu, 26 Jan 2023 09:10:00 +0000

In this article, we will talk about how to provision an Azure SQL Database with authentication restricted to Active Directory users/groups/applications. We will use Pulumi to do that.

Why this article?

In a previous article, I already talked about connecting to an Azure SQL Database using Azure Active Directory authentication. However, my focus was on querying an Azure SQL Database from C# code (from an ASP.NET 6 Minimal API that was using Microsoft.Data.SqlClient 'Active Directory Default' authentication mode to be more precise), and not on the configuration of the Azure AD authentication itself.

Still, in that article, I wrote an Azure CLI script that showed how to provision and configure the database with Azure AD authentication enabled. So why write another article about that? First because I did not show how to give an Azure AD entity (user, group, or managed identity) permission to access the database. (In my samples, to simplify things I was using the SQL server Azure AD administrator account to make my queries 🤫). Yet, it is something you will probably have to do if you want your App Service or Function App to query your database. Second because even if Azure CLI is great to handle Azure resources (if you are a reader of my blog, you probably know that I enjoy very much Azure CLI), in a real project I would probably use a more advanced Infrastructure as Code solution like Pulumi. And that is what we will show here.

🗨️ If you are not familiar with Pulumi, it is an IaC solution similar to Terraform but using programming languages like C#. Speaking of C#, that is what I will use to write my infrastructure code but you can easily do the same in another language supported by Pulumi (TypeScript, Go, Python,... choose the one you are used to), the concepts stay relevant and the code will be similar.

Now, let's get to the heart of the matter.

An Azure AD user as our SQL Server administrator

Usually, when you create an Azure SQL Server, you have to provide an administrator login and an administrator password. But I said I wanted to limit the authentication to Azure Active Directory authentication only. So we will only need an Azure AD account to set as the administrator of our SQL Server. We could use an existing Azure AD account, but let's create a new Azure AD user just for that:

var config = new Config();
var sqlAdAdminLogin = config.Require("sqlAdAdmin");
var sqlAdAdminPassword = config.RequireSecret("sqlAdPassword");

var sqlAdAdmin = new User("sqlAdmin", new UserArgs
{
    UserPrincipalName = sqlAdAdminLogin,
    Password = sqlAdAdminPassword,
    DisplayName = "Global SQL Admin"
});

To create a new Azure AD user we need a login (it will be the email of the new user in our tenant) and a password. In this example, we retrieve these values from the configuration which is stored in the YAML settings file. You can notice there that we retrieve a secret (the password) from the configuration thanks to the config.RequireSecret method. Indeed to avoid exposing a secret in the configuration file or the state file, Pulumi has built-in support for secret encryption and decryption (not sure Terraform folks can say the same thing 😉).

Create the Azure SQL Server and its database.

Now that we have our administrator account, we can create the Azure SQL Server:

var sqlServer = new Server($"sql-sqlDbWithAzureAd-{Deployment.Instance.StackName}", new ServerArgs
{
    ResourceGroupName = resourceGroup.Name,
    Administrators = new ServerExternalAdministratorArgs
    {
        Login = sqlAdAdmin.UserPrincipalName,
        Sid = sqlAdAdmin.Id,
        AzureADOnlyAuthentication = true,
        AdministratorType = AdministratorType.ActiveDirectory,
        PrincipalType = PrincipalType.User,
    },
});

Nothing special here: we are using the variable sqlAdmin that is our newly created user to set the administrator of the SQL Server and we set the authentication to Azure AD only. We can then create the database:

var database = new Database("sqldb-sqlDbWithAzureAd-Main", new DatabaseArgs
{
    ResourceGroupName = resourceGroup.Name,
    ServerName = sqlServer.Name,
    Sku = new SkuArgs
    {
        Name = "Basic"
    }
});

Grant SQL Database access permissions to Azure AD entities

Once we have provisioned the Azure SQL Server and its database, here comes the tough part: we need to configure who can access the database. In a project, you will probably have to give access to some users and to the Azure resources that need to query the database (you will have to assign these resources a managed identity before that). But to keep things simple, we will just consider we need to grant SQL Database access to an Azure AD group. That could be a good way to do things by the way: create an Azure AD group, grant permissions to this group and add users and managed identities that need access to the database.

Why did I say that this part was tough? It's because to grant SQL database permissions, we need to execute an SQL command on the Server as you can read in the documentation.

CREATE USER [<identity-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];
GO

With this command, we are creating a user and giving db_datareader and db_datawriter roles. However it is not a classical user, it's a user that is "external" to the database: in our case, it corresponds to an Azure AD entity (a user, group, or application).

So it's not just about setting a property to properly configure an Azure resource, it's a bit more complicated.

I see multiple ways of doing that:

Create a new Pulumi provider "SQL Server provider" that is to able manage users in an SQL Server database
Write custom C# code that executes the SQL command once the database is created
Use the Pulumi Command provider to execute the SQL command using the sqlcmd utility

Let's review these solutions.

New "SQL Server Provider"

To manage SQL Server resources like users and roles, we can create a complete provider. We could create it from scratch of course or use this Pulumi GitHub repository that provides some boilerplate code to create a Pulumi provider. Usually, Pulumi providers are written in Go (like the Terraform providers by the way) and generate SDKs for all programming languages supported by Pulumi.

Another way would be to adapt the existing Microsoft SQL Server Provider for Terraform. This Terraform provider made by the community enables you to create and manage logins and users on a SQL Server. I talked about "adapting" this provider because you can create a Pulumi provider out of a Terraform provider by using the Pulumi Terraform Bridge. That's great because instead of reinventing the wheel you can benefit from Terraform ecosystem by creating a Pulumi provider that wraps an existing Terraform provider. This GitHub repository contains boilerplate code to do exactly that.

You might have noticed that I sometimes criticize Terraform in my articles. That's not because I think Terraform is a bad infrastructure as code solution, in fact, I think it is a great solution with a rich ecosystem. However, I am critical of Terraform because I believe Infrastructure as Code should be done with programming languages instead of Domain-Specific Languages. Moreover, there are some areas (API coverage of major cloud providers, security, IDE support, ...) where I found Terraform is not good enough, especially compared to other platforms like Pulumi. So I am always a bit disappointed when I see that many people choose by default Terraform as their infrastructure as code platform without considering alternatives (and I am not only talking about Pulumi, there are also Farmer and Bicep for instance), even when these alternatives would be better suited to their use cases. That being said, Terraform has also advantages like its great community that creates and contributes to many providers like the mssql one.

This first solution of creating a new "SQL Server Provider" (whether it be from scratch, from boilerplate code, or from the mssql Terraform provider) is interesting but could be time-consuming because there are some things to set up and some amount of code to write.

Custom C# code

When you need to do something specific and there is no existing provider that can help you with it, you can just write the code to do it yourself without creating a complete provider. It's one of the reasons why I like Pulumi, even if you are doing Infrastructure as Code, at the end of the day you are just developing software so you can code what you need in the language you are familiar with. For instance, as I am developing in .NET, I can use the Microsoft.Data.SqlClient library (which is a data provider for Azure SQL Database) to connect and send commands to the database. And if I want to use Dapper on top of it because that's the library I am used to for querying a database I can. Hence writing the code that executes on the database the SQL command we have previously seen should not be very difficult.

Now, even if we are using imperative language in Pulumi to write the infrastructure code it's still declarative infrastructure as code with a state. Therefore, we have to be careful about how and when this custom code should be executed.

The easiest way is to use an Apply method on an output of the database like this:

database.Name.Apply(name =>
{
    /*** 
     * Indempotent code using Microsoft.Data.SqlClient library
     * to execute the SQL command that assigns the correct roles
     * to the Azure AD group we want to have access to the database.
    ***/ 
    return true;
});

The code in the Apply will execute on every run after the resource is created, that is why it needs to be idempotent. Having to make the code idempotent is a constraint that I would prefer to avoid but at least it gives us a simple way to execute the code that grants access to the database.

Another way would be to use Dynamic Providers whose purpose is exactly that: do an infrastructure task that no existing provider can help you deliver. You can see some use cases of dynamic providers in this Pulumi article. In our use case, we could imagine writing a dynamic resource provider for an Azure AD entity user in an Azure SQL Database. We would have to implement the different CRUD operations to handle the different use cases properly (a user is added, a user is removed, user roles are updated, ...). Unfortunately, as you can see in this GitHub issue, .NET Dynamic Providers are not yet supported (only TypesScript, JavaScript and Python are for the moment). It's a shame because Dynamic Providers provide an easy and efficient way of supporting custom resource types.

Command provider with the `sqlcmd` utility

The Microsoft tutorial, that shows how to grant database permissions to an Azure AD entity, explains how the necessary SQL commands can be run using the sqlcmd utility. So instead of writing some C# code to do the same, an interesting idea would be to directly run the sqlcmd utility. And you know what? There is a Pulumi provider for executing commands and scripts: the Command Provider.

Because it's a Pulumi provider, the sqlcmd command would be executed "as part of the Pulumi resource model" which means the scripts would be executed at the corresponding time of the resource life-cycle (the create script when the resource is created and so on). So it's very nice and not the same as executing the sqlcmd outside of a Pulumi program, without access to all the variables and where you would have to make your script idempotent. Moreover, the ability to execute commands remotely can bring interesting use cases, just not for our current concern here.

Pulumi Command Provider is currently in preview and only supports running scripts on create and destroy operations (support for diff, update and read operations will probably be added later). It works fine but does not log details about the error when a script fails, which makes debugging difficult. That should not prevent you from using it but as with any components in preview, use it with caution knowing everything is not perfect yet.

Implement the database permissions for an Azure AD Group

Of the 3 possible solutions let's take the 3rd one with the Command provider and the sqlcmd utility. It is probably not the "best" solution but I thought it would be simpler to use the sqlcmd utility than writing a complete provider or even custom C# code to do the same. Furthermore, it's the opportunity to test the Command provider which is fairly new.

Allow the machine running the Pulumi program to connect to the SQL Server

To run a SQL command in the database, the machine that executes the Pulumi program needs to have its public IP authorized. To programmatically retrieve the public IP address from where the Pulumi program is running we can use ipify API. It's a simple open source HTTP API that returns the public IP address of the caller.

var publicIp = Output.Create(new HttpClient().GetStringAsync("https://api.ipify.org"));

You can note here that we are just using standard C# code with an HttpClient that makes a GET to the API and returns asynchronously a string. I like the fact that with Pulumi we can reuse our existing C# skills, and the libraries we are used to. If we were to do that in Terraform we would have to look in the documentation how to do HTTP calls, discover that there is an http data source that can be used, understand how it works (to be honest it seems quite simple but still that is not natural) and use it.

Now we can enable this public IP by creating a firewall rule in the SQL Server.

var enableLocalMachine = new FirewallRule("AllowLocalMachine", new FirewallRuleArgs
{
    ResourceGroupName = resourceGroup.Name,
    ServerName = sqlServer.Name,
    StartIpAddress = publicIp,
    EndIpAddress = publicIp
});

Create the Azure AD group that will be given access to the database

We said we wanted to grant SQL Database access to an Azure AD group that will contain in the future users and application managed identities that need access to the database. So let's create that:

var sqlDatabaseAuthorizedGroup = new Group("SqlDbUsersGroup", new GroupArgs
{
    DisplayName = "SqlDbUsersGroup",
    SecurityEnabled = true,
    Owners = new InputList<string> { sqlAdAdmin.Id }
});

We set the Azure SQL Server admin as the owner of the group. This way, the admin of the database can add Azure AD users to the group and they directly have the permissions configured for this group. I like authorizing an Azure AD group instead of each Azure AD user because:

it is easier to manage a group than individual users (adding a user to a group is less work than using SQL commands to assign the correct role for each user)
you don't lose granularity of access control (you can always create several groups with different permissions if you need to)
you can ensure that your application runs with the same permissions locally (the code you debug uses your user account identity) and on Azure (the code uses the managed identity of the App Service where it is hosted) by putting users and managed identities in the same group

Assign the roles to the Azure AD group using the Command provider

As we already talked about, we can specify a script to run on the create operation and another on the destroy operations. To keep things simple for this sample, we will only handle the creation scenario where we will add our Azure AD group as a user of the database and give it the expected roles. We already showed the SQL Command to execute, with our new group name it becomes:

CREATE USER {sqlDatabaseAuthorizedGroup.DisplayName} FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER {sqlDatabaseAuthorizedGroup.DisplayName};
ALTER ROLE db_datawriter ADD MEMBER {sqlDatabaseAuthorizedGroup.DisplayName};
GO

The sqlcmd utility can be used like this to send a command on the database:

sqlcmd -S {sqlServer.Name}.database.windows.net -d {database.Name} -U {sqlAdAdmin.UserPrincipalName} -P {sqlAdAdmin.Password} -G -l 30 -Q ' ___SQL Command___'

You can check the documentation to learn more about how to use sqlcmd but that is quite simple: we are just specifying to send a command line query on our database using Azure Active Directory to authenticate.

If we use all that with our Command provider, we get the following C# code.

var authorizeAdGroup = new Command("AuthorizeAdGroup", new CommandArgs
{
    Create = Output.Format($"sqlcmd -S {sqlServer.Name}.database.windows.net -d {database.Name} -U {sqlAdAdmin.UserPrincipalName} -P {sqlAdAdmin.Password} -G -l 30 -Q 'CREATE USER {sqlDatabaseAuthorizedGroup.DisplayName} FROM EXTERNAL PROVIDER; ALTER ROLE db_datareader ADD MEMBER {sqlDatabaseAuthorizedGroup.DisplayName}; ALTER ROLE db_datawriter ADD MEMBER {sqlDatabaseAuthorizedGroup.DisplayName};'"),
    Interpreter = new InputList<string>
    {
        "pwsh",
        "-c"
    }
});

As you can see, we can specify a specific interpreter to use (PowerShell here).

Don't do like me and forget that our variables are outputs (only fully known when the infrastructure resource is completely provisioned). Because of that it is necessary to use the Output.Format method for string interpolation instead of using the C# operator $. Thanks to the community on Slack for helping me on that one because with the Command provider not logging the errors details I had a hard time on this.

Results

And that's it! We now have created the Azure AD group as an external user in the database and assigned it the db_datareader and db_datawriter roles. Here is what it looks like in Azure Data Studio:

Conclusion

This article is a bit long because I explain all the steps and possibilities but the complete code is not very big or complex. You can find it in this GitHub repository.

I did not see that many articles on the web that talk about using Azure Active Directory authentication for an Azure SQL Database, and even less that showed how to properly configure it using Infrastructure as Code. Yet, I think it's an important thing to do to properly secure your Azure SQL database. So I hope you enjoyed it and learn something. Whether you use Azure CLI, Bicep, ARM Templates, Terraform, or Pulumi, don't hesitate to use Azure AD authentication on your Azure SQL Database, for me that is the right and secure way to go.

As you have seen in this article, even when there is no provider for your custom resource or task, there are always several solutions to do what you want with Pulumi. Some are more elegant, some are more complex than others but you will always find a way and you will not be limited by the platform.

A big thank you to the Pulumi community that gave me some insights on how to configure Azure AD authentication on a database properly using Pulumi. Without the help of some people in the Pulumi Slack or the GitHub Issues/Discussions I would not have been able to write this article. Indeed some ideas and solutions are directly inspired by people's answers to my questions. This article is my way of contributing back and helping others that would have similar questions.

IaC Hot Reload with Pulumi Watch

Alexandre Nédélec — Thu, 19 Jan 2023 09:26:00 +0000

Do you like using hot reload when developing applications? How about using hot reload when developing the cloud infrastructure of an application? Keep reading because that's what we are going to talk about.

Developing and deploying Cloud Infrastructure

When doing Infrastructure as Code for a cloud application we usually do the following steps:

we write the code describing the desired state of the infrastructure
we build this infrastructure code and compare the resulting desired state against the current state of the infrastructure
we deploy to the provisioned infrastructure the changes needed to achieve the desired state

When using Pulumi, you can run the pulumi preview command for step 2 and the pulumi up command for step 3.

As its name suggests, the pulumi preview command only "preview" the updates that could be made to the infrastructure but does not apply them. To perform an update of the cloud infrastructure you have to use the pulumi update command which also does a preview of the changes, prompts the user to approve the changes to be made, and performs these changes. That is why, to be honest I don't bother with pulumi preview: most of the time I only use the pulumi up command (which means I do steps 2 and 3 in one row).

🗨 In case you wonder, if you already have run pulumi preview before running pulumi up you can skip the preview in the up command by using the --skip-preview option.

Of course, you can use these commands to automate the deployment of your cloud infrastructure using your favorite CI/CD system.

The need for a hot reload-like experience when doing IaC

All this is great but there are times when all you want is to quickly write your infrastructure code and check that you can successfully provision and configure the cloud resources you need. This can happen when you want to prototype something, test a new cloud resource, or simply when you are developing your infrastructure and want to verify your infrastructure code works. Usually, you are using a "sandbox" cloud environment for this, the same way you would use your local environment for debugging application code. At these moments, you don't care about CI/CD. You care about quickly experimenting with changes to your infrastructure, being productive, making changes in your code, and checking what it does, so you want to be able to quickly iterate to make your code work. Yet, this is not possible if each time you make a change to the code you have to manually run the pulumi up command, and approve the deployment.

🗨 You can use the --yes option to automatically approve the changes and directly perform the update when running the pulumi up command.

But guess what? Fast feedback when doing a code change is exactly what you want when developing an application. Indeed whether you are building an application or building infrastructure you are doing software development so you have the same needs and practices. And what do application developers have in their toolbox to be more productive when developing? They have "hot reload": while debugging locally an application, they can modify the source code, and changes made will be almost instantaneously reflected on the application. Wouldn't it be great if similarly you could make a change in your infrastructure code and have the provisioned infrastructure automatically updated? That is what the pulumi watch command is here for.

Using Pulumi Watch

pulumi watch is a command currently in preview that watches for changes in the infrastructure code directory and continuously updates the cloud resources.

But the best is to see by yourself. In the following example, you can see on the left of the screen a terminal opened with the pulumi watch command running, and on the right of the screen vscode opened with the code describing the currently provisioned Azure infrastructure for my project. Some lines to create a "Tweets" table in the storage account are commented. When I uncomment them and save the code file, you can see that pulumi detects it, builds the code, and deploys the changes so creates the table in that case.

I don't know what you think but I find this pretty cool: it's like hot reload for your infrastructure as code. Of course, you will probably not use pulumi watch all the time, but for quickly writing and testing your infrastructure code it can be very helpful.

As far as I know (don't hesitate to correct me in the comments if I am wrong), there is no such feature in Terraform and it's too bad because when you start using the watch command you don't want to do without it.

Pulumi with an Azure Blob Storage backend

Alexandre Nédélec — Thu, 12 Jan 2023 09:00:00 +0000

By default when you use Pulumi, the state is managed by Pulumi Service which is very convenient as you can concentrate on building your project infrastructure instead of spending time on where to store the state and how to handle concurrency. However, sometimes for governance or pricing concerns, or any other reasons, you don't want to use Pulumi Service and you prefer to manage the state yourself with your own backend. In this article, we will see how we can do that using Azure.

A quick reminder about states and backends

What is this state we need to store?

Like other Infrastructure as Code platforms, Pulumi uses a declarative approach:

we write code to describe the desired state of our infrastructure
Pulumi engine compares this desired state with the current state of the infrastructure and determines what changes need to be made
Pulumi deploys these changes and updates the current state of the provisioned infrastructure

🗨 Some people think using Pulumi means adopting an imperative approach because we are using programming languages (so imperative languages) instead of using declarative languages (like YAML, JSON, and HCL). However, being declarative is not about the language used but about defining the "what" (the infrastructure we want to provision) instead of the "how" (the steps to provision this infrastructure). So Pulumi has the best of both worlds by being declarative while using programming languages.

As you understood, being able to provision and modify an infrastructure with this declarative approach requires 2 states: the desired state and the current state of the infrastructure. The desired state is the infrastructure code that we usually store in a Git repository alongside the application code. The current state however is computed by the Pulumi engine each time we modify the infrastructure and needs to be stored somewhere.

That is why we need a "backend" to use Pulumi, it's just a place to store the current state of the provisioned infrastructure.

If you want more information about states and backend, Pulumi has a documentation page about that and there is also a page about how Pulumi works.

What "backends" can we use to manage the infrastructure?

The default backend is Pulumi Service which is a web application that stores the infrastructure state and has additional features like concurrent state locking, team policies, or deployment history. This service is managed by Pulumi, is free for individuals but charged for teams, and enterprises. It can be self-hosted in the enterprise plan. Just as a side note, Pulumi Service (along with support and training) is how the company Pulumi makes money because everything else is free and open source.

Yet, we don't have to pay anything to use Pulumi because Pulumi Service, no matter how good it may be, is not the only solution to store the infrastructure state. Indeed, Pulumi supports other backends that we can manage ourselves:

Local Filesystem
AWS S3 (or compatible server)
Google Cloud Storage
Azure Blob Storage

In the rest of this article, we will see how to use Pulumi with Azure Blob Storage as the backend for our infrastructure state.

Using Pulumi with the Azure Blob Storage backend

What do we need?

Pulumi documentation on using Azure Blob Storage backend is short. It only says that we need to:

set the AZURE_STORAGE_ACCOUNT environment variable to specify the Azure storage account to use
set the AZURE_STORAGE_KEY or the AZURE_STORAGE_SAS_TOKEN environment variables to let Pulumi access the storage
execute the following command pulumi login azblob://<container-path> where container-path is the path to a blob container in the storage account

Once this command is executed, we can start using Pulumi as we would with any other backend. The infrastructure's current state will automatically be stored in the blob container you specified. It will be compared to the desired state when a change is made in the code to know what resources need to be created/updated/deleted.

In fact, that is not very complex. Nevertheless, the documentation assumes we already have created an Azure storage account with a blob container in it and retrieved the key to access it. That is not the case, so now that we know what we need let's script it!

How to create and configure the Azure Blob Storage backend?

For me, the easiest way to write a script to create and configure the storage account we need is to use Azure CLI. One nice way of writing Azure CLI scripts is to do it in vscode with the Azure CLI Tools extension: you can create .azcli files with IntelliSense on them and run the commands you are writing in the integrated terminal (see screenshot below).

🗨 If you are not familiar with Azure CLI, you can check my article "Goodbye Azure Portal, Welcome Azure CLI".

Let's first define a few environment variables: the name of the resource group that will contain our storage account, its location, and the name of the storage account (I am using PowerShell but don't forget to change the syntax if you are using another shell like bash).

$random=Get-Random -Maximum 1000
$location="West Europe"
$rgName="rg-iacstate-westeu-$random"
$saName="stiacstate$random"

Then let's create our resource group and our storage account:

az group create -n $rgName -l $location
az storage account create -g $rgName -n $saName -l $location --sku Standard_LRS

The key to access the storage account can be retrieved with the following command:

az storage account keys list --account-name $saName -g $rgName -o tsv --query '[0].value'

Using this command, we can now set the environment variables that will be used by the Pulumi CLI to access our Azure Blob Storage account backend:

$env:AZURE_STORAGE_KEY=$(az storage account keys list -n $saName -g $rgName -o tsv --query '[0].value')
$env:AZURE_STORAGE_ACCOUNT=$saName

And finally, we can create the blob container that will contain the infrastructure state:

az storage container create -n iacstate

How to provision your project infrastructure using the Azure Blob Storage backend?

Now that our blob container exists, we can use the pulumi login command we already talked about to indicate pulumi to use the newly created azure blob storage as the backend.

pulumi login azblob://iacstate

To verify Pulumi can correctly provision cloud resources using our Azure Blob Storage backend, we can create a new Pulumi project using the azure-csharp template and deploy the infrastructure with the pulumi up command:

mkdir infra;cd infra;
pulumi new azure-csharp -n AzureStorageBackend -s dev -y
pulumi up -y

When executing these commands, Pulumi will ask us to provide a passphrase. Why is that? It is to encrypt secrets contained in the infrastructure state. This way no secret is stored in plain text in the state.

Once the pulumi up command is finished, the infrastructure requested is provisioned, and we can see a new state file has been created in the iacstate blob container.

Managing state sensitive data

Why is it needed to protect sensitive data in the state ?

The state is transmitted and stored securely by Pulumi and whatever the backend you use you should restrict its access. For instance, in our example, you should have assigned the permissions on the storage account so that only the right people have access to it. Nevertheless, securing the state file is not enough because it contains sensitive data (keys, connection strings, ...) that you probably don't want anyone that access to the file to be able to get.

Indeed, it's not because a developer needs to read the state file to debug an issue that you want him to be able to see some production sensitive data in plain text in the state. Having secrets in plain text in a state file would be like putting secrets in your source control and telling it is safe because only developers of the project team have access to it. Moreover, even if an unauthorized person succeeds to get access to the state file, it won't be an issue if all secrets in it are encrypted. Hence that is very nice to see Pulumi take security seriously and always encrypt sensitive information.

What are the available encryption providers?

As we have seen previously, when using a self-managed backend like Azure Blob Storage, by default Pulumi uses a passphrase to encrypt sensitive data.

The passphrase is just one of the supported encryption/secrets providers but there are others:

AWS Key Management Service
Azure Key Vault
Google Cloud Key Management Service
HashiCorp Vault Transit Secrets Engine
Pulumi Service (used by default when using Pulumi Service as the backend)

As for the backend, you don't have to use the default encryption provider and can come with your own resource. These providers can be used whatever the backend you chose, which lets you many possibilities. Now let's see how to use Azure Key Vault as our encryption provider.

How to use Azure Key Vault as the encryption provider?

Let's first create a Key Vault:

$kvName="kv-iacstate-westeu-$random"
$vaultId=az keyvault create -g $rgName -n $kvName --enable-rbac-authorization true --query "id"

We retrieve its id so that we can use it to assign the correct role to my user to be able to perform cryptographic operations. With the --enable-rbac-authorization parameter we set the permissions model on the key vault to Role-Based Access Control but you can use the classic Vault access policies as well. I prefer using RBAC because I think it's more modern and more consistent with how we manage permissions on other Azure resources.

To assign the appropriate permission to the current logged-in user, we will need its current identifier in Azure that we can retrieve with the following command:

$myUserId=az ad signed-in-user show --query "objectId" -o tsv

We can then assign to this user the Key Vault Crypto Officer role that will allow us to create a key and encrypt/decrypt data.

az role assignment create --scope $vaultId --role "Key Vault Crypto Officer" --assignee $myUserId

The key to encrypt/decrypt data can be created with the following command:

az keyvault key create -n encryptionState --vault-name $kvName

By default, Pulumi CLI will try to use environment variables to authenticate to the key vault, so we need to tell it to use the Azure CLI instead as we gave the permission on the key vault to the user currently logged in:

$env:AZURE_KEYVAULT_AUTH_VIA_CLI="true"

Now that everything is configured, we can modify our previous command to create a new Pulumi project by specifying the encryption provider to use:

pulumi new azure-csharp -n AzureStorageBackend -s dev -y --secrets-provider="azurekeyvault://$kvName.vault.azure.net/keys/encryptionState"

Comparing with how Terraform handle state

Terraform is another very popular Infrastructure as Code platform with lots of similarities so I thought it might be interesting to look at how Terraform handles state compared to Pulumi.

Terraform has a SaaS platform called Terraform Cloud that can be used to manage the infrastructure state. It is similar to what Pulumi Service offers. However, when using Terraform the default backend is not Terraform Cloud but local filesystem. That is not better or worse, just a different choice HashiCorp (the company behind Terraform) did. Although I must say that when I started working on Pulumi, I found it easier not having to take care of where the state is stored and how it is managed, so maybe a SaaS backend by default is simpler.

On Microsoft documentation, there is a tutorial "Store Terraform state in Azure Storage" that shows how to use Terraform with an Azure Storage backend. I have done it and it is very similar to what we have done in this article with Pulumi. Instead of using a CLI command to configure the infrastructure to use Azure Blob Storage as the backend for the state, in Terraform, you configure it directly in one of the code files but the idea is the same. Both IaC tools store the infrastructure state in a JSON file in a blob container.

One big difference however is that by default Terraform does not encrypt sensitive information in the state file. As far as I know, there is no concept of secret providers in Terraform so no built-in solution. Terraform documentation just says to treat the state itself as sensitive data. That means when I created a storage account using Terraform with the Azure Blob Storage backend, the keys of my storage were available in plain text in my state file (as you can see in the image below).

You should not have this kind of security issue using Terraform Cloud and there are probably external tools to avoid this, but I think an IaC platform should be secure by default and that encryption of sensitive data should be built-in.

To conclude

You can find below the complete Azure CLI script used in this article:

# PowerShell variables used in the script 
$random=Get-Random -Maximum 1000
$location="West Europe"
$rgName="rg-iacstate-westeu-$random"
$saName="stiacstate$random"
$kvName="kv-iacstate-westeu-$random"

az group create -n $rgName -l $location

# Configure the Azure Blob Storage that will contain the state 
az storage account create -g $rgName -n $saName -l $location --sku Standard_LRS
# Set environment variables needed to write on the storage account
$env:AZURE_STORAGE_KEY=$(az storage account keys list -n $saName -g $rgName -o tsv --query '[0].value')
$env:AZURE_STORAGE_ACCOUNT=$saName
az storage container create -n iacstate

# Configure the Key Vault that will be used to encrypt the sensitive data
$vaultId=az keyvault create -g $rgName -n $kvName --enable-rbac-authorization true --query "id"
$myUserId=az ad signed-in-user show --query "objectId" -o tsv 
az role assignment create --scope $vaultId --role "Key Vault Crypto Officer" --assignee $myUserId 
az keyvault key create -n encryptionState --vault-name $kvName
# Use az cli to authenticate to key vault instead of using environment variables 
$env:AZURE_KEYVAULT_AUTH_VIA_CLI="true"

# Indicate pulumi to use the newly created azure blob storage as a backend
pulumi login azblob://iacstate
# Create and use a folder to store the infrastructure code
mkdir infra;cd infra;
# Create a new Pulumi project using the azure blob storage as the backend and the keyvault as the encryption provider 
pulumi new azure-csharp -n AzureStorageBackend -s dev -y --secrets-provider="azurekeyvault://$kvName.vault.azure.net/keys/encryptionState"
# Deploy the infrastructure
pulumi up -y

Using Pulumi without Pulumi Service was not complicated as I thought it would be. I like the fact that Pulumi is not limited to be used with Pulumi Service backend and secret provider. It gives us the choice to use what we want: if I want to use Google Cloud Storage as my back-end and AWS Key Management Service as my encryption provider I totally can. Many options are available and well integrated without requiring much work which is nice.

Yet honestly, I think that using Pulumi Service will be my default choice because of the many built-in features it offers (deployment history, concurrent state locking, collaboration functionalities, ...). It's free for individuals so I would not bother with a self-managed backend for individuals. For teams and companies, you have to pay (even if there is a monthly free grant of credits for the team plan) but I don't have enough perspective to say if it's worth it. You can find the pricing here if you want to see by yourself. I guess the choice between that and a self-managed backend will probably depend more on the project and the organization you are working for.

Why will I choose Pulumi over Terraform for my next project?

Alexandre Nédélec — Thu, 05 Jan 2023 09:00:00 +0000

In today's world of cloud-first applications, multi-cloud/hybrid cloud companies, and complex infrastructures, using infrastructure as code is essential. In recent years, Terraform has become one of the most popular IaC solutions, but its challenger Pulumi is quickly gaining traction. In this article, I will tell you why I think Pulumi is better and why I will choose it over Terraform for my next project.

But first, let's talk about what makes a good Infrastructure as Code solution.

What makes a good Infrastructure as Code solution?

There is no universal answer to this question, but I can give you the characteristics I am looking for in an IaC solution.

In my opinion, an IaC solution should be:

declarative. I think it is important to focus on what infrastructure we want to provision rather than how to provision it
open source. Beyond being a good thing, open source favors the adoption of technology and makes an ecosystem healthy with contributions from the community
multi providers. Even if I work mainly with Azure, companies tend to be multi clouds; projects often involve provisioning resources in different cloud providers and services. Moreover, beyond cloud providers, I want to be able to automate the provisioning of many things like my Azure DevOps or GitHub projects.
easy to learn, easy to use, and easy to be productive with. I love learning new things but even more when it's easy and I can be quickly productive with new technology.
up to date with main cloud providers' resources and features. IT (and specifically the cloud) is evolving very quickly. The infrastructure we provision needs to be able to benefit from the latest resources, innovations, security improvements... I don't want to have to wait for novelties to be available
flexible and customizable. Cloud infrastructures are more and more complex, and each project has its specificities so flexibility and the ability to easily write custom code to address these specificities are important
secure. Security in IT is of paramount importance (especially when dealing with infrastructure) and therefore should be built-in

Terraform and Pulumi have many similarities and some of the characteristics (like being declarative, open source, or multi providers) I mentioned above are present in both solutions. However, that is not the case with all these characteristics. Furthermore, Terraform and Pulumi differ in many other aspects that we will talk about in this article.

Pulumi, a modern IaC tool with many built-in features

Usually, tools that have been there for quite some time have more features than new tools. New tools bring modernity and innovative features but need a bit of time to catch up with all the features. This is not at all the case with Pulumi, it is even the opposite. Although Terraform is older (created in 2014 vs. 2018 for Pulumi), Pulumi has more built-in features (including key features) than Terraform. Moreover, some of Terraform features are restricted to its paid version Terraform Cloud 💸.

State, backends, and security

Both Terraform and Pulumi use code (HCL and programming languages respectively) to describe the desired state of an infrastructure that is compared to the current state of the infrastructure to know which operations (create, update, delete) to do on resources. The current state of the infrastructure is stored in a "backend" than can be for instance the local filesystem, AWS S3, Google Cloud Storage, Azure Blob Storage, or the SaaS offering of Terraform (Terraform Cloud)/Pulumi (Pulumi Service). Terraform Cloud and Pulumi Service are self-managed backends that offer similar functionalities (deployment history, collaboration functionalities, RBAC for an organization...).

The state stored in a backend contains sensitive data (secrets like connection strings 🔑) that you need to secure. Whatever the backend you choose, when using Pulumi the secrets in your state are always encrypted using an encryption provider. The default encryption provider depends on the backend but you can easily configure Pulumi to specify another encryption provider to use. The encryption provider can be a passphrase, AWS Key Management Service, Azure Key Vault, Google Cloud Key Management Service, HashiCorp Vault Transit Secrets Engine, or Pulumi Service. The ability to choose an encryption provider and to encrypt secrets in the state is not something Terraform supports. By default, Terraform will store the state in a local JSON file with the secrets in it 🙀. You probably won't run into security issues if you use Terraform Cloud, yet security should be built-in and not something you have to pay for.

You may not see this as a big concern as you are probably not storing your state locally but on a cloud storage (like an Azure Blob Storage) where access is restricted to only a few people. But let's imagine one of your storage access keys gets compromised. If you are using Terraform, someone could have access to all the secrets of your infrastructure. If you are using Pulumi he will not because all secrets in the state file are encrypted. And he will have trouble decrypting them because he would have to gain access to the encryption provider. Whether you use Azure Key Vault, AWS Key Management Service, or any other encryption provider, these are components whose purpose is to keep data safe 🔐, and that require proper permissions to have access to encryption/decryption keys. I am not saying you can't make your infrastructure safe with Terraform. (In my example above with an Azure Storage Account, you could always prevent the shared key authorization and use only Azure AD authorization to reduce the security risk.) I am just saying that Pulumi is secure by default, Terraform is not and extra work is required.

If you want to learn more about state, backend, security, and how Terraform handles state compared to Pulumi you can check this article where I talk about all. I also show how to use Azure Blob Storage as the backend and Azure Key Vault as the encryption provider for my infrastructure.

IaC brownfield development

Infrastructure as Code is not a new concept and before Terraform and Pulumi arrived, cloud providers' native solutions have been widely used to provision cloud infrastructure. Some infrastructures were also created manually. So today, there is a lot of existing infrastructure and most projects are not greenfield but brownfield projects. When choosing an IaC solution it is important to consider that and have the tools to integrate the existing infrastructure.

Both Terraform and Pulumi have an import CLI command to import existing infrastructure. Currently, Terraform can only import one resource at a time and can only import it into the state without generating the corresponding configuration code. Pulumi supports bulk import operations (using a JSON file to specify the resources to import) and generates the corresponding infrastructure code to add. It may seem like anecdotal features but they become important when you have a lot of resources to import.

Besides, Microsoft has recently announced a new tool Azure Terrafy to "quickly turn existing Azure infrastructure into Terraform HCL and import to Terraform state". I guess they did not want to wait for Terraform to have this feature built-in. This won't help you if you are using Terraform with AWS or GCP though.

Being able to import existing resources into Pulumi/Terraform is nice. However, for complex infrastructure, you will probably do it progressively or not at all if you want to keep some parts managed by other tools/teams. No matter the case, you will need your new infrastructure to coexist with the existing infrastructure not (yet) managed by Pulumi/Terraform. Both Terraform and Pulumi can reference existing infrastructure but Pulumi goes beyond that. First, it can reference other Pulumi stacks i.e Pulumi projects, which is especially useful when you are in a big organization or when your architecture is divided into microservices. Second, it can reference external states, i.e outputs from infrastructure created with other IaC tools than Pulumi. For instance, you could reference a Terraform state (whether it is a local tfstate or a remote state like a state in a Terraform Cloud workspace) or an AWS CloudFormation stack: you would get access to all the outputs of the corresponding provisioned infrastructure. That way, even if you have some existing infrastructure managed outside your Pulumi project, you can reference it and use it in your project without having to reference each resource with hard-coded names.

If you have already spent time building a complex infrastructure with another IaC tool and want to migrate to Pulumi while preserving the organization of your code and without rewriting everything with Pulumi SDKs from scratch, Pulumi has some conversion tools to help you with that. For instance, you can use the arm2pulumi converter to convert your ARM templates to Pulumi code written in your preferred programming language. You can try it yourself on the website to see what it looks like.

I like how Pulumi has been designed to work with brownfield projects: it offers all that is needed to coexist with existing infrastructure, adopting it, and converting it to Pulumi code if desired. It goes far beyond the built-in capabilities of Terraform on the topic.

Pulumi has a very well-written documentation about "adopting Pulumi" if you want to deep dive into working with existing infrastructure.

Environments and configuration

Thanks to its concept of stack, Pulumi has built-in support for deploying the same infrastructure in multiple environments. You can use configuration files to have different settings depending on the environment. For example, if you have a development environment and a production environment that need to have different sizes of VMs to avoid paying too much for the development environment, you will have 2 configuration files: Pulumi.development.yaml and a Pulumi.production.yaml. These files will contain the same setting to specify the size of the VM with different values. This concept of having a configuration file by environment is quite similar to what you would use when developing an application. In addition to that, you can use the Pulumi CLI to set settings as secrets that will be encrypted in your configuration files (using the same encryption provider that encrypts your state). So Pulumi offers you everything you need to easily and safely provision infrastructure in different environments.

Of course, Terraform can also provision infrastructure in different environments. Having different folders for the different environments used to be the way of handling different environments in Terraform which meant a lot of code duplication (unfortunately some companies still do that today😕). Because of that and other deficiencies of Terraform, different Terraform wrappers and frameworks (like Terragrunt or Terraspace) were created by the community to keep the infrastructure code DRY and structured.

If you want to know the differences between Terraform, Terragrunt, and Terraspace, BlogOps (the creator of Terraspace) has an interesting article on the topic.

In 2017, Terraform also introduced its built-in way of managing different environments with Terraform workspaces. I think it's great to have different alternatives, but the drawback is to have the Terraform community divided between people that are using pure Terraform and people using other tools built on top of Terraform. Moreover, whatever the tool used I find managing environments and configuration a bit more complicated in Terraform than when you use Pulumi: a lot of documentation and blog posts to read before knowing how to manage environments the proper way.

One important downside of Terraform concerning environments and configuration is that there is no built-in way of managing secrets. Unless you are a Terraform Cloud customer (in which case your secrets will be stored in workspaces as sensitive variables), you have to find a custom way to keep the secrets in your configuration safe. Gruntwork, the company behind Terragrunt has a detailed article about managing secrets in Terraform that I suggest you read. It describes different techniques to keep secrets safe (so not hardcoded in plain text in Terraform code): using environment variables, encrypted files, or a secret store. As you can read in the conclusion of this article (and see in the screenshot of this article below), all these options have trade-offs and require extra work in comparison to Pulumi where secrets encryption is integrated. Moreover, even if you succeed in managing secrets properly in Terraform, they will end up in plain text in Terraform state as we previously mentioned.

Embedded IaC through an API

To provision infrastructure using Terraform or Pulumi, you can use their respective CLI.

If you are using Terraform Cloud, you can also perform Terraform runs (called remote operations in the documentation which are concepts specific to Terraform Cloud) from there by using an API, UI controls or webhooks of your Version Control System (GitHub, GitLab, BitBucket, Azure DevOps, ...). These are useful capabilities but once again these are only available if you are using Terraform SaaS product.

Now, there are use cases where you would want to provision infrastructure programmatically instead of using a CLI. It can be for instance to:

provide self-service infrastructure to development teams in your organization (through developer portals for example)
integrate provisioning of infrastructure into your platforms and tools (whether it is your custom framework, CLI, or CI/CD workflow)
automate infrastructure provisioning for your custom needs
do complex deployments that mix infrastructure and application code such as database migrations

And for that, Pulumi has an Automation API which allows you to build, deploy, and manage infrastructure dynamically from your code thanks to an SDK instead of a CLI. I think it's awesome and unfortunately Terraform does not offer something like that. There would be much to say about Automation API (and that's something that will probably continue to evolve), yet the best is that you check the documentation to learn more about it.

What else?

Pulumi has many more built-in features where it stands out compared to Terraform but I can't cover everything in this blog post. The ones I previously talked about were the main ones in my opinion but you can check the Pulumi vs. Terraform page in Pulumi's documentation to read about other differences between Pulumi and Terraform. Other interesting capabilities of Pulumi like dynamic providers or testing will be discussed later in this article.

Providers

Why providers?

Providers are the reason why I think Terraform and Pulumi have a great future ahead. Instead of focusing on a specific cloud or platform (which is what Cloud Formation, Azure Bicep, or Google Cloud Deployment Manager do), Terraform and Pulumi allow you to provision resources in many different cloud providers and SaaS providers. That does not mean you will write the same infrastructure code to provision cloud resources on AWS and Azure. Of course not, each cloud provider has its specificities and the resources will be different on each platform so the code needs to be different as well. However, instead of having to use multiple IaC platforms (Cloud Formation and Azure Bicep for instance) if you need to provision resources from different clouds in your project, you will only use one (Terraform or Pulumi) with different providers.

You can see how this works in Pulumi on this schema from the documentation:

Today lots of companies are using multiple clouds to meet their needs and to avoid putting all their eggs in the same basket. And beyond cloud providers, a lot of other SaaS products are used in an organization and you will probably automate the provisioning of resources for these products too to make them available to your teams (whether it is a VCS or a monitoring platform). So being able to provision and manage all these resources from the same tools, using the same concepts and processes is a must-have, and that is what Pulumi and Terraform offer by supporting many providers 👍.

How does Pulumi benefit from Terraform ecosystem?

When Pulumi came out in 2018, instead of reinventing the wheel they choose to take advantage of Terraform Providers' mature ecosystem to build most of their own providers. Indeed, Pulumi created tools to adapt/bridge any existing Terraform provider.

To understand what it means, we have to talk about what is exactly a provider. According to Terraform's documentation, "providers are a logical abstraction of an upstream API. They are responsible for understanding API interactions and exposing resources". That means a provider defines a schema describing the resources available on a cloud provider API, and all the mappings (parameters, models, responses ...) needed to interact with this API. Instead of doing the same job of mapping everything, a Pulumi provider that is created by "bridging" a Terraform provider simply reuses the same schema, that's it. But, Pulumi itself does not use Terraform, they have a completely different engine.

If you are looking for a better explanation about how Pulumi "bridges" Terraform providers you can look at this article from Lee Briggs who work at Pulumi.

Why do I talk about all this? It's because I think it's great for Pulumi to be able to benefit from Terraform Providers ecosystem. Thanks to this, like Terraform, Pulumi supports lots of cloud providers and modern cloud SaaS offerings. And in the event there were a provider available in Terraform and not in Pulumi, it would always be possible for anyone to create a Pulumi provider out of this Terraform provider thanks to the Pulumi Terraform Bridge.

By the way, the fact that some Pulumi providers are created by adapting Terraform providers is completely assumed by Pulumi as you can read in Pulumi documentation.

The problem with Terraform providers

We have seen that Pulumi benefits from Terraform providers ecosystem. However, there is a major problem with Terraform providers (and so with corresponding Pulumi providers as well): they are implemented manually.

It has the following inconveniences for a provider:

it is more likely to contain bugs
it doesn't have full coverage of its corresponding API
it is always a little behind an API because it takes time for new resources or new features to be added

At the beginning of the article I explain that I wanted my IaC solution should be up to date with main cloud providers' resources and features and that is not the case with Terraform providers even if the community (Pulumi included) is doing a great job at contributing to Terraform providers to make new resources available.

Moreover, a version of a provider matches a version of the resources in the API. So you can't have 2 resources from different API versions coexist. For instance, let's say you need to use an old version of the Terraform provider for Azure because they are a lot of breaking changes in the latest version of the provider. You don't want to handle these changes yet as it involves some big changes in some of your resources. But in the same time, you want to use a resource that is only available in the latest version of the provider. Well in this case it's going to be complicated for you. The issue is that with Terraform providers you can't be very flexible with your resources and customize everything you want

What are Pulumi native providers?

In order to solve the problem described in the previous section, Pulumi introduced the concept of native providers for the providers Microsoft Azure, AWS, Google Cloud Platform, and Kubernetes. These providers are automatically built every day from the cloud providers' APIs 🎉. It has the following advantages:

100% API coverage, so all resources available including the ones in preview
Providers are always up-to-date with the APIs
Access to all the versions of the APIs so that resources from different API versions can coexist in a project (as you would have with a cloud provider native solution like Azure Bicep)

Honestly, these are good enough reasons to choose Pulumi over Terraform. If you are developing cloud applications, you don't want to be limited to what you can do by your IaC solution, especially when it concerns the major cloud providers you are probably using

It's worth noting that people from Microsoft seem also concerned about these limitations of the Terraform Azure RM provider as they announced a new Azure provider AzAPI, built on top of the Azure ARM APIs that can be used to have access to Azure features and services in preview. However, it seems that for other resources, Microsoft expects people to continue using the existing Terraform provider with its limitations.

I think generating the providers from the APIs is the right way of doing things. Unfortunately, it's only possible to create native providers for a cloud provider or a SaaS provider if its API exposes the necessary mapping. But if more APIs do that, more Pulumi native providers will probably be added in the future.

Another thing I appreciate a lot with these native providers: you work with the same "models" as the ones of the corresponding cloud. On the contrary, because a Terraform provider is hand-coded you will have a more or less thin abstraction layer and potential differences between the models. That's not a big deal but can sometimes complicate things because you have to understand how the Terraform models map to the cloud API models.

More about providers

If you have looked at Terraform registry, you may have seen that there is a huge amount of community providers. Does it mean Terraform is better than Pulumi? I don't think so: quantity does not mean quality. That's not me saying that there are many bad quality Terraform providers, not at all. That's me saying that there are probably lots of providers you don't care about. For instance, I assume you don't care that there is a Terraform provider to order a Domino's Pizza 🍕. Okay, that may be fun, but that's it. And concerning the more serious providers, a lot of them are just there to overcome the inherent limitations of HCL (not being a programming language) such as not being able to make an HTTP call without using a provider. You don't have these limitations with Pulumi where you use programming languages and their libraries.

We will talk more about that in the next section but being able to use a programming language and all its ecosystem is a true advantage of Pulumi over Terraform. There are some times when you need to provision some cloud resources and there is no provider to manage them (whether it be Pulumi or Terraform). If you are using Terraform you will have to wait for the community to implement this provider, if it ever really happens. If you are using Pulumi, you are using programming languages and therefore can implement anything you need (by using SDKs or making the API calls yourself). And I am not talking about implementing yourself a whole provider covering a complete API (which would require some time), but just implementing the resources you need.

For that, Pulumi has a concept of Dynamic Providers with which you implement the different CRUD operations for a resource so that you are still doing declarative infrastructure as code but with custom logic. It's like implementing on the fly a custom provider specific to your needs directly in your project. Dynamic providers' usage is not limited to supporting a cloud provider that does not yet exist in Pulumi, it is also to do any infrastructure task that no existing provider can help deliver (see examples in this article).

Using programming languages: the best way to do IaC

Pulumi's approach is to use programming languages to write your infrastructure code. On the opposite, Terraform's approach is to uses a DSL called HCL (that stands for Hashicorp Configuration Language). It's worth reminding that both tools are declarative, even when using an imperative language.

When comparing IaC, the big debate ⚡ is often: show we use Domain Specific Languages (DSL) or programming languages? If you have read the previous sections of this article you know this is just one of many questions, there are other important aspects to consider. Nevertheless, it's an important question because there is more to it than simply a question of personal preference. In my opinion, using programming languages to write your infrastructure code is the right way of doing things and is the future of infrastructure as code. Let me explain to you why and how it is particularly great to use programming languages with Pulumi.

Better aligned with the DevOps culture

DevOps aims at continuously delivering value to end-users by removing the barrier between software development and IT operations. As one of the practices of DevOps, Infrastructure as Code should help bring closer people from Development teams and people from Operations teams.

Therefore I don't think using different languages, tools, and practices for the application development and the infrastructure development is the right approach. And yet, this is what you do when you write your infrastructure code in HCL while the application code is written in TypeScript or C# for instance. Unfortunately, in some companies, I think using Terraform reinforces the Development and Operations silos more than anything else. It's difficult to deliver value to a customer if that means for a developer to create a ticket to the Operations team just to add a new setting in a web app because only them have access and knowledge of the Terraform code 😿.

I truly believe that the proper way of adopting DevOps practices is to have multidisciplinary self-organizing teams. And what a better way to make software developers, IT operations people, security engineers, ... collaborate in such teams than by making them "speak" the same language, use the same tools, and adopt the same engineering practices. That's what using programming languages for the infrastructure code is about and that's what Pulumi is about.

Be productive faster and more

Whatever the IaC solution you choose, you will have to learn new concepts that may not be obvious. Yet, writing the infrastructure code will be easy to learn if you are using a programming language you already know. On the contrary, if you use a DSL, it will add another thing for you to learn (especially HCL that I don't find very intuitive).

Using Pulumi you will not only be able to use the programming language you know but also your favorite IDEs, as well as the libraries and the tools you are familiar with 🛠️. The programming languages supported by Pulumi (TypeScript/JavaScript, Python, Go, .NET languages, Java languages, and probably more to come) are used by lots of people for software development. Therefore IDE support (typing, static analysis, code completion....) is already great and tooling in general better than the tooling for an IaC DSL could ever be.

So in addition to learning faster IaC using programming languages you will be more productive too. That is also true for people not coming from development but from ops, they probably already have some scripting knowledge (Bash, PowerShell, Python...), that's why programming languages can be a good fit for them as well.

Making people quickly productive on an IaC solution is important because as everywhere in IT, in IaC field it's hard to find skilled people to recruit so it's sometimes easier to train people already in your company. Speaking of that, I hear sometimes people saying that: as Terraform is currently more used than Pulumi (due to Pulumi being more recent), it will be easier to hire people who know Terraform than people who know Pulumi. Yes, that's true, but it will be much harder to find people who know HCL than people who know TypeScript, Python, .NET, or Go.

Independently of HCL, I find Terraform to be more complex to learn than Pulumi, with a lot of different concepts to grasp (variables, local values, data sources, configuration, workspaces, modules) that are unique to Terraform. Pulumi felt much easier. Of course, learning is unique to each individual so you may have a different opinion but this has been my experience.

A better developer experience

The developer experience is so much better when using programming languages instead of a DSL.

If you are not familiar with the term Developer Experience or DX, it's like User Experience but for software engineers using digital products (developer tools, IT solutions, platforms...).

I already talked about the better code completion of Pulumi which is great to know which resource you can create, what properties can be set, which ones are required, and what are the possible values.

There is also the fact that you can debug infrastructure code because it's just code in a program. With Automation API, Pulumi can be used from anywhere (a console application, a custom CLI, a web application, ...) and easily debugged. Good luck debugging Terraform code 😉. You even have something similar to hot reload for infrastructure with pulumi watch command (see my article on the topic).

Another topic is testing. You can only do unit testing (understand the testing of components without deploying real infrastructure) with code written in a programming language. Pulumi allows you to write unit tests by mocking the external dependencies using your usual test and mock frameworks. Integration testing/end-to-end testing however can be done with both Pulumi and Terraform. If you do a bit of search, you will find out that there are several frameworks to write end-to-end tests for Terraform and they require you to write your tests in Go or Ruby (so finally using a programming language after all 😀). You can read more about testing with Pulumi in the documentation.

More capabilities

Using a programming language you are not limited to what providers or modules can do. You have the power of a programming language to implement what you need (for example using the dynamic providers I talked about before). Some people are afraid of that, I don't think they should. Programming languages have static analysis mechanisms to ensure best practices are respected in the code. Pulumi also provides policy as code to let you write the rules you want your infrastructure to follow (it could be rules about security or cost for instance).

Terraform has a great community that creates packages and tools for Terraform. As Pulumi is younger, the ecosystem is not as developed as Terraform's. However, when you use Pulumi you use programming languages that have a huge ecosystem from which you can benefit ❤️.

The future

I have given several reasons why I think programming languages is the best way to do IaC. Today, the majority of people are using DSL based on YAML or JSON to write infrastructure code but things are changing at a great speed. Following the example of Pulumi, there are more and more IaC tools that support programming languages to write infrastructure code, AWS CDK for instance. Even Terraform itself is starting to see the limits of HCL and has launched its CDK in beta. Unfortunately at the time of writing it's still in preview since July 2020, has some limitations, and is not yet mature according to the documentation. Pulumi has a clear head start but it's very interesting to see the whole IaC ecosystem evolving in this direction.

Final thoughts

Summary

To sum up, I will choose Pulumi over Terraform for my next project because:

it has 100% resource coverage of my cloud provider and more flexibility
it allows me to be more productive using languages, tools, and libraries I am already familiar with
it has more built-in functionalities and is more modern
it is easier to learn and use (something that my teammates will appreciate)
it is secure by default ### Disclaimers

Just like any other article on my blog, "the opinions expressed herein are my own and do not represent those of my employer or any other third-party views in any way".

This article is not sponsored, I don't own any shares in Pulumi (unfortunately 😉), and I don't work for Pulumi. That means the article just reflects my point of view, the point of view of a cloud developer interested in infrastructure who has worked with both Terraform and Pulumi, and much prefers Pulumi.

Even if I like Pulumi a lot as it is very nice working with it, I have tried to remain as objective as possible in this article. You will probably not agree with everything I said, but I hope you will understand what are my reasons for choosing Pulumi for my Infrastructure as Code and that it will help you with your choice, whatever it is.

Is Terraform bad?

Not at all. I would have a hard time saying Terraform is bad and Pulumi is awesome when they rely on similar concepts like declarative infrastructure as code, state file to store the current state of the infrastructure, and providers to support multiple cloud providers and services. In fact, I think Terraform is a great Infrastructure as Code solution, just not the best one in my opinion.

I think Terraform has truly revolutionized infrastructure as code when it came out in 2014. At that time, cloud providers native solutions were too verbose and too complex, and there was no true alternative to them. Terraform came to simplify that and has enabled people to use the same IaC solution to deploy resources of different cloud providers. Today, things have changed: cloud providers' native solutions have evolved, there are new modern alternatives to Terraform (and I am not talking only about Pulumi), and Terraform has shown some limitations.

Because Terraform is used in many companies, benefits from a rich ecosystem, and has a great community, you will probably not make a big mistake if you go with Terraform instead of Pulumi for your next project. However, if you do so, you have to be aware of the limitations and weaknesses of Terraform that I talked about in this article. This is something very important because each project has its needs and constraints, so maybe Terraform's limitations are not a big deal for your use case, maybe it is. Just make sure which one it is.

Despite all I said, there is one thing I like very much about Terraform, it's its community. Because many people have been using it, and for some years now, there are a lot of examples on the internet and many interesting tools or frameworks have been created around it.

Is Pulumi perfect?

No Pulumi is not perfect, no IaC solution is, there are always things to improve.

For instance, a few Pulumi features are not yet available in .NET like Dynamic providers or policy as code (not a real problem as you can write them in TypeScript or Python even if your stack is in .NET).

I also hope more native providers will be created (even if I know it's not only up to Pulumi) because I think native providers are a game-changer. In particular, I would want to have a native provider for Microsoft Graph (you can vote for the issue here).

More generally, I think Infrastructure as Code is evolving quickly and there are many things yet to come. But I am confident Pulumi will continue to bring more features and innovations to this space 🚀.

Which Infrastructure as Code solution should you choose?

To be honest, I can't think of any good reason why I would choose Terraform over Pulumi for a project. But that's just me.

If you have already invested a lot of time learning HCL/Terraform and are happy with it, you should probably continue using Terraform.

If you don't know either Terraform or Pulumi, I would suggest you use Pulumi even if you don't know any programming language. It's in my opinion the right way to do infrastructure as code. Furthermore, it is better to learn a programming language that could be useful somewhere else than HCL which you will only use in HashiCorp products.

I would like to emphasize one thing: when choosing an IaC solution, make an informed decision. Do not choose Terraform because your favorite influencer promotes it. Do not choose Terraform because most people around you use it. The same is true for Pulumi. Do not choose Pulumi just because I say you should. Read articles from people with other points of view. Check what topics are important for you, and compare both solutions on these topics. Make up your own mind.

In the end, you should choose the solution you feel is more appropriate to you and your project, and that you think will be easier for you to learn and use in the long term. If it's Terraform then go with it! If it's Pulumi, welcome to modern Infrastructure as Code!

When Pulumi met Nuke: a .NET love story

Alexandre Nédélec — Sun, 18 Dec 2022 00:00:00 +0000

Today is a great time to be a developer:

there are plenty of languages and frameworks to choose from to build an application
there are very powerful IDEs and tools to help us write, analyze, refactor, test and debug code
there are many nice CI/CD platforms that allow us to package and deploy our applications anywhere
thanks to cloud platforms and infrastructure as code we can provision infrastructure on-demand in an automated way

Yet, sometimes it seems quite complex and time-consuming to deploy an application in the cloud.

As a .NET developer, do I really need to master YAML, and Domain Specific Languages like HCL to deploy a simple ASP.NET Core API in Azure? Should I forget about local debugging when developing CI/CD pipelines? Do I have to learn everything from scratch each time I use another CI/CD platform?

Thanks to Nuke and Pulumi, I don't think so and that is what we are going to talk about in this article.

The scenario

They are already lots of great articles about Pulumi or Nuke, so I won't spend time explaining what they are and why you should use them. Instead, I will show you how you can use them together with an example.

My scenario is the following: I have a very basic ASP.NET Core API that I want to deploy to Azure App Service using a CI/CD pipeline.

To do that, I want to use my existing .NET skills and code everything with the language and tools I know and love.

Steps of the CI/CD pipeline

There are often two main steps (or stages or whatever you call them) in a CI / CD pipeline: the packaging and the deployment.

To package a .NET application, we have to first restore the dependencies, then compile the application and publish it. So my Package step is composed of 3 steps.

💬 A dotnet publish does an implicit restore and build the application so only one step could be used but I like separating these steps for clarity. Moreover it is sometimes needed, for instance when you are restoring packages from private Nuget feeds.

I said the application needed to be deployed to Azure App Service but I don't have an existing Azure App Service resource, and I don't want to manually create one. So I also need a step to deploy the infrastructure

It seems fine. I will just add another optional step at the beginning to clean the temporary files I could have created on previous builds.

If your pipeline runs on a hosted agent/runner (managed by the CI/CD platform you use), the Clean step might not be very useful but I intend to also run this pipeline locally.

Now, that we know the different steps of our pipeline, let's get to the code.

Getting started with the code

Code organization

I put all the code in the same Git repository because:

it makes sense as everything is linked
it's easier to maintain (all the code in one place)
it's easier to version (one tag on one commit in one repository)

I chose to organize my repository with the following folders:

📁 src ➡️ for the application code of the API
📁 infrastructure ➡️ for the infrastructure code that provisions the App Service
📁 build ➡️ for pipeline code that builds and deploys the application
📁 artifacts ➡️ for the package created by the pipeline

Create the C# projects

To create the API project, we just use the default ASP.NET Core API template in .NET 7 that creates a simple Weather API.

I can initialize the infrastructure project using the Pulumi CLI new command with the azure C# template:

pulumi new azure-csharp

I will show later how to modify the code of the template to provision an App Service.

You can check Pulumi Getting Started with Azure tutorial to see how to set up your environment and start creating Azure resources in C# (or in another language).

To initialize the build project, we can use Nuke's .NET global tool as explained in the documentation:

nuke :setup

Everything in .NET

What I like about using Pulumi (in .NET) and Nuke is that all the code is just C# code. My infrastructure project and my build project are standard .NET console applications. And I can open the 3 projects (API, infrastructure, and build) in the same solution in my preferred IDE.

Why does it matter? Because any .NET developer in a team would be able to understand and maintain this code. How many times have you seen a project slow down because the person responsible for the infrastructure code written in YAML, JSON, Bicep, or HCL was on vacation or ill? How often have you been stuck because the only few people in the team that knew how to modify the YAML pipelines were not available?

But it's not a question of knowledge only. It's also because the developer experience of writing build or infrastructure code in .NET is much better than writing code in YAML or other declarative "languages".

I talk a lot about the benefits of using programming languages for infrastructure code in my article "Why will I choose Pulumi over Terraform for my next project?" if you have not read it yet.

Implementing the pipeline steps from Clean to Publish

The Nuke pipeline

Here is what looks like the default build project after its creation:

The main method is contained in a Build.cs file. This file contains the steps of the pipeline that are called Target in Nuke. We can set the dependencies between targets.

💡The build project is a .NET console application so it works out of the box in any .NET IDE or from the command line. But to be more productive you can install a plugin for your IDE that will add snippets and a way to easily debug each target individually.

As you see we can define properties with the attribute Parameter if we need to pass parameters to our pipeline, like the Configuration parameter.

The Clean target

We can define the Clean target like that:

Target Clean => _ => _  
    .Before(Restore)  
    .Executes(() =>  
    {  
        SourceDirectory.GlobDirectories("*/bin", "*/obj").ForEach(DeleteDirectory);  
        EnsureCleanDirectory(ArtifactsDirectory);  
    });

This code deletes all the bin and obj directories of the source directory. It also deletes the content in the artifacts directory. Nuke overloads the division operator to allow us to easily define paths in the project.

AbsolutePath SourceDirectory => RootDirectory / "src";  

AbsolutePath InfrastructureDirectory => RootDirectory / "infra";  

AbsolutePath ArtifactsDirectory => RootDirectory / "artifacts";

The Restore target

To restore .NET dependencies, we can use the dotnet restore command. Nuke supports executing CLI tools and has even auto-generated CLI wrappers for some common tools like dotnet CLI to use a Fluent API instead of string interpolation to pass parameters.

Target Restore => _ => _  
    .Executes(() =>  
    {  
        DotNetRestore(_ => _.SetProjectFile(Solution));  
    });

The Compile target

The compile target uses the dotnet build command. We can start to see the benefits of using this Fluent API that provides us with autocompletion and documentation. For instance, as we already restored the dependencies in the previous step, we can set the --no-restore option using the EnableNoRestore auto-generated method.

Target Compile => _ => _  
    .DependsOn(Restore)  
    .Executes(() =>  
    {  
        DotNetBuild(_ => _  
            .SetProjectFile(Solution)  
            .SetConfiguration(Configuration)  
            .EnableNoRestore());  
    });

The Publish target

The publish target uses the dotnet publish command and then creates a zip api.zip of the resulting package in the artifacts directory.

Target Publish => _ => _  
    .DependsOn(Compile)  
    .Executes(() =>  
    {  
        DotNetPublish(_ => _  
            .SetProject(Solution.CSharpEverything_Api)  
            .SetConfiguration(Configuration)  
            .EnableNoBuild()  
            .SetOutput(ApiPackageDirectory));  

        ZipFile.CreateFromDirectory(ApiPackageDirectory, ArtifactsDirectory / "api.zip");  
    });

💡If you need more compressing archives options, you can check Nuke documentation, they have some utilities to do more complex scenarios.

You may have noted on the line where I set the project that I have strong-typed access to the projects in my solutions. This is possible by adding this field with the Solution attribute and its GenerateProjects property set to true.

[Solution(GenerateProjects = true)]  
readonly Solution Solution;

🪄 It looks like magic but it's not! Nuke uses a source generator to do that behind the scenes.

Provisioning the App Service with Pulumi

The Pulumi project

By default, the infrastructure code is contained in the Program.cs file of our project. The resources to provision are declared in the lambda in parameter of the Deployment.RunAsync method.

💬The project uses the top-level statement feature of C#.

As we don't have many resources to declare for our scenario we will keep all the code in the Program.cs file but that is not what you would do in a more complex project.

Azure resources to provision

There are 3 Azure resources we need to create in our stack (instance of a Pulumi program):

a resource group to contain the different Azure resources
an App Service Plan which defines the set of compute resources for a web app to run
a Web App / App Service which is where the API will be deployed

var resourceGroup = new ResourceGroup($"rg-{Deployment.Instance.ProjectName}-{Deployment.Instance.StackName}");  

var appServicePlan = new AppServicePlan($"plan-{Deployment.Instance.ProjectName}-{Deployment.Instance.StackName}", new AppServicePlanArgs  
{  
    ResourceGroupName = resourceGroup.Name,  
    Kind = "App",  
    Sku = new SkuDescriptionArgs  
    {  
        Tier = "Basic",  
        Name = "B1",  
    },  
});  

var appService = new WebApp($"app-{Deployment.Instance.ProjectName}-{Deployment.Instance.StackName}", new WebAppArgs   
{   
    ResourceGroupName = resourceGroup.Name,  
    ServerFarmId = appServicePlan.Id  
});

The code is quite simple, and because we are writing C# in our IDE, we have autocompletion and everything we need to make writing the infrastructure code easier.

💡If you are used to Azure Bicep or ARM templates, the names of the classes or properties will look familiar to you. It's because we are using Azure Native, which is a Pulumi native provider that is generated from Azure APIs.

Stack outputs

Provisioning the cloud resources we need is great we have to think about the next step which is to deploy our API on these resources. So what will we need for that?

First, we will need to have the name of the provisioned App Service. That's easy it's the property Name of the appService variable.

Second, because we are going to use the Kudu API to zip deploy our application to the App Service, we will need the site credentials (aka the Publishing Profile Credentials). These can be retrieved in the Pulumi program using the following code:

var publishingCredentials = ListWebAppPublishingCredentials.Invoke(new()  
{  
    ResourceGroupName = resourceGroup.Name,  
    Name = appService.Name  
});

💬 Using the Kudu API is just one of the many ways to deploy a zip package to an App Service. I could have chosen another way like using the Azure CLI, in that case retrieving the site credentials would not have been needed.

Pulumi, like Terraform, has this concept of stack output where outputs are information about your stack/infrastructure that you want to expose. That is exactly what we need to export our App Service name and our site credentials so that they can be retrieved later by the Nuke code that will take care of the application deployment. To export these values we can return them in a Dictionary like that:

return new Dictionary<string, object?>  
{  
    ["publishingUsername"] = Output.CreateSecret(publishingCredentials.Apply(c => c.PublishingUserName)),  
    ["publishingUserPassword"] = Output.CreateSecret(publishingCredentials.Apply(c => c.PublishingPassword)),  
    ["appServiceName"] = appService.Name  
};

You might notice that we use the Output.CreateSecret method to create outputs for our publishing credentials. The aim is to tell Pulumi to treat these values as secrets what it will do by encrypting them in the state file for extra protection (that is not something Terraform does by the way).

Implementing the Provision Infrastructure step

To deploy the infrastructure, we can use the pulumi up command. We will write the code in a fluent way as we did with the dotnet CLI:

AbsolutePath InfrastructureDirectory => RootDirectory / "infra";

Target ProvisionInfra => _ => _  
    .Description("Provision the infrastructure on Azure")  
    .Executes(() =>  
    {  
        PulumiTasks.PulumiUp(_ => _  
            .SetCwd(InfrastructureDirectory)  
            .SetStack("dev")  
            .EnableSkipPreview());  
    });

Deploying the ASP.NET Core API to Azure App Service

I previously said we were going to use the Kudu API to deploy our application. You can check the documentation about that but concretely we will do a POST request to the zipdeploy endpoint using Basic authentication.

To retrieve a stack output, we can use the pulumi stack output command. To avoid duplicating the code I wrote a short method:

string GetPulumiOutput(string outputName)  
{  
    return PulumiTasks.PulumiStackOutput(_ => _  
            .SetCwd(InfrastructureDirectory)  
            .SetPropertyName(outputName)  
            .EnableShowSecrets()
            .DisableProcessLogOutput())  
        .StdToText();  
}

The step itself is not very complicated, just standard C# code using an HttpClient to send a POST request (with our application package as the content) to the Kudu API.

Target Deploy => _ => _  
    .DependsOn(Publish)  
    .After(ProvisionInfra)  
    .Executes(async () =>  
    {  
        var publishingUsername = GetPulumiOutput("publishingUsername");  
        var publishingUserPassword = GetPulumiOutput("publishingUserPassword");  
        var base64Auth = Convert.ToBase64String(Encoding.Default.GetBytes($"{publishingUsername}:{publishingUserPassword}"));  

        await using var package = File.OpenRead(ArtifactsDirectory / "api.zip");  
        using var httpClient = new HttpClient();  
        httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", base64Auth);  
        await httpClient.PostAsync($"https://{GetPulumiOutput("appServiceName")}.scm.azurewebsites.net/api/zipdeploy",  
            new StreamContent(package));  
    });

💡 George Dangl already wrote a nice article about using Nuke to deploy an application to Azure App Service using the Kudu API, so you can have a look at it. The code in the article is similar to the one we have here except that the credentials don't come from Pulumi outputs but from an Azure Key Vault.

What I like about this approach is that you know exactly what you are doing, and the deployment logic is not hidden from you in an obscure YAML task whose code you will never read (yes I am talking to you Azure Pipelines and GitHub Actions 😃).

But the awesome part in Nuke is that you can put a breakpoint in the code and debug it locally. If you need to modify your pipeline, you don't need to write YAML code modifications without knowing if it would work or not 🤞, commit and push your modifications, wait for an agent to run the changed pipeline in the cloud, wait for it to fail, browse the logs to try to understand the problem, and try again until it works.

Final pipeline

If I fold everything, the pipeline code we created looks like that:

I think it is quite clear with the different steps/targets defined with their dependencies/order. Yet if this is not clear enough for you, you can use the nuke --plan command to display a visual representation of the pipeline (how cool is that !?)

Let's execute the complete pipeline:

If I go to my Azure portal I can see the new Azure resources, among them an App Service where my Weather API is deployed.

Conclusion

Improvements to the example pipeline

The pipeline I have shown in this article is just a simple sample. They are lots of things that could be done to improve it. Beyond obvious ones like adding a Test target or using GitVersion to version the package, I want to talk about some choices I made in the pipeline implementation that may not be the best ones.

As I said there are many ways to deploy a package to an App Service. While using the Kudu API is fine and allowed me to show you how we can use Pulumi stack outputs to retrieve publishing credentials, it might be a bit limited in some cases and involves a bit of manual code to make the HTTP request. A good alternative would be to use the Azure CLI that has a command for that. But my preferred option would be to use the Azure Resource Manager libraries for .NET. Unfortunately this SDK is quite new and miss samples on how to do that.

Speaking of SDK, Pulumi has an API called the Automation API to use the Pulumi engine as an SDK. I think it would be a better option than using the Pulumi CLI. Generally speaking, I think using SDK instead of CLIs to write the targets of a pipeline brings more power, more flexibility, and a better developer experience.

About Nuke and CI/CD

Nuke has many features I did not show in this small example. If we add some attributes to the pipeline code, Nuke can generate YAML workflow files to execute the Nuke pipeline. When executing the pipeline locally everything works fine because I am logged in to Pulumi CLI and Azure CLI in my terminal but I have to add secret parameters to my Nuke pipeline (a Pulumi token and an Azure Service Principal identifier/password) to make the authentication works when the pipeline is run from a CI/CD platform runner/agent.

Moreover, there are many things I don't know yet about Nuke because I am just starting to use it. That is why I advise you to have a look at its documentation, at some resources and start playing with it by yourself.

In the future, I see myself using Nuke for most of my CI pipelines, and not only for .NET projects (because I can run any CLI tools from Nuke, it also works for front projects where I would use the pnpm CLI for instance). I am not saying that because I am afraid of YAML or because I'm not familiar with ready-made tasks like Azure Pipelines tasks or GitHub Actions. I have been using Azure Pipelines for several years now and I have also played a bit with GitHub Actions. They are good platforms but lack local debugging and the great developer experience provided by a tool like Nuke. So I will continue using them but to run my Nuke pipelines 😉.

The Ops Community ⚙️: Alexandre Nédélec

Create an Azure-Ready GitHub Repository using Pulumi

What's an Azure-Ready GitHub repository?

The GitHub part

The Azure part

The problem with secret credentials

The complete solution to implement

Why use Pulumi in that context?

Automate the creation of the Azure-Ready GitHub Repository

Create the Pulumi project

Create the repository on GitHub

Create the identity in Azure Active Directory for the GitHub Actions workflow

Authorize the Service Principal to provision resources on the subscription

Add the configuration for the GitHub Actions workflow

Create the GitHub Actions workflow

Test the Azure-Ready GitHub Repository

To conclude

Additional information

Potential Enhancements

Related articles

Complete code solution

4 tips about GitHub Actions environment variables and contexts

Tip n°1: Environment variables syntax depends on the shell you are using in your job

Tip n°2: Do not use your repository GITHUB_TOKEN in tasks that need to trigger another workflow.

Tip n°3: Assign information from the event triggering a GitHub Actions workflow to a PowerShell variable.

Tip n°4: Enable debugging logs to help you understand what is going wrong in your workflow

How to provision an Azure SQL Database with Active Directory authentication

Why this article?

An Azure AD user as our SQL Server administrator

Create the Azure SQL Server and its database.

Grant SQL Database access permissions to Azure AD entities

New "SQL Server Provider"

Custom C# code

Command provider with the sqlcmd utility

Implement the database permissions for an Azure AD Group

Allow the machine running the Pulumi program to connect to the SQL Server

Create the Azure AD group that will be given access to the database

Assign the roles to the Azure AD group using the Command provider

Results

Conclusion

IaC Hot Reload with Pulumi Watch

Developing and deploying Cloud Infrastructure

The need for a hot reload-like experience when doing IaC

Using Pulumi Watch

Pulumi with an Azure Blob Storage backend

A quick reminder about states and backends

What is this state we need to store?

What "backends" can we use to manage the infrastructure?

Using Pulumi with the Azure Blob Storage backend

What do we need?

How to create and configure the Azure Blob Storage backend?

How to provision your project infrastructure using the Azure Blob Storage backend?

Managing state sensitive data

Why is it needed to protect sensitive data in the state ?

What are the available encryption providers?

How to use Azure Key Vault as the encryption provider?

Comparing with how Terraform handle state

To conclude

Why will I choose Pulumi over Terraform for my next project?

What makes a good Infrastructure as Code solution?

Pulumi, a modern IaC tool with many built-in features

State, backends, and security

IaC brownfield development

Environments and configuration

Embedded IaC through an API

What else?

Providers

Why providers?

How does Pulumi benefit from Terraform ecosystem?

The problem with Terraform providers

What are Pulumi native providers?

More about providers

Using programming languages: the best way to do IaC

Better aligned with the DevOps culture

Be productive faster and more

A better developer experience

More capabilities

The future

Final thoughts

Summary

Tip n°2: Do not use your repository `GITHUB_TOKEN` in tasks that need to trigger another workflow.

Command provider with the `sqlcmd` utility