Background

Before digging in to the solution, let's take a quick look at the different pieces involved and how they relate to this sceNario.

ACR webhooks

With webhooks in ACR you can register for HTTP notifications when images are pushed (or deleted).

An example usage of webhooks is to use Brigade to respond to new images pushed to your registry to kick of a deployment of the new version (or something like that): example.

Geo-replication

If you're deploying your services in Azure then a definite benefit of ACR is that your images are network-close to where you are deploying them. If you are deploying services across multiple regions then having your images in each of those regions preserves this network-locality benefit. Whilst you could deploy separate ACR instances in each region and update your build to push to each region, ACR lets you have one logical registry instance that automatically replicates images across the regions that you choose. This is pretty cool - you get a single registry endpoint that you use to push/pull and the images automatically replicated across your chosen regions. When you push/pull you are directed to the nearest replicated instance for performance.

However, as mentioned earlier the webhooks are fired per-region. For some scenarios this is desirable but for others you might want to get a notification once the image that you've pushed has been replicated across all the regions you have configured. To achieve this with minimal effort (and cost) we'll use Azure Durable Functions...

Azure Durable Functions

Azure Durable Functions build on top of Azure Functions and add an orchestration/coordination layer. There is some great documentation that shows some of the common patterns that you can use Durable Functions for. The pattern that we will use here is the External Event pattern (also referred to as Human Interaction in some of the documentation scenarios).

Durable Functions just hit General Availability for C# on Functions v1, so for this post I will show C#. There is preview support for JavaScript Durable Functions on Functions v2 with support for more languages coming.

Creating the solution

The first part of the solution will be an HTTP-triggered function. This will be the function that subscribes to the ACR webhook.

We will also have an orchestration function. This will be responsible for determining whether we have had notifications from all of the regions. You can have multiple instances of an orchestration, each having its own set of state. We will have an instance of the orchestration per set of regional notifications. The id property of the webhook body is the id for the logical operation for the registry, i.e. it is the same across regional webhook invocations for the same image push/delete, so we will use this as the instance id for our orchestration.

Each invocation of the HTTP-triggered function will get a reference to the orchestration instance for the for creating the orchestration instance if required. (Typically an orchestration instance is created without specifying the ID, but in this case we want to use the ID from the webhook notification to allow us to route notifications to the correct instance.) Once the trigger function has the reference to the orchestration instance it will raise an external event for the region that the notification corresponds to. In this way the trigger function translates the webhook notification for each region into a Durable Function external event for each region.

Inside the orchestration function we can call WaitForExternalEvent to wait for the event for each region. This is an async method so returns a Task. Rather than awaiting these Tasks we capture them all and pass them to Task.WhenAll which gives us back a new Task that represents all of the external event Tasks completing. By awaiting this new Task we handle the join or fan-in over the notifications.

Show me the code

All of this is handled in the sample code for the blog post.

I named the HTTP-triggered function "ImagePush"

[FunctionName("ImagePush")]
public static async Task<HttpResponseMessage> ImagePush(
    [HttpTrigger(AuthorizationLevel.Function, "get", "post")]
    HttpRequestMessage request,
    [OrchestrationClient]
    DurableOrchestrationClient starter,
    TraceWriter log)

Notice the DurableOrchestrationClient that is passed in. This is a special type for use in Durable Functions and lets us create and query orchestration instances, as well as raise external events against them (as we'll see later).

The HttpRequestMessage parameter gives us access to the HTTP Request that triggered the function (in our case the webhook notification). When I registered the ACR webhooks I simply added a querystring parameter to the function URL to identify which region the webhook is firing for. The following code retrieves this:

var query = request.RequestUri.ParseQueryString();
var region = query["region"];

Similarly, the request is used to read the body of the HTTP Request to retrieve the notification id. From there, we look up the orchestration instance and create it if required:

var status = await starter.GetStatusAsync(instanceId);
if (status == null)
{
    await starter.StartNewAsync("WaitForAllRegions", instanceId, notification);
}

And then finally raise the event for that region that the webhook fired for

await starter.RaiseEventAsync(instanceId, GetEventName(region), null);

Now that we've seen the core parts of the trigger function , let's turn to the orchestrator function. It has a pretty simple declaration:

[FunctionName("WaitForAllRegions")]
public static async Task WaitForAllRegions([OrchestrationTrigger] DurableOrchestrationContext context)

This time we have a Durable Functions orchestration context that allows us to call into activity functions or wait for external events. In our case we want to wait for an external event for each region that we're replicated to. The orchestration context has a WaitForExternalEvent method that allows us to wait for an external event by awaiting the Task it returns. In our case, we won't await the Task - instead we will build up a list of Tasks (one per region). We can then take this List and pass it to Task.WhenAll. This gives us a single Task that represents all of the Tasks in the List completing.

var eventTasks = new List<Task>();
foreach (var region in GetRegions())
{
    eventTasks.Add(context.WaitForExternalEvent<object>(GetEventName(region)));
}
Task replicationCompletedTask = Task.WhenAll(eventTasks);
await replicationCompletedTask

By awaiting the replicationCompletedTask we won't continue with any further code until that Task has completed. Since that was created using Task.WhenAll for the Tasks for the external events, that corresponds to all the external events having been raised.

The last step is to take some action at this point, so we call into an activity function:

await context.CallActivityAsync<string>("FirePushNotification", notification);

The activity function is just a placeholder function in the sample code, but you could use this function to make an HTTP call to notify another system, post to teams/slack, ...

[FunctionName("FirePushNotification")]
public static string FirePushNotification([ActivityTrigger] WebHookNotification notification, TraceWriter log)
{
    log.Info($"TODO: All regions are sync'd - add whatever onward notification you want here! Repository: {notification.Target.Repository}, Tag: {notification.Target.Tag}, Id: {notification.Request.Id}");
    return $"All regions are sync'd!";
}

What's with all the Tasks?

I really like how the Durable Functions runtime exposes Tasks as the interface to the units of work (calling activity functions, waiting for external events) as it means that we can bring in experience of working with Tasks from other contexts. We can use await and Task.WhenAll that are familiar from other async programming in C#.

SIDE NOTE:

It is important to note that while these give the illusion that the orchestration function will keep running and wait for the potentially long-running Tasks to complete, that's not actually the case. When the orchestrator reaches an idle point where it is blocked waiting on Tasks, the underlying runtime suspends it, which is particularly cool for the consumption billing plan of Azure Functions - if it's not running then you're not paying! With this coolness, you do need to be aware that the orchestrator will be replayed when a new notification has come in and it needs to resume. The documentation covers how replay works and the constraints this puts on orchestration functions.

Adding another layer

In my experience with the ACR geo-replication it has been rock-solid. However, in the interests of exploring Durable Functions a little further, let's add in a requirement to be notified if we don't get all of the notifications within a specified time period. Let's use 1 minute for this, but we could have picked 10 seconds or 3 days :-)

The code we have so far uses the orchestration context to get Tasks for various external event notifications, and then uses Task.WhenAll to join multiple notifications together to create a single Task that represents all the notifications completing. Let's call this the "completion Task".

One of the other things we can do with the orchestration context is to create a timer, and hopefully it won't come as a surprise that this returns a Task that completes when the timer fires. Now we have the completion Task and the timer Task, and we can use the Task.WhenAny method to combine these two Tasks into a new Task that completes when *either* of the input tasks completes, i.e. Either when the timer fires, or when the notifications have all completed. Hey presto, we have now implemented the timeout!

In code, we create the timeout Task by using the orchestration context. We use the CurrentUtcDateTime property to calculate the timer expiry as it will give us a consistent DateTime value even if the orchestration function is being replayed.

Task timeoutTask = context.CreateTimer(context.CurrentUtcDateTime + timeOutInterval, cts.Token);

Then we combine the timeoutTask with the replicationCompletedTask we had before:

var winningTask = await Task.WhenAny(timeoutTask, replicationCompletedTask);

Once we've returned from this await, winningTask will be set to whichever task has completed. We can then test whether this is the timeoutTask or the replicationCompletedTask to determine which action to take.

Trying it for yourself

All of the code for this post is available on github (https://github.com/stuartleeks/acr-global-webhook). There are instructions in the repo README for deploying and configuring.

Find out more

If you want to find out more about Durable Functions there is some great documentation:

• Overview https://docs.microsoft.com/en-gb/azure/azure-functions/durable-functions-overview
• Timers https://docs.microsoft.com/en-gb/azure/azure-functions/durable-functions-timers
• External Events https://docs.microsoft.com/en-gb/azure/azure-functions/durable-functions-external-events

For more information on Azure Container Registry see

• Overview https://docs.microsoft.com/en-gb/azure/container-registry/container-registry-intro
• Webhooks https://docs.microsoft.com/en-gb/azure/container-registry/container-registry-webhook
• Geo-replication https://docs.microsoft.com/en-gb/azure/container-registry/container-registry-geo-replication

In this short post I’m going to be looking at the PowerShell experience and will walk through setting up Cloud Shell to work with posh-HumpCompletion (a module that adds tab completion richness to PowerShell and which I was inspired to write after working with the verbose clear naming of the Azure cmdlets). You can see a GIF of it in action on the GitHub page.

Launch Azure Cloud Shell

The first step of this is to launch the Cloud Shell: https://shell.azure.com/PowerShell.

Currently the PowerShell experience is in preview and it can take a while to start and connect – hang in there!

If this is your first time using Cloud Shell then it will walk you through configuring a file share. This is then automatically mounted for you in each Cloud Shell session to allow you to save files across sessions. You can even mount it on your local machine to share content from your local machine with Cloud Shell (docs for Windows, Linux, Mac).

Install posh-HumpCompletion

Now that you have Cloud Shell running you can install posh-HumpCompletion from PowerShell Gallery

Install-Module posh-HumpCompletion

Once you have installed the module simply import it to bring posh-HumpCompletion to life

Import-Module posh-HumpCompletion

Add to your $profile

If you want posh-HumpCompletion to be active automatically when you start a new instance of Cloud Shell then simply add an Import-Module to your PowerShell profile. Since this is stored on the cloud drive that you set up when you first started Cloud Shell it will be invoked for each new instance. The following command appends the import to the profile

echo "`nImport-Module posh-HumpCompletion`n" >> $profile

NOTES

One thing to mention is that the PowerShell Cloud Shell has both the Desktop PowerShell (powershell) and PowerShell Core (pwsh) installed, and they share the $profile. So if you use both and add posh-HumpCompletion to your profile you should install it in both environments to avoid errors!

Update: This post originally said that you needed to specify “-Scope CurrentUser” on the Install-Module command, but thanks go to Aleksandar Nikolić for setting me straight and teaching me about $PSDefaultParameterValues. In short, the Cloud Shell team have set you up for success by defaulting to the CurrentUser scope when installing modules

The Goal

The Code

Creating a Function with EasyAuth

Creating a Client

Logging In

Working with Authentication in the Function

Putting it All Together

Further Reading

• EasyAuth Docs
• Chris Gillum on EasyAuth
• Tsuyoshi Ushio on Configuring Microsoft Graph bindings for Azure Functions with B2C
• Chris Gillum on Token store (details of refreshing tokens etc)

    public class HeaderTelemetryInitializer : ITelemetryInitializer
    {
        public List<string> RequestHeaders { get; set; }
        public List<string> ResponseHeaders { get; set; }

        public HeaderTelemetryInitializer()
        {
            RequestHeaders = new List<string>();
            ResponseHeaders = new List<string>();
        }

        public void Initialize(ITelemetry telemetry)
        {
            var context = HttpContext.Current;
            if (context == null)
            {
                return;
            }
            if (context.Request != null)
            {
                foreach (var headerName in RequestHeaders)
                {
                    var header = context.Request.Headers[headerName];
                    if (header != null)
                    {
                        telemetry.Context.Properties.Add($"request-{headerName}", header);
                    }
                }
            }
            if (context.Response != null)
            {
                foreach (var headerName in ResponseHeaders)
                {
                    var header = context.Response.Headers[headerName];
                    if (header != null)
                    {
                        telemetry.Context.Properties.Add($"response-{headerName}", header);
                    }
                }
            }
        }
    }

            TelemetryConfiguration.Active.TelemetryInitializers.Add(
                new HeaderTelemetryInitializer
                {
                    RequestHeaders =
                    {
                        "Accept"
                    },
                    ResponseHeaders =
                    {
                        "Content-Type"
                    }
                });

The Solution

"$schema": "https://raw.githubusercontent.com/mesosphere/marathon/master/docs/docs/rest-api/public/api/v2/schema/AppDefinition.json",

"$schema": "https://raw.githubusercontent.com/mesosphere/marathon/master/docs/docs/rest-api/public/api/v2/schema/Group.json",

In the previous post we saw how to show the progress as PowerShell loads your profile.

I spend a lot of time working with the Azure PowerShell cmdlets so I had added them to my profile. However, it turned out that they can be a little slow to load (yes, I know I’m impatient!). Since I frequently start PowerShell I wanted a way to be able to load the Azure cmdlets only when I needed them,. Since my computer isn’t yet psychic, I opted for a simple approach where I hold down the Shift key while PowerShell loads to signal that I want the Azure cmdlets loaded. The rest of the post will show how this can be achieved

The building blocks

Windows exposes a GetKeyState function that can be used to query the state of a key (e.g. whether it is currently pressed). If we were using this from C#, we would use P/Invoke via a DllImport. Since PowerShell is built on top of .NET we can take advantage of the same functionality (with a shout out for a helpful example).

Paste the following code into a PowerShell window to create the Get-KeyState function

function Get-KeyState([uint16]$keyCode)
{
  $signature = '[DllImport("user32.dll")]public static extern short GetKeyState(int nVirtKey);'
  $type = Add-Type -MemberDefinition $signature -Name User32 -Namespace GetKeyState -PassThru
  return [bool]($type::GetKeyState($keyCode) -band 0x80)
}
$VK_SHIFT = 0x10

Now we can execute Get-KeyState $VK_SHIFT to test the current state of the Shift key. Naturally it will return false. Instead, paste the following code into a PowerShell window and try holding down the shift key and releasing it:

while($true) { Get-KeyState $VK_SHIFT; Start-Sleep -Milliseconds 500 }

Now we have the starting point for the conditional loading, the only thing that remains is to use this to test the state of the Shift key and then conditionally load the Azure module accordingly.

Show me the code

To see an example of this, check out this gist that incorporates it into a profile script. It also includes the module loading messages from the previous post to make it easy to see what is going on.

In this post we look at adding rotating output at the top of the PowerShell window as shown here:

Introduction

Recently I realised that PowerShell was taking a while to load on my machine. I'd been adding more and more things to my profile and wanted a way to easily see what was taking the time (although I had a pretty good idea).

Thoughts

A couple of ideas came to mind pretty quickly. First was good old Write-Host, so I peppered these calls throughout my profile but wasn’t happy with the result as it felt a bit verbose.

Next was the idea of using System.Diagnostics.Debug.WriteLine. Since PowerShell is built on .NET, this is pretty easy to do, and I’ve used this in other places to good effect . You can use DebugView from SysInternals to view the output, and in terms of the console window it is pretty unobtrusive. In fact, it is maybe a little too unobtrusive as you only get an indication of progress if you have something like DebugView open.

Then I came back to the fact that PowerShell is built on .NET and had an idea for how to implement the rotating text…

Implementing the rotating text

So, as I’ve mentioned, PowerShell is built on .NET. And in .NET, console applications use System.Console to interact with the console (to read/write text etc). To test this you can enter [Console]::WriteLine(“Test”)

At this point an idea was definitely forming, as Console has another method: SetCursorPosition

Aside: As shown above, if you don’t include parameters and try executing a function in PowerShell it returns the type info for the function – handy way to check parameters and overloads

We can put this function to work by setting the location to 0,0 (top left) and then immediately writing some output:

Now we can simply wrap that in a function. Note that we’re padding the output to the full width to erase any previous messages that were written.

function OutputStatus($message){
    [Console]::SetCursorPosition(0,0)
    Write-Host $message.PadRight([Console]::BufferWidth)
}

And then we can use OutputStatus “Loading something” in our profile and we get output like this:

Show me the code

The code for this is in this gist. The gist also includes tracking messages to display at the end of loading, but hopefully that code doesn’t need an explanation

I’m a little behind on things, but the first video is now up, and covers building posh-HumpCompletion from scratch. It skips over some of the optimisations, but covers the main functionality.

After a bit of searching I found this issue which steered me in the right direction.

To set up persistence, start a PowerShell session and authenticate (e.g. run Login-AzureRmAccount).

From that session, run

Save-AzureRmProfile –Path C:\your-path-here\AzureRmProfile.json

Then update your profile (I like to run “ise $profile”) to include

Select-AzureRmProfile –Path C:\your-path-here\AzureRmProfile.json | out-null

Et voila! Now when you create a new PowerShell session it will import the saved profile.

NOTE: YMMV: this is working for me so far – if it works for you too, that’s great! I’ve also only been running like this for less than a day, so don’t know how long I’ve got until the token expires, or whether it gets refreshed! Use at your own risk ;-)

These days I find myself working in both PowerShell and bash, and when I’m in PowerShell, I like to have objects that I can work with. With the Azure CLI I can use the --json switch and then use something like jq to process the output, or in PowerShell I can use ConvertFrom-Json to parse the JSON into objects that can be piped/filtered/projected in the normal way.

When working with the docker command line, things are slightly different. The query commands (e.g. ps, images) support filtering but only the ps command seems to support formatting.

To enable me to work with docker more easily in PowerShell, I wrote a little helper: ConvertFrom-Docker

Installing ConvertFrom-Docker

To get started, grab the script from https://gist.github.com/stuartleeks/4661c3c05678eec822bc and save as ConvertFromDocker.ps1

Then you need to dot source it, simply because I’ve not found time to wrap it up in a module yet – I’ll update this post if I do :-)

. ./ConvertFromDocker.ps1

Using ConvertFrom-Docker

With this done you can run the following command:

docker ps --no-trunc | ConvertFrom-Docker

The output will be similar to

Image       : containersched
Ports       : 0.0.0.0:5123->5000/tcp
Names       : desperate_jang
Command     : "dnx -p project.json web"
Created     : 12 days ago
ContainerId : 9fb9d10f6a6d6423ff3b3a7734375726cc79706038942201442e636b50fa7979
Status      : Up 12 days

Image       : stuartleeks/vorlon
Ports       : 0.0.0.0:1337->1337/tcp
Names       : stoic_yalow
Command     : "node /vorlon/bin/vorlon"
Created     : 2 weeks ago
ContainerId : 5e64f5a8accabd039b24bcfec6b89127f46c14eb16e2d165461071f1e557151c
Status      : Up 2 weeks

Image       : jwilder/nginx-proxy
Ports       : 0.0.0.0:80->80/tcp, 443/tcp
Names       : angry_visvesvaraya
Command     : "/app/docker-entrypoint.sh forego start -r"
Created     : 2 weeks ago
ContainerId : 7fb4709668946f5bdc915874b9537b5cc52ccaf7fa2c74586b93af279db6512b
Status      : Up 2 weeks

This works with docker ps, docker images, etc and uses the first line of output from the command to determine the property names for the object :-)

Enjoy!