Forem: Steven Murawski

ClickOps to GitOps (an Azure Marketplace story)

Steven Murawski — Mon, 25 Sep 2023 16:32:35 +0000

Our GitOps Journey So Far

What Has Come Before

Our team has dug into some of the basics of GitOps over the past week. So far, we've talked about:

A Quick Recap

The Principles of GitOps

1) Declarative

A system managed by GitOps must have it's state expressed declaratively.

2) Versioned and Immutable

Desired state is stored in a way that enforces immutability, versioning and retains a complete version history.

3) Pulled Automatically

Software agents automatically pull the desired state declarations from the source.

4) Continuously Reconciled

Software agents continuously observe actual system state and attempt to apply the desired state.

Application of the Principles

GitOps tools boil down to:

A Git repository
An artifact repository (by default, a branch in the Git repo)
An agent that is responsible for ensuring that the state of the cluster matches the configuration defined in the artifact repository (over time)

Applying GitOps

Applying these principles to the use of the tools identified, we can effectively manage our Kubernetes clusters and workloads therein with auditable, automated changes and maintain a consistent configuration despite unintentional configuration drift.

Our Next GitOps Tool Exploration - ArgoCD

Now, it's time to dig in to the next GitOps tool in the GitOps ecosystem - Argo CD.

Argo CD is part of the Argo ecosystem of tools. Argo CD is a GitOps engine and continuous delivery tool. Argo CD is a Kubernetes controller that monitors the applications running inside your cluster and ensures that it matches the desired state (as represented by manifests or Helm charts in your target repository).

Reducing Time to Impact with the Azure Marketplace

The Azure Marketplace is integrated into our Azure Kubernetes Service (AKS) clusters and provides a way for open source and commercial offerings that are container-based to be easily deployed into AKS clusters.

Installing ArgoCD from the Azure Marketplace

Argo CD is offered through the Azure Marketplace. Marketplace offers are installed as extensions into AKS.

We'll start in the Azure Portal on the AKS Cluster view.

Extensions + Applications

We'll navigate down the left-hand side of the page to the Extensions + applications item under Settings.

Add an Application

Next, we'll select Add.

We'll put argocd in the search box and select the Argo CD packaged by Bitnami offering.

The search will return two options, one a container and one a Kubernetes App. We'll select the Kubernetes App and click Create

This will open up the Create Argo CD packaged by Bitnami page. We specify a subscription and resource group, as well as whether or not we need a new AKS cluster.

The next step will be moving to the Kubernetes Cluster (AKS) Details tab.

After we specified the cluster details, we move to the Application Details tab. Here, we add a resource name (which has to be lowercase letters or numbers - no symbols - of between 6 and 30 characters). We can customize the namespace, but we'll take the default. And we can decide if we want the extension to be able to automatically deploy minor version updates.

The last step of this process is to go to the Review + create tab. Here we'll see the versions of the application and deployment resources, as well as any potential cost (for the packaged application specifically) and other details like terms of use. We'll click Create here.

Clicking Create kicks of the deployment process.

After the deployment completes, we'll have argocd listed in our Extension + applications section of our AKS Cluster.

Access the Argo CD Server

We'll retrieve the Argo CD Server password with kubectl.

kubectl get secret argocd-secret -o jsonpath='{.data.clearPassword}' | base64 --decode

(or if you are like me and using PowerShell)

kubectl get secret argocd-secret -o jsonpath='{.data.clearPassword}'  | % {[system.text.encoding]::utf8.getstring([system.convert]::FromBase64String($_))}

Then, we need to expose the Argo CD server so we can access it from our workstation.

kubectl port-forward svc/argocd-argo-cd-server 30443:80

Then, we can access the Argo CD Server at https://localhost:30443 with the user name admin and the password we retrieved in the previous step.

From there, we could jump into the sample in the Argo CD documentation and carry on from there.

Summary

The AKS Marketplace provides a convenient way to installed a somewhat managed experience and quickly get started with new applications.

Getting Argo CD up and running is pretty simple and we can start exploring it in greater depth in our AKS environment.

Continue the conversation

Leave your questions in the comments or come over to the Microsoft Open Source Discord and chat with me and my team in the cloud-native channel!

And check back with our team tomorrow, as Paul digs into Flagger.

My Git and VS Code Settings

Steven Murawski — Wed, 20 Sep 2023 19:06:36 +0000

I work regularly with several different project types and languages across Windows, Mac, and Linux.

I find some basic settings for Git and VS Code smooth out some headaches.

My user settings include:

"files.eol": "\n", // Windows usually doesn't care, but Linux/Mac tooling is way more sensitive
"editor.trimAutoWhitespace": true,
"editor.fontSize": 16,
"editor.formatOnPaste": true,
"editor.formatOnSave": true,
"window.zoomLevel": 0,
"[powershell]": {
    "editor.tabSize": 4
},
"[ruby]": {
    "editor.tabSize": 2
}

My git config consists of:

[credential]
    helper = wincred
[user]
    email = <my email here>
    name = Steven Murawski
    signingkey = <my gpg signing key here>
[diff]
    tool = default-difftool
[difftool "default-difftool"]
    cmd = code --wait --diff $LOCAL $REMOTE
[alias]
    commit = commit -S -s
[core]
    editor = code --wait
    eol = lf
    autocrlf = input
    excludesfile = ~/.gitignore
[difftool "winmerge"]
    cmd = /c/Program\\ Files\\ \\(x86\\)/WinMerge/WinMergeU.exe
[gpg]
    program = c:/Program Files (x86)/GNU/GnuPG/gpg2.exe

Since I work on a number of projects that require a DCO signoff, I just default to signing off my commits (alias.commit) and I GPG sign them because I like how they look in the GitHub UI. ;)

I've set git to only use Linux line feeds for new clones/fetches (core.eol) and change anything with CRLFs on upload (core.autocrlf). To aid in this, my editor config has line endings set to \n as well.

What Really is GitOps?

Steven Murawski — Tue, 19 Sep 2023 15:59:54 +0000

Welcome

Welcome to the second post in our series on GitOps. You'll find the first post - Just Enough Git for GitOps - here.

GitOps describes the process and tooling around managing the state of a Kubernetes cluster based on content in a Git repository. We aren't going to get into specific tooling in this post - that'll start tomorrow with a post on FluxCD (with lots more to follow over the course of the next week and a half).

GitOps is ...

Defining GitOps

There are a number of definitions for GitOps (kinda like how we had a bajillion definitions for DevOps).

Steve Buchanan (of [bucahtech.com] and a teammate here at Microsoft) defines GitOps as:

GitOps is an operating model pattern for cloud native applications storing application & declarative infrastructure code in Git as the source of truth used for automated continuous delivery.

The Principles of GitOps

The OpenGitOps standards group defines GitOps using a set of four principles:

1) Declarative

A system managed by GitOps must have it's state expressed declaratively.

2) Versioned and Immutable

Desired state is stored in a way that enforces immutability, versioning and retains a complete version history.

3) Pulled Automatically

Software agents automatically pull the desired state declarations from the source.

4) Continuously Reconciled

Software agents continuously observe actual system state and attempt to apply the desired state.

Elements of a GitOps Environment

Bare Minimum

GitOps, at a minimum, requires a Git repository and an agent (usually an operator) in your Kubernetes cluster. The agent's role is to poll for configuration changes between the state of configuration files in a particular branch in the Git repo and the state of the cluster.

Example:

More Realistic Environment

The basic example ignores the container build process and image deployment. A more realistic example may look like:

The Essence of GitOps

The GitOps principles defined by the OpenGitOps group drills down to the core of what GitOps is:

A Git repository with a specified branch protected from change by technical measures and process.

An agent (operator) that monitors both the cluster configuration and the specified branch to detect change and remediate configuration differences.

Why GitOps?

Why would we want to use GitOps? I'll call back to the OpenGitOps group and what they enumerate as the potential benefits of using GitOps tools and practices.

Increased Developer & Operational Productivity
Enhanced Developer Experience
Improved Stability
Higher Reliability
Consistency and Standardization
Stronger Security Guarantees

Is GitOps Different from DevOps?

GitOps seems to have a lot in common with traditional DevOps practices.

If we go back to the Continuous Delivery concept, we see one of the foundations is Configuration Management - which is where GitOps tooling and process fall.

GitOps is for Kubernetes what Chef/Puppet/PowerShell DSC/CF Engine/and others were for server configuration management.

So, GitOps isn't a replacement or different concept from DevOps - it's tooling and process specialized for working with Kubernetes environments.

What I Like about GitOps

Coming from an infrastructure as code background, I really like the concept of the GitOps operator performing consistency checks and remediation of configuration drift over my infrastructure.

Using a source control driven process also makes me happy (though not completely... see below). There are tremendous benefits (see all the State of DevOps reports) to operational stability and reductions in mean time to recovery when your infrastructure configuration is a version-able artifact.

My Problem(s) with GitOps

I have one philosophical problem with GitOps and one operational problem.

My Operational Problem with GitOps

Let's start with the operational problem, as that's more of an observation based on many years in the infrastructure as code space.

Typically, most teams I've worked with have a very difficult time giving control of environmental and operational changes to an agent. One of the reasons tools like Ansible or active deployment by CD tools were so popular was that it was a "push" process where some operator or developer action was required to initiate the process to deploy or change configuration.

When folks attempted to operate agent-based configuration management tools where the agent ran on some schedule and performed a "test and repair" process, the concern was often "what if someone made a manual change?". While this isn't a technical problem with the tooling, it is a people and process problem. Folks had a difficult time (either personally or organizationally) allowing the agent to take control and then having to trust (and monitor) the status of those agent operations.

Some of this boiled down to a lack of trust in the configuration management tooling (not the agent, but the instructions the agents had to follow). This trust could be built by quality testing - which was often neglected.

Again, this isn't a technical problem with GitOps, but it is a potential blocker if teams cannot buy into funneling all changes through the agent and staying away from the kubectl command.

My Philosophical Problem with GitOps

One of the core principles of GitOps is that the configuration is "versioned and immutable" and this versioning provides an accurate audit log.

This pushes the responsibility of being an artifact repository to the Git repository, which is not the purpose of the tooling. We have to rely on hosting solutions and process to enforce process to make sure the repository can achieve those goals.

Additionally, managing application configuration and secrets requires special handling and forces us to build process outside of the GitOps workflow to ensure auditability and versioning for those values.

Fortunately, there are options to move "GitOps" artifacts to actual artifact stores (like OCI artifacts), I just wish that was the default.

Summary

GitOps is an umbrella for practices and tooling to use Git-based configuration elements to manage our Kubernetes environment via an agent that manages the cluster configuration.

Adopting GitOps practices and tools can improve your operational capabilities but requires some forethought and buy in from your team.

Continue the conversation

Leave your questions in the comments or come over to the Microsoft Open Source Discord and chat with me and my team in the cloud-native channel!

Join us tomorrow to take a look at Flux with Paul Yu!

Just Enough Git for GitOps

Steven Murawski — Mon, 18 Sep 2023 16:47:35 +0000

GitOps Series

This week and next, my team and I are going to be exploring different facets of GitOps and some of the tools in the space. Watch our social media for new posts:

Josh Duffney: twitter|linkedin|github
Paul Yu: twitter|linkedin|github
Jorge Arteiro: twitter|linkedin|github
Yosh Wuyts: twitter|linkedin|github
Steven Murawski (me): twitter|linkedin|github

Some of the topics we'll cover include:

What is GitOps?
How do Secure Supply Chain tools fit in a GitOps workflow?
FluxCD
ArgoCD
Dealing with secrets in GitOps

What else would you want to see? Leave a comment below with topics you'd like to see covered and we'll see what we can do!

Let's get started with some concepts about Git and then cover a basic set of commands that will get you ready to work with GitOps tools.

Git Concepts

Git is a distributed version control system that allows multiple developers to collaboratively manage and track changes to source code, enabling efficient code development, and review.

Distributed

The distributed nature of Git means that you can have multiple independent copies of a repository with some shared history. That shared history makes it possible to push or pull changes from other copies effectively.

What this effectively means is that Git does not, by design, have the concept of a central repository. All copies of a repository are just as valid as any other. We, as developers and operations personnel, enforce authority to one particular copy of a repository by pattern and practice. Tools and services like GitHub, GitLab, Azure Repos, and others help facilitate that practice.

For the purposes of GitOps, this means that we enforce the source of truth for our environment by convention and process.

Branches

In Git, branches are separate workspaces that allow developers to work on features, bug fixes, or experiments independently from other changes.

This makes it easier to manage and merge changes into the project when they are ready.

By convention, the primary branch in a repository is main. Older projects may use the master, though that terminology is perceived as culturally insensitive or offensive and the industry has shifted towards other, equally accurate terminology. Another term you may see for the main branch is trunk.

Repository

Repositories in Git are represented as the directory structure of the project under control. There is a hidden .git directory that handles all the change tracking and content across branches and tags represented in the repository.

Repo is a common shorthand version of repository.

Special files

As I previously mentioned, a Git repository has a special directory for tracking Git related operations - the .git directory.

One other key file to be aware of at the start is the .gitignore file. This file allows you to define specific files or groups of files (wildcards supported) that Git should ignore. This is commonly used to keep Git from tracking specific binary files, intermediate build artifacts, local settings files, and editor specific files - though it can be used for any file or set of files you do not want tracked.

Remotes

Remotes are repositories that are in a physically different location (either on the local filesystem or available over a network). Git can track named references to these other locations.

By convention, if you copy (clone) a repository from a remote source, that original source is tracked as a remote named origin.

Commands

These are the commands, in order of use, that I think will be helpful as you get started with Git and GitOps. There are more complicated operations - let me know in the comments below if you'd like to see more specific scenarios with Git.

Clone

We'll often be starting with a source repository from a central server. One common location is from GitHub. To create a local copy of a repository from a remote source, we use the git clone command.

Git can operate over local file system paths or over a network using HTTPS or SSH. We provide a remote source to git clone and Git will track that method and use it for future operations with that remote repository.

The cloned remote repository will be tracked as a remote named origin.

Example:

HTTPS

git clone https://github.com/Azure-Samples/aks-store-demo

SSH

git clone git@github.com:Azure-Samples/aks-store-demo.git

Init

If you aren't starting from a remote Git repository, you can create a new git repository from just about any directory structure. git init will create the tracking data required for the repository (the .git folder). There will be no origin or other remotes defined.

Example:

> mkdir init_sample

    Directory: C:\Users\stmuraws\source

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----           9/18/2023 10:10 AM                init_sample

> cd init_sample
> git init .
Initialized empty Git repository in C:/Users/stmuraws/source/init_sample/.git/

Status

The most common command I run inside a Git repo is git status. This will tell you the current state of changes. You'll see your current branch, status compared to the same branch against any origin you are tracking against (usually origin), as well as any pending file changes staged by git add (described next).

Example (from the init_sample repository):

> git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

Add

Regardless of how you got your Git repository locally (whether you cloned an existing repo or used git init to create a new one), when you add new, remove existing, or change existing files, you need a way to tell Git what you want to track.

Git is not like autosave. It does not continuously track changes. We'll tell Git specifically which changes to track.

git add is what we'll use to tell Git which changes to stage as part of a commit.

Example (from the init_sample repository):

> 'some content' > sample_file.txt
> git add sample_file.txt
> git status

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   sample_file.txt

git add does not create a new commit by itself. We'll use it in conjunction with the next command, git commit.

Commit

Once we have some changes staged, we can commit them to our repository. Each commit is identified by a hash.

Commits require a message by default. If you do not pass one at the command line or use a flag to allow an empty message, then an editor will open to allow you to type a new commit message. I'll typically use the -m parameter to supply a message at the command line.

Example (from the init_sample repository):

> git commit -m "First commit to the sample repository."

[main (root-commit) 01e9e34] First commit to the sample repository
 1 file changed, 1 insertion(+)
 create mode 100644 sample_file.txt

Ideally, each commit would be a set of related changes.

Push

Now that we've made a change, if we are working with a shared remote repository, we can push our changes to that repository.

If we started by cloning a remote repository, then we'll already have a remote configured.

For this example, let's use the repository we used for git init (so we don't make random changes to something we might really be using). To use this repository, we'll need to do a bit of setup.

Setup (from the init_sample repository):

> cd ..
> mkdir push_sample
> cd push_sample
> # Initialize a new git repo as bare (no working directory)
> git init --bare .
> cd ../init_sample

Once we are back in the init_sample directory, we'll configure the new repository as a remote.

> git remote add origin ../push_sample

Now, we are ready to push our changes. The remote setup usually only happens once for the repository (and if we cloned a repository, it'll be setup for us already). We'll specify the remote we are pushing to (origin) and the branch we are pushing (main). The -u is only needed once. It tells Git that the main branch of my local repository and my remote repository should be associated (tracked).

> git push origin main -u

Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 254 bytes | 254.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To ../push_sample
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Fetch

git fetch retrieves the contents and commits. It does not change anything in your working directory.

I prefer to use git fetch, in combination with the next command git merge, rather than git pull to retrieve changes from a remote repository. This puts me in greater control of the changes that will happen to the files I'm currently working on. git pull is convenient until it bites you (which can be a rare occurrence).

Example (from our init_sample repository):

> cd ..
> mkdir fetch_sample
> cd fetch_sample
> git init .
> git remote add origin ../push_sample
> git fetch origin

remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 234 bytes | 21.00 KiB/s, done.
From ../push_sample
 * [new branch]      main       -> origin/main

Merge

git merge allows you to bring changes from one branch into your current branch. The source branches can be local or from a remote (which have been fetched locally).

Now that we have changes from a remote repository in our local Git repository (from the git fetch), we can merge changes from the remote branch to our local branch.

Example (from the fetch_sample repository):

> # Verify the directory is empty (other than the hidden .git directory)
> ls
> git merge origin/main
> ls

    Directory: C:\Users\stmuraws\source\fetch_sample

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           9/18/2023 11:09 AM             13 sample_file.txt

Checkout

git checkout allows us to switch between branches inside our repository. This allows us to more easily keep our work isolated from other ongoing changes. git checkout has a handy switch, -b, that lets us create a new branch from the current branch (otherwise, you can use the git branch command, but I almost never use that to create new branches since git checkout is so convenient).

Ideally, we create a branch for every set of related changes we want to make.

Example (from the fetch_sample repository):

> git checkout -b 'new_branch'
Switched to a new branch 'new_branch'
> git checkout main
Switched to branch 'main'

Reset

Sometimes, we can get our repositories all messed up. git reset can help us. (There are other uses too, but early on this is the most common.)

There are two modes for git reset, soft and hard.

Soft resets

A soft reset leaves the changes from commits after the specified commit in your working directory, allowing you to retain the changes you made in those commits as uncommitted modifications. Any of the previously staged changes (things we added with git add) will be no longer be staged, but those changes will still be present as uncommitted modifications.

Use a soft reset when you want to rework and recommit some changes from the commits after the specified commit. Or if you accidentally committed something but want to include those changes in a different commit.

Hard resets

A hard reset resets both the staging (things we added with git add) area and the working directory (any current changes in files) to match the state of the specified commit. This means any changes made in commits after the specified commit are completely removed.

WARNING: A hard reset can and will remove/lose changes that are not present in target commit you are resetting to.

Use a hard reset when you want to completely discard all changes made in commits after a certain point and start fresh.

Rebase

The last command I'm going to introduce here is git rebase. There are two modes of git rebase that I commonly use, but we'll focus on the most critical use case.

We can use rebasing to bring our branch history current to the state of whatever branch we want to target. This will make it easier to bring our changes into that target branch and let us solve any conflicts in our working branch locally.

For example, I'm working on some Helm charts for the AKS Store Demo project. My working branch is currently behind the state of the project source. I can bring my project current with git rebase and make it easier for the project maintainers to accept my contribution.

> git clone https://github.com/smurawski/aks-store-demo
> cd aks-store-demo
> git checkout origin/helm
> git checkout -b helm
> git remote add upstream https://github.com/Azure-Samples/aks-store-demo
> git fetch upstream
> git rebase upstream/main
Successfully rebased and updated refs/heads/helm.

What about merging the main branch back into my working branch? You can do that, but it can make the history pretty messy and, in some cases, make reviews more difficult (especially when there are a lot of files modified or moved around).

Summary

This was a very brief introduction to a lot of commands, but it should be enough to get started. For a more hands-on exploration of Git, check out this learning path on Microsoft Learn.

We didn't cover anything about dealing with merge conflicts, but we get into that a bit in this video or you can get hands on with Microsoft Learn

Continue the conversation

Leave your questions in the comments or come over to the Microsoft Open Source Discord and chat with me and my team in the cloud-native channel!

Watch for a post from our team tomorrow covering what GitOps is!

Getting Started with Helm

Steven Murawski — Fri, 08 Sep 2023 17:52:31 +0000

Over the past few days, my team and I have looked into tools that can help you deploy containerized workloads into Kubernetes more easily.

Here's a quick roundup of those posts:

Video: Deploying to Azure Container Apps
Lab: Deploying to Azure Container Apps
Blog post: Jump Start Your Applications with Draft
Blog post: Effortlessly Deploy to AKS with Open Source Tools Draft and Acorn
Lab: Deploying Apps to AKS
Blog post: Deep Dive into Using Draft
Blog post: Building Multi-Architecture Container Images
Blog post: Level-up Container Security: 4 Open-Source Tools for Secure Software Supply Chain
Blog post: Pushing Multi-Architecture Container Images

Understanding Helm

Today, we are going to look at [Helm]. Helm can seem like a mystical tool, taking a bunch of marked up files, putting together a bunch of data about your environment, and then making a service appear in your cluster.

What is Helm?

Helm is a package manager for Kubernetes. Helm provides a way to create templates for Kubernetes configuration files, apply those configurations with local data specific to your cluster, and manage updates, rollbacks, and other release concerns. We'll focus on the packaging and deployment aspects of Helm in this article.

Using Helm

Getting started with Helm is pretty straight forward. Installing a local copy of Helm is the first step.

Helm will also require you to have kubectl installed and configured to access a Kubernetes cluster.

Finding Helm Charts

The templates that Helm uses are called Charts. Helm allows you to find and install charts from repositories. Artifact Hub can help you find repositories (Artifact Hub).

Step one is to add the chart repository. We'll use my fork of the AKS Store Demo as an example. We'll use the helm repo add command and provide it a (local) name for the repository, as well as the URL to the published chart repository.

aks-store-demo ❯ helm repo add aks-demo https://raw.githubusercontent.com/smurawski/aks-store-demo/helm/packages/
"aks-demo" has been added to your repositories

We can inspect what charts are available from the repository with helm search repo

aks-store-demo ❯ helm search repo aks-demo
NAME                    CHART VERSION   APP VERSION     DESCRIPTION
aks-demo/aks-store-demo 0.1.0           1.16.0          A Helm chart for Kubernetes

Installing a Helm Chart

The simplest way to install a Helm chart, with no customization, is with helm install with a name for the installation (called a release) and the specific chart to deploy.

aks-store-demo ❯ helm install aks-store-demo aks-demo/aks-store-demo
NAME: aks-store-demo
LAST DEPLOYED: Fri Sep  8 11:59:57 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Thank you for installing aks-store-demo.

Your release is named aks-store-demo.

To learn more about the release, try:

  $ helm status aks-store-demo
  $ helm get all aks-store-demo

We can list the Helm releases with helm list. These are namespace specific.

aks-store-demo ❯ helm list
NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                   APP VERSION
aks-store-demo  default         1               2023-09-08 11:59:57.0813261 -0500 CDT   deployed        aks-store-demo-0.1.0    1.16.0

We can remove the release with helm uninstall followed by the name of the release.

aks-store-demo ❯ helm uninstall aks-store-demo
release "aks-store-demo" uninstalled

Customizing the Installation

Helm charts typically have Values, which are default settings, that can be customized.

We can find the various options by using helm show values and providing the chart name.

aks-store-demo ❯ helm show values aks-demo/aks-store-demo
[LOTS OF YAML follows]

We can redirect this to a file and customize any of the values there. Then, when we install the helm chart, we can point to our custom values.yaml.

aks-store-demo ❯ helm show values aks-demo/aks-store-demo > local_values.yaml
aks-store-demo ❯ # make a few changes in local_values.yaml (maybe change some replica counts)
aks-store-demo ❯ helm install aks-store-demo aks-demo/aks-store-demo -f local_values.yaml
... release details ...

That's the quick and dirty guide to getting up and running with Helm charts. Now, we'll look into what it takes to convert our Kubernetes manifests into a Helm charts.

Creating a Helm Chart

Helm offers a "quick" way to get started creating your own Helm charts with helm create.

mkdir charts
cd charts
helm create aks-store-demo

That's going to create a sample Chart with in the aks-store-demo directory.

In the directory will be an (empty) charts directory, a directory of templates (delete everything inside except for the Notes.txt file), a .helmignore file, a Chart.yaml file, and a values.yaml file. You can delete the contents of the values.yaml file.

In our template directory, we can drop any and all of our manifests. In my example, I broke up the all-in-one.yaml into individual manifests. To me, it was easier to experiment with the templating engine with smaller files.

Converting a Manifest into a Template

Any of the manifests in the templates directory will be evaulated and applied as part of the helm install. If a file does not have any templating features used, it'll just be applied as it exists. For example, the config_map_rabbitmq.yaml doesn't have any values I want to change, so it just exists as it did in the aks-store-all-in-one.yaml.

The first thing I wanted to be able to customize is what container image to pull for each of the deployments. I'll walk through how I changed one of the deployments, and you can explore the repo and files to see the changes made for the other deployments.

Let's use the store-front as our example. I started out by identifying the default container image specified, which was ghcr.io/azure-samples/aks-store-demo/store-front:latest.

First, I opened my values.yaml, which should be empty (since we deleted all the contents earlier). I then added the following to the file and saved it.

store_front:
  image:
    repository: ghcr.io/azure-samples/aks-store-demo/store-front
    tag: latest

The values.yaml is just a YAML file with whatever structure of data you feel will map effectively into your configs.

Then, I modified the image element of the deployment manifest to look like:

image: "{{ .Values.store_front.image.repository }}:{{ .Values.store_front.image.tag }}"

Next, I wanted to control the number of replicas for my deployment. I updated values.yaml to look like:

store_front:
  replicaCount: 1
  image:
    repository: ghcr.io/azure-samples/aks-store-demo/store-front
    tag: latest

Then, I updated the deployment manifest with:

replicas: {{ .Values.store_front.replicaCount }}

Since everything for this deployment is namespaced under store_front in my values.yaml, I can simplify this a bit by using with, which allows me to set a context from the values.yaml to use when referencing elements to apply to the template.

I added {{ with .Values.store_front }} to the top of the manifest and {{ end }} to the bottom. Then my two existing references need to be updated to look like this:

image: "{{ .image.repository }}:{{ .image.tag }}"

replicas: {{ .replicaCount }}

Now, that looks much simpler. :)

The last element I wanted to be able to customize is the resource requests and limits. I moved those elements to the values.yaml like so:

store_admin:
  replicaCount: 1
  image:
    repository: ghcr.io/azure-samples/aks-store-demo/store-admin
    tag: latest
  resources:
    requests:
      cpu: 1m
      memory: 200Mi
    limits:
      cpu: 1000m
      memory: 512Mi

And then I got to use my with again, along with the toYaml function to basically copy the YAML keys and values from the values.yaml into my template. You'll notice there's a new element in the template, the -. This tells the templating engine to only render that section if there's content for it from the values.yaml. If there's no resources defined there, it'll leave that section out.

        {{- with .resources }}
        resources:
          {{- toYaml . | nindent 10 }}
        {{- end }}

Testing Template Rendering

Once we've made a few updates to our templates, we can test to see how they come out.

From the root of the repository, you can run

helm install aks-store-demo ./charts/aks-store-demo --dry-run --debug

Which will evaluate and render the templates to the console, applying any values from the values.yaml file.

Another way to make sure you have valid templates is to use helm lint. You'll have to be in the directory with the chart when the command executes.

pushd ./charts/aks-store-demo
helm lint
popd

The Notes.txt

I haven't mentioned it until now, but the Notes.txt gets rendered by the templating engine and written to the console upon the installation of a release of the chart. You can include any information that folks may find useful in using what was installed by your chart.

Closing

I hope this quick intro to Helm helps. Please drop me a comment with any questions or feedback!

You'll find my updates to the demo repository here

Deep Dive into Working with Draft

Steven Murawski — Fri, 01 Sep 2023 17:51:24 +0000

What is Draft and what does it do?

Draft exists to help folks get up and running on Kubernetes more easily.

This command line tool is run in your project's working directory and attempts to identify the type of project in the repository.

From there, Draft will ask you some questions and generate all the files you need to containerize the application and deploy into a Kubernetes cluster.

In addition to the Dockerfile, Draft can provide Helm charts, kustomize configuration files, or plain old Kubernetes manifests.

Once your project has those configuration files, Draft can help you set up GitHub actions to build, package, and deploy your application into a Kubernetes cluster.

How does Draft Work?

Draft has several subcommands that we'll look at in depth.

First is draft create which will generate the Dockerfile and any supporting configuration files necessary.

Second is draft setup-gh which configures GitHub OpenID Connect with Microsoft Entra ID (formerly Azure Active Directory).

The third subcommand is draft generate-workflow which creates GitHub workflow files to build, package, and deploy your application into Kubernetes.

The fourth main subcommand is draft update which can update your configuration files to allow your application to be accessible from outside the cluster.

There are a few other minor features that we'll review as well.

Setting up an Azure Environment

To create a basic environment to test with Draft, we can use the Bicep template that I've included in my sample repo. It will create a resource group called drafttesting with an AKS cluster and Azure Container Registry in the region you specify.

git clone https://github.com/smurawski/drafttesting
cd drafttesting

# I deployed to eastus, but pick a region that fits for you.
az deployment sub create --template-file ./deploy/main.bicep --location eastus

Setting up a test project

To start, I'm going to create a simple Go project. (or feel free to copy it from my sample repo

mkdir DraftTesting
cd DraftTesting
go mod init DraftTesting

And add a file main.go (which I borrowed from learn.microsoft.com)

package main
import (
    "fmt"
    "net/http"
)
func main() {
    http.HandleFunc("/", HelloServer)
    http.ListenAndServe(":8080", nil)
}
func HelloServer(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello, %s!", r.URL.Path[1:])
}

Getting Started with `draft create`

After installing Draft, while still in the DraftTesting directory, I'll run draft create.

Dockerfile generation

Draft detects that I've got a Go project and asks if I want to use Go Modules. Other languages will have appropriate questions asked for their specific needs.

~/source/DraftTesting ❯  draft create
[Draft] --- Detecting Language ---
v yes
[Draft] --> Draft detected Go (88.475836%)

Once the language is identified, Draft moves on to create a Dockerfile. You'll be asked for the port to expose in the Dockerfile. My app is listening on 8080, so I'll use that. Then it asks for the version of Go my module requires, which for me was 1.21.

[Draft] --- Dockerfile Creation ---
Please enter the port exposed in the application (default: 80): 8080
Please enter the version of go used by the application (default: 1.18): 1.21.1
[Draft] --> Creating Dockerfile...

Now, I have a Dockerfile.

FROM golang:1.21
ENV PORT 8080
EXPOSE 8080

WORKDIR /go/src/app
COPY . .

RUN go mod vendor
RUN go build -v -o app
RUN mv ./app /go/bin/

CMD ["app"]

Generating Kubernetes Manifests

Draft continues to ask me which type of deployment I want to use. I'll keep it simple and pick manifests.

[Draft] --- Deployment File Creation ---
v manifests

In one of the more annoying bits of the workflow, I get asked for the exposed port again.

Please enter the port exposed in the application: 8080

Draft prompts me to enter a name for the application.

Please enter the name of the application: drafttesting

Continuing on with Draft's fascination with ports, it asks which port should be used to expose my application outside the cluster, though it makes the default my previously selected port.

Please enter the port the service uses to make the application accessible from outside the cluster (default: 8080):

Next, I'm asked for the namespace to deploy the application into. I took the default.

Please enter  the namespace to place new resources in (default: default):

This leads to the first question where things could start to go REALLY wrong if we aren't paying attention. Draft wants to know the image name for the deployment. Here's where we'll need to know what container registry our application is going to be deployed to.

Thanks to the Bicep template we ran earlier, I do have an Azure Container Registry to which I can deploy my container. We need to prefix our container image name with URL of the container registry.

Please enter the name of the image to use in the deployment (default: drafttesting): acrxms72d.azurecr.io/drafttesting

Finally, we provide the tag to deploy.

Please enter the tag of the image to use in the deployment (default: latest): v1

Now, we have our manifests to deploy our application into the Kubernetes cluster.

[Draft] --> Creating manifests Kubernetes resources...

[Draft] Draft has successfully created deployment resources for your project
[Draft] Use 'draft setup-gh' to set up Github OIDC.

Draft created a manifests folder in my project directory with a deployment.yaml and a service.yaml. I'm not going to reproduce them here, but if you want a bit more on these files, check out Kubernetes Fundamentals - Pods and Deployments and Kubernetes Fundamentals - Services and Ingress.

So, what templates are used by `draft create`?

The templates are embedded in the tool and can be found in the source on GitHub. The Dockerfile templates are here and the deployment templates are here.

Securing Access to Azure for my GitHub Workflow with `draft setup-gh`

Draft suggested we move onto setting up GitHub OpenID Connect (OIDC), so let's get that done.

OpenID Connect with Microsoft Entra ID/Azure Active Directory

First, let's define what's going to happen. Draft is first going to create an Microsoft Entra App Registration.

Then, it will configure a federated credential for that app registration. The federated credential will define what GitHub resources can request a token to access my subscription via the application.

Finally, it creates a service principal for that application and assigns it permissions to the resource group specified. The application will use that service principal to access the resources for GitHub Actions.

Running `draft setup-gh`

First, Draft prompts me to enter an app registration name.

Enter app registration name: drafttesting

Then, I can pick the subscriptions I have access to based on my current az CLI login session.

Enter app registration name: drafttesting
Use the arrow keys to navigate: ↓ ↑ → ←
v my-azure-subscription-guid

Then, I need to provide a resource group to provide access to. My AKS cluster and ACR instance are in the drafttesting resource group I created earlier.

Enter resource group name: drafttesting

Next, we need to enter our GitHub organization (or user) and repository. As you can see, my naming skills are on point and very clever.

Enter github organization and repo (organization/repoName): smurawski/drafttesting

After that, Draft setups up OIDC between Microsoft Entra ID and GitHub. This can take a minute or two.

[Draft] Draft has successfully set up Github OIDC for your project 😃
[Draft] Use 'draft generate-workflow' to generate a Github workflow to build and deploy an application on AKS.

Troubleshooting the Federated Credential

To see what federated credential was created and the values supplied by Draft, you can use the Azure CLI.

applicationName=drafttesting
objectId=$(az ad app list --display-name $applicationName --query '[].id' -o tsv)
az ad app federated-credential list --id $objectId

This will output a configuration for your federated credential. Take note of the subject property. That's where the configuration for what can access the credential lives. You'll see values like repo:smurawski/drafttesting:ref:refs/heads/main which means that for requests originating from changes to my main branch, Microsoft Entra ID can provide access to my subscription.

The most likely mismatch will be attempting to deploy from a branch that was not specified when using draft setup-gh.

Generating Build Automation with `draft generate-workflow`

With our GitHub OIDC set up and configured to allow access to my Azure subscription, we can create our workflow.

Draft first asks what type of deployment manifests we are using. We selected manifests earlier, so we'll keep that choice now.

DraftTesting on  main ❯  draft generate-workflow
[Draft] --> Generating Github workflow
v manifests

Next, we are prompted for our Azure Container Registry name, our container image name, the resource group for our AKS cluster, and the cluster name.

Please enter the Azure container registry name: acrxms72d
Please enter the container image name: drafttesting
Please enter the Azure resource group of your AKS cluster: drafttesting
Please enter the AKS cluster name: aks1

Then we are prompted to enter which branch to deploy from and where in the project repository should be our Docker build context (I specified the default which is the project folder root).

Please enter the Github branch to automatically deploy from: main
Please enter the path to the Docker build context (default: .):

Draft then generated our workflow file and ensured that our deployment manifest had the correct repository and deployment, but it removed the tag. This is not a problem as the build created will replace the image at deployment time with one tagged and built in that GitHub Actions run.

[Draft] Draft has successfully generated a Github workflow for your project 😃

So, what templates are used by `draft generate-workflow`?

The templates used for the workflows can be found here

Allowing Traffic to my Application with `draft update`

The draft update subcommand supports enabling extensions to AKS. Currently, only webapp_routing is supported.

You'll need a TLS certificate stored in Azure Key Vault to use this feature.

You can find the templates for this feature here.

Other `draft` subcommands

There are a few other subcommands available.

draft completion will provide autocompletion helpers for your particular shell.

DraftTesting on  main ❯  draft completion --help
Generate the autocompletion script for draft for the specified shell.
See each sub-command's help for details on how to use the generated script.


Usage:

  draft completion [command]


Available Commands:

  bash         Generate the autocompletion script for bash
  fish         Generate the autocompletion script for fish
  powershell   Generate the autocompletion script for powershell
  zsh          Generate the autocompletion script for zsh

draft info will dump out all the support answers for the languages/runtimes and deployment options.

DraftTesting on  main ❯  draft info
{
  "supportedLanguages": [
    {
      "name": "javascript",
      "displayName": "JavaScript",
      "variableExampleValues": {
        "VERSION": [
          "10.16.3",
          "12.16.3",
          "14.15.4"
        ]
      }
    },
    {
      "name": "erlang",
      "displayName": "Erlang",
      "variableExampleValues": {
        "BUILDERVERSION": [
          "24.2-alpine"
        ],
        "VERSION": [
          "3.15"
        ]
      }
    },
    {
      "name": "go",
      "displayName": "Go",
      "variableExampleValues": {
        "VERSION": [
          "1.16",
          "1.17",
          "1.18",
          "1.19"
        ]
      }
    },
    {
      "name": "php",
      "displayName": "PHP",
      "variableExampleValues": {
        "BUILDERVERSION": [
          "1"
        ],
        "VERSION": [
          "7.1-apache"
        ]
      }
    },
    {
      "name": "gradlew",
      "displayName": "Gradle",
      "variableExampleValues": {
        "BUILDERVERSION": [
          "jdk8",
          "jdk11",
          "jdk17",
          "jdk19"
        ],
        "VERSION": [
          "8-jre",
          "11-jre",
          "17-jre",
          "19-jre"
        ]
      }
    },
    {
      "name": "java",
      "displayName": "Java",
      "variableExampleValues": {
        "BUILDERVERSION": [
          "3-jdk-11"
        ],
        "VERSION": [
          "8-jre",
          "11-jre",
          "17-jre",
          "19-jre"
        ]
      }
    },
    {
      "name": "python",
      "displayName": "Python",
      "variableExampleValues": {
        "ENTRYPOINT": [
          "app.py",
          "main.py"
        ],
        "VERSION": [
          "3.9",
          "3.8",
          "3.7",
          "3.6"
        ]
      }
    },
    {
      "name": "ruby",
      "displayName": "Ruby",
      "variableExampleValues": {
        "VERSION": [
          "3.1.2",
          "2.6",
          "2.5",
          "2.4"
        ]
      }
    },
    {
      "name": "rust",
      "displayName": "Rust",
      "variableExampleValues": {
        "VERSION": [
          "1.70.0",
          "1.65.0",
          "1.60",
          "1.54",
          "1.53"
        ]
      }
    },
    {
      "name": "clojure",
      "displayName": "Clojure",
      "variableExampleValues": {
        "VERSION": [
          "8-jdk-alpine",
          "11-jdk-alpine",
          "17-jdk-alpine",
          "19-jdk-alpine"
        ]
      }
    },
    {
      "name": "gradle",
      "displayName": "Gradle",
      "variableExampleValues": {
        "BUILDERVERSION": [
          "jdk8",
          "jdk11",
          "jdk17",
          "jdk19"
        ],
        "VERSION": [
          "8-jre",
          "11-jre",
          "17-jre",
          "19-jre"
        ]
      }
    },
    {
      "name": "swift",
      "displayName": "Swift",
      "variableExampleValues": {
        "VERSION": [
          "5.2",
          "5.5"
        ]
      }
    },
    {
      "name": "csharp",
      "displayName": "C#",
      "variableExampleValues": {
        "VERSION": [
          "3.1",
          "4.0",
          "5.0",
          "6.0"
        ]
      }
    },
    {
      "name": "gomodule",
      "displayName": "Go Module",
      "variableExampleValues": {
        "VERSION": [
          "1.16",
          "1.17",
          "1.18",
          "1.19"
        ]
      }
    }
  ],
  "supportedDeploymentTypes": [
    "manifests",
    "helm",
    "kustomize"
  ]
}

And, of course there's draft version which will dump out the version information for the build you are using.

DraftTesting on  main ❯  draft version
version:  0.0.33
runtime SHA:  2142dbc745ac8284999f3384358680c7bc6f8570

Try it out!

Head over to the project releases and grab the version for your system. Try it out and give us some feedback via Issues or drop me a comment here!

Getting Started with Hippo - a WebAssembly PaaS (Part 3)

Steven Murawski — Wed, 17 Nov 2021 22:43:16 +0000

Converting an Existing Application

With the understanding we’ve built of the runtime environment, I feel ready to start porting a simple CLI I’ve built in Rust to run in WebAssembly as a service hosted in Hippo. [The project we’ll start with is J2Y(https://github.com/smurawski/j2y/tree/1-getting-started) – which is a little Rust application that converts JSON to YAML or YAML to JSON. We’ll adapt this to, depending on the target, either be a CLI or a WebAssembly binary to run in WAGI. The heavy lifting of the conversion is done by the serde-json and the serde-yaml crates.

We’ll start out by taking a look at the existing application. We are still using VS Code with the Remote-SSH extension to connect to our dev server. The main function in main.rs ( https://github.com/smurawski/j2y/blob/1-getting-started/src/main.rs ) module is the primary entry point for the application. The function sets up the CLI experience and resolves the incoming parameters and arguments. The application then reads the source content. Based on the direction of the conversion, it passes off the text it read to the desired conversion function. Finally, the application writes the output file in the desired serialization.

Goals

This isn’t a treatise on how to properly structure a Rust application, but mostly to show how we can adapt an existing application to a WebAssembly module to run in Hippo. There will be plenty of opportunities to clean up the code base and refactor to make it more maintainable over time.

For our web service, we’ll take a posted body of either JSON or YAML and return the opposite. We’ll use the Content-Type header to help us determine the direction of the conversion. Then, then we’ll return a response with the appropriate file content as the body.

Evolving the App

Compile to WASM

We’ll start by adjusting our main function to behave conditionally based on whether or not it’s built as a WASM module. The cfg! macro helps us here, as we can create conditions in our code based on the target family (or operating system, or target architecture) we compile for. On anything that isn’t WASM, we want to build our CLI as normal. I’ve stubbed out the return of the parameters for the function and added a conditional based on our target_family.

    let (verbose, input_file, output_file, source_format) = if cfg!(target_family = "wasm") {
        get_wasm_args()
    } else {
        get_cli_args()
    };

Again, ideally we’d refactor to a common branch point or push the decision logic further down into the functions like read_content, but for this example, we’ll keep all the branching up in main to keep it visible.

Working with Input from WAGI

Let’s create a module to contain our WASM and WAGI specific behaviors. We’ll start with a function to create the tuple of arguments similar to what the get_cli_args function does. Then we’ll adjust the stubbed out response in main.rs to call our new function. You can see the full changeset here and the current state of the full project.

// in wasm.rs
pub fn get_wasm_args() -> (bool, String, String, SourceFormat) {
    // we'll default to verbose being false as it writes stdout,
    // and stdout is what becomes our response back
    let verbose = false;
    // the input and output files are not used.
    // this is a good point for some future refactoring
    let input_file = String::new();
    let output_file = String::new();
    let input_content_type = env::var("HTTP_CONTENT_TYPE")
        .expect("The Content-Type header was not specified. Unable to convert the source content.");
    let source_format = get_source_format(&input_content_type);
    (verbose, input_file, output_file, source_format)
}

As we learned in our experimentation in the last post, we can inspect our environment to get the incoming headers. Next, we can add a function to read from standard in, which is where the body of the incoming request will be available and update main.rs.

// in wasm.rs
pub fn read_wagi_content() -> String {
    let mut input_content = String::new();
    stdin()
        .read_to_string(&mut input_content)
        .expect("Failed to read from standard in.");
    input_content
}

// in main.rs
    let contents = if cfg!(target_family = "wasm") {
        read_wagi_content()
    } else {
        read_content(&input_file, verbose)
    };

The last tweak we have to make is our output. Rather than writing to a file, we’ll write to standard out. Since we are following the CGI convention, we’ll write our our headers, then a blank line, then our body. We’ll update main.rs to call write_wagi_output.

// in wasm.rs
pub fn write_wagi_output(output: &str, source_format: &SourceFormat) {
    println!("Content-Type: {}", get_output_format(source_format));
    println!();
    println!("{}", output);
}

// in main.rs
    if cfg!(target_family = "wasm") {
        write_wagi_output(&output_content, &source_format);
    }
    else {
        write_content(&output_file, output_content, verbose).expect("Failed to write the output file");
    }

Connecting with Hippo and Bindle

Now, how do we get this app into Hippo? We can use yo wasm again! We can use that to create our project in Hippo, create the HIPPOFACTS file, and prep us to deploy to Bindle. There are a few files that we’ll get a conflict on, and we can just ask yo wasm to leave our existing files alone.

(HINT: if you need your environment variables again before running yo wasm, check ~/output.txt.)

After yo wasm is run, we'll see our app configured in Hippo.

As before, we’ll build our app for the wasm32-wasi target. We can use the Hippo CLI to push the artifact to Bindle and then into Hippo.

cargo build --release --target wasm32-wasi
hippo push -k .

Now that, we’ve deployed the application, we can see in the Hippo dashboard that it’s running at https://admin.j2y.localhost:5003. Let’s make sure that 5003 is being forwarded by our VS Code Remote session.

Testing our App

Now that I have that port forwarded, I can start to test that my service behaves as expected. (If you are playing along, we are here) Let’s start out with some curl commands. I've created a few sample data files in a tests directory (a json file and a yaml file) that we'll use to feed in as the POST body.

cd tests/
url="https://admin.j2y.localhost:5003/"
# I expect this to fail because there is no application header
curl -vv --request POST -k --data @test.json $url
# This should succeed and return some YAML
curl --header "Content-Type: application/json" --request POST -k --data @test.json $url

# This should succeed and return some JSON
curl --header "Content-Type: application/yaml" --request POST -k --data @test.yml $url

# Uh oh... Let’s look closer
curl -vv --header "Content-Type: application/yaml" --request POST -k --data @test.yml $url

Dealing with Errors

We can see that something failed in the conversion from YAML to JSON. Let’s try our CLI and make sure we didn’t break anything.

cargo run -- -s YAML test.yml output.json
cat output.json

Well, that seemed to work ok. That doesn't help. I was hoping that something was wrong with my YAML file.

So, how can we figure out what’s going wrong? We could introduce some custom output to help us understand where the failure was. Currently, if anything fails in the conversion between serialization formats the application panics causing a failure and a 500 response, but no helpful information. Let’s change the behavior and rather than unwrapping the conversion results in our main function, let’s pass that into our functions that actually return the results. Because each of the deserializations returns a different error (serde_yaml::Error or serde_json::Error, let’s add a custom error of our own to wrap those in converter.rs.

// in converter.rs
pub struct Error {
    pub message: String,
    pub detail: String,
    pub status_code: usize,
    pub source_content: String,
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl fmt::Debug for Error {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(
            f,
            "{}\n{}\nReturn Status Code: {}\nSource Content: \n{}",
            self.message, self.detail, self.status_code, self.source_content
        )
    }
}

This custom error will allow us to capture different points of the failure and give us information to troubleshoot the problem. We can then wire it up into the conversion functions. You’ll see that we won’t need to change our main function just yet. (Find the full code for this checkpoint here.)

// in converter.rs
pub fn convert_json_to_yaml(json_str: &str, verbose: bool) -> Result<String, Error> {
    // Parse the string of json data into serde_yaml::Value.
    let v: serde_yaml::Value = match serde_json::from_str(json_str) {
        Ok(v) => v,
        Err(e) => {
            let wrapped_error = Error {
                message: "Failed to read the content as JSON.".to_string(),
                detail: format!("{:?}", e),
                status_code: 406,
                source_content: json_str.to_string(),
            };
            return Err(wrapped_error);
        }
    };
    let yaml_string = match serde_yaml::to_string(&v) {
        Ok(v) => v,
        Err(e) => {
            let wrapped_error = Error {
                message: "Failed to convert the JSON content into YAML.".to_string(),
                detail: format!("{:?}", e),
                status_code: 500,
                source_content: json_str.to_string(),
            };
            return Err(wrapped_error);
        }
    };

    if verbose {
        println!("\nAfter YAML conversion: \n");
        println!("{}", &yaml_string);
    }

    Ok(yaml_string)
}

// in converter.rs
pub fn convert_yaml_to_json(yaml_str: &str, verbose: bool) -> Result<String, Error> {
    // Parse the string of json data into serde_yaml::Value.
    let v: serde_json::Value = match serde_yaml::from_str(yaml_str) {
        Ok(v) => v,
        Err(e) => {
            let wrapped_error = Error {
                message: "Failed to read the content as YAML.".to_string(),
                detail: format!("{:?}", e),
                status_code: 406,
                source_content: yaml_str.to_string()
            };
            return Err(wrapped_error);
        }
    };
    let json_string = match serde_json::to_string(&v) {
        Ok(v) => v,
        Err(e) => {
            let wrapped_error = Error {
                message: "Failed to convert the YAML content into JSON.".to_string(),
                detail: format!("{:?}", e),
                status_code: 500,
                source_content: yaml_str.to_string()
            };
            return Err(wrapped_error);
        }
    };

    if verbose {
        println!("\nAfter YAML conversion: \n");
        println!("{}", &json_string);
    }

    Ok(json_string)
}

After we add that custom error, we can wire up our output methods to use it more effectively and provide us some useful output from our Hippo service. You can see the full changes here.

// in wasm.rs
pub fn write_wagi_output(output_result: Result<String, Error>, source_format: &SourceFormat) {
    let mut content_type = get_output_format(source_format);
    let mut status = 200;
    let output = match output_result {
        Ok(output) => output,
        Err(e) => {
            content_type = "text/plain".to_string();
            status = e.status_code;
            format!("{:?}", e)
        }
    };

    println!("Content-Type: {}", content_type );
    println!("Status: {}", status);
    println!();
    println!("{}", output);
}

// in cli.rs
pub fn write_content(file_path: &str, output_result: Result<String, Error>, verbose: bool) -> io::Result<()> {
    if verbose {
        println!("\nWriting: {} \n", file_path);
    }
    let output_content = output_result.unwrap();
    let mut file = File::create(file_path).expect("Failed to create the output file.");
    file.write_all(output_content.into_bytes().as_ref())
}

// in main.rs

      let output_content =
        match source_format {
            SourceFormat::YAML => convert_yaml_to_json(&contents, verbose),
            SourceFormat::JSON => convert_json_to_yaml(&contents, verbose),
        };

Now, we can build and publish our app, and then re-rerun our test.

cargo build --release --target wasm32-wasi
hippo push -k .

cd tests/
curl --header "Content-Type: application/yaml" --request POST -k --data @test.yml $url

Now, we can see why it failed! When we passed in the YAML file, it appears that our line breaks have been lost! Fortunately, we can fix that easily by using a different switch ( --data-binary rather than --data ). With that change, we can see our conversion from YAML to JSON works as well.

Wrapping up

We now have our application running as a WASM module as a service hosted on our Hippo server. From here we can continue to improve our application, explore the different hosting options inside of Hippo – testing the different deployment based on the tags assigned for example, or dive deeper into the WAGI runtime.

If you’d like to try to migrate the app along the same path I did, you can start from https://github.com/smurawski/j2y/tree/1-getting-started

Have fun with WASM and Hippo!

Getting Started with Hippo - a WebAssembly PaaS (Part 2)

Steven Murawski — Wed, 17 Nov 2021 22:41:49 +0000

Creating a WebAssembly App and Interacting with WAGI

In Part 1, we defined some of the moving parts of the WASM ecosystem and set up a development server with Hippo, Bindle, and the development tooling that we’ll use to dig around with how we can interact with the WAGI runtime.

We’ll start out by connecting to our development server. We could just SSH into the server (and that’s how we’ll start), but for our longer term work, we’ll move to Visual Studio Code and use Remote-SSH extension to more effectively work on our project. Let’s get started.

The cloud-init script left us an output log in output.txt which we can read with

cat output.txt

In that log, we can see that NodeJS, .NET Core, and Rust were installed, along with wasmtime, the hippo CLI, and Yeoman. The last one is what’ll get us started. I like to be organized about my projects, so I’ll create a projects directory and then a directory for helloworld (our exploratory project). There’s also some helpful exports to make the Yeoman generator a bit easier to get started with. The exports are using the same username and password what we configured in the previous post.

After making the environment variables available, it’s time to create our helloworld project. We’ll use the yo-wasm generator.

export USER=admin
export HIPPO_USERNAME=admin
export HIPPO_PASSWORD='Passw0rd!'
export HIPPO_URL=https://localhost:5001
export BINDLE_URL=http://localhost:8080/v1
export GLOBAL_AGENT_FORCE_GLOBAL_AGENT=false

mkdir projects/helloworld
cd projects/helloworld
yo wasm

Yeoman will ask you a few questions:

What is the name of the WASM module? (the default is the current directory name – which we’ll take)
What type of application is the module? (For a project with Hippo, we want “Web service or application using WAGI”)
What is the name of the author? (I filled in my name)
What programming language will you write the module in? (I chose Rust, because Rust is just fun)
Where do you plan to publish the module? (We are going to publish it to Hippo)
What is the URL of your Hippo service? (This is defaults to the value in HIPPO_URL variable that we exported earlier)
What is the URL of your Hippo’s Bindle server? (This defaults to the value in the BINDLE_URL variable that we exported earlier)
Would you like to create a new Hippo application for your Hippo app? (“Yes” will connect to the Hippo API with our credentials from HIPPO_USERNAME and HIPPO_PASSWORD, which are asked for in a couple of question, and create the application and several deployment environments – which we’ll look soon)
What storage ID (bindle name) would you like for your Hippo app? (Since this is a dev box, we’ll accept the default of application name.localhost)
Enter your Hippo user name (default is pulled from the HIPPO_USERNAME)
Enter your Hippo password (default is pulled from HIPPO_PASSWORD)

After asking those questions, most of which we take the defaults, Yeoman will scaffold out the project and create the application in Hippo. The project will include a basic “Hello World” application and the necessary files to publish it to Bindle and Hippo. We also get GitHub Actions workflows to make it easier to wire up CI/CD down the road.

At this point, we’ll switch to VS Code and use the VS Code Remote-SSH plugin to connect to our development server. This will give us a great editor experience, simplify port forwarding for local testing, and otherwise simplify our experience.

The Application

We now have the bare minimum required to publish an application to Hippo. The Rust application that was scaffolded down will create a WASM file that can be run in Hippo. Let’s get that started. Since I have a new terminal, I also re-exported the environment variables from the output.txt file to have them handy. Let’s build our app targeting the wasm32-wasi runtime. Then we’ll use the hippo CLI to push the artifact and metadata to our Bindle server.

cargo build --release --target wasm32-wasi
hippo push -k .

Now that we have our test application deployed, let’s see where that ended up.

I’ve used the VS Code Remote-SSH plugin to forward a couple of ports – 5001 and 5003.

The Hippo dashboard is running on 5001 and my app will be published on 5003. I’ve logged on to the dashboard at https://localhost:5001 and entered my username and password. Now, I see my helloworld app with “two channels unhealthy”.

Let’s dig in further and click on helloworld.

The yo-wasm generator configured three environments for our application. We can see that the app we pushed with the Hippo CLI has been published to the development environment. Let’s see how that’s configured. From the three dots to the right of the environment, we can see an option to edit.

In the environment configuration, we can:

change the domain configured,
add or edit environment variables and
specify how we want our app to deploy into this environment.

Autodeploy is configured, with a version spec. The artifacts being looked at are stored in our local Bindle server. As new versions of the application are published, this environment will deploy any newer versions that match the version range.

Let’s see what our application looks like and what content it returns. Back on the application details page, each channel has a dedicated link to that environment. Clicking on the link for the development environment and we should see “Hello, world!”

Now, let’s go back to our editor and start exploring the runtime environment. Let’s start with seeing what environment variables are available to our WASM application. We can edit src/main.rs to print out the environment variables.

use std::env;

fn main() {
  println!("Content-Type: text/plain\n");
  println!("Environment vars:");
  for (k,v) in env::vars() {
    println!("\t{}: {}", k, v);
  }
}

Looking closer at the output that we expect, we can see that we start by writing to standard out the Content-Type header. Then, after a blank line (the \n), we can write out our content.

Once we build and publish that change, we’ll use the REST Client extension to make it easier to validate our changes. I’ll create a test.http file and put a GET request to my development environment.

GET https://admin.helloworld.localhost:5003/

Running that should return a response with the current environment variables as seen by my application. Our response returns a list of variables and their values.

Environment vars:

  PATH_INFO:
  HTTP_TRACEPARENT: 00-74fe18ddc171754089fa3bc394cfbea8-ce7be6b2abfb6847-00
  HTTP_USER_AGENT: vscode-restclient
  REMOTE_HOST: 127.0.0.1
  REMOTE_USER:
  SERVER_PROTOCOL: HTTP/1.1
  SERVER_SOFTWARE: WAGI/1
  HTTP_X_FORWARDED_FOR: 127.0.0.1
  SCRIPT_NAME: /
  X_MATCHED_ROUTE: /
  X_FULL_URL: http://127.0.0.1:32770/
  CONTENT_TYPE:
  GATEWAY_INTERFACE: CGI/1.1
  CONTENT_LENGTH: 0
  PATH_TRANSLATED:
  SERVER_NAME: 127.0.0.1
  SERVER_PORT: 32770
  HTTP_HOST: 127.0.0.1:32770
  HTTP_X_FORWARDED_HOST: admin.helloworld.localhost:5003
  REMOTE_ADDR: 127.0.0.1
  HTTP_X_FORWARDED_PROTO: https
  HTTP_ACCEPT_ENCODING: gzip, deflate
  X_RAW_PATH_INFO:
  QUERY_STRING:
  AUTH_TYPE:
  REQUEST_METHOD: GET

The environment for the process provides a lot of context around the user request. We can see where we’d find our query string parameters (in QUERY_STRING).

GET https://admin.helloworld.localhost:5003/?my=query&string=here

Would set the QUERY_STRING environment variable to

QUERY_STRING: my=query&string=here

And what about the request body? Where would we see that? The CGI standard is that would be treated as standard input. Let’s update our sample app to show how input would come in.

use std::env;
use std::io::{stdin, Read};

fn main() {
  println!("Content-Type: text/plain\n");
  println!("Environment vars:");
  for (k,v) in env::vars() {
    println!("\t{}: {}", k, v);
  }

  let mut input_content = String::new();
  stdin().read_to_string(&mut input_content).expect("Failed to read from standard in.");
  println!("The request body is:");
  println!("{}", input_content);
}

After rebuilding and pushing that to Bindle and Hippo,

cargo build --release --target wasm32-wasi
hippo push -k .

We can make a POST request to the application.

POST https://admin.helloworld.localhost:5003
Content-Type: text/plain

Hello from the request body!

And we'll see a response of:

Environment vars:
    SCRIPT_NAME: /
    REMOTE_HOST: 127.0.0.1
    PATH_INFO:
    X_FULL_URL: http://127.0.0.1:32770/
    GATEWAY_INTERFACE: CGI/1.1
    HTTP_X_FORWARDED_HOST: admin.helloworld.localhost:5003
    SERVER_PROTOCOL: HTTP/1.1
    CONTENT_LENGTH: 28
    HTTP_X_FORWARDED_FOR: 127.0.0.1
    QUERY_STRING:
    AUTH_TYPE:
    REMOTE_USER:
    PATH_TRANSLATED:
    SERVER_PORT: 32770
    HTTP_ACCEPT_ENCODING: gzip, deflate
    HTTP_USER_AGENT: vscode-restclient
    REQUEST_METHOD: POST
    SERVER_SOFTWARE: WAGI/1
    HTTP_X_FORWARDED_PROTO: https
    HTTP_TRACEPARENT: 00-ac52510305f6fc4c94dab9ec51e4bf1d-609c9e1830b79343-00
    X_RAW_PATH_INFO:
    REMOTE_ADDR: 127.0.0.1
    SERVER_NAME: 127.0.0.1
    HTTP_CONTENT_TYPE: text/plain
    CONTENT_TYPE:
    X_MATCHED_ROUTE: /
    HTTP_CONTENT_LENGTH: 28
    HTTP_HOST: 127.0.0.1:32770

The request body is:
Hello from the request body!

We’ve now got a way to run our application, get parameters and return ouput. There are a few other things to mention before we move to part three of this post. We can return non-200 status messages by writing the status to standard out, like:

println!("Status: 404");

We can set other return headers the same way. If we want to send a redirect, we can send a “Location” header and the status will be automatically set to 302 for us.

Now that we have a handle on the runtime environment, let’s take a small CLI I’ve built and convert it to a WASM application.

Getting Started with Hippo - a WebAssembly PaaS (Part 1)

Steven Murawski — Wed, 17 Nov 2021 22:39:56 +0000

Setting up a Development Environment

Hey y’all, I’ve recently been dipping into the cloud native space and wanted to share one of the projects I’m looking into. In this series, we’ll set up a development environment, explore how we can interact with that environment, and then port a little CLI tool I built to run as an application in a WebAssembly PaaS called Hippo.

One of the interesting developments has been the focus on WebAssembly (or WASM) as a secure and portable engine. You may have heard about WebAssembly as a way to improve the performance of web applications that run in the browser, which it can do and does well. WASM is also being looked at to run workloads in other contexts. Right out of the box, WASM brings a lightweight engine and a very strong sandbox model. There’s a standard being defined for how that sandbox can interact with the system around it, the WebAssembly System Interface (WASI). This standard paved the way for an implementation, called Wasmtime, which is now being used in a number of different projects, one of which we’ll dig into here.

What is ...?

Before we get too far into the weeds, there are lot of acronyms and projects, we’ve seen two already in the first paragraph and more are coming. Let’s define a few things here, so if you’re like me and take a time or two to get them straight, there’s a place to go for reference.

WASM or WebAssembly, a compact, low-level language with a binary format, initially designed to run in the browser. There are a multitude of ways to get a WebAssembly file (a .wasm file for a binary output or .wat file with a textual representation). There are, according to webassmbly.org, twelve or thirteen programming languages that support creating WebAssembly outputs. We’ll look at using Rust in this exploration.

WASI or WebAssembly System Interface, which is a standard for how the WebAssembly engine can be exposed to the underlying system resources. It offers a controlled path to system resources and requires explicit delegation of resources to the WebAssembly engine. It covers capabilities like file system access, networking, and other core operating system features (like random number generation).

Wasmtime is an implementation of a WASM runtime (hence wasmtime) that implements the WASI standard. The project provides the C API defined by the WASI standard, as well as providing a place to experiment with new features which may end up in the standard. Wasmtime can be used in projects in a variety of languages, offering bindings for Rust, Python, Go, and .NET as part of the project and Java, Perl, Zig, and Ruby as external projects. There are two toolchains for targeting Wasmtime, one in C/C++ and one in Rust.

WAGI or the WebAssembly Gateway Interface. Since the WASI standard doesn’t have network support defined yet, WAGI takes the Common Gateway Interface standard and provides the infrastructure to route network requests to WASM modules configured as HTTP handlers.

Bindle is an aggregate object store – allowing you to create versioned artifacts and store them with any and all the files needed. Bindle provides the object store for Hippo.

Hippo is a Platform-as-a-Service (PaaS) designed to provide a hosting environment that makes following cloud-native best practices easier. Hippo uses WAGI to provide a sandboxed, secure, and highly performant runtime environment with a great developer experience.

Enough with the definitions and background, let’s get started building an application for WASM and hosting it on Hippo.

Environment Setup

Fortunately, my colleague Scott Coulton has made this easier for us. We can go to his Hippo-Dev repository where we have two ways to get started. First, for a local development experience, we could use Multipass and

curl -L -o cloud-init.yaml "https://raw.githubusercontent.com/scotty-c/hippo-dev/blob/main/cloud-init.yaml"

multipass launch --name hippo-server --cpus 2 --mem 4G --disk 20G --cloud-init cloud-init.yaml

Our second option, and the route I’ll take, is to spin up a VM in Azure. We’ll need an Azure subscription and the Az CLI. Then,

curl -L -o deploy-azure.sh "https://raw.githubusercontent.com/scotty-c/hippo-dev/main/deploy-azure.sh"

bash deploy-azure.sh

I had to create a new resource group to start out.

Then the script will prompt you for your subscription ID, the resource group you want to use, and the name of the VM you want to deploy.

In either case, the cloud-init script will handle setting up a development environment on that server, along with Hippo and Bindle servers running. After the deploy happens (and we wait a few moments for the build of Hippo to complete), we should be able to access the Hippo web portal on port 5001.

Let’s create a new user from the registration link on the login page.

I’ll use the same login credentials as the Hippo tutorial (admin as the user and Passw0rd! for the password), as we’ll start there as we get our first deployment up and running, but that’s our next post!

We now have a server with Hippo running and a full suite of development tools to explore this new runtime environment.

Forem: Steven Murawski

ClickOps to GitOps (an Azure Marketplace story)

Our GitOps Journey So Far

What Has Come Before

A Quick Recap

The Principles of GitOps

Application of the Principles

Applying GitOps

Our Next GitOps Tool Exploration - ArgoCD

Reducing Time to Impact with the Azure Marketplace

Installing ArgoCD from the Azure Marketplace

Extensions + Applications

Add an Application

Access the Argo CD Server

Summary

Continue the conversation

My Git and VS Code Settings

What Really is GitOps?

Welcome

GitOps is ...

Defining GitOps

The Principles of GitOps

1) Declarative

2) Versioned and Immutable

3) Pulled Automatically

4) Continuously Reconciled

Elements of a GitOps Environment

Bare Minimum

More Realistic Environment

The Essence of GitOps

Why GitOps?

Is GitOps Different from DevOps?

What I Like about GitOps

My Problem(s) with GitOps

My Operational Problem with GitOps

My Philosophical Problem with GitOps

Summary

Continue the conversation

Just Enough Git for GitOps

GitOps Series

Git Concepts

Distributed

Branches

Repository

Special files

Remotes

Commands

Clone

Init

Status

Add

Commit

Push

Fetch

Merge

Checkout

Reset

Soft resets

Hard resets

Rebase

Summary

Continue the conversation

Getting Started with Helm

Understanding Helm

What is Helm?

Using Helm

Finding Helm Charts

Installing a Helm Chart

Customizing the Installation

Creating a Helm Chart

Converting a Manifest into a Template

Testing Template Rendering

The Notes.txt

Closing

Deep Dive into Working with Draft

What is Draft and what does it do?

How does Draft Work?

Setting up an Azure Environment

Setting up a test project

Getting Started with draft create

Getting Started with `draft create`

So, what templates are used by `draft create`?

Securing Access to Azure for my GitHub Workflow with `draft setup-gh`

Running `draft setup-gh`

Generating Build Automation with `draft generate-workflow`

So, what templates are used by `draft generate-workflow`?

Allowing Traffic to my Application with `draft update`

Other `draft` subcommands