Forem: Simon Waight

Practical adoption of generative AI as part of your software development lifecycle

Simon Waight — Tue, 04 Apr 2023 00:00:00 +0000

As the pace at which new technology ships increases, so do the chances that businesses will opt out or disable new capabilities because they don't feel they have time to adequately assess the impact before people have access. A downside to this approach is that those businesses who have slow or no adoption of new technology will quickly be outpaced by their competitors (emerging and exitsing) that are better able to assess and adopt.

Over the past decade I have experienced this first hand with cloud adoption, where many large organisations now restrict access to new services and features as standard operating procedure. More mature businesses put a structured assessment process in place, but it still feels like a barrier to innovation from potentially beneficial new technology.

More recently I am seeing the same behaviour with the introduction of generative AI, so in this post I am going to concentrate on adoption of this emerging technology as part of the softare delivery process. Examples of generative AI services you have access to today include GitHub Copilot, Amazon CodeWhisperer and Tabnine.

TL;DR - here's a basic scaffold GitHub Project to help with your adoption process.

The more things change, the more they stay the same

This famous quote ("Plus ça change, plus c'est la même chose" ) from 19 Century French journalist Jean-Bapiste Alphonse Karr is quite apt for the situation in which we find ourselves.

Developers have been using assistive technology for many years to help reduce time to ship software or to remove the tedium of repetitive work. Code generation has been around since at least the late 1970s with the likes of MATLAB plotting the course we find ourselves on today.

Intelligent code completion has also played a big part in modern developer experience with most Integrated Developer Environments (IDEs) supporting some form of code completion. Code completion is also not a new idea and traces its history all the way back to the 1950s.

Clearly the idea that every single line of code in any application codebase is 100% produced only through direct human edeavour has been outdated for a while!

Protecting your IP from generative AI

Many businesses have invested substantial amounts in building software that solve their business problems or those of their customers. It's understandable busineses want to protect their Intellectual Property (IP).

However, the reality is that the IP is not just the sourcecode, it's in the business logic and the data, and the unique aspects of the user experience the software delivers. The code is just a means to an end. While it's true some companies such as Microsoft (amongst others) have built their business on IP that is in code, the majority of businesses are not in this position.

I know this is perhaps a controversial opinion (and likely your lawyers will disagree), but if your only reason for not adopting new technology is the perception you are protecting IP in your source code, you might be focusing on the wrong things. You might also want to stop reading here! 🙂

Still with me? Good, let's look at how you can manage your adoption of generative AI services as part of your software delivery lifecycle.

Legal review of service prior to roll-out

You should sit down with the appropriate members of your legal department or advsior and formally review the terms of service and privacy policy of the generative AI service(s) you are considering. This way you have a clear understanding of what data is being collected and how it is being used by the service provider.

If you don't have a legal capability then you need to either engage one, or make best efforts to decide on your intrepertation of the terms of service and privacy policy. Make sure to note down the process used to decide and justifications for future reference!

For example, GitHub Copilot for Business clearly states it doesn't retain any code snippets sent to the service as a prompt. If the services you are considering have no clear declaration then you should ask the service provider for one. Depending on their answer you might not want to adopt their service!

This is also not a one-time process. It should be reguarly reviewed to ensure the service provider has not changed their policy in a way that is not acceptable to your business. Watch out for "we've changed our terms of service" or "we've updated our Privacy Policy" notifications!

Limit use of generative AI to specific codebases, tasks or teams

If you have a large codebase, you may want to limit the use of the generative AI service to a specific part of a codebase or a specific team. This way you can control the amount of data being sent to the generative AI service and also the amount of generated code being included in your solution. You can also have confidence that certain parts of your codebase, potentially those with what you consider your actual IP, are not exposed to the generative AI service or will contain generated code.

If you are unsure where in your codebase this thinking applies, I think we can agree that the Data Access Layer (DAL) of your solution is likely not to be where your IP lives and it's also not where you want your teams to be spending their time writing code. 😉

There is a swirling debate around whether or not the outputs of generative AI models or services can be copyrighted, and if they can, who holds that copyright? If you want to ensure you hold copyright, limiting the places where this technology is used can be a good start.

Require human explainability and review

This might be a tough ask depending on how much code generation you are prepared to allow, but ultimatley your business will be responsible for any experiences resulting from this code. If your code generation service produces code nobody can explain then you bear the risk of something unexpected happening.

If you consider the previous point (limited use) then you can ring fence certain key parts of your business logic and require human explainability and review of generated code in these areas if that helps limit the scope.

It's important to be aware of what is happening in this space of human explainability from a regulatory standpoint too. The Europe Union's General Data Protection Regulation (GDPR) includes mentions of automated decision making and the need for human explainability. The GDPR covers this most clearly in Article 22 and Recital 71. It's safe to say other duristictions will likely follow suit in due course and you need to be ready!

Leaning on your DevOps practices

If you are still not using DevOps practices widely, then now is the time to start! If you have quality gates in place for human-created code and you run your machine-generated code through the same process, you can have a degree of confidence around the quality and functionality of the code. There are a few aspects to this suggestion:

Small commits containing only generated code: avoid mixing human and machine-generated code in commits. Ideally these commits are associated with a specific task or user story so you already have that context. Any Pull Request resulting from these commits must be human reviewed.
Only generate what you need: I can foresee a situation where a developer is using a code generation service to generate a complete API or library for, say, database access. They will generate all the normal Create, Read, Update and Delete (CRUD) methods and add the code to a commit. Perhaps they just needed a Read operation? This is all the code that should have been kept and committed to the repository. If we require humans to review code changes, then we want to limit the volume of code to review and reduce the chances that problems will arise later when unreviewed code is used in the application.
Static code analysis or linting: just because code compiles doesn't mean it is correct! You should be running a static code analysis tool as part of your CI/CD pipeline. This will help identify any issues with the generated code. If you are using a generative AI service that is integrated with your IDE then you should be running the same analysis tool or linter locally. This will help you identify issues before you commit the code.
Clearly identify code as generated: today there is no automated way to provide a clear indication that code is machine-generated. Depending how widely you decide to use code generation,s you can add a developer standard that requires developers to clearly mark code as machine-generated. This could be as simple as a comment at the top of the file or a section of a file. This will help you identify generated code and avoid the risk of human-generated code being overwritten or vice versa. If the code is manually modified it should be noted in the comment. I asked the team at GitHub if Copilot could add comments around generated code like the below sample (today it's not possible was the answer).

//GHCP: Start
/*
Model release: x.xxx.xx
Model date: 2023-03-28
Prompt: a function to calculate the sum of two numbers
*/
public int Sum(int a, int b)
{
    return a + b;
}
//GHCP: End

Test coverage: ensuring all key parts of your codebase have code coverage will provide confidence that changes that are machine-generated are not introducing any regressions. This is also a good practice to have in place for any code changes regardless! I know you are probably thinking about machine-generated unit tests at this point... I'll refer you to the human explainability and review point above. If you are using code generation to create unit tests simply to hit code coverage targets you are looking at this the wrong way!
Revisit generated code as part of BAU or updates: don't assume that today's best suggestion will be tomorrow's - just because it's generated doesn't mean it should be frozen in time. It is worth revisiting generated code over time to see if they are better ways to implement the logic. This is no different to using new language features or libraries as they become availbale and can replace bespoke code you have developed.

The bottom line is, if you are already allowing changes into production without the necessary quality gates, then all adding generative AI to the mix is going to do is increase the volume of change you are now submitting to your CI/CD pipeline or requiring human review of!

Generative AI doesn't mean less people

Let's not overlook the obvious concern many people have around the introduction of generative AI technology into the workplace - job security. I think it's important to understand that generative AI is not a replacement for humans. It's a tool that can help developers be more productive and deliver more value to their business while at the same time helping them to learn and grow their skills.

If you are a manager or business owner and you are thinking you can replace your developers with generative AI sevices like Copilot you are going to suffer in the long term. You will notice that a lot of what I've written about so far requires human oversight or intervention. Smart people want interesting and challenging work, and if you can use generative AI to remove the busy work from their lives they will be more productive and happy. This also provides them with space to help grow new team members who you should absolutely be hiring!

It's worth the time and the (perceived) risk

I know there is a lot of hype (and a fair amount of concern) floating about on the impacts of AI at the moment, but I honestly believe the benefits of generative AI will far outweigh the risks.

Like any new technology it's worth taking a considered approach to adoption. To this end I created a basic scaffold GitHub Project which you can copy to your organisation and use to get started with adoption of generative AI in your enviornment. Make sure you select "Draft issues will be copied if selected" so you get the baseline tasks I created for you to use. You can read about copying projects on GitHub's documentation.

I recently recorded a session with Damian Brady where we discussed risks associated with pushing Copilot code to production in more detail. You can watch the discussion below.

I will leave you with this thought...

Let's be honest, the only time you review generated SQL from an Object Relational Mapper (ORM) is when there are performance issues, right? And that code is typically generated by a machine at runtime! 😜

😎

Moving from Azure Logic Apps to Power Automate Flow

Simon Waight — Wed, 07 Sep 2022 00:00:29 +0000

You may be sitting there are wondering why are we doing an Azure Logic App to Power Automate Flow migration? In most cases you’d likely be heading the other direction, but I can give you a few pointers why this move makes sense:

Bring a low-code solution and data into an environment that more people have access to (Office 365)
Allow policies around data management to easily applied using existing platform capabilities.
Easier to share the implementation with others by exporting the Power Automate Flow or granting them ownership rights.
Make use of features like Process Insights to help improve my low-code solution.

For this post I will be moving my meetups alerts Logic App.

Step 1: Move data from Azure Table Storage to SharePoint

While we are moving our business logic to an easier to manage location, we might as well move out data as well. It is possible with Power Automate Flow to connect to Azure Table Storage, but it may be that the people managing your Flow may not have access to the Azure environment which would be an issue. To avoid issues, let’s move the data into a platform that Flow editors are likely to also have access to – SharePoint.

The process you use to migrate your data will depend on the volume of data you are moving. For my scenario the list of items is fairly small, so I will take a simple approach.

First up, let’s export the Azure Storage Table Storage data to CSV using the free Azure Storage Explorer.

Once we have the CSV downloaded open it up in Excel and delete the columns that denote data type. Once done, save the file as a Excel Workbook (xlsx).

Next, we are going to go ahead and create a new SharePoint List for our data by using the Microsoft Lists service.

The easiest way to navigate to Lists is to expand the “waffle menu” in the top left in any online Office 365 application (Outlook, OneDrive, etc) and then select Lists.

Once the Lists main page has loaded go ahead and click + New list at the top. On the next screen go ahead and choose From Excel as shown below.

Once the Excel file is uploaded you can select the columns you want to import (it should be all of them as we deleted the data type columns earlier).

Finally, you can give your List a name, select a colour and icon, and most importantly, the location you want to store it. I selected a SharePoint Teams site which means the list is actually created as a standard SharePoint List.

Now we have our data in SharePoint, let’s go ahead and rebuild our Logic App.

Step 2: Rebuild the Logic App as a Power Automate Flow

The big tip I will give you here is to name your Power Automate Flow Actions (Steps) identically to those in your Logic App. The reason? You can copy complex dynamic expressions from your Logic App and paste them right into your Flow.

The big change between our original Logic App and Flow implementation is that our data is now stored in a SharePoint List, so instead of an Azure Table Storage connector (which is actually available to Flow) you use a SharePoint connector. Every other element remains the same.

The other item to be aware of is that the HTTP Connector (built-in for both Logic Apps and Flows) is considered a Premium connector in Power Automate. This means you must determine if you are licensed for Premium connectors or not. The easiest way to view if you’re covered or not is to review the documentation on Power Automate Plans.

The main body of my new Power Automate Flow is shown below. You can see I am now using a SharePoint connector in place of the original Azure Table Storage one in the Logic App.

If I expand the meetup loop you can also see that the steps match the Logic App except I now use SharePoint as my target to track status.

Now that the Flow is created, I can use the dashboard to quickly view when the Flow ran, add other users as Owners of the Flow, export the Flow to share, and also determine any changes I can make to improve the Flow performance by using Process Insights!

Unsurprisingly this migration wasn’t a tough one – Logic Apps and Power Automate Flow share a lot in common, and my data source was not a complex one. As I said at the start of this post, it’s an unusual move to make – most migrations would go from Power Automate Flow to Azure Logic Apps, but it is a real positive to see it is possible to go back the other way!

Happy Days! 😎

How to consume GraphQL APIs from Azure Logic Apps

Simon Waight — Tue, 05 Apr 2022 00:00:47 +0000

If you’ve been reading my blog for a while then you will see that I am a heavy user of RESTful APIs in my solutions, going so far as to build a custom Azure Logic Apps Connector for Meetup’s REST API. I’ve used this Connector in a few places and blog about one example previously in Integrate Meetup announcements with Microsoft Teams using Azure Logic Apps and Adaptive Cards.

Recently my solution for Meetup integration ceased working as Meetup decided to shift their API from REST to GraphQL without providing any advance notice. This change has quite a big impact on API consumers because the client interaction model and API endpoints are completely different between the REST and GraphQL. Thankfully GraphQL still utilises HTTP primitives and returns JSON responses so we at least have a starting point for our new client code.

In this post I am going to look at how you can call a GraphQL API from within an Azure Logic App by using the in-built HTTP Action.

Our sample query

For the purpose of this post I am going to use a GraphQL query against the Meetup GraphQL API which uses the predefined groupByUrlname query and use it to return the next scheduled event for the specified group. The sample is shown below.

This query shows one of the benefits of GraphQL espoused by its proponents – the ability to send what is effectively two queries (get group AND event details) to the API at once and receive a single response. I must admit this is really handy and helped remove a step in my Logic App.

Using in a Logic App

As I hinted at above, GraphQL still uses all the usual HTTP primitives, so we can use the in-built HTTP Action in Logic Apps to call the Meetup GraphQL API.

The Meetup API documentation includes a few samples that show how to call the GraphQL API using curl which is a really handy way to expose exactly what is required. I’ve included a sample below.

The key items of note are:

Wrap the GraphQL query and any variables in the body of your request as a JSON payload. Specify ‘query’ and ‘variables’ with their own JSON property.
Set Content-Type to application/json.
Use the POST HTTP verb.
The URI to hit is https://api.meetup.com/gql.

Given I’m retrieving information on public Meetup groups I don’t need to provide an Authorization token, but apart from that I can use the rest of the curl sample to help me setup my Logic App HTTP Action as shown below.

The response that comes back is in a JSON format which I will parse into an object to make it easier to use elsewhere in my Logic App. The easiest way to build the schema is to run the HTTP Action once, look at the ‘output’ of the Action in the Run, copy the response and then use the “Use sample payload to generate schema” option in the Parse JSON Action.

In the HTTP Action I am dynamically replacing the URL of the Meetup group with the RowKey from an Azure Storage table. I am doing this because my data design means the RowKey contains the URL component of the meetup group – i.e. “Azure-Sydney-User-Group”.

The net result of this implementation is that my Meetup-to-Teams bridge is functional again, and in fact is now simplified with only a single Meetup API call. Unfortunately, I can’t use my Custom Connector for the Logic App anymore, but I at least my integration works and I can keep across new meetups as they are announced!

Happy Days! 😎

Real-time air quality monitoring and alerting with Azure and PurpleAir – Part 1

Simon Waight — Mon, 10 Jan 2022 22:45:44 +0000

Anyone who was living in Australia during the 2019/2020 summer can’t help but remember the massive bushfires we had, and the impact they had on air quality.

Probably the starkest way to illustrate how bad it was is this post from December 10, 2019. I also added a recent follow-up post to show what it normally looks like here.

Simon Waight

@simonwaight

Visibility of maybe 100m. Can usually see kilometres from here... 🙁

22:33 PM - 09 Dec 2019

Simon Waight

@simonwaight

Not quite 2 year later, but here’s a reference picture for what this usually looks like…

03:47 AM - 24 Dec 2021

I’ve had a weather station for the house for probably 10 years or so, and around the time of these fires I started looking into air quality sensor as a way to identify when we shouldn’t be spending time outside.

If I’m quite honest, needing to check outside air quality safety feels a little crazy, but I think it’s a wake-up call that many of us might have needed to realise that this issue affects everyone, not just certain heavily industrialised areas of the world.

On top of this, while the first photograph above shows it’s clearly unhealthy to head outside, it doesn’t need to get to that level of visibility before air quality is at dangerous enough levels for some people.

After a number of months looking I was unable to find a good quality consumer air sensor in stock. The increased demand due to the following year’s North American and European fires, along with pandemic-driven shortages meant I put this on the back-burner and only periodically checked for stock. One of my colleagues, Dave Glover, built his own hardware solution, but I wasn’t ready to go down that rabbit hole!!

During a recent browsing session I happened across PurpleAir. Their devices are less consumer-orientated than I would have liked, and I was ideally wanting something battery-operated, but I also liked that they listed their device details, including that it has two laser-based particle sensors (PMS5003) (coincidentally, the same Dave used in his DIY project).

Having a bit of a dig I could also see that they make data publicly available and that you can access it yourself as well. This is a win-win for me. Everyone gets the benefit of more readings and I get something I can build on top of.

Despite the pricing (and the shipping 😪) I decided to take the plunge…

Simon Waight

@simonwaight

Less a week to arrive! Now to get this mounted and sending AQI data to ⁦@ThePurpleAir⁩. This sensor has some heft to it!

01:24 AM - 05 Nov 2021

After installation I went to check the PurpleAir map for my device and was happily surprised to find that the New South Wales Government’s Department of Planning, Industry and Environment (DPIE) is using these sensors – this one in Manly.

Understanding Air Quality Index (AQI) and measurements

👨‍🔬 Non-scientist alert 👨‍🔬 I’m going to put this disclaimer here. I’m not an air quality expert. Please take what follows with a grain of salt and do your own reading!

The aforementioned DPIE has a really good summary of Air Quality.. if you want to go and have a read, I’d highly recommend it.

The PMS5003 sensors are particle sensors, so for us, the two air quality properties we can measure will be:

Measure	Period	Units	GOOD	FAIR
Particulate matter < 10 µm (PM10)	1 hr	µg/m³	< 50	50-100
Particulate matter < 2.5 µm (PM2.5)	1 hr	µg/m³	< 25	25-50

The PMS sensors send through data for much finer particles than PM2.5, but the two measures above will be key for our final solution. We'll use DPIE's Air Quality Categories (AQC) as well for our measure which means anything other than "GOOD" will impact sensitive people. I haven't put all categories here, but we'll alert on state change for each category (up and down).

Oh, look the PA-II support Azure IoT!

Well, yes, the registration screen includes Azure as a potential Data Processor, except.. good luck if you can get it to work… and it’s currently totally undocumented.

Sadly I was unable to get it to work and the PurpleAir team is currently shifting support platforms, so I wasn’t able to find out how to get it working.

Which means…

The proposed solution

As with any self-respecting nerd I have various bits of tech to hand, with my Network Attached Storage (NAS) device from Synology being a really useful swiss army knife. The Synology NAS supports Docker containers and has been handy for hosting a bunch of things for me, so I thought it would make sense to re-use for this solution.

.NET 6 also recently shipped, and I wanted to have a play with the new Minimal API model that removes a lot of boilerplate code from your solutions. What a great scenario to use it for!

The diagram below shows the high level flow of the overall solution that will allow us to get our sensor data into Azure IoT Hub.

Time to code!

I chose to use Visual Studio Code to build my Gateway solution which is a standard ASP.NET Web API. This Gateway accepts HTTP POST requests from the PA-II sensor and parses the JSON payload which is then sent to an Azure IoT Hub using the IoT Device C# SDK.

You can find the final API solution on GitHub. You will see it includes a Dockerfile which is then used by the associated GitHub Action to build the solution and publish the resulting image to Docker Hub.

All the logic to handle the data from the sensor lives in the SensorReadingController.cs file which contains a single method to hand the HTTP POST request (view it on GitHub). I created a C# class to model the JSON payload from the sensor which also makes the code a bit easier to read!

Given I have a closed network with a strong security setup I probably could have left this Web API open to any caller.. but we’ve all seen horror stories of security breaches of all types happening from insecure endpoints, so I thought it best to at least perform some basic client validation (see the lines that perform the check) before allowing the request to be processed. I know this wouldn’t stop a motivated attacker, but hopefully it’d be enough in most cases!! Yes, I could go a lot further, probably right down in the guts of ASP.NET Authentication… but for my use case this will suffice.

Deploying the gateway

I’m using Docker Hub to host my Container Image as it is the default Container Repository that Synology’s Docker setup uses which makes it easy for me to pull the resulting Container Image to my NAS (it’s also free which is handy!)

On my NAS I open up the Docker application and search for my customer gateway Image on Docker Hub. Once found I can then select the Image and Download it.

Once the image is downloaded I then need to launch on instance of it, so I switch over Image, select my downloaded Image and click Launch.

In order for my API to run I need to configure some environment variables and to also define the TCP port I want to expose the Web API on. I do this by selecting Advanced Settings on the Launch dialog.

Specify the port mapping..

and then set the four required environment variables as detailed in the readme on the GitHub repository.

Once configured you can now start the gateway Container and should see confirmation in the logs that it has started.

Next we need to update our PA-II device registration so that it calls our newly deployed API Gateway, so let’s go ahead and configure that on the PurpleAir registration site.

Once the registration is saved we should see a call to the Gateway API every two minutes.

As a final check we can switch over to our Azure IoT Hub Overview tab and see that events are arriving as expected.

So, what now?

At this stage we are now delivering filtered events from our local sensor to an Azure IoT Hub instance, but this is only a part of our overall solution.

The IoT Hub instance will hold our event data for up to 7 days before it expires. We could choose to route the events to an Azure Storage Account or other endpoint, but for the purpose of this blog series I am simply going to leave them sitting in IoT Hub until we are ready to build the next stage of our solution. This way I am avoiding incurring additional costs until I’m ready to develop and deploy the cloud processing and storage part of my solution.

Hopefully this has been an insightful post which shows you how you can quickly take locally generated data and push it into Azure for additional processing.

Until the next post! 😎

Setting Helm Chart version and appVersion properties during CI/CD with GitHub Actions

Simon Waight — Tue, 14 Dec 2021 01:29:08 +0000

The release of Helm 3.7 sees some major changes to the way Helm behaves and the commands you work with. In addition to this, stricter adherence to Semantic Versioning (semver) can be observed for both Chart and Application versioning.

In this post I am going to look at one way you can simplify setting the version and appVersion values for your Helm Charts whilst ensuring you meet the semver 2 requirements.

TL;DR show me the code!

If you’re here simply looking for the full solution then head on over to the sample GitHub Action workflow and check it out!

Read on if you want to understand the approach.

Understanding version and appVersion

The first thing we need to understand is why there appears to be two fields for a Helm Chart that look to do the same thing. The documentation of the Chart.yaml file format is great, but I’ll summarise here as well and dig a bit more into each.

version

Quite simply version represents the version of the Helm Chart you are deploying. This is not the same as the version of the application you are deploying with the Chart. Charts define application components AND their configuration. If the configuration changes then the Chart version property should be updated. Updating an application component such as a Container image doesn’t necessarily mean there is a configuration change.

The only way to set this value is to update it in the Chart.yaml file. This represents some challenges when automating build and deployment – either you need to submit an updated Chart.yaml file or write some scripting to update / create the Chart.yaml file.

appVersion

In many cases appVersion will be the property you want to update on every deployment as it is represents the version of the application component(s) you are deploying. This might simply be an updated container image (or set of images).

The appVersion can be set either though manually updating the Chart.yaml file (similar to updating version), with the additional capability to override it at packaging time by supplying the --app-version argument as shown below.


helm package . --app-version 1.0.0

Great, and the problem is?

I’m sure many would argue there is no problem here, but I do see a problem. You can set the version of your application regardless of the value contained in the Chart.yaml file, yet you are unable to do the same with the Chart version.

Yes, I could manually update the Chart.yaml file to denote a version change (perhaps as part of a Pull Request), but why should I have to edit a file when all I need to do is change one value? It introduce the chance of human error and I also require people to have more knowledge of the Helm ecosystem than many may ever need. Alternatively, you could argue this approach ensures the value is only updated when really necessary… but it still strikes me as odd!

Here’s my approach

For this demo I am going to use GitHub Actions as my CI/CD platform, but this approach will work on any platform. I’ll also use Azure Container Registry (ACR) as my Image and Chart repository, and deploy the resulting Container and Chart to Azure Kubernetes Service (AKS). While the ACR and AKS steps aren’t necessary, they do form part of an end-to-end process most people are likely to use.

I’m using the sample repository for this demo, but you can use any Helm chart you have previously scaffolded with helm create.

Start by editing the Chart.yaml file and setting the version to a known value that you can parse is a script. You can also set a value for the appVersion but this will be overridden at the command line as we will see.

Next, in your GitHub Action workflow define two environment variables chartVersion and appMajorMinorVersion as shown below.

env:
  chartVersion: 0.1.0
  appMajorMinorVersion: 0.1

I have set a full semantic version for the Chart and only the major and minor versions for the application. I want full centralised control for the Chart version and the approach I have chosen means I do need to update my GitHub Action workflow if I want to change the Chart version, but I can live with that (at least it’s not hidden in a source code file somewhere in the repo!)

Hopefully in future we’ll have a plain text variable store for GitHub Actions which means I can define the value elsewhere and just reference in the workflow file. I don’t want to use secrets because I want these values visible to anyone who looks at this workflow.

When we want to package our Chart we need to do a few additional steps. As our workflow runs on a Linux host we can utilise Linux commands to help. In this case we’re going to use printf and sed to format and replace the version placeholder.

In the below workflow step we start by escaping the dots in the chartVersion environment variable. We do this is so the sed replacement works as expected on the next line.

Using this escaped value, which is held in $escaped_version, we then use the sed command to replace the version placeholder in the Chart.yaml file.

The final two commands packages up the Helm Chart, specifying the appVersion at the command-line, and then push the Chart to a remote repository (the sample uses Azure Container Registry).


    - name: Helm Chart Update, Package and Push
      run: |
        cd ./content-web/charts/web
        escaped_version=$(printf '%s\n' "${{ env.chartVersion }}" | sed -e 's/[\/.]/\\./g')
        sed -i "s/version\: 0\.0\.0/version\: $escaped_version/" Chart.yaml

        helm package . --app-version ${{ env.appMajorMinorVersion }}.${{ env.tag }}
        helm push web-${{ env.chartVersion }}.tgz oci://${{ env.containerRegistry }}/helm

As a result of this step we can now control the version and appVersion properties of our Chart.

More control

The thing I do like about the approach I have, is that should anyone tamper with the Chart.yaml file and change the version value the build will break and I avoid downstream issues as a result. As appVersion is overridden I can also be confident that any change made to the file will be ignored.

Having said this, the approach I am using is just one way to achieve this outcome, and it’s also important to note that it doesn’t suit every use case (and maybe not yours!)

It might be that you would break the GitHub Action workflow into multiple separate workflows in order to give you better control over when the two Helm Chart properties are updated. Also, the sample workflow uses a fairly basic process – it assumes every invocation should build a new Container Image, a new Helm Chart and deploy to AKS. Clearly that may not be ideal, so at a minimum you’d probably want to add Approvals or other mechanism that ensures you only build a new Chart when necessary, and only deploy the Chart when you want.

Hopefully you’ve picked up some useful information on working with Helm from this post, and it will help you be successful in packaging and releasing applications using Helm. If you come up with a different or better way feel free to leave a comment!

Happy days! 😎

P.S. You can check out the GitHub repository with the sample workflow.

How to port AWS Serverless solutions to Microsoft Azure

Simon Waight — Mon, 29 Nov 2021 22:30:38 +0000

Avoid Vendor Lock-in.

Three words. I wonder how many hours (days, weeks, months?) have been lost to designing and building software solutions and systems to the lowest common denominator simply to avoid the perceived risk of betting on the wrong platform?

While risk mitigation and extensibility should form a part of any design, I’ve believed for a while now, especially since the rise of modern cloud platforms, that the need to build abstractions in solutions simply to avoid perceived future risk is a massive sinkhole and a large inhibitor to innovation, especially in the enterprise.

Imagine, if you will, designing and building a solution that makes direct use of SDKs and platform features provided by a cloud vendor. Compare this to building the same solution, but instead of using the SDKs or features directly you first wrap them in abstractions. It’s easy to see the amount of additional effort involved in the second scenario.

If you consider the amount of non-functional development work required in scenario two and it’s impact of this work on delivery time and cost along with potential reduction in overall functional capabilities of the resulting solution you can see it can be a fairly large impact. Also consider this in the context that at some future point (let’s say 3 years from now) you might need to move to a different platform.

There are an absolute minority of businesses that might require true multi or hybrid cloud solutions (👋 Kubernetes), but I can tell you nobody at Netflix has lost sleep over their bet on a single cloud vendor.

I firmly believe that you can, in many cases, push re-platforming risk into the future. Any cloud migration will invariably be a multi-step process that involves infrastructure, data and application code. While you don’t want to rewrite your entire application codebase, if all you need to do is rewrite code that is tightly coupled to a cloud API then your overall effort is relatively small, and can likely be factored into the costs of migration.

Anyhow, enough of my opinions, let’s look at a practical example.

List Manager Event-driven sample

AWS has a few sample Lambda applications on their documentation site, and I thought I would find the most intricate one and use it as the basis for the demo code to go along with this blog. To that end I chose the List manager sample application for AWS Lambda as my preferred demo.

I also wanted to select a Lambda solution because it’s the most tightly bound to the cloud platform it is running on. Almost every aspect of this sample application relies on a piece of AWS that is available on AWS only – the two items that are not are the Node.js code containing the business logic along with the RDS MySQL instance which is just a managed MySQL service.

Switching to Azure

If we’re starting with serverless, we might as well target serverless! In most inter-cloud migrations I’d expect this type of mapping to occur given the level of equivalence in services between vendor lock-in is really not a factor any more.

Yes, we’ll have to change some SDKs and libraries that determine how we interact with as-a-Service offerings, but at the core there is not much business logic that needs to change.

If you want simply to see the source code you can check it out on GitHub, otherwise read on for how the migration was completed.

Here’s a high level architecture diagram to give you a feel for what we’re aiming for.

The porting process

The only bits we really need to keep from the original are the Node.js logic implementations and the format and data for the events driving the solution. Everything else is just supporting infrastructure which we can replace.

The original sample uses private networking to connect everything except the event source, so we can easily rebuild the infrastructure from scratch in Azure. However, rather than starting with this, as I will assume it’s just a secure pipe between PaaS in Azure, I’m more interested in porting the Node.js and event source code so I can have an end-to-end test that allows me to validate my Azure implementation.

At this point I could easily have run the Cosmos DB emulator and a MySQL Server on my developer box to act as surrogates for their Azure equivalents and developed the Azure Functions using Visual Studio Code and the Azure Core Functions tooling.

However, I didn’t want to setup MySQL locally, and running it all in Azure is just handier 🙂 – especially as I’d still need to use an actual Azure Event Hub for my testing. I did develop the Functions locally and then connected them directly to Azure as required. If I’d spun up the development infrastructure to use private networking I’d need to do this development on a Virtual Machine running on the same network – something that just felt unnecessary at this point.

So, with all these pieces in place I began working on the Node.js Functions and converted them to use Azure. The ‘dbadmin’ Function really needed a change as the source sample allows any arbitrary SQL query to be sent to this Function – something that strikes me as massively dangerous. I solved this by hardcoding the SQL that can be used and controlling any variables via only Azure Functions or Azure Key Vault configuration values that are only ever used on the server and never exposed to any client.

The ‘processor’ Function was a little more work, not helped by me not being a massively experienced Node developer, and the need to update code to better handle Node Promises, as well as the differences between Cosmos DB and DynamoDB. From what I can see it looks like DynamoDB accepts and emits JSON as simple strings, whereas Cosmos DB (or its Node SDK) readily accepts and emits JSON objects ready for code to consume. Additionally, Cosmos DB has the idea of an ‘upsert’, which does seem to exist in DynamoDB, but is not used in the source application codebase at all.

The final difference between Cosmos DB and DynamoDB is the concept of a Table. Cosmos DB doesn’t have a Table construct, and the anti-patten a lot of first time Cosmos DB users fall into is to map a Table (typically from a relational data model world) into a Cosmos DB Container. At first glance this looks like a good fit, but it’s actually likely to cause you pain (mostly around cost, but potentially also performance).

Cosmos DB stores JSON documents, and each document can have a different set of properties. While you are required to meet a few basic rules including having an identity field with high cardinality (basically the field should have a lot of different possible values) you can otherwise store multiple different document types in one Container, which is what I’ve done with this sample.

Once I had everything working end-to-end with this hybrid development setup it was then time to build out the final infrastructure deployment which requires private networking.

The easiest way I find to achieve infrastructure modelling is to use the Azure Portal. This is because it hides a lot of complexity in the underlying REST APIs being used to provision the infrastructure and it also provides me with an easy way to discover required attributes to provision infrastructure I may not have worked with previously. There were a few items in this demo that I knew of, but hadn’t used, so this worked out perfectly. I’d also note I didn’t look at the exiting CloudFormation definitions and try and convert those. What I actually did was use the documentation and diagram on the source GitHub repository as my guide – proving to me that solid existing documentation is key to any migration!

Now with the baseline environment in place I exported the deployment to an ARM template so I could create a reusable template to go into my GitHub sample. I’ve been meaning to learn Bicep for a while now, so I took the opportunity to decompile the ARM template into Bicep which did a pretty good job. I suspect the resulting Bicep definition is overly verbose because it contains a lot of properties with default values that could be removed, but I’m pleasantly surprised at how I could do things like define Storage Account Containers, Cosmos DB Databases and Containers, Key Vault secrets, and a whole range of other things that used to be manual steps. It took me a little while to convert the Bicep into a re-usable template, but I’m pretty happy with the result which also now supports comments!

Once I had the infrastructure deployed I used the Azure Functions Deployment Center to setup a GitHub Action for my deployment. This simple process creates the necessary Secret in GitHub to enable the deployment and also results in a GitHub Action workflow embedded in my sample repository which can easily be forked and cloned as required by others.

Finally, I could sit down and document the sample both on GitHub and via this blog.. so here we are! 😎

Rather than wrap shell scripts around all the commands needed for the sample I’ve tried to expose the raw Azure CLI commands you’d need to use. They aren’t actually that complex and really show the level of consistency the Azure CLI has and how straightforward it is to work with!

Future bets

So if you’ve stuck it out this far… thanks for that!

The process for this blog has been a fun one, but I do think there will be a better way forward with at least some aspects of these types of solutions in future.

Containerisation and Kubernetes offer great platform-agnostic ways for hosting solution components, even if not all solution components live within a portable environment. This also doesn’t mean you need start with this as an option either!

The Azure Functions runtime has been portable since its v2 release and can be run on Azure, on-premises or anywhere you can run a Container. Additionally, I see the work Microsoft is doing around Kubernetes Extensions such as the Azure App Services on Kubernetes and I start to see ways for people to have confidence that they can build solution components once and then have flexibility on where they host them, without needing to do a huge amount of porting work.

Broadening cloud hosted services to provide access to popular technologies like MySQL, Postgres, MongoDB, Redis, Grafana, et al, also means over time you will have confidence that you can truly take your solutions anywhere!

Happy Days! 😎

P.S. You can check out the List Manager Azure sample on GitHub.

How to Build and Debug an Alexa Skill with Python and Azure Functions

Simon Waight — Mon, 30 Aug 2021 23:30:52 +0000

Voice assistants have become all the rage, and they provide a great way to access and consume information. A fairly common scenario, and one that most assistants ship with, is reading the latest news headlines.

This got me thinking about how I could take the foundation of my last post on generating a PowerPoint presentation from the latest Azure Updates RSS feed and use it to create a way for people to hear these updates via a voice assistant.

The assistants most people would be familiar are Amazon Alexa, Google Assistant and Apple’s Siri. For this post I am going to pick Amazon’s Alexa assistant and build a Skill that allows Alexa users to hear the latest Azure news.

Most code samples in the Alexa documentation simply use AWS Lambda serverless backends, but for my post I am going to replace Lambda with it’s equivalent in Azure – Azure Functions. We’ll be using Python to build our Skill.

Note: I opted to go with a bare-bones implementation on Azure, but if you’re looking to build a more complex user experience it’s worth looking at the Azure Bot Service and SDK and then connecting the resulting Bot to Alexa. The benefit of this route is you can build your Bot logic and flow once and then publish to multiple channels.

TL;DR… show me the code!

Maybe you’re looking for a complete non-Lambda Alexa Skill sample in Python and struggling to find anything in the official docs or repositories. If all you want is the code from this blog, you can find it on GitHub.

Want to know how to get it all working as well? Read on!

Pre-requisites

If you’d like to build your own Alexa Skill similar to the one in this post, this is what you’ll need:

Python 3 (I used 3.8) including pip
Visual Studio Code with these extensions:
An Amazon Alexa Developer Account.

Getting Started

Once you have all the pre-requisites in place you can start by creating a new Python-based Azure Functions project in Visual Studio Code using the official Microsoft Quickstart as a guide. You need a HTTP trigger (which the Quickstart uses) and should set the authentication for the method to “Anonymous”.

If you run the Azure Function locally you will see the URL published in a format similar to:

http://localhost:7071/api/YourFunctionName

At this point we are ready to add the code to support our Alexa Skill.

Add the Alexa Python SDK to our Azure Function

We need to first add the SDK that Amazon publishes for developers wishing to build Alexa backends using Python.

If you look in your Azure Functions project you will see a ‘requirements.txt’ file. Open that file in Visual Studio Code and add the Alexa SDK items we need, along with a couple of other libraries we will need to complete our implementation. Once finished your file should look like the snippet below.

azure-functions
beautifulsoup4
requests
ask-sdk-core
ask-sdk-webservice-support

Once you have made these change, and so you have all the libraries locally for development purposes, you can run this command in the terminal in Visual Studio Code:

pip install -f requirements.txt

Note: I found that the Alexa webservices library has a reliance on a version of the cryptography library that appears to clash with versions required for some Azure SDK Python libraries such as Azure Storage. In this sample it’s not an issue, but one to keep an eye out for. Pip will complain when trying to install the package so you’ll know if you hit it!

Now we have the necessary components locally for our development environment we need to configure our Alexa Skill via the Alexa Developer Console. I had a quick look at the Alexa CLI (ask) but it once again appears only to tie into Lambda-based environments so it’s a no-go for us here and we’ll need to use the Console.

Configure our Alexa Skill

When a user invokes your Skill, the request is directed to an Amazon-managed Alexa API which performs the voice-to-text action and then forwards the text to your Skill backend implementation.

In order for Alexa to know about your Skill and its implementation, you have to configure it via the Alexa Developer Console.

Let’s go ahead and do that now.

First we need need to define the Skill, the interaction model to use, and how the Skill will be implemented. I called my Skill “Read Azure cloud news” (you’ll note the Console hint on brand name use – if I wanted to publish this Skill I would need to show I have the right to use the Azure brand, but for this demo it works fine). I will build a Custom interaction model and use my own hosting (the other two options will give you Lambda-hosted solutions).

On the next screen select “Start from scratch” for the template to use.

Next let’s define the Skill Invocation Name.

This is what users will say after they wake up Alexa, so for my Skill I want a user interaction to be “Alexa, ask the Azure cloud news service for the latest news”.

In the Developer Console expand the “Invocations” section and select “Skill Invocation Name” and enter your text. Click “Save Model” at the top.

We have one more step to go before we can head back to Visual Studio Code and cut some code!

We need to create an Intent which is what we use to drive actual user interaction.

To help understand what an Intent is, consider the user interaction of “Alexa, ask the Azure cloud news service for the latest news”. In this interaction our Intent is derived from the “latest news” statement.

In the Developer Console expand the “Intents” section and click the “+ Add Intent” button. We are going to create an Intent for reading the latest top five news items. Give it an Intent Name and click “Create custom intent”.

The Intent Name is important as it is what we will use to match incoming requests in our code.

We then need to provide some sample Utterances (sentences or statements) that a user might use to signal that this is their action (or intent) when using the Skill.

If the Alexa model matches a voice or text command to an Utterance then it will select the Intent and send it through to your backend implementation. Note these matches aren’t simply a 1:1 match – these Utterances help train a voice-to-text recognition model which matches more than just the samples you provide!

Alright, now we’re ready to implement the first parts of our Alexa Skill backend in our Azure Function.

Handling Alexa Intents in your Azure Function

There are a few ways you can implement an Alexa Skill in Python, but for this post I am using Python classes where each class will be used to handle a single Intent.

The below code snippet shows how can handle the Intent we just defined. You can see that it simply does a match on the name of the Intent and then passes any match to the handle function where our actual logic is stored.

For our Skill we download the Azure Updates RSS feed and return to the top five headlines to Alexa for it to read.

You can embed Speech Synthesis Markup Language (SSML) snippets in the text to control how Alexa reads the text.

We also need a couple of other default handlers as well. One for the launch of the Skill which introduces the Skill and tells the user what they can do, and an exception handler which can be used to handle any unexpected errors in your Skill. The code snippets for these are shown below. The LaunchRequest intend doesn’t require you to configure anything in the Developer Console – it’s there by default.

Finally, we need to create a SkillBuilder in our main Azure Function to ensure incoming requests are validated, passed to the right handler, and an appropriate response sent back to the caller.

You can grab your Skill ID from the Alexa Developer Console. In the final implementation I am reading the Skill ID from the application settings so it’s easy for you to update to your own.

You can grab the completed Python Function code from GitHub and add it to your project. This ensures you have the right imports and the RSS function in place to run the solution.

Testing your Skill

Our code is now complete enough that it will manage simple interactions. Before we can test using the Alexa Developer Console we need to do a few things:

Publish our local Azure Function via an ngrok proxy (remember we installed the extension in VS Code). Use Port 7071 which is the default the Azure Functions Core Tools will use. The free tier for ngrok should suffice.
Copy the ngrok proxy address to our clipboard.
Go into the Alexa Developer Console for our Skill and select the Endpoint section.
Switch the Endpoint from being a Lambda ARN to HTTPS and then put in the ngrok proxy address and our Azure Function relative path (/api/YourFunctionName).
Rebuild the Alexa Model.

The video below shows you these steps. Note the video has no audio.

Once we’ done the above steps we can now switch over to the Test tab in our Skill in the Alexa Developer Console and test out our Skill. Here’s a sample of how it works.

Note that if you stay in a breakpoint in Visual Studio Code for too long the Alexa service will automatically timeout and give the user a default message around not being able to complete the request.

Moving to Production

If you go and look at the GitHub repository you will see there is a GitHub Actions workflow which was created by the Azure Functions Deployment Centre in Azure after this repository was selected as a source. Updates pushed to the repository are automatically built and deployed.

You do need deploy the two Application Settings into Azure – one for the RSS endpoint and one for your Alexa Skill ID. For our demo you can manually insert them, but it is possible to automate their deployment as well in the Actions workflow if we really wished.

At this point we can update our Skill Endpoint in the Alexa Developer Console to point at our deployed Azure Function URL, rebuild the model and we are then calling our Production Skill!

If you wanted to launch the serivce you would still need to go through distribution checks with Amazon. In my example they’d be unlikely to approve my use of the Microsoft brand “Azure” so I’d have to change that, but apart from that our Skill is pretty much feature complete!

Bonus Points – Intent with a Slot

Right now we have a fully functional, if basic, Alexa Skill powered by Azure Functions. If you want to see how we can extend the usefulness of the service, read on!

Let’s add support for reading news from a particular date and see how we can build that out. For this we will need to define another Intent for our Skill and define a “Slot” within it for our date.

In the Alexa Console add a new Intent called “ReadItemsFromDate”.

This time when we provide sample Utterances we want to define a placeholder (known as a Slot in the Alexa world) that will be replaced by a user saying a date.

You can add a Slot to an Intent by adding a placeholder in Utterances enclosed in {curly braces}, as shown in the screenshot below. Once you have done this you should then define the data type for the slot.

In our case we will use the pre-defined “AMAZON.DATE” type. As a tip, make sure to understand how these Slots can be interpreted. For example, any date that doesn’t specify a year is always assumed to be a future date… which isn’t really helpful if we are asking for past news items!!!

You can continue to use the Slot in other Utterances so that the model can start to figure out how users might ask for news from a particular date. You can see in the below screenshot where we have set the Slot data type as required.

Now we have this configured we need to write a handler for it in our Azure Function. The code for this is shown below.

The great thing with the Slot type we are using is a Skill user can say something like “top news items from last Tuesday” and Alexa will figure it out and simply send you a date in an ISO-8601 format (YYYY-MM-DD). You can even pass dates back to Alexa in ISO-8601 format and Alexa will speak them out completely to the user.

Wrapping Up

Whew! There’s a lot in this post, but I do so hope you’ve found it useful and it saves you some time – even just having a full non-Lambda sample to help understand how webservice-hosted Alexa Skills hang together.

As a final thought, even though I’ve used Azure Functions as my hosting option, I can easily Containerise this solution and then deploy it anywhere I can run a Container, which means I’m able to deliver a highly available Alexa service that is cloud agnostic without any code or runtime hosting changes!

Until next time, happy days! 😎

Generate a PowerPoint file using Azure Functions and Python

Simon Waight — Mon, 26 Jul 2021 23:30:00 +0000

For many years I have been involved with the Azure Sydney User Group, and even though I’m no longer the organiser I still gather updates for Azure in the prior month and prepare a PowerPoint presentation that contains them. My go-to place for the information is the Azure Updates website and I’ve typically just been browsing the site and manually updating an existing PowerPoint template.

Recently I reflected on the amount of time it takes for me to click through the pages and pull out the headlines, and decided this probably wasn’t a great use of my time. Even though it’s typically under 10 minutes to do it’s still repetitive which clearly means it’s the perfect candidate to automate!

I’ve used it for other integration in the past, so I know the updates website has an RSS feed which is perfect for automation.

Choosing an implementation approach

There are a few ways I could have built an automation, and my original intention was to use either Azure Logic Apps or Power Automate Flow and integrate into PowerPoint online in Microsoft 365. Unfortunately, it turns out there is no native PowerPoint online connector which means this approach became a no-go!

In the absence of this integration capability, I decided to turn to a code-based solution because I know there are many ways to generate Office documents through SDKs that implement the Office Open XML File Formats standard (ECMA-376).

One of the reasons I also looked at Logic Apps or Power Automate was their serverless pay-on-execution model. Keeping this in mind I turned to my trusty friend, Azure Functions. At this stage the no-brainer for me as a long-term C# developer would have been to implement a .NET-based Function, but as I’ve said a few times before, I’m wanting to push my skills to cover other languages, so I thought I’d have a go with Python.

Azure Functions + Python = ❤

It turns out there is an excellent PowerPoint library called python-pptx that has everything I needed, and I found an great blog and sample from Matthew Wimberly that had what I needed to read and parse an RSS feed. Now I had these two elements I needed a little bit of Functions magic to tie it together and provide a simple HTTP API I could use to generate my presentation.

The resulting Azure Function (shown below) does all I need in less than 200 lines of code.

To run it, you invoke the Function via a web browser with a URL similar to:

https://your-func-app.azurewebsites.net/api/GeneratePresentation?code=YOUR-FUNC-KEY&start=2021-06-20&end=2021-06-30

If the supplied date range is valid and there are updates that fall within it, you receive a simple web page with a link to a downloadable PowerPoint file held in a private Azure Storage account which is served for a limited period using a SAS-protected URL. The full documentation around how to debug, deploy and execute the Azure Function can be be found on the GitHub repository for the solution. Also, here’s a sample of what you can generate.

I have deployed the solution onto a Consumption plan in Azure which means I’m not paying for idle compute, and the PowerPoint takes up so little space that my Storage Account costs will be tiny, especially given this API endpoint can’t be invoked by just anyone. Finally, to save myself even more money, I have a Timer Function that once a week deletes any PowerPoint files sitting in the Storage Account, which won’t be many (if any) for most of the time.

I’m pretty happy with the solution as it stands, but in future I might look to use my existing PowerPoint template as the base for the resulting presentation which means there would be even less manual work for me to do. Right now I still need to copy / paste from one PowerPoint to the other, but this is so trivial that I’m not bothered about automating it away … just yet 😉.

Hopefully you find some inspiration in the solution here!

Happy Days! 😎

P.S. The GitHub repository with the solution is here: https://github.com/sjwaight/AzureUpdatesPresentationGen

How to build and run a free link tracker using VS Code, Java, GitHub, MongoDB and Azure

Simon Waight — Wed, 14 Jul 2021 02:17:30 +0000

Many developers are interested in learning how to build and run software on cloud platforms, but are wary of the potential for hidden costs and bill shock.

Often times this bill shock come from not understanding how consumption-based services work, and by being lulled into a false sense of security by the relatively tiny amount per-request / per-MB many services charge. This is all well-and-good until you build something unexpectedly popular that explodes over night and ramps up you bill.

However, most of us will actually never face this dilema and I think it’s a shame that people are limiting themselves to learn something new based on what might happen, not what will happen. Having said this, let’s look at how we can remove some uncertainty when building with Azure.

Building cost-safe solutions

Most of the solutions I’ve built cover the last 18 months easily fit into the “runs for the price of a coffee (at Sydney prices) or less” category, but I am always looking for ways to do better. To this end I am going to try and find ways for you to learn with Azure without the worry that you might need a second mortgage.

The first thing I would recommend doing is looking at the Azure Free Tier and understanding what services it contains and what their limits are, with a particular focus on what happens when you exceed the Free Tier offer. You should revisit periodically as services are added or modified over time – as an example Cosmos DB recently increased the Request Units (RUs) and storage available under their free offer.

Also, consider what you want to do or learn with the platform. If you are completely new to Azure and want to make use of the time-limited financial credits and 12 month increased free service tier, make sure you have goals in mind, otherwise you’ll waste your benefits. I wrote about this in 2018, so it’s worth a read before starting.

Finally, always setup Budget alerts for PAYG subscriptions you pay for. This won’t stop exponential growth happening, but at least you will know about it sooner than your next bill and can act accordingly to limit your expenses.

Our demo scenario

For this post I will be building a simple REST API that can be used to create and track URL shortlinks (think bit.ly). These can be used on blogs like mine to track outbound link clicks.

If I want track any outbound link (say when I reference a GitHub repository), I create a shortlink for the destination, use that shortlink in my blog in place of the actual destination and when a blog visitor clicks on the link their request first hits my shortlink system before being redirected to the actual destination. The shortlink code logs the request and I can report on it later.

As I like to mix things up I’m going to build the solution using Java Spring Boot and MongoDB.

Free local development and deployment

If I’m going to challenge myself to run services for free, I might as well extend that to the entire lifecycle of my application. To that end I’m going to be using the following to help me build and debug my solution locally.

Java JDK 11: you can use one of the free JDKs out there – AdoptOpenJDK or the Microsoft Build of OpenJDK will do.
The Azure Command Line Interface (CLI).
MongoDB Community.
Visual Studio Code: the best free development environment out there. Add these great extensions

Once I’m done writing my solution, I want somewhere to publish my code and to then deploy it to Azure, so for that I’ll be using GitHub and GitHub Actions.

Free hosting in Azure

As a developer I hate managing infrastructure. If it requires a Virtual Machine, you’re doing it wrong! So, for hosting our solution I am going to use Azure App Service and Azure Cosmos DB configured with MongoDB API support. Both these services offer a compelling free tier:

App Service: F1 Free Tier – not designed for prod workloads, but guarantees you stay free. When your app consumes more than 60 minutes of CPU time in a day the web app will be stopped and callers will receive a 503 (Unavailable) message.
Cosmos DB: Free Tier – you can run some good small solutions on this tier. The 1,000 Request Units (RUs) and 25 GB is generous and should suit most use cases. If you generate calls that exceed the RU limit you’ll receive a 429 (Too Many Requests) message and will need to handle in your calling code. You can manage the storage growth by using Time-To-Live (TTL) settings to ensure you don’t exceed the limits, though 25 GB is a lot of documents!

Let’s build our app!

As a starting point, connect to your MongoDB instance and make sure you have an empty database available. I called my database “bloglinks”, but you can use any name you want. Copy the connection URI and database name for use later on.

You can also create an empty repository on GitHub where the application source code will be stored when you are finished and ready to deploy to Azure.

Now, using Visual Studio Code, open an empty folder on your computer and then bring up the command palette (View > Command Palette) and select Spring Initialzr by starting to type ‘spring’. Select “Create a Maven Project…”

Next up let’s select the Spring Boot version. I tend to favour stable releases, but the choice is yours. Note your versions will likely look different to the below one depending on when you read this blog.

Make the project language Java.

Now set up the necessary details to generate your package name.

Set Packaging Type to ‘Jar’ and Java version to ’11’.

Finally, let’s pull in the Spring Dependencies that will help us get going quickly with our solution. For our application we’ll use Spring Web, Spring Data MongoDB and Spring Security.

OK, so now we have a basic Spring Boot web application scaffold which we can build on top of. Rather than spend more time on pulling this together I am going to direct you to the source code for a pre-built version of the application which you can use as the basis of yours.

Make sure to pay attention to the application.properties.prod file. You can use this locally on your machine (rename it application.properties) to manage configuration for basic authentication and connection to MongoDB. It’s important to ensure you add this file to your gitignore when committing to GitHub though, especially if you use a remote MongoDB instance.

Once you’ve completed coding up the solution you will find that the Spring Data MongoDB library will automatically create the necessary Collections for you in your Database. We will use these two Collection names when we create placeholders in Azure in our next step.

Setting up Azure

We will use the Azure CLI to complete these steps, so make sure you have it installed and that you have logged into the subscription you want to deploy to.

First we’ll create a Resource Group which can contain all our services. You can choose the location that suits you.

az group create --name MyResourceGroup --location westus2

Create a free Azure App Service Plan.

az appservice plan create \
    --resource-group MyResourceGroup \
    --name MyAppsPlan \
    --is-linux \
    --sku FREE

Create Web App using the Plan. We will pre-configure the Web App with the right Java environment (Java SE web server 8 with Java 11).

az webapp create \
    --name myuniquewebappid123 \ 
    --resource-group MyResourceGroup \
    --runtime "JAVA|8-java11" \
    --plan MyAppsPlan

Create free tier Cosmos DB configurated with the MongoDB API v4.0.

az cosmosdb create \
    --name MyCosmosAccount \
    --resource-group MyResourcegroup \
    --enable-free-tier true \
    --kind MongoDB \
    --server-version 4.0 \
    --default-consistency-level "Session"

Now we can create our Database and Collections in Cosmos DB.

# Create 'bloglinks' Database
az cosmosdb mongodb database create \
     --account-name MyCosmosAccount \
     --resource-group MyResourcegroup \
     --name bloglinks 

# Create 'shortLink' Collection
az cosmosdb mongodb collection create \
     --account-name MyCosmosAccount \
     --resource-group MyResourcegroup \
     --database-name bloglinks \
     --name shortLink

# Create 'linkClick' Collection
az cosmosdb mongodb collection create \
     --account-name MyCosmosAccount \
     --resource-group MyResourcegroup \
     --database-name bloglinks \
     --name linkClick \
     --idx '[{"key":{"keys": ["_ts"]},"options":{"expireAfterSeconds": 5184000}}]'

Now, you might look at that last Collection create statement and wonder what I am doing here? Well, remember earlier I mentioned we wanted a way to ensure we don’t hit our storage limit (even though that’s unlikely to ever happen… but why find out?!), well this is how I will manage it this scenario.

Cosmos DB has a great Time-To-Live (TTL) feature which can be used to expire documents, meaning they are removed from result sets and ultimately purged from storage. Best of all? No cost involved!!

If you want to use this feature with the MongoDB API you need to use Mongo Indexes over the Cosmos-internal “_ts” document property to drive this feature. Based on the official Microsoft documentation you can define these indexes when creating a Collection (as above) or separately later using a MongoDB client to create the index. I’ve set the expiry at 60 days as I should ideally of processed the collection data by this point, and if not… that’s on me!!

As a last step, let’s grab the MongoDB connection URI for our Cosmos DB we can use in our configuration below.

az cosmosdb keys list \
     --name MyCosmosAccount \
     --resource-group MyResourcegroup \
     --type connection-strings

OK, so at this stage we have a web server and a MongoDB database ready for our application to be deployed.

Deploying and configuring our web application

The final piece of the puzzle is to deploy and configure our web application.

Let’s start with the configuration. We have four configuration elements we need in order for our web application to work:

spring.security.user.name
spring.security.user.password
spring.data.mongodb.database
spring.data.mongodb.uri

Locally we have been holding the values in our application.properties file, but we don’t want to push that file to GitHub, so make sure when you publish the solution to GitHub that you exclude this file.

Azure Application Service provides a nice neat way to provide these four values via App Settings which we can deploy as follows. Convert each application.properties placeholder into an equivalent with underscores instead of dots.

az webapp config appsettings set \
    --resource-group MyResourcegroup \
    --name myuniquewebappid123 \
    --settings SPRING_SECURITY_USER_NAME=youruser \
SPRING_SECURITY_USER_PASSWORD=5ecureP4ssword \
SPRING_DATA_MONGODB_DATABASE=bloglinks \
SPRING_DATA_MONGODB_URI=mongodb://your_cosmos_uri/

Finally, let’s configure the GitHub Action to deploy the application for us.

az webapp deployment github-actions add \
    --resource-group MyResourcegroup \
    --name myuniquewebappid123 \
    --repo "youruser/your-repo" \
    --runtime "JAVA|8-java11" \
    --login-with-github

You will be prompted to log into GitHub at https://github.com/login/device using a specific ID, and after completed you should find that there is now a new folder in your repository which contains the workflow which will build and deploy your solution!

After a few minutes you find that a workflow kicks off and your application is now deployed and ready to serve requests!

Testing it out

Before we wrap up, let’s test out our deployed solution. The easiest way to do this is to install Thunderclient for VS Code and then open the collection I’ve included in the sample app repository. Make sure to update the hostname to match the one you used in Azure, and that you set the basic authentication username and password to match yours too.

When you use the POST call to create a new shortlink you will receive a “201 Created” HTTP response code and the details for the created entry are in HTTP response header as the ‘location’ field. This is shown below. If you try to create a link that already exists you will receive a “200 OK” HTTP response code and the shortlink data will be returned in the response body.

Wrapping up

We’ve done a lot in this post, but I’m not 100% done yet. If you’ve run all the requests you will notice that there is a field called “visitors” that has a value of zero. We need to build a solution that will populate this field for use periodically, ideally in a zero-cost fashion as well. In a future post I’ll take a look at how we can do this.

In the meantime… happy days! 😎

Windows Containers and .NET Framework applications: DevOps with Kubernetes

Simon Waight — Tue, 20 Apr 2021 23:11:40 +0000

In my previous two posts on .NET Framework applications and Windows Containers I took a look at the rationale and approach for bringing these applications to containers before using a sample application (MVC Music Store) to show what is involved with containerising an application.

In this post I am going to take the next step – take our containerised ASP.NET web application and deploy it to Kubernetes whilst making sure the build and deployment process is centralised and repeatable.

Setting up Kubernetes

I’m going to use Azure Kubernetes Service (AKS) for this post, so to start I am going to create a new AKS cluster with a Windows Node Pool. Even though I’ve selected an Azure managed service there is nothing stopping you from using a similar approach to deploying to Kubernetes either on your own infrastructure or in another cloud.

Let’s start by creating a new AKS cluster using the following commands.

You will be prompted for a strong Windows password for the specified admin user. If you receive an error with “Invalid adminPassword” then you haven’t met the security standards set via policy and will need to increase complexity or length of the Windows admin user’s password.

# Only required if AKS creation fails due to Service Principal 
# not existing or unable to be created automatically.
az ad sp create-for-rbac \
    --skip-assignment \
    --name myAksServicePrincipal

# Create new cluster with 2 system (Linux)
# nodes (you will be prompted for a password)
az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-count 2 \
    --enable-addons monitoring \
    --generate-ssh-keys \
    --location myAzureRegion \
    --windows-admin-username windowsAdminUser \
    --vm-set-type VirtualMachineScaleSets \
    --network-plugin azure \
    --service-principal myAppIdFromAdCreate \
    --client-secret myAppPasswordFromAdCreate

# Add Windows Node Pool with 2 nodes
az aks nodepool add \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --os-type Windows \
    --name winnp \
    --node-count 2

At this point we now have a 4 node Kubernetes cluster – two nodes running Linux and two nodes running Windows.

As a final piece let’s export the kubeconfig that we will use later for depoying our solution’s Container to AKS from GitHub Actions.

az aks get-credentials \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --admin \
    --file akscreds.txt

The local file “akscreds.txt” now contains the data you’ll need to configure a deployment into AKS. Protect this data as it is the keys to your Kubernetes castle (hint: once you’ve used it later to configure the deployment you should delete the file).

Configuring our connection string

In the previous post we used the new Microsoft.Configuration.ConfigurationBuilders.Environment extensions available for .NET 4.7.1+ to allow us to supply the database connection for our sample ASP.NET web application via Windows environment variables.

In Kubernetes we can supply these environment variables via a few methods to container instances. As we are dealing with sensitive information we’ll use Kubernetes Secrets which are managed centrally within any cluster. Let’s go ahead and add our MusicStoreEntities environment variable to our cluster.

Secret values must be supplied as base64 encoded strings. This means we have to encode our connection string before we create a Secret with it. On Windows we can do this use the following PowerShell snippet.

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("YOUR_CONNECTION_STRING"))

This will output the connection string as a base64 encoded value. Copy the value as we will use it the next step.

Next, use your favourite text editor (VS Code, right 😉) to create a new file called “musicstoreentities-secret.yml” that will look similar to the below. Replace the “connstring” entry with the base64 encoded connection string you just created, then save the file.

Now we have this file we can go ahead and create the secret in our cluster. Exactly how you do this will depend on how (or where) your Kubernetes setup is hosted. You can use the Kubernetes command line tool (kubectl) to add the secret, but that requires setup first which I won’t cover here.

In my instance I’m using features in AKS that allow me to add the secret via the Azure Portal so I don’t need to have kubectl installed or configured (I could also do it via Azure Cloud Shell *with* kubectl… but that’s another story 😉).

OK, so we should now have everything we need in our Kubernetes setup so we can deploy and run our application!

Back to the Dock(er)yard

Let’s return to our updated Visual Studio Solution and review the Dockerfile that was added by the Visual Studio Container tools.

This is a very succinct Dockerfile 😎. There is no definition in this file that tells the executing builder how to actually perform steps like NuGet restore or execute MSBuild – these are all defined outside of this context because the assumption is that Visual Studio will run and that the resulting build output lives in “obj\Docker\publish”.

The problem we have is that it works very well when you are building using Visual Studio, but not when you try to use this in a Continuous Integration scenario where Visual Studio may not be installed on the build host (this is a good thing BTW – not having VS on your build host).

We can fix this, but it requires some manual work as we cannot get Visual Studio to generate a full file for us. The resulting Docker file is shown below and also sits in the sample GitHub repository.

The above Dockerfile is a multi-stage Docker file and it’s worth exploring it a bit. Our initial build and compilation takes place on the sdk:48 base image (tagged as “build”). This image contains the full .NET Framework SDK which includes tooling such as MS Build.

Once the application has been succcessfully compiled we then use a new base image (aspnet:4.8 – tagged as “runtime”) to which our build output is copied. This new base image does not contain the full SDK. Both from an image size and security standpoint this is a win – we don’t have unnecessary files on our runtime host which is great.

Storing our Container Images

Once built we need a location to store our Container Images. In most cases these Images are held in private Container Registries, and for this post I am going to use Azure Container Registry (ACR) as my storage location. You can choose to use any Docker-compatible Registry you like though as long as GitHub Actions can publish to it.

az acr create --name myContainerRegistry \
              --resource-group myResourceGroup \
              --sku Basic \
              --admin-enabled true \
              --location myAzureRegion

Once the Container Registry is provisioned I then need to attach it to my AKS cluster. This will enable AKS to pull images from the ACR instance without the need for pull secrets.

az aks update \
   --resource-group myResourceGroup \
   --name myAKSCluster \
   --attach-acr $(az acr show --name myContainerRegistry --resource-group myResourceGroup --query "id" -o tsv)

Building our Container Image with GitHub Actions

Thankfully the task of building and pushing our Container is not that difficult, particularly if we select ‘windows-latest’ as our build host in GitHub Actions. Windows Server 2019 (‘windows-latest at time of writing) contains all the necessary Docker binaries we need to build a Windows Container, so we don’t need to spend time specialising the host which is great.

The below Gist contains the contents of the GitHub Action that does exactly what we need. You can find the actual GitHub Action definition in the ‘deploy-to-k8s’ branch of the repository on GitHub.

In order to get this Action functional we need to define a few GitHub Actions Secrets which are only made available to the build agent when the Action executes. Secrets are a great way to hide information from others not authorised to access upstream services (such as our Container Registry) or from those who may troubleshoot failures looking at logs (Secrets are not captured in logs).

Our Secrets are as follows:

ACR_USER: Azure Container Registry user (Username on Access Keys blade in Azure Portal – typically same as Registry name).
ACR_INSTANCE: Azure Container Registry name.
ACR_SECRET: Azure Container Registry Password or Password2 value.
IMAGE_NAME: Used as the Docker image name. Doesn’t necessarily have to be a secret, but might be useful to obfuscate the image name. This also ends up as the ‘repository name’ in Azure Container Registry.
KUBECONFIG: grab the contents of the ‘akscreds.txt’ file and paste it into this. We’ll use this later to deploy to Kubernetes.

Deploying to Kubernetes

The last piece of the puzzle is taking our freshly minted Container Image and deploying it to Kubernetes. We have a couple of ways to do this – either by defining some YAML and deploying the Image using kubectl, or we can look at using Helm. For this post I am going to use Helm. You’ll need toinstall the Windows release of Helm first before you can work with it on your local developer machine.

Once Helm is installed, open the MVC Music Store project in Windows Explorer and in the root folder create a new sub-folder called ‘charts’. Open this folder at a command-line and issue the following command to create a Helm Chart scaffold.

helm create mvcmusicstoreweb

A series of files and folders will be created and we only need to make a few minor changes to the scaffolded files to be able to use them.

Edit the Chart.yaml file and update it as follows. We should auto-update some values in this file and the values.yaml file, but for the purpose of this blog post we’ll go with static values. Key items of note below are the name, description and appVersion attributes.

Then we need to make some modifications the the values.yaml file as well. Key entries to update or add here include the nameOverride, fullnameOverride, requests (cpu and memory) and the nodeSelector to ensure the workload is scheduled onto a Windows Container host.

The final piece of the puzzle is to make sure that our environment variable containing our database connection string (MusicStoreEntities) is populated from a Kubernetes Secret.

In order to make this happen we need to edit the templates\deployment.yaml Helm file and add the env section (lines 36 - 41) that tells Kubernetes to create an environment variable and pull the value from a named Secret (dbconnection) which we created earlier in this post.

We also need to build and deploy the Helm Chart somewhere. For my purposes I am going to use Azure Container Registry’s inbuilt Helm Chart support for storing built Charts and then add a stage to my GitHub Action that builds the Chart for me.

You can find the ‘build-and-push-helm-chart step in theAction on GitHub and which is reproduced in full below.. Note that we don’t need to install Helm on the build host as the Windows 2019 hosts used by GitHub Actions already have it deployed.

Now if we submit this GitHub Action we should see a new Windows Container image built, published to Azure Container Registry, followed by a new Helm Chart being created and published, also to Azure Container Registry. Finally, the Helm Chart is then used to tell Kubernetes to either deploy or update the Image running on the cluster. You can view this successful run on GitHub.

You can see the Image build takes 11 minutes. That’s not a trivial amount of time, but I am using the free running tier in GitHub Actions, so it’s likely you could speed this up. Having said this, you may not run this process on every check-in and may wish to use it only for PR-merges into a deployment branch (for example!)

Once these steps are completed we should find that we have a new Service in AKS called ‘mvcmusicstore’ and that it has a LoadBalancer type with an External IP address.

If we click on that IP address we get…

… the sweet taste of success!!

Whew! 🤓

So we made it through – taking an existing ASP.NET Web Application and moving it into Windows Containers and then showing how we can deploy it to Kubernetes, while ensuring it can still connect to its database.

While this has been a fairly simple application to move, a lot of concepts are the same, even for complex applications. Most work will likely go into bringing the .NET release up to a supported version (3.5+), along with making sure any third party libraries work as expected.

I hope you’ve learned about modernisation of .NET applications using Windows Containers in this series of posts, and until next time…

Happy Days! 😎

Windows Containers and .NET Framework applications: Migration

Simon Waight — Mon, 22 Mar 2021 22:30:00 +0000

We previously looked at the basics of what is involved in bringing .NET Framework applications to Windows Containers. In this second post we are going to go a little deeper and look at migrating an application.

We already know that we have some discreet requirements around the types of applications that can be migrated, so for this post I am going to use one of the original ASP.NET MVC sample applications – MVC Music Store – the source code for which we can find on GitHub.

As previously discussed, anything earlier that .NET Framework 3.5 will require an upgrade to that release. Depending on the complexity of your solution this may or may not be a trivial task. If you’ve come here looking for a magic bullet for that… unfortunately I don’t have one!

While MVC Music Store is a good sample application for this post, it’s important to note that it is already running on .NET Framework 4.0 so there is not much work for us to do here, but I do want to bring it up to .NET Framework 4.7.2 – more on why later!

Your Toolkit

In order to have a go at this yourself you will need the following:

A GitHub Account
Hyper-V / virtualisation enabled in Windows 8 or 10 Pro
Minimum of 10 GB free disk space for Windows Container / ASP.NET base images
Docker Desktop for Windows
Visual Studio – ideally 2017 (v15.7+) or 2019 (16.x). You can use the Community Edition if this is for non-commercial or open source contribution purposes. We want these versions as they include Docker tooling that we can use to build and debug the application
.NET Framework 3.5.x or 4.x installed. Your target SDK must be installed to upgrade
[Optional] Azure Subscription. For my purpose I will use Azure SQL Database as my database storage engine and in a later post I will use Azure Container Registry and Azure Kubernetes Service to host and run my containerised app.

Why not Visual Studio Code?

We are using the full Visual Studio application as opposed to Visual Studio Code because we are porting a .NET Framework application that likely relies on the Visual Studio Solution format. This format holds the metadata about how the multiple projects in the Solution relate to one another, along with build configurations. Visual Studio Code doesn’t natively support Solution files, and while you can still work with the projects it would likely mean lots of lost time tying together the individual projects and building and releasing them.

Upgrade our application

Start by forking the MVC Music Store repository you can find on GitHub, followed by cloning it to a machine with your developer tools on. You can do this from the command line, or use the in-built Git support in Visual Studio.

Once cloned, open the solution in Visual Studio (for my purposes I’m using VS 2019 Community Edition). You will be prompted to migrate the project if you are using a newer release of Visual Studio than the solution was created with.

You can see the project isn’t loaded at this point, so right-click on it and select ‘Load Project’ from the context menu. When you do this you will be presented with one or more dialogs that detail what changes are necessary to migrate the project to the version of Visual Studio you are running.

Interestingly, despite our migration we can still open this project all the way back to Visual Studio 2010!

Follow the prompts and migrate the projects using the in-built Visual Studio tooling. Depending on your solution this option may not be available. I realise the first sentence glosses over a lot of potential complexity, but in the case of our sample application, not much is required. It’s likely with older or more complex solutions that this is where you will start your journey of upgrading / replacing components of your solution so it runs on a more modern release of the .NET Framework.

In the case of our sample MVC Music Store application the tooling advises that some features of ASP.NET MVC 3 may not work as expected in the IDE, and sure enough, if we open a Razor view we can see that there are lot of errors reported, though the solution builds and runs just fine.

Now let’s switch the .NET Framework version we’re running on.

Right-click the project you want to change and choose Properties at the very bottom of the context menu. On the project properties Application tab, update the project to the .NET Framework version you want (note: you must have it installed in order to be able to select it). Once again, if you are making a big step up in Framework versions you may either receive lots of warnings or errors at this point, or you may be unable to change. If you have multiple projects you will need to bring them all up to the same level as well.

Once this update has been done (and you’ve fixed any issues arising) then let’s restore the NuGet packages required to run the application. Open the Package Manager console by selecting the Tools menu > NuGet Package Manager > Package Manager Console and running the following three commands.

At this point we should have a functional codebase that compiles and that can run. The final two pieces we need before we containerise the application are updating the app so it doesn’t use SQL CE and so that session state is not “InProc”.

As I mentioned earlier in the post, I have decided to use Azure SQL Database for my scenario, but you can use any SQL Server you like that doesn’t get bundled with the app like SQL CE. The below script gives the Azure CLI commands you can use to create a new Serverless Azure SQL Database instance and obtain the connection string. Replace the placeholders with appropriate arguments.

The MVC Music Store sample will automatically populate the database on first run, so we don’t need to populate any data in the database, but we do need to modify the web.config file so that it points at the right Azure SQL Database for MusicStoreEntities connection string.

While you are editing the web.config, also find all instances of ‘DefaultConnection‘ that were inserted when you installed the Microsoft.AspNet.Providers and set them to MusicStoreEntities so that all the providers use the same database. In a production environment we’d likely split all our provider datastores out from our application data, but for our sample application this will suffice.

For the session state we should have all the necessary bits present in the web.config after installing the Providers NuGet package. All you need to do to use SQL Server for session state is update the sessionState section of the web.config and point it at our SQL Database by using our Azure SQL DB connection string name for the DefaultSessionProvider.

Now you should be able to run the application in Visual Studio and after a few moments the website will load and the database will be populated. Once you’ve had a click around you can stop debugging.

Note: if you want to use the ‘Admin’ section of the site you will need to manually create a new ‘Administrator’ role and then map it to a user you create via the website registration link. You can perform all these steps using the open source Azure Data Studio.

Containerising our application

Now the fun begins! 😁

In Visual Studio right-click on the project file and select Add > Docker Support…

After a few minutes processing you will find that a Dockerfile has been added to the project along with a .dockerignore file which controls what content is copied during a container build. You will also find that a new debug option appears in Visual Studio – you can debug with “Docker” which will build the application as a container image and deploy the image to Docker Desktop and then attach the debugger.

If you have been previously running Linux containers using Windows Subsystem for Linux (WSL) you will find when you first run your application in a container that the Visual Studio container tools will switch Docker to use Windows Containers instead.

As you are also unlikely to have the base container image (the default currently for ASP.NET apps is ‘4.8-windowsservercore-ltsc2019) this image will also be downloaded and unpacked, which can take a while (and which is the reason you need free disk space!)

At this point, once the base image has downloaded everything should fire up just like it did previously. I think we can call that “step 1 complete” 😁

Making an idempotent container image

Up until this point we’ve been focused on updating our application codebase to work with a more recent release of the .NET Framework, along with getting all the tooling and process in place so that inner loop development is rapid and not that different to a non-containerised app.

There is one item we still need to deal with though. This might be something you don’t care about, but I suspect you will.

Here’s how we currently manage how we connect to our database.

In a traditional ASP.NET build and deployment environment we would likely use web.config transforms for each environment we want to deploy to and allow tooling like Web Deploy to manage this setting for us at deployment time. We could continue to use this approach, but it would mean a different container image per environment with the only difference being the configuration file. Not ideal with such large base image sizes and potentially a big overhead for large environments. This also isn’t a common way of managing containers.

One reason you want to aim for .NET Framework 4.7.1+ is that Microsoft introduced some new capabilities in this release that provide a way for us to easily override certain web.config sections and use a more container-centric way of managing per-environment configuration. If you are unable to move up to this Framework release then you have some options. You could develop your own solution if you had enough applications warranting it, but I don’t see why that yak shaving should be necessary.

For our scenario we are going to use environment variables to hold per-environment configuration and use the library Microsoft has provided. If this doesn’t work for you, Microsoft PM, Anthony Chu has a good approach on his blog to solving this in other ways. If you are doing a lot of container or non-.NET development work then using environment variables for runtime configuration will be very familiar to you.

In order to support this capability in my MVC sample you need to install the NuGet package that contains the logic for this new configuration source.

Install-Package Microsoft.Configuration.ConfigurationBuilders.Environment -Version 2.0.0

You can read about the this and other configuration sources on the GitHub repository hosting the code.

Once installed you then need to do a few things on your development machine:

Create an Windows environment variable called “MusicStoreEntities” (this matches the web.config key) and set its value to the connection string.
Add an attribute to the connectionStrings section that sets it to be read from environment variables.
Remove the connection string value from the config file so it just reads “ignored” (this avoids confusion later)
Restart Visual Studio to force it to re-read environment variables.

The result is our configuration section looks like the below.

At this stage we can run the application in Docker again and get….

Oh.

Actually, we should expect this. We set the environment variable in Windows (the container host) but the value is not cascaded to the running container, so our running container has no idea how to connect to the database!

How to fix? The standard containerised app way is to pass the environment variable to the docker command when running the container, but this gets a tricky if we want to debug from within Visual Studio using the standard “hit F5” experience.

The solution we’ll use comes from Stackoverflow and requires you to modify the csproj file manually and to add a pre-build event.

In the project file (after unloading it) find the Debug configuration (we don’t want to use this for Release builds… we’ll deal with those other ways) and add the following XML snippet.

<DockerfileRunEnvironmentFiles>debug_config.env</DockerfileRunEnvironmentFiles>

Once the XML snippet is added close the project file and reload the project and edit the pre-build event and populate the contents of this file by using the standard Windows echo command to write the environment variable to the file we referenced above (it’s OK if the file doesn’t exist – it will be created).

Now when you go to debug the solution the pre-build step will create the file that contains the environment variable which will be passed to the container at start and your database will now be accessible to the application that runs there.

Next steps

I could keep on going with this post, but I think this makes a logical place to pause.

For my next blog I will cover how we can centralise our container image build and how we can define a deployment pipeline so the container image can be deployed to Azure Kubernetes Service (AKS).

In the meantime, if you’d like to see how the MVC Music Store solution is after the work we’ve done in this post, then you can check out that version of it on the ‘post-containerisation’ branch on GitHub.

Until next time! 😎

Windows Containers and .NET Framework applications: The Basics

Simon Waight — Mon, 04 Jan 2021 22:21:15 +0000

In this multi-post series I am going to look at what is required to take existing .NET Framework applications and bring them to Windows Containers.

Rather than just dive into the mechanics of the process, first I’d like to take a look at why you might want to move to Windows Containers and what you should be aware of before you start this journey.

Let’s dig in!

Why should I containerise my .NET Framework app?

This is honestly the place you need to start any conversation. A lot of our industry is driven by trends, and the current one is to Containerise everything and then run it on Kubernetes!

My advice is to not blindly decide this is the path for your current applications simply because you read a lot about it and see it at all the conferences you attend!

From my point of view I think the following reasons are why you might consider containerisation:

Clear fit for purpose. If you have modern .NET Framework 4 applications that fit nicely into the microservices paradigm then it probably makes sense to containerise them and run them on an orchestrator like Kubernetes.
Consistent deployment and management methods for all platforms. If you are already heavily invested in containerisation for other stacks in your business or team, then why not for your Windows and .NET Framework apps too? Now you have one way to package, deploy, rollback and manage your apps.
Pushing ops left in your SDLC. I’m amazed that people still remote into production servers and change stuff on the fly. Containers make this a more difficult proposition and force developers to build solutions with immutability in production in mind. This is probably the biggest hidden benefit in adopting Windows Containers though many developers may not agree! 😉
Better resource utilisation and separation. Containers have less overhead than a full VM and represent much better App Domain separation than running multiple .NET applications on the same Windows VM. As Windows Containers only contain your application and user mode portions of Windows you have a smaller overall footprint versus a traditional VM but benefit from a clearer separation between applications that may run on the same Container host.

Can I bring any .NET Framework app to Windows Containers?

TL;DR – the answer is no. Read on for more detail…

Windows Desktop applications

The first use case that isn’t supported is Windows desktop applications. Some people might look at a Container as a way to provide remote desktop services to end users, but this scenario isn’t supported and from what I’ve read is unlikely to be supported.

If this is a requirement in your environment then you should look at Microsoft’s App-V (Application Virtualisation) that can be used to serve desktop applications to users on demand such that the applications aren’t installed on the users desktop. Alternatively a hosted remote desktop service like Azure’s Windows Virtual Desktop might also suffice.

.NET 1.x and 2.x applications

The minimum requirement you have to meet for .NET on Windows Containers is .NET Framework 3.5. This means if you have codebases (or pre-compiled apps) that rely on either the 1.x or 2.x .NET Framework then you’re out of luck.

Given .NET Framework 3.5 first shipped around 2008 that means you’ve had at least a decade to update your application to it. If in that decade you haven’t, then unfortunately Windows Containers are not a silver bullet for you!

If you’ve come here to figure out how to move forward from .NET 1.1, then I’d recommend reading the official Microsoft documentation on migrating from .NET 1.1 to 4.x.

Dependencies requiring manual installation

If you have dependencies such as third party libraries or software that require you to manually intervene in their installation then you’re going to need to find alternatives.

While it is possible to install software in Windows Containers as part of your Dockerfile, the installation must be totally command-line driven. If you’re unable to execute the installer and provide it with configuration via the command line then it’s a ‘no go’.

Here’s a sample showing how to install an MSI using PowerShell. This is taken from a Dockerfile to install iisnode which enables integrated Node.js support on Windows’ in-built web server IIS.

RUN Write-Host 'Downloading iisnode' ; \
    $MsiFile = $env:Temp + '\iisnode.msi' ; \
    (New-Object Net.WebClient).DownloadFile('https://github.com/tjanczuk/iisnode/releases/download/v0.2.21/iisnode-full-v0.2.21-x64.msi', $MsiFile) ; \
    Write-Host 'Installing iisnode' ; \
    Start-Process msiexec.exe -ArgumentList '/i', $MsiFile, '/quiet', '/norestart' -NoNewWindow -Wait

Picking your base image

Now that you’ve finally decided that you want to move to Windows Containers you need to figure out which base image you’ll use.

Microsoft has introduced a new way in which it offers updated Windows Server releases so it’s important to understand this first.

Most of us would be familiar with Windows Server 2016 and Windows Server 2019. These two releases are part of the Long-Term Servicing Channel (LTS) for Windows which follows the fairly traditional ~ 3 year cycle of major releases with regular updates and fixes.

The newer concept is the Semi-Annual Channel (SAC) which is updated with new capabilities much more regularly than the LTS releases. These releases are referred to by their release number rather than a year. So, for example, “Windows Server 20H2” or “Windows Server 1903”.

You can read more about the differences between LTS and SAC on the official Microsoft Docs site.

Which foundation image you choose is up to you, but for my money I’d be more inclined to switch to the Semi-Annual Channel releases because your Container Images probably shouldn’t be long-lived any way, and as you need to rebuild from a base Image on a regular basis it’s best if you’ve got the latest bits, especially if they include Windows Container updates!

But wait, there’s more!

In addition to choosing the Windows Server release to use you will also need to determine which Windows Server image type you want: Windows Sever Core, Windows Nano Server, Windows or Windows IoT Core.

I know this seems like a lot to grok, but the reason you have these choices is really about reducing the size of your base Image.

Nano Server offers the smallest size, but really only supports .NET Core applications. Most .NET Framework applications can run on Windows Server Core, and you only need to consider the full Windows Server Image if you have dependencies on Windows capabilities like GDI+.

There’s also some additional options for base Images that come with either the .NET Framework or ASP.NET pre-loaded.

You can dive into the detail, and how to select the right Image on Microsoft Docs.

What’s next?

In my next post I am going to take an existing .NET Framework application and work through how we get it up and running on Windows Containers. Exciting!!

Until then… 😎