DEV Community: Thorsten Hans

Run WebAssembly on DigitalOcean Kubernetes with SpinKube - In 4 Easy Steps

Thorsten Hans — Wed, 27 Mar 2024 14:37:39 +0000

DigitalOcean is a cloud infrastructure provider catering to developers, offering scalable virtual servers, storage solutions, networking services, and managed Kubernetes clusters. It simplifies application deployment, management, and scaling through its intuitive user interface and CLI (doctl), allowing developers to efficiently utilize cloud resources for their projects.

As part of this article, you'll learn how to

Provision a new Kubernetes cluster on DigitalOcean
Deploy SpinKube
Create a simple WebAssembly app using Spin 💫 and Rust 🦀
Deploy the Spin App to Kubernetes using an OCI compliant registry

What is SpinKube

SpinKube is an open-source project that allows you to run WebAssembly workloads on top of Kubernetes. Essentially, SpinKube is a stack that consists of the following components:

In addition to running WebAssembly workloads side-by-side with containers, you can run workloads more efficiently and with higher density. Because of WebAssembly’s portability, you can run the same WebAssembly workload on different architectures to reduce cloud spendings even more by using - for example - arm64 worker nodes 🚀.

At KubeCon EU 2024 - The application for contributing SpinKube to the Cloud Native Computing Foundation (CNCF) has been filed. Click here to watch the keynote recording.

Prerequisites

To follow along this article, the following software must be installed on your local machine:

The Spin CLI (spin)
- See installation instructions
- The kube plugin for spin
  - Install it via spin plugins install kube
Rust
- See installation instructions
- The wasm32-wasi target
  - Install it via rustup target add wasm32-wasi
A DigitalOcean Account & the DigitalOcean CLI (doctl)
- See installation instructions
The Kubernetes CLI (kubectl)
- See installation instructions
The Helm CLI (helm)
- See installation instructions

Although the DigitalOcean account itself is free, you have to provide payment information and you will be charged for allocating resources and renting services - such as the Managed Kubernetes Cluster we will create as part of this article.

1. Provision a Managed Kubernetes Cluster in DigitalOcean

Although the DigitalOcean Control Panel is an easy to grasp UI for provisioning cloud resources, we will use doctl CLI and its doctl kubernetes cluster create command to provision the managed Kubernetes cluster. Execute the following command, to provision a cluster consisting of two worker nodes:

# Variables
location=fra1
node_size=s-4vcpu-8gb-intel

# Create a new Kubernetes cluster
doctl kubernetes cluster create my-spinkube-cluster \
  --region $location \
  --count 2 \  
  --size $node_size \
  --set-current-context \
  --wait

DigitalOcean provides different regions and machine sizes for managed Kubernetes clusters. Use doctl kubernetes options regions to get a list of all regions. By running
doctl kubernetes options sizes you get a list of all supported machine sizes for Kubernetes worker nodes.

Once the managed Kubernetes cluster is provisioned, we can double-check if the corresponding context has been added to kubectl and is marked as the current context:

# List all contexts of kubectlkubectl config get-contexts
CURRENT   NAME                  CLUSTER 
*         my-spinkube-cluster   my-spinkube-cluster 
          k3d-wasm-cluster      k3d-wasm-cluster    

# Set current context to my-spinkube-cluster (if not already)
kubectl config use-context my-spinkube-cluster
Switched to context "my-spinkube-cluster".

2. Install SpinKube

On top of its core components, SpinKube depends on cert-manager. cert-Manager is responsible for provisioning and managing TLS certificates that are used by the admission webhook system of the Spin Operator. Let’s install cert-manager and KWasm using the commands shown here:

# Install cert-manager CRDs
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.crds.yaml

# Add Helm repositories jetstack and KWasm
helm repo add jetstack https://charts.jetstack.io
helm repo add kwasm http://kwasm.sh/kwasm-operator

# Update Helm repositories
helm repo update

# Install cert-manager using Helm
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.14.4

# Install KWasm operator
helm install \
  kwasm-operator kwasm/kwasm-operator \
  --namespace kwasm \
  --create-namespace \
  --set kwasmOperator.installerImage=ghcr.io/spinkube/containerd-shim-spin/node-installer:v0.13.1

KWasm will install containerd-shim-spin on Kubernetes nodes annotated with kwasm.sh/kwasm-node=true. For the sake of this article, we will annotate all nodes of our cluster using the following command:

# Annotate all Kubernetes nodes with kwasm.sh/kwasm-node=true
kubectl annotate node --all kwasm.sh/kwasm-node=true

Finally, we can install the Spin Operator on the Kubernetes cluster along with necessary Custom Resource Definitions (CRDs), the RuntimeClass and the SpinAppExecutor:

# Install SpinKube CRDs
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.crds.yaml

# Install a RuntimeClass for wasmtime-spin-v2
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.runtime-class.yaml

# Install the containerd-spin-shim SpinAppExecutor
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml

# Install Spin Operator with Helm
helm install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.1.0 \
  --wait \
  oci://ghcr.io/spinkube/charts/spin-operator

3. Create a Spin App

Having SpinKube installed on our managed Kubernetes cluster, we can build a simple Spin App for verification purposes. We will use the http-rust template and apply some small changes to the app generated by spin:

# Create a new Spin App
spin new -t http-rust --accept-defaults hello-do-k8s

# Move into the Spin App
cd hello-do-k8s

Modify the implementation ( in ./src/lib.rs) to match the following:

use spin_sdk::http::{IntoResponse, Request, Response};
use spin_sdk::http_component;

#[http_component]
fn handle_hello_do_k8s(req: Request) -> anyhow::Result<impl IntoResponse> {
    println!("Handling request to {:?}", req.header("spin-full-url"));

    Ok(Response::builder()
        .status(200)
        .header("content-type", "text/plain")
        .body("Hello from DigitalOcean Kubernetes")
        .build())
}

With this, we expect our Spin App to respond on incoming HTTP requests with an HTTP 200, a Content-Type of text/plain and payload of Hello from DigitalOcean Kubernetes.

Compile the Spin App using spin build and use spin up to test your app locally:

# Build the Spin App
spin build

## snip 
Finished release [optimized] target(s) in 8.92s
Finished building all Spin components

# Run the Spin App locally
spin up
Logging component stdio to ".spin/logs/"Serving http://127.0.0.1:3000
Available Routes:
  hello-do-k8s: http://127.0.0.1:3000 (wildcard)

# You can terminate the app at any time using CTRL+C

You can test the Spin App locally, by sending an HTTP request to localhost:3000 from within a new terminal instance:

# Send a HTTP GET request to localhost:3000
curl -iX GET http://localhost:3000
HTTP/1.1 200 OK
content-type: text/plain
transfer-encoding: chunked
date: Tue, 25 Mar 2024 11:40:28 GMT
Hello from DigitalOcean Kubernetes

4. Deploy the Spin App via OCI compliant registry

Spin Apps are distributed as OCI artifacts, meaning we can choose from many different container registries for distributing them. For demonstration purposes, we will use ttl.sh (an anonymous and ephemeral Docker image registry) in which the tag of an artifact defines how long the artifact remains available (TTL).

We use the spin registry push command for distributing Spin Apps through OCI compliant registries.

You can also use the spin registry login command to authenticate with private registries and distribute your Spin Apps without making them publicly available at all.

# Build the Spin App
spin build

# Publish the Spin App as OCI artifact
# The artifact will remain accessible for 24 hours (24h tag)
spin registry push ttl.sh/hello-do-k8s:24h
Pushing app to the
Pushed with digest sha256:b77b7cd7644be0b32613cbec1be5049eb96c7e536377165c4c08e1467c4087b2

Finally, we deploy our Spin App to the managed Kubernetes cluster running on DigitalOcean. Again, we use the spin CLI to scaffold the necessary Kubernetes manifests and pipe them to kubectl which will interact with Kubernetes API server and provision the SpinApp custom resource (CR):

# Deploy Spin App to Kubernetes
spin kube scaffold -f ttl.sh/hello-do-k8s:24h | kubectl apply -f -
spinapp.core.spinoperator.dev/hello-do-k8s created

Let’s use kubectl and take a closer look at what we got:

# List Spin Apps in the default namespacekubectl get spinapps
NAME            READY   DESIRED   EXECUTOR
hello-do-k8s    2       2         containerd-shim-spin

# List Deploymentskubectl get deployments
NAME            READY   UP-TO-DATE   AVAILABLE   AGE
hello-do-k8s    2/2     2            2           103s

# List Pods (wide)kubectl get pods -o wide
NAME                             READY   STATUS     AGE     IP
hello-do-k8s-665676d5bd-9gt4s    1/1     Running    2m14s   10.42.0.7
hello-do-k8s-665676d5bd-5fjpm    1/1     Running    2m14s   10.42.1.7

# List all Services and their Endpointskubectl get services,endpoints
NAME                    TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
service/hello-do-k8s    ClusterIP   10.43.75.164    <none>        80/TCP    4m7s

NAME                      ENDPOINTS                   AGE
endpoints/hello-do-k8s    10.42.0.7:80,10.42.1.7:80   4m7s

As you can see, the Spin Operator takes care of all the Kubernetes primitives for running and accessing our Spin App.

Testing the Spin App running on Kubernetes

Let’s configure port forwarding, to access the Spin App using curl from our local machine:

# Start port-forwarding
kubectl port-forward services/hello-do-k8s 8080:80
Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

Use a new terminal instance and send an HTTP request to locahost:8080 and verify receiving the expected response back:

# Send an HTTP GET request to localhost:8080
curl -iX GET http://localhost:8080
HTTP/1.1 200 OK
content-type: text/plain
transfer-encoding: chunked
date: Tue, 25 Mar 2024 11:48:21 GMT
Hello from DigitalOcean Kubernetes

Cleaning up the Cloud Resources

To remove the cloud infrastructure we created as part of this article from your DigitalOcean account, run the following command:

# Delete the DigitalOcean managed Kubernetes cluster
doctl kubernetes cluster delete my-spinkube-cluster --force

Conclusion

By deploying SpinKube onto your managed Kubernetes clusters in DigitalOcean, you can run WebAssembly workloads right beside containers. As WebAssembly apps are way smaller than containers, you can run more workloads on the same amount of compute resources. As you’ve learned in this article, the deployment of SpinKube is simple and requires only a couple of steps.

If you want to learn more about SpinKube, consider reading the SpinKube documentation. There are plenty of tutorials, like, for example:

Building Serverless Apps with Spin and htmx

Thorsten Hans — Mon, 05 Feb 2024 15:33:00 +0000

Hi,

In this article, I’ll walk you through the process of building serverless applications using the power of WebAssembly with Fermyon Spin and htmx. For demonstration purposes, we will build a simple shopping list. We will implement the serverless backend in Rust. For building the frontend, we’ll start with a simple HTML page, which we will enhance using htmx.

Before we dive into implementing the sample application, we will ensure that everybody is on track and quickly recap what Fermyon Spin and htmx actually are.

What is Fermyon Spin

Fermyon Spin (Spin) is an open-source framework for building and running event-driven, serverless applications based on WebAssembly (Wasm).

Developers can build applications using a wide variety of different programming languages (basically developers can choose from all languages that could be compiled to Wasm). Spin uses Wasm because the core value propositions of Wasm perfectly address common non-functional requirements that we face when building distributed applications:

Near-native runtime performance
Blazingly fast cold start times (speaking about milliseconds here) that allow scale-down to zero
Strict sandboxing and secure isolation

At Fermyon we're obsessed when it comes to developer productivity. The spin CLI and the language-specific SDKs ensure unseen developer productivity in the realm of WebAssembly.

What is htmx

htmx is a lightweight JavaScript library built for developers, facilitating progressive enhancements in web applications. By seamlessly updating specific parts of a webpage without necessitating a complete reload, htmx empowers us to create dynamic and interactive user experiences effortlessly. Its simplicity and performance-oriented approach, utilizing HTML attributes for defining behavior, make it a valuable tool for augmenting existing projects or crafting new frontends.

The sample application

For demonstration purposes, we will create a simple shopping list to illustrate how Spin and a simple frontend crafted with htmx could be integrated. From an architectural point of view, our shopping list consists of three major components, as shown in the diagram below.

Persistence: We use SQLite as a database to persist the items of our shopping list
Backend: We will build an HTTP API using Rust and Spin
Frontend: The frontend consists of HTML, CSS, and progressive enhancements provided by htmx

You can find the source of sample application on GitHub at https://github.com/ThorstenHans/spin-htmx.

Prerequisites

To follow along with the sample explained in this article, you need to have the following tools installed on your machine:

Rust - See installation instructions for Rust (I am currently using Rust version 1.75.0)
The wasm32-wasi compilation target - You can install it using the rustup target add wasm32-wasi command
The spin CLI - See installation instructions for Spin (I am currently using spin version 2.1.0)

Creating the app skeleton

First, we will use the spin CLI to create our Spin application and add the following components to it:

app: A Spin component based on the static-fileserver template which will serve our frontend
api: A Spin component based on the http-rust template, which will serve the HTTP API

Because the spin CLI is built with productivity in mind, generating the entire boilerplate is quite easy, as you can see in this snippet:

# Create an empty Spin app called shopping-list
spin new -t http-empty shopping-list
Description: A shopping list built with Spin and htmx

# Move into the app directory
cd shopping-list

# Create the app component
spin add -t static-fileserver app
HTTP path: /...
Directory containing the files to serve: assets

# Create the frontend-asset folder
mkdir assets

# Create the API component
spin add -t http-rust api
Description: Shopping list API
HTTP path: /api/...

Having our Spin app bootstrapped and added all necessary components, we can move on and take care of the database.

Preparing the database

Although Spin takes care of running the database behind the scenes, we must ensure that the desired component(s) can interact with the database. This is necessary because Wasm is secure by default and Wasm modules must explicitly request permissions to use or interact with different resources/capabilities.

This might sound like a complicated task in the first place, but Spin makes this super easy. All we have to do is update the application manifest (spin.toml) and add the sqlite_databases configuration property to the desired component(s). In our case, the api component is the only one, that should be able to interact with the database. That said, update the [component.api] section in spin.toml to look like this:

[component.api]
source = "api/target/wasm32-wasi/release/api.wasm"
allowed_outbound_hosts = []
sqlite_databases = ["default"]

Next, we have to lay out our database using a simple DDL script. We create a new file called migration.sql in the root folder of our application and add the following content to it:

CREATE TABLE IF NOT EXISTS ITEMS (
  ID INTEGER PRIMARY KEY AUTOINCREMENT,
  VALUE TEXT NOT NULL
)

With the update to spin.toml and our custom migration.sql file, we have prepared everything regarding the database. We could move on and take care of the serverless. backend.

Implementing the serverless backend

Our serverless backend exposes three different endpoints that we’ll use later from within the frontend:

HTTP GET at /api/items : to retrieve all items of the shopping list
HTTP POST at /api/items: to add a new item to the shopping list by providing a proper JSON payload as the request body
HTTP DELETE at /api/items/:id: to delete an existing item from the shopping list using its identifier

The Spin SDK for Rust comes with batteries included to create full-fledged HTTP APIs. We use the Router structure to layout our API and handle incoming requests as part of the function decorated with the #[http_component] macro:

use spin_sdk::http_component;
use spin_sdk::http::{IntoResponse, Request, Router};

#[http_component]
fn handle_api(req: Request) -> anyhow::Result<impl IntoResponse> {
  let mut r = Router::default();
  r.post("/api/items", add_new);
  r.get("/api/items", get_all);
  r.delete("/api/items/:id", delete_one);
  Ok(r.handle(req))
}

Before we dive into implementing the handlers, we add some 3rd party crates to simplify working with JSON and creating HTML fragments:

# Move into the API folder
cd api

# Add serde and serde_json
cargo add serde -F derive
cargo add serde_json

# Add build_html
cargo add build_html

Those commands will download the 3rd party dependencies and add them to the Cargo.toml file.

Implementing the `POST` endpoint

To add a new item to the shopping list, we want to issue POST requests from the frontend to the API and send the new item as JSON payload using the following structure:

{ "value": "Buy milk"}

First, we create the corresponding API model as a simple struct and decorate it with Deserialize from the serde crate:

use serde::{Deserialize};

#[derive(Deserialize)]
pub struct Item {
  pub value: String,
}

Having our model in place, we can implement the add_new handler. We can offload the act of actually deserializing the payload to the http crate, by precisely specifying the request type (here http::Request<Json<Item>>). Additionally, we use Connection and Value from spin_sdk::sqlite to securely construct the TSQL command for storing the new item in the database. Finally, we return an HTTP 200 along with a HX-Trigger header.

Later, when implementing the frontend, we’ll use the value of the HX-Trigger header, when implementing the frontend:

use spin_sdk::sqlite::{Connection, Value};
use spin_sdk::http::{Json, Params};

fn add_new(req: http::Request<Json<Item>>, _params: Params) -> anyhow::Result<impl IntoResponse> {
  let item = req.into_body().0;
  let connection = Connection::open_default()?;
  let parameters = &[Value::Text(item.value)];
  connection.execute("INSERT INTO ITEMS (VALUE) VALUES (?)", parameters)?;
  Ok(Response::builder()
    .status(200)
    .header("HX-Trigger", "newItem")
    .body(())?)
}

Implementing the `GET` endpoint

Next on our list is implementing the handler to retrieve all shopping list items from the database. Before we dive into the implementation of the handler, let’s revisit our Item struct and extend it, to match the following:

#[derive(Debug, Deserialize, Serialize)]
struct Item {
  #[serde(skip_deserializing)]
  id: i64,
  value: String,
}

Instead of returning plain values as JSON, our API will create response bodies as HTML fragments (Content-Type: text/html) with htmx enhancements.

To achieve this, we must specify how a single item (an instance of the Item structure) is represented as HTML. The build_html create provides the Html trait, which we can use to lay out how an item should look like in HTML. Let’s implement the Html trait for our custom type
Item as shown here:

use build_html::{Container, ContainerType, Html, HtmlContainer};

impl Html for Item {
  fn to_html_string(&self) -> String {
    Container::new(ContainerType::Div)
      .with_attributes(vec![
        ("class", "item"),
        ("id", format!("item-{}", &self.id).as_str()),
      ])
      .with_container(
        Container::new(ContainerType::Div)
          .with_attributes(vec![("class", "value")])
          .with_raw(&self.value),
      )
      .with_container(
        Container::new(ContainerType::Div)
          .with_attributes(vec![
            ("class", "delete-item"),
            ("hx-delete", format!("/api/items/{}", &self.id).as_str()),
          ])
          .with_raw("❌"),
      )
      .to_html_string()
  }}

On top of creating an HTML representation of the actual item, the snippet also contains a hx-delete attribute. We add this attribute to the delete-icon, to allow users to delete a particular item directly from the shopping list.

The handler implementation (get_all) reads all items from the database, constructs a new instance of Item for every record retrieved, and transforms every instance into an HTML string by invoking to_html_string. Finally, we join all HTML representations together into a bigger HTML fragment and construct a proper HTTP response.

fn get_all(_r: Request, _p: Params) -> anyhow::Result<impl IntoResponse> {
  let connection = Connection::open_default()?;
  let row_set = connection.execute("SELECT ID, VALUE FROM ITEMS ORDER BY ID DESC", &[])?;

  let items = row_set
    .rows()
    .map(|row| Item {
      id: row.get::<i64>("ID").unwrap(),
      value: row.get::<&str>("VALUE").unwrap().to_owned(),
    })
    .map(|item| item.to_html_string())
    .reduce(|acc, e| format!("{} {}", acc, e))
    .unwrap_or(String::from(""));

  Ok(Response::builder()
    .status(200)
    .header("Content-Type", "text/html")
    .body(items)?)
}

Implementing the `DELETE` endpoint

The last endpoint we have to implement is responsible for deleting an item based on its identifier. We do some housekeeping here to ensure that requests contain an identifier and ensure that the identifier provided is a valid i64. If that’s the case, we delete the corresponding record from the database and return an empty response with status code 200 (which is done via Response::default()):

fn delete_one(_req: Request, params: Params) -> anyhow::Result<impl IntoResponse> {
  let Some(id) = params.get("id") else {
    return Ok(Response::builder().status(404).body("Missing identifier")?);
  };
  let Ok(id) = id.parse::<i64>() else {
    return Ok(Response::builder()
      .status(400)
      .body("Unexpected identifier format")?);
  };
  let connection = Connection::open_default()?;
  let parameters = &[Value::Integer(id)];

  match connection.execute("DELETE FROM ITEMS WHERE ID = ?", parameters) {
    Ok(_) => Ok(Response::default()),
    Err(e) => {
      println!("Error while deleting item: {}", e);
      Ok(Response::builder()
        .status(500)
        .body("Error while deleting item")?)
    }
  }}

With that, our serverless backend is done and we can move on and take care of the frontend.

Implementing the Frontend

We’ll keep the frontend as simple as possible. All sources will remain in the assets folder (you remember, we specified that as the source for the static-fileserver component when creating the Spin app at the very beginning).

First, let’s create all necessary files and bring in our 3rd party dependencies (htmx and the json-enc extension):

# Move into the assets folder
cd assets

# Create the HTML file
touch index.html

# Download the pre-coded CSS file
curl -o style.css \
  https://raw.githubusercontent.com/ThorstenHans/spin-htmx/main/app/style.css

# Download the latest version of htmx
curl -o htmx.min.js \
  https://unpkg.com/browse/htmx.org@1.9.10/dist/htmx.min.js

# Download the latest version of json-enc
curl -o json-enc.js \
  https://unpkg.com/htmx.org@1.9.10/dist/ext/json-enc.js

As a starting point, we use a fairly simple HTML page. Please note that the page is already linking the stylesheet (<link rel=...>) as part of the <head> tag.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Shopping List</title>
  <link rel="stylesheet" href="/style.css">
</head>
<body>
  <header>
    <h1>Shopping List | <small>powered by Spin &amp; htmx</small></h1>
    <p class="slug">This is a simple shopping list for demonstrating the combination of
      <a href="https://htmx.org/" target="_blank">htmx</a> and
      <a href="https://developer.fermyon.com" target="_blank">Fermyon Spin</a>.
    </p>
  </header>
  <main>
    <div id="all-items">
    </div>
  </main>
  <aside>
    <h2>Add a new item to the shopping list</h2>
    <form>
      <input type="text" name="value" placeholder="Add Item" maxlength="36">
      <button type="submit">Add</button>
    </form>
  </aside>
  <footer>
    <span>Made with 💜 by</span>
      <a href="https://www.fermyon.com" target="_blank">Fermyon</a>
      <span>Find the code on</span>
      <a href="xxx" target="_blank">GitHub</a>
  </footer>
</body>
</html>

Adding htmx to the app

First, we have to ensure htmx and the json-enc extension are brought into context correctly. Update the index.html file and add the following <script> tags before the closing </body> tag:

<!-- ... -->
    <script src="/htmx.min.js"></script>
    <script src="json-enc.js"></script>
  </body>
</html>

Loading and displaying items

Let’s have a look at loading and displaying the items on our shopping list now!

We can use the hx-get attribute to issue an HTTP GET request to /api/items for loading all items. Using the hx-target attribute, we specify where the received HTML fragment should be placed. We control how the HTML fragment is treated with the hx-swap attribute.

Last, but not least, we use the hx-trigger attribute to determine when HMTX should issue the HTTP GET request. We update the HTML, and modify the <main> node to match the following:

<main hx-get="/api/items"
      hx-target="#all-items"
      hx-swap="innerHtml"
      hx-trigger="load">
    <!-- ... -->
</main>

Deleting an item

The HTML fragment for every item contains an icon and a hx-delete attribute. Users can press the delete icon, to delete the corresponding item. Although we could issue the HTTP DELETE request immediately, we can prevent users from accidentally deleting items by adding a confirmation dialog. (Although there are fancier UI representations possible, we’ll keep it simple here and use the standard confirmation dialog provided by the browser.)

Because we place all items inside of #all-items, we can add hx- attributes on that particular container, to control the actual delete behavior. We customize the message shown in the confirmation dialog, using the hx-confirm attribute. To specify which child node should be manipulated when the delete operation is confirmed, we use the hx-target attribute. Again, we use hx-swap to specify that we want to remove the corresponding .item .

Let’s update the <div id="all-items"> node as shown in the following snippet:

<div id="all-items"
     hx-confirm="Do you really want to delete this item?"
     hx-target="closest .item"
     hx-swap="outerHTML swap:1s">
</div>

Adding a new item

Our frontend contains a simple <form> which allows users to add new items to the shopping list. Upon submitting the form, we want to issue an HTTP POST request to /api/items and send the provided text as JSON to our serverless backend. Once an item has been added, we want our UI to refresh and display the updated shopping list.

Our serverless backend expects to receive the payload for adding new items as JSON. Because of this, we have added the JSON extension for htmx (json-enc.js) to our frontend project.

We can alter the default behavior of htmx (because it normally sends the data from HTML forms as form-data) by adding the hx-ext="json-enc" attribute to the <form> node.

Additionally, we will update the <form> definition by adding the hx-post and hx-swap attributes. We specify the hx-on::after-request attribute, to control what should happen after the request has been processed. Modify the <form> node to look like shown here:

<form hx-post="/api/items"
     hx-ext="json-enc"
     hx-swap="none"
     hx-on::after-request="this.reset()">
    <!-- ... -->
</form>

By adding those four attributes to the <form> tag, we control how and where the form data is sent. On top of that, the form is reset after the request has been processed. Finally, we have to
reload the shopping list once the request has finished.

Do you remember the response that we sent from the backend when a new item has been added to the database? As part of the response, we sent an HTTP header called HX-Trigger with the value newItem. We use this value and instruct htmx to reload the list of all items. All we have to do in the frontend is alter the hx-trigger attribute on <main> and add our “custom event” as a trigger. Update the <main> tag to match the following:

<main hx-get="/api/items"
     hx-trigger="load, newItem from:body"
     hx-target="#all-items"
     hx-swap="innerHTML">
    <!-- ... -->
</main>

Running the application locally

Now that we have implemented everything, we can test our app. To do so, we move into the project folder (the folder containing the spin.toml file) and use the spin CLI for compiling and running both components (frontend and backend).

# Build the application
# Actually, only the backend has to be compiled... 
# Spin is smart enough to recognize that
spin build

Building component api with `cargo build --target wasm32-wasi --release`
Working directory: "./api"
# ...
# ...

# Start the app on your local machine
# by specifying the --sqlite option, we tell Spin to execute the migration.sql 
# upon starting
spin up --sqlite @migration.sql

Logging component stdio to ".spin/logs/"
Storing default SQLite data to ".spin/sqlite_db.db"
Serving http://127.0.0.1:3000
Available Routes:
 api: http://127.0.0.1:3000/api (wildcard)
 app: http://127.0.0.1:3000 (wildcard)

As the output of spin up outlines, we can access the shopping list by browsing to http://127.0.0.1:3000, which should display the serverless shopping list like this:

Deploying to Fermyon Cloud

Having our shopping list tested locally, we can take it one step further and deploy it to Fermyon Cloud. To deploy our app using the spin CLI, we must log in with Fermyon Cloud. We can login,
by following the instructions provided by the spin cloud login command.

Deploying to Fermyon Cloud is as simple as running the spin cloud deploy command from within the root folder of our project. Because our app relies on a SQLite database, we must provide a unique name for the database inside of our Fermyon Cloud account.

# Deploy to Fermyon Cloud
spin cloud deploy

Uploading shopping-list version 0.1.0 to Fermyon Cloud...
Deploying...
App "shopping-list" accesses a database labeled "default"
Would you like to link an existing database or create a new database?: 
Create a new database and link the app to it

What would you like to name your database? 
Note: This name is used when managing your database at the account level.
The app "shopping-list" will refer to this database by the label "default".
Other apps can use different labels to refer to the same database.: shopping

Waiting for application to become ready........ 
ready

Available Routes:
 api: https://shopping-list-1jcjqxxq.fermyon.app/api (wildcard)
 app: https://shopping-list-1jcjqxxq.fermyon.app (wildcard)

Once the initial deployment has been finished, we must ensure that our ITEMS table is created in the database that was created by Fermyon Cloud. To do so, we can use the spin cloud sqlite execute command as shown in the next snippet:

# List all SQLite databases in your Fermyon Cloud account
spin cloud sqlite list
+-------------------------------+
| App       Label      Database |
+===============================+
| shopping  default    shopping |
+-------------------------------+

# Apply migration.sql to the shopping database
spin cloud sqlite execute --database shopping @migration.sql

Fermyon Cloud automatically assigns a unique domain to our application, we can customize the domain and even bring a custom domain using the Fermyon Cloud portal.

Conclusion

In this article, we walked through building a truly serverless application based on Spin and htmx. Although our shopping list is quite simple, it demonstrates how we can combine both to build a real app. Looking at both, Spin and htmx have at least one thing in common:

They reduce complexity!

With htmx we can build dynamic frontends without having to learn the idioms and patterns of full-blown, big Single Page Application (SPA) frameworks such as Angular. We can declare our intentions directly in HTML by adding a set of htmx attributes to HTML tags.

With Spin we can focus on solving functional requirements and choose from a wide variety of programming languages to do so. Integration with services like databases, key-value stores, message brokers, or even Large Language Models (LLMs) is amazingly smooth and
requires no Ops at all.

On top of that, the spin CLI and the language-specific SDKs provide amazing developer productivity, that is unmatched in the context of WebAssembly.

Terraform - The definitive guide for Azure enthusiasts

Thorsten Hans — Mon, 21 Oct 2019 20:27:52 +0000

This post has been published initially on my blog at thorsten-hans.com

Terraform is a product in the Infrastructure as Code (IaC) space, it has been created by HashiCorp. With Terraform you can use a single language to describe your infrastructure in code. This guide explains the core concepts of Terraform and essential basics that you need to spin up your first Azure environments.

What is Infrastructure as Code (IaC)
What is Terraform
- Terraform Providers
- The HashiCorp Configuration Language (HCL)
- Previewing changes
Setting up Terraform
- Terraform Extension for Code
DataTypes in HCL
- Booleans
- Strings
- Lists
- Maps
How does a Terraform project look like
Variables in HCL
- Referencing Variables
Outputs in HCL
Overrides
The Azure Provider
- Authenticating mechanisms offered by the Azure Provider
Your first Azure Environment with Terraform
Destroying Terraform Environments
The Terraform Lifecycle
Download the code from GitHub
Summary

What is Infrastructure as Code (IaC)

Infrastructure as Code (IaC) is the process of describing infrastructural components such as servers, services, or databases using a programming language. Once all infrastructural requirements are described in code, that code can be stored in source control.

Source control means that the infrastructure is versioned, transparent, documented, testable, mutable and discoverable. Once the first version is stored in source control, all team members see which infrastructure is required to bring a project alive. Everyone sees which configuration settings are required to make -for example- the database perform as good as expected.

Changes are done to the infrastructure exist as dedicated commits -or more significant changes as pull requests- and will be reviewed by peers before being merged into the latest version. The code is also easy to test and on top, Continuous Integration (CI) builds can execute existing tests automatically with no human interaction. Having tests means errors in the infrastructure configuration are spotted earlier.

Also, having code in a repository is 100% more documentation as if all necessary information is stored in just one human brain. This is also a critical risk reduction for every project. Let's elaborate on risk reduction a bit:

Before Infrastructure as Code, John -the smart guy everyone has on his/her software projects- was responsible for maintaining the infrastructure. John gave his best to describe all essential infrastructure parts and their configuration values. However, modern software projects evolve. Services have to be added or removed from the overall architecture; things must be scaled dynamically and/or manually based on external events. So there is a good chance that John has some critical information only in his head... Maybe has Tim -the guy who sits next to John- some tribal knowledge about the Redis configuration, but would you bet on it?

That said, everyone on the team knows John. Everyone trusts him. However, every teammate is afraid when John wants to take a couple of weeks off and go on vacation.

Look at your current project team and try to spot John. Everybody knows situations or constellations like these. To be clear: It's not Johns fault. It's the fact that the entire organization isn't using IaC.

Having Infrastructure as Code would remove that critical path.

What is Terraform

Now, knowing what Infrastructure as Code is, it's time to look at Terraform itself. Terraform is currently the best tool to implement IaC. And it doesn't matter if you're using Azure, Azure Stack or other vendors as a target for your infrastructure. With Terraform you can create, modify and destroy environments safely and efficiently.

For me, these are the three significant benefits offered by Terraform:

It works with almost every environment (On-Demand and On-Premises)
You've to learn only a single and simple language
Terraform can preview changes before applying them

Let's take a closer look at those three benefits now.

Terraform Providers

HashiCorp created a small, yet powerful tool which can talk to numerous platforms using a flexible provider model. Vendors like Microsoft expose functionalities as APIs, and the corresponding Terraform provider is responsible for making those APIs accessible to you. If you ask yourself which platforms Terraform is supporting, go and check the list of providers.

So, means dealing with different APIs, that each platform supports different features?

Yes. Take Azure Functions as an example. You can quickly query information about an existing Azure Functions instance or create/modify/destroy another Azure Function instance using the Azure provider for Terraform. However, if you talk to a local VMWare Cluster, you can't interact with Azure Functions because VMWare doesn't have a first-class citizen of type Azure Function.

The HashiCorp Configuration Language (HCL)

The HashiCorp Configuration Language (HCL) is a small domain-specific language which is based on JSON. The HashiCorp team removed some language-specific plumbings to make us a bit more productive by saving some keystrokes.

On the other side, Terraform adds some powerful interpolation features to HCL, which you'll use and love every day. You'll dive into HCL later in this guide. However, take the following short snippet as sneak-peek to see how Terraform scripts look like:

resource "azurerm_redis_cache" "sample" {
  name                = "tf-redis-basic"
  location            = "${azurerm_resource_group.test.location}"
  resource_group_name = "${azurerm_resource_group.test.name}"
  capacity            = 0
  family              = "C"
  sku_name            = "Basic"
  enable_non_ssl_port = "${var.redis_enable_non_ssl}"
  tags                = "${local.all_tags}"
}

Previewing changes

Being able to preview changes before they are applied to a platform is the most significant benefit offered by Terraform in day-to-day business. You can think of it as the git status of IaC. You describe your infrastructure in HCL and use the handy terraform plan command to see what would happen if that Terraform script gets applied to the chosen platform.

Besides those three major benefits, Terraform offers things like:

centralized state management
implicit dependency resolution
parallelization of execution
reusable modules
terraform module registry

and many more.

Setting up Terraform

Setting up Terraform is quite smooth. Terraform can be used on every popular operating system. It can be downloaded directly from the official website.

On macOS you can install it also using homebrew by executing brew install terraform.

On Windows you can install it using chocolatey by executing choco install terraform.

The installation can be verified by executing the terraform command. Terraform should now show all available subcommands.

Terraform Extension for Code

There is an extension for Visual Studio Code called Terraform (by Mikael Olenfalk). Once installed Code can do syntax highlighting, code completion, IntelliSense and on top of that you can drill through your resource graph using a nice visual tree.

DataTypes in HCL

The introduction already mentioned that HashiCorp Configuration Language (HCL) is a relatively simple language. This simplicity continues when we dive deeper in HCL DataTypes. Currently HCL knows four different data types that you'll use to craft your scripts.

Booleans

A boolean in HCL must have a value. The value can either be true or false. HCL has no native support for booleans; instead, it converts every string into a boolean if possible.

variable "storace_account_enable_firewall" {
  type    = "string"
  default = true
}

Strings

A string in HCL is either a single line of text or text that spreads over multiple lines. The following snippet shows, how those two kinds of string can be defined:

variable "single_line_string" {
  type    = "string"
  default = "value"
}

variable "multi_line_string" {
  type = "string"
  default = <<EOF
This value spreads
over several lines.
EOF
}

When receiving string values, HCL inspects the value and converts it to a number or a boolean if possible (as mentioned earlier). However, there are some important caveats that every Terraform user needs to know. You can read more about those caveats here.

Lists

A list in HCL is a collection of string values which are indexed by numbers. Lists in HCL are zero-based (so the first index of a list is always 0 in HCL). It's a typed JSON Array.

variable "simple_list" {
  type    = "list"
  default = ["development", "staging", "production"]
}

Maps

A map in HCL is a dictionary of string values, indexed by string keys. You can think of it as a regular JavaScript object. Defining a map looks like this:

variable "custom_tags" {
  type      = "map"
  default   = {
    author  = "Thorsten"
    version = "1.0.0"
  }
}

How does a Terraform project look like

Terraform projects are easy to understand. Every folder is a valid Terraform project if it contains at least a single .tf or .tf.json file. (Yes you can write your scripts in plain old JSON, but my advice is to stick with .tf files)

However, if you have multiple .tf files in a folder, files are processed in alphabetical order. While processing, .tf files are merely appended together.

Variables in HCL

In Terraform variables can be specified to make scripts more flexible and dynamic. Variables are either created directly inside of regular .tf scripts or they could be organized in dedicated variables.tf files. There is no real best practice here because each Terraform projects differ in both: size and complexity.

Because of Terraform's implicit dependency resolutions, variables are always available, no matter where they end up in the final script. To keep things organized, we'll start with a dedicated variable file. In such a situation, I choose names like variables.tf. frontend-variables.tf or backend-variables.tf.

A variable has a reasonably simple schema in HCL.

variable "storage_account_name" {
  type        = "string"
  default     = "thorstensstorage"
  description = "provide a unique name for the Storage Account"
}

variable "storage_account_location" {
  type        = "string"
  description = "name of the Azure datacenter where the Storage Account should be generated"
}

Every variable requires a value at runtime. There are five ways how the value of a variable could be specified in Terraform.

The actual value of the variable is provided by the default property as part of the variable definition as shown above for storage_account_name.
The variable storage_account_location has no default value. When terraform apply or terraform plan is executed, a simple wizard will ask for a value.
Actual variable values could also be specified using Environment Variables. This is an excellent approach to build servers or scenarios where Terraform scripts are applied without human interaction. Environment Variables are pulled if their name follows the schema TF_VAR_{variable_name} (TF_VAR_storage_account_location in this example)
Values can be specified by passing arguments to the terraform apply command. This approach is great for development time or -if required due to limitations- for unattended execution contexts such as build servers
The last and most convenient method to specify variable values are so-called .tfvars files. .tfvars files should never go to source control. In real-world scenarios, it's often required to pass some sensitive data into Terraform scripts (Think of Service Principal credentials for example). My projects normally contain a values.tfvars.template file which is explicitly added to git and tells other teammates which values should be defined. Providing concrete values for the sample variables above could look like this.

storage_account_name = "storagethorsten"
storage_account_location = "West Europe"

Referencing Variables

Referencing variables in Terraform scripts is done by using the Terraform interpolation syntax. Both variables that were defined above are used in the following sample to provide essential metadata for an Azure Storage Account. The following script contains HCL keywords that weren't explained yet. Don't worry about those for now. The concept of using variables is essential for now.

resource "azurerm_storage_account" "storageacc" {
  name                     = "exports${var.storage_account_name}"
  resource_group_name      = "thh"
  location                 = "${var.storage_account_location}"
  account_tier             = "Standard"
  account_replication_type = "GRS"
}

Execute terraform plan and see how the interpolations construct runtime values.

Outputs in HCL

Every Terraform script has to read data from resources. Data like Connection Strings, IP addresses or DNS names from items that are created as part of the script itself. This can be achieved using so-called outputs in HCL. The definition syntax is quite similar to variable definitions. For smaller projects, my advice is to put all outputs into a single file called all_outputs.tf. A simple output that grabs the primary access key from the Azure Storage Account specified above may look like this:

output "storage_account_access_key" {
  value       = "${azurerm_storage_account.storageacc.primary_access_key}"
  description = "The storage account's primary access key"
  sensitive   = false
}

The value of the output is queried from the Azure Storage Account, once again the resource is referenced by interpolation. To identify the custom resource, the combination of the type azurerm_storage_account and the custom, unique name storageacc is used for identification. When the resource is identified, the exported property is referenced by the name (here primary_access_key).

The official Azure provider documentation is providing a list of all exported attributes. Check the documentation of azurerm_storage_account here.

Besides description, the output scheme defines another important property called sensitive. If the output is marked as sensitive, Terraform won't write the actual value to logs. sensitive is set to false in the definition above for demonstration purpose.

Execute the Terraform script using terraform apply and check the log messages for the storage_account_access_key.

Overrides

As said, all .tf files within a Terraform project are appended together. Overrides behave a bit differently, they're loaded at the end, and their values are merged into existing configurations instead of being simply appended. Overrides are a great solution to change simple properties without actually changing the configuration itself.

Typical scenarios for Overrides are

build servers
temporary modifications

Override files must be named override.tf or end with _override.tf. If multiple Override files are present, they're merged in alphabetical order. For example, consider the following Azure App Service:

resource "azurerm_app_service" "webapi" {
  name    = "sample-api"
}

The name can be modified by defining override.tf like this:

resource "azurerm_app_service" "webapi" {
  name    = "override-sample-api"
}

The Azure Provider

The real power of Terraform is defined by the actual provider that is used. Luckily, the Azure provider is a compelling one. Besides creating, modifying or deleting resources, existing resources (including those, that were not created by Terraform) could be used as a data source, and their values can quickly be brought into every Terraform scripts.

Bevor we're diving deeper into resources and data sources, a new Terraform project must be created, and the Azure provider has to be configured. Create a new folder azure-sample and a new file called main.tf with the following content:

provider "azurerm" {
  version = "=1.22.0"
}

To download the desired provider, you've to execute terraform init in the project's folder. The terraform providers command can be executed in any project to list all providers used in the current project.

Without further configuration, the Azure provider will reuse existing authentication from Azure CLI. The project runs in the security context provided by the local az installation. All modifications are applied to the currently selected Azure Subscription.

You can verify this in Azure CLI using az account list. Terraform uses the default subscription. You can change the subscription in az by executing

az account set --subscription 00000000-0000-0000-0000-000000000000
# replace 00000000-0000-0000-0000-000000000000 with your subscription ID

Authenticating mechanisms offered by the Azure Provider

The Azure provider supports four different kinds of authentication mechanisms. Depending on your security implementation, you've to select the proper mechanism for your needs.

Authenticating to Azure using the Azure CLI
Authenticating to Azure using a Service Principal and a Client Secret
Authenticating to Azure using a Service Principal and a Client Certificate
Authenticating to Azure using Managed Service Identity

Authenticating to Azure using Azure CLI is excellent to get started, however, you should switch to an authentication which is independent from az early.

The other guy on the team may not have a local instance of az or think of the build server. You should not add az as a dependency, except for local development.

Authenticating to Azure using a Service Principal (SP) is more convenient. To configure this kind of authentication, either a combination of ClientId and ClientSecret or -for Service Principal identification by a certificate- the combination of client certificate password and client certificate path is required.

To authenticate to Azure using a Managed Service Identity (MSI), the use_msi variable must be set to true and a msi_endpoint could optionally be specified. Last but not least the actual Azure Environment can be specified on the provider. You can chose between public (default), usgovernment, german or china.

Instead of putting those sensitive data into .tf files either .tfvars files or Environment Variables should be used. The Azure Provider excepts the names of those environment variables to follow a strict schema ARM_{variablename}. (eg.: ARM_ENVIRONMENT or ARM_USE_MSI).

No matter which kind of "authentication mechanism" used, ARM_ENVIRONMENT and ARM_TENANT_ID and ARM_SUBSCRIPTION_ID should always be specified.

To keep things simple, this guide will stick with tokens being acquired by Azure CLI. But environment, tenant and subscription will be pinned by using Environment Variables.

export ARM_ENVIRONMENT=public
export ARM_TENANT_ID=00000000-0000-0000-0000-000000000000
# replace 00000000-0000-0000-0000-000000000000 with your Tenant ID
export ARM_SUBSCRIPTION_ID=11111111-1111-1111-1111-111111111111
# replace 11111111-1111-1111-1111-111111111111 with your Subscription ID

Of course, those export commands are not required if the suggested Azure Subscription matches the current one chosen one in Azure CLI, but it's a good practice and critical to understanding. Especially if Terraform will be executed without human interaction (eg. on the build server).

For further information on how to configure the different authentication mechanisms, check out the official provider documentation.

Your first Azure Environment with Terraform

Having the provider configuration in place, it's time to dig into Azure specific resources and data sources. Everything in Azure belongs to a Resource Group so let's get started with such a Resource Group:

provider "azurerm" {
  version = "=1.22.0"
}

variable "location" {
  type        = "string"
  default     = "westeurope"
  description = "Specify a location see: az account list-locations -o table"
}

variable "tags" {
  type        = "map"
  description = "A list of tags associated to all resources"

  default = {
    maintained_by = "terraform"
  }
}

resource "azurerm_resource_group" "resg" {
  name     = "terraform-group"
  location = "${var.location}"
  tags     = "${var.tags}"
}

So far so good. Verify what Terraform would do in Azure with terraform plan. Before applying it to Azure, some refactorings are required, to ensure our project remains clean and readable. First, all variable should be moved to a dedicated global_variables.tf file.

#global_variables.tf
variable "location" {
  type        = "string"
  default     = "westeurope"
  description = "Specify a location see: az account list-locations -o table"
}

variable "tags" {
  type        = "map"
  description = "A list of tags associated to all resources"

  default = {
    maintained_by = "terraform"
  }
}

Your local main.tf should now look like this:

provider "azurerm" {
  version = "=1.22.0"
}

resource "azurerm_resource_group" "resg" {
  name     = "terraform-group"
  location = "${var.location}"
  tags     = "${var.tags}"
}

Although the tags variable is specified in global_variables.tf, you should always specify critical variables using .tfvars files (keep in mind that those will not go to source control!). Add local.tfvars and provide specify tags as shown below.

tags = {
  author = "Thorsten Hans"
}

To verify, use terraform plan -var-file=local.tfvars now. Terraform should print something matching the following picture:

The tags variable isn't overwritten, the values from default and those from local.tfvars are merged (in case of looking at a map variable). However, if both maps contain the same key, the value from the .tfvars file is used.

Next, add a all_outputs.tf file. This file will query essential, resource-independent data from Azure once resources are applied or modified. For now, the name of the Azure Subscription will be queried and written to the console once the script will be applied.

#all_outputs.tf
data "azurerm_subscription" "current" {}

output "target_azure_subscription" {
  value = "${data.azurerm_subscription.current.display_name}"
}

Let's apply this state to the cloud!

Execute terraform apply -var-file=local.tfvars and confirm the execution plan by answering Terraforms confirmation-question with yes. (You can also prevent Terraform from asking for confirmation by adding the --auto-approve flag). Once finished, Terraform will print the name of the modified Azure Subscription to the console.

Great! But having only a Resource Group being deployed to Azure solves no need. For demonstration purpose, extend the script and deploy an instance of Application Insights. Add the following to main.tf;

resource "azurerm_application_insights" "ai" {
  name                = "terraform-ai"
  resource_group_name = "${azurerm_resource_group.resg.name}"
  location            = "${azurerm_resource_group.resg.location}"
  application_type    = "Web"
  tags                = "${var.tags}"
}

When working with Application Insights, the instrumentation_key is critical. It has to be provided to any resource which should write application-specific logs using Application Insights. Add an output and query the instrumentation_key in all_outputs.tf:

output "instrumentation_key" {
  value = "${azurerm_application_insights.ai.instrumentation_key}"
}

Execute terraform plan -var-file=local.tfvars again and verify, that only one resource will be added. Terraform looks at the currently deployed resources in Azure and verifies that all properties are still matching those described in your script. If so, no action is required for that resource(s).

If the changes look good, go ahead and apply them by invoking terraform apply -var-file=local.tfvars --auto-approve. Finally Terraform should display the following result:

Last, but not least, the actual Azure App Service and the underlying Azure App Service Plan have to be created to complete the sample. Both resources expose a vast of properties, which have to be set depending on the kind of App Service / App Service Plan you want to create. Again, the official documentation helps to spot and to understand all those properties. This sample will create a Linux App Service Plan and a App Service for Containers. For demonstration purpose, a plain NGINX Docker Image will be deployed to the App Service.

To ensure flexibility, several configuration properties should be set by variables. Add a frontend.variables.tf and provide the following content:

variable "appservice_plan_tier" {
  type        = "string"
  default     = "Standard"
  description = "Specify the SKU tier for the app service plan"
}

variable "appservice_plan_size" {
  type        = "string"
  default     = "S1"
  description = "Specify the SKU size for the app service plan"
}

variable "appservice_plan_kind" {
  type        = "string"
  default     = "Linux"
  description = "Specify the kind for the app service plan (Linux, FunctionApp or Windows)"
}

variable "appservice_always_on" {
  type        = "boolean"
  default     = true
  description = "Specify if the app service should be always online"
}

variable "appservice_docker_image" {
  type        = "string"
  default     = "nginx:alpine"
  description = "Specify the Docker image that should be deployed to the app service"
}

Having the variables in place, the actual resource (App Service Plan) goes to main.tf:

resource "azurerm_app_service_plan" "appsvcplan" {
  name                = "terraform-app-svc-plan"
  resource_group_name = "${azurerm_resource_group.resg.name}"
  location            = "${azurerm_resource_group.resg.location}"
  kind                = "${var.appservice_plan_kind}"
  reserved            = true
  tags                = "${var.tags}"

  sku {
    tier = "${var.appservice_plan_tier}"
    size = "${var.appservice_plan_size}"
  }
}

An Azure App Service Plan without an actual App Service is useless. Add the following resource to main.tf.

resource "azurerm_app_service" "appsvc" {
  name                = "terraform-app-linux-app-svc"
  resource_group_name = "${azurerm_resource_group.resg.name}"
  app_service_plan_id = "${azurerm_app_service_plan.appsvcplan.id}"
  location            = "${azurerm_resource_group.resg.location}"
  tags                = "${var.tags}"

  app_settings {
    WEBSITES_ENABLE_APP_SERVICE_STORAGE = false
  }

  site_config {
    always_on        = "${var.appservice_docker_image}"
    linux_fx_version = "DOCKER|${var.appservice_docker_image}"
  }
}

Did you recognize that all required variables were already specified in the previous snippet? If not, verify their existence. To verify our deployment once it has been applied, add another the public DNS name of the Azure App Service as output to global.outputs.tf:

output "appservice_dns_name" {
  value = "${azurerm_app_service.appsvc.default_site_hostname}"
}

Finally, the runtime configuration has to be specified in local.tfvars as shown below.

appservice_plan_tier = "Basic"
appservice_plan_size = "B1"

Execute terraform plan -var-file=local.tfvars to preview the upcoming changes. If everything looks good, apply the changes using terraform apply -var-file=local.tfvars --auto-approve. Terraform will now print the public DNS name as part of all output variables to the console. Open that URL using your favorite browser. You should see the beautiful NGINX Welcome Page as shown below.

Cool!

But did you recognize the values specified in the .tfvars file? Those differ from the default values defined in frontend_variables.tf. Imagine, that you recognize a bigger load as expected on the App Service, so let's scale up to the App Service Plan to Standard and S1 as initially defined as default values. Change local.tfvars to:

tags = {
  author = "Thorsten Hans"
}
appservice_plan_tier = "Standard"
appservice_plan_size = "S1"

Because terraform apply also prints the execution plan before actually modifying the target, you can use terraform apply -var-file=local.tfvars and preview the upcoming changes before they are applied. Now you should see that Terraform will modify exactly one resource - the Azure App Service Plan. It's even more precisely. It tells you exactly which properties it'll change. If it looks good, go ahead and confirm the changes.

That wasn't the only issue in our script. We've also forgotten to set the instrumentation_key on the Azure App Service. To demonstrate Terraform state management, let's set the instrumentation_key on the Azure App Service manually using Azure CLI. You'll use terraform output to query actual information from Azure and finally set the appsetting manually using the following script:

terraform output instrumentation_key
# will print the Instrumentation ID (GUID) to the terminal
# 22222222-2222-2222-2222-222222222222

terraform output appservice_dns_name
# will print the entire DNS name of the web app to the terminal
# terraform-app-linux-app-svc.azurewebsites.net

#!! HERE WE NEED ONLY the SUBDOMAIN

az webapp config appsettings set --resource-group terraform-group
     --name terraform-app-linux-app-svc
     --settings INSTRUMENTATION_KEY=22222222-2222-2222-2222

Having the appsettings updated, move on and execute terraform plan -var-file=local.tfvars. Terraform recognized that an untracked change has happened to the Azure App Service. It suggests to change the appsettings back to the value specified in the Terraform script - which is not existing indeed. We want to keep the App Service as it is, for now, so cancel the script at this point.

No worries you can reuse the output of one resource as variable in another, but that requires to have Modules in your Terraform script, so definitive content for another article on Terraform.

Destroying Terraform Environments

Terraform is also able to destroy entire environments it has created previously. Just execute terraform destroy inside of the project's folder and after reviewing the execution plan -and confirming- Terraform will destroy all resources. Once finished, the Azure Subscription should be clean again.

The Terraform Lifecycle

Now that you've created, modified and destroyed resources in Azure using Terraform, you covered all aspects of the single developer Terraform workflow. Several actions -like creating resources- has been executed quite often and I hope you memorized those basics already. To visualize it again, here the single developer Terraform Lifecycle:

Download the code from GitHub

The entire Terraform project is available on GitHub. Browse through it and use it to grasp even more knowledge on Terraform in an Azure world.

Summary

I hope you enjoyed reading Terraform - The definitive guide for Azure enthusiasts. If you made it through the post, you gained a ton of knowledge about Terraform, and you made some necessary steps with the Azure Provider for Terraform. Having this introduction in place, I'll publish more advanced posts on Terraform and Infrastructure as Code in the upcoming weeks and months.

Infrastructure as Code is something every developer and IT-Pro should care about. Modern applications are way more complex than those five years ago. Developers, teams, and organizations are combining cloud services from different vendors to build the best user experience for their customers. With IaC and Terraform you can manage the jungle of services and make that essential knowledge discoverable and collaborate on it. However, keep in mind that moving a real-world project or perhaps an entire organization on the IaC and Terraform track isn't an easy task!

If you need further assistance on that journey, reach out. I would be thrilled to help.

DEV Community: Thorsten Hans

Run WebAssembly on DigitalOcean Kubernetes with SpinKube - In 4 Easy Steps

What is SpinKube

Prerequisites

1. Provision a Managed Kubernetes Cluster in DigitalOcean

2. Install SpinKube

3. Create a Spin App

4. Deploy the Spin App via OCI compliant registry

Testing the Spin App running on Kubernetes

Cleaning up the Cloud Resources

Conclusion

Building Serverless Apps with Spin and htmx

What is Fermyon Spin

What is htmx

The sample application

Prerequisites

Creating the app skeleton

Preparing the database

Implementing the serverless backend

Implementing the POST endpoint

Implementing the GET endpoint

Implementing the DELETE endpoint

Implementing the Frontend

Adding htmx to the app

Loading and displaying items

Deleting an item

Adding a new item

Running the application locally

Deploying to Fermyon Cloud

Conclusion

Terraform - The definitive guide for Azure enthusiasts

What is Infrastructure as Code (IaC)

What is Terraform

Terraform Providers

The HashiCorp Configuration Language (HCL)

Previewing changes

Setting up Terraform

Terraform Extension for Code

DataTypes in HCL

Booleans

Strings

Lists

Maps

How does a Terraform project look like

Variables in HCL

Referencing Variables

Outputs in HCL

Overrides

The Azure Provider

Authenticating mechanisms offered by the Azure Provider

Your first Azure Environment with Terraform

Destroying Terraform Environments

The Terraform Lifecycle

Download the code from GitHub

Summary

Implementing the `POST` endpoint

Implementing the `GET` endpoint

Implementing the `DELETE` endpoint