Karl Cardenas | Portfolio

Using observability to trace agentic AI workflow decisions

Thu, 04 Sep 2025 20:08:30 -0700

This blog was originally published on Spectro Cloud’s offical blog site. Click here for a direct link to the original blog.

Like many organizations, we here at Spectro Cloud are exploring how Artificial Intelligence (AI) can help our teams be more productive and improve the experience we give our customers.

One clear barrier emerges time and again: agentic development can be challenging to debug and analyze due to the ‘black box’ nature of this technology. In fact, as an industry we struggle to audit the decision-making process of agentic workflows.

But that doesn’t mean we shrug and give up. We hold ourselves to high expectations and standards here at Spectro Cloud!

For us to release an AI capability in our product, we must first have a deep understanding of how the AI is behaving and attempt to answer critical questions such as “Why did it choose that tool? Why did it take that action? What information did it have at that point in time?” and so on. Only through the understanding of behavioral questions can we produce agentic solutions that provide value — and reliability.

To help fellow builders and those pursuing agentic workflows, this blog shares how we’re working to improve our understanding of agentic workflows through observability (O11y), using an example AI application to debug an incorrect output.

Open-source FTW

Commercial platforms exist that provide you with built-in capabilities to ease the development of agentic workflows, which may include observability out of the box.

However, not all agentic development platforms offer the same amount of information, and you sometimes have to stitch things together yourself to understand what’s really happening. One open-source solution we stumbled upon early in our journey to building an understanding of our agentic workflows was Arize Phoenix.

Phoenix is an observability platform focusing on helping builders answer questions related to their AI applications. Getting started is easy: with a single Docker command, you can start and stand up the observability platform.

`1`	`docker run --rm -p 6006:6006 --name phoenix arizephoenix/phoenix:latest`

Once the container is ready, you can access the Phoenix dashboard and view traces. Below is an image of a freshly initialized Phoenix dashboard hosted on localhost port 6006.

Enabling tracing

Depending on your agentic framework (assuming you are using a framework), Phoenix supports many integrations that let you get started in seconds with a few one-liners. Check out its integrations page to view all supported integrations.

If you are not using a framework, you can use the SDK to focus on tracing calls to the LLM. You can also add custom functions to define the start and stop of tracing spans. We prefer the latter, as we can inject richer context into the span data by managing the span lifecycle ourselves, but that’s a bit more advanced.

Using the Smolagents framework as an example, the steps to get started are:

Install the required Python dependencies.

1
2

pip install arize-phoenix-otel && \
pip install openinference-instrumentation-smolagents smolagents

Point to where Phoenix is listening, such as localhost:6006. The code snippet below would go into your LLM application.

1
2

import os
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "http://localhost:6006"

from phoenix.otel import register

tracer_provider = register(
 project_name="my-llm-app", # Default is 'default'
 auto_instrument=True
)

That wraps up the steps to get started with Smolagents. There are many more customization options available and advanced features you can enable. The main point to take away from the example is that enabling tracing can be done very quickly, especially if the integration use case you are using has first-class support.

Making sense of a trace

Curious readers may wonder at this point what a trace looks like. What information can we glean from a trace? To answer this question, we’ll use an example application using smolagents called “palette-package” with access to an example Model Context Protocol (MCP) server called “palette-mcp”. Assume both the LMM application and the MCP server have been configured to use Phoenix. Below is the view from the Phoenix dashboard.

To kick things off, in this example application, assume we fired off a prompt asking “Do I have any active Kubernetes clusters?”. The expected order of operations is for the application to process the query, leverage any tool calls, if available, and return a reply to the user. The MCP server in this example has a single tool function named getActiveClusters. The expectation is that the LLM agent will use the function to call to determine if there are any active clusters in the project.

The application replied with the following answer.

1
2
3

{
    "data": "You do not have any active Kubernetes clusters in your project."
}

This is unexpected, as the correct answer is two active clusters in the project of interest. Where in the process could things have gone wrong? The list can be quite exhaustive for any application, especially if multiple tool function calls are expected. The first set of questions that should be answered are:

Did the tool return incorrect data?
Did the MCP register correctly?
Did the agent parse the data incorrectly from a tool call?
Was something misconfigured, such as the projectId or API key that is used to interact with the Palette API?

Getting the answer to these questions will most likely explain the incorrect result, or so we hope. To start the investigation, the trace from the main application, palette-package, should be reviewed. A single span is displayed upon clicking on the palette-package card from the dashboard.

Clicking on the span row reveals the chain of events, including the tool calls. There is a lot going on here, so to help you follow along, use the annotated image below.

The first annotated item contains the input received, including the prompt injected in every call to support this example application. The first item checked here is to make sure an API key and project ID is included in the request. The tracing data reveals that an API key and project ID were included. So let’s keep looking.

The next item is the nested spans. You can think of this as the order of operations. The application reached out to the MCP server and used a function call. After the function call, the LLM application processed the tool call results and returned the reply. That’s what’s displayed in item number three.

By clicking on the nested span titled MCPAdapterTool, more information about the tooling call is revealed, such as what went into it, and what was outputted. From the image below, it’s evident that the LLM interpreted the results correctly: the tool function returned an empty list. The function call also received the expected number of parameters, an API key, and a project ID. The span also reveals that the MCP server was registered correctly, along with its available functions.

The other important piece of information is that the trace status is a green OK. This means the HTTP request against the Palette API returned a 200 HTTP status code. The MCP server function call was configured to set the trace status using the HTTP return code. This lil trick allows us to get more information from a single span.

Everything uncovered so far leads to us taking a closer look at the input API key and project ID. Upon reviewing the input to the function call, the project ID provided seems a bit off. The ID ends with 2859c6. That does not align with the Palette project of interest. How did the function call get this project ID? Did the LLM make up this project ID? The first view containing the overall input to the application can reveal the answer.

Upon a closer look at the trigger that includes the system prompt, user prompt, and additional context such as AP key and project ID, it’s evident that the application behaved correctly, but received incorrect configurations. The project ID the application received ends with 2859c6 and is not correct. How the incorrect configuration got there is a different story that must be chased up the stack, but from an LLM application perspective, the application can be ruled out as the culprit.

Wrapping up: why observability matters in a ‘black box’ world

Developing agentic applications is challenging due to AI systems’ lack of idempotent nature. As we’ve seen, open-source tools like Phoenix by Arize can enable observability in an AI application that gives us clues about what happens inside the ‘black box’.

Thanks to trace data, we safely ruled out a number of possible causes. The AI application was not at fault when the system produced an incorrect output. While our example here is not as complex as you might find in a real-world deployment, it certainly shows the value of adding observability to AI applications.

If you’re developing agentic applications, we strongly suggest you take the time and effort to set up observability. You can get started in minutes and start developing your AI application with a greater level of confidence. That’s what we do here while researching and investigating many different AI use cases.

Tidbyt Application Development Fundamentals

Tue, 22 Oct 2024 09:49:01 -0700

I recently purchased a Tidbyt second-generation smart display. I was immediately intrigued by the idea of creating custom applications that could present fun messages or images to those who either have to walk by my office or those I interact with in a Zoom call. The first idea that came to mind was to create a clock that rotated through different Spectro Cloud graphics. Why Spectro Cloud? That’s where I work, so having the logo displayed on my Tidbyt would be a fun way to suprise my coworkers during Zoom calls.

Below is a preview of the final product. The clock rotates through different Spectro Cloud graphics every 60 seconds and supports a 24-hour format.

I want to share the lessons I learned along the way. This post will help you create custom Tidbyt applications and share them with the world. There are so many possibilities with Tidbyt, and the official application store already has a wide variety of applications to choose from. Think of this article as a supplemental guide to the official documentation.

Don’t have a Tidbyt? No problem

You don’t need a physical Tidbyt to start building applications. You can use the Pixelet CLI to start a local development server and preview your applications in a web browser.

Where to Start?

The first step is to install Pixelet, the Tidbyt development tool. The Installing Pixlet guide provides detailed instructions on how to install Pixelet.

Once you have Pixelet installed, create a new project by issuing the following command:

`1`	`mkdir my-starter-app && cd my-starter-app && pixlet create my-starter-app`

You will be prompted for an application name, description, and summary. After you provide the information, Pixelet will create a new directory with the project files.

Name (what do you want to call your app?): Sup World
Summary (what's the short and sweet of what this app does?): Demo app
Description (what's the long form of what this app does?): Demo app.
Author (your name or your Github handle): Karl Cardenas

App created at:
	/Users/karlcardenas/projects/tidbyt/my-starter-app/sup_world.star

To start the app, run:
	pixlet serve sup_world.star

For docs, head to:
	https://tidbyt.dev

Pixelet will generate two new files, sup_world.star and manifest.yaml. The sup_world.star file is where you will write your application code, and the manifest.yaml file is where you will define the application metadata.

Below is the content of the sup_world.star and manifest.yaml files.

---
id: sup-world
name: Sup World
summary: Demo app
desc: Demo App.
author: Karl Cardenas

"""
Applet: Sup World
Summary: Demo app
Description: Demo App.
Author: Karl Cardenas
"""

load("render.star", "render")
load("schema.star", "schema")

DEFAULT_WHO = "world"

def main(config):
    who = config.str("who", DEFAULT_WHO)
    message = "Hello, {}!".format(who)
    return render.Root(
        child = render.Text(message),
    )

def get_schema():
    return schema.Schema(
        version = "1",
        fields = [
            schema.Text(
                id = "who",
                name = "Who?",
                desc = "Who to say hello to.",
                icon = "user",
            ),
        ],
    )

The next step is to start the application by running the following command:

`1`	`pixlet serve sup_world.star`

Pixelet will start a local development server on http://localhost:8080. You can preview the application in a web browser by navigating to http://localhost:8080.

Press Ctrl + C to stop the development server. If you are on a Mac, you can press Cmd + C. You will start and stop the development server multiple times throughout the development process.

Core Concepts

Now that you have an application available and understand how to start the development server let’s explore the core concepts of Tidbyt applications.

Programming Language

Tidbyt applications are written in Starlark, which was designed to manage and maintain configuration for the Bazel build system. The syntax may look familiar if you have experience with Python.

Starlark Implementation

Tidbyt used the Go implementation of Starlark.

The best resource I found for understanding Starlark’s capabilities is the Starlark Language Specification document. This document provides a comprehensive overview of the language and its capabilities, such as built-in functions, data types, and control structures. Do keep this document handy as you build your Tidbyt applications. I found myself referencing it multiple times throughout the development process.

Libraries

Tidbyt provides a set of libraries, also called modules, that you can use to build your applications. You can find the list of available modules on the Tidbyt Modules page. I would encourage you to review the modules page and to keep it handy as you build your applications. For example, the load("render.star", "render") render module is the most important module you will use to build your applications. The rendering module provides a set of functions to create and render elements on the Tidbyt display.

Rendering Elements

You will use the render module to create and display elements on the Tidbyt display. All Tidbyt applications must return a Root element that contains the child elements you want to render. The Root element is the root of the element tree and is the parent of all other elements. Only one Root element is allowed per application.

When building my application, I struggled with understanding how to create and render elements. I couldn’t find the reference page for the render module. I later learned that the Tidbyt Wiget page acts as the reference page for the render module. The page provides information on using common elements such as Text, Box, Row, and Column, and many other elements that will help you paint your application on the Tidbyt display.

My best advice to you is to replace the return render.Root function and experiment with different elements and the code snippets provided on the Widget page to observe how the different elements render on the Tidbyt display. The more you experiment, the more you will understand how to make your vision a reality.

1
2
3

    return render.Root(
        child = render.Text(message),
    )

For example, the code below creates a Column element that contains three Box elements. The Box element is a simple element that renders a colored box on the Tidbyt display.

    return render.Root(
        child = render.Column(
            children=[
                render.Box(width=10, height=8, color="#a00"),
                render.Box(width=14, height=6, color="#0a0"),
                render.Box(width=16, height=4, color="#00a"),
            ],
        ),
)

If you do this for all the widgets, you will better understand how to create and render elements on the Tidbyt display.

Learn from others

Check out the Tidbyt Community repository on GitHub. You can learn a lot from the available applications in the apps directory.

Images

You can include images with your application. When images are pre-loaded into the application, they must be base64 encoded. You can convert an image to base64 format using an online tool such as Base64 Image Encoder. Once you have the base64 image, you can use the render.Image element to render the image on the Tidbyt display. The render.Image element has a src property that accepts the base64 image data. You need to import the encoding/base64.star module to decode the base64 image data. The encoding/base64.star module provides a set of functions to encode and decode base64 data. You can use the base64.decode function to decode the base64 image data.

Question

Can I import a file instead of hardcoding the base64 image data?

Unfortunately, you cannot import an image file directly into the Tidbyt application. You must convert the image to base64 format and hardcode the base64 image data in the application code. The alternative is to download the image from a URL and pass it to the render.Image element’s src attribute. Check out the Loveland Ski Area Webcams application for an example of how to download an image from a URL and pass it to the render.Image element.

The code example below is from the Crypto Tracke guide. The majority of the code is omitted for brevity. The code snippet shows how to decode the base64 image data and pass it to the render.Image element. Keep in mind that the image must be either a PNG, GIF, or JPEG image.

load("encoding/base64.star", "base64")

BTC_ICON = base64.decode("""
iVBORw0KGgoAAAANSUhEUgAAABEAAAARCAYAAAA7bUf6AAAAlklEQVQ4T2NkwAH+H2T/jy7FaP+
TEZtyDEG4Zi0TTPXXzoDF0A1DMQRsADbN6MZdO4NiENwQbAbERh1lWLzMmgFGo5iFZBDYEFwuwG
sISCPUIKyGgDRjAyBXYXMNIz5XgDQga8TpLboYgux8DO/AwoUuLiEqTLBFMcmxQ7V0gssgklIsL
AYozjsoBoE45OZi5DRBSnkCAMLhlPBiQGHlAAAAAElFTkSuQmCC
""")

# Later in the code. Pass the image data to the render.Image element.
    return render.Root(
        child = render.Row( 
                children = [
                    render.Image(src=BTC_ICON),
                ],
        )
    )

Size

You need to be mindful of the size of the image you render on the Tidbyt display. The Tidbyt display can display 64x32 pixels. If you render an image larger than 64x32 pixels, the image will be cropped. It may take a few tries to get the image size right. I used the free image editing tools from Pinetools to re-size images down to the correct size for my application.

Pixelate

A common mistake when building a Tidbyt application is assuming you have to pixelate the image before rendering it on the display. The Tidbyt display is already pixelated, so you do not need to pixelate the image before rendering it on the display. If you pixelate the image before rendering it on the display, the results may differ from what you expect. Instead, focus your attention on the size of the image and ensure its quality.

Animations

Tidbyt applications support animations. You can animate elements using the render.Animation element. The animate element provides a set of methods that you can use to manipulate the element’s behavior. The list of available methods is on the Tidbyt Animation page.

Fonts

Tidbyt supports eight different fonts that you can use in your applications. When using the render.Text function, you can set the font property to one of the eight available fonts. Specify the font by its name. For example, to use the 5x8 font, set the font property to 5x8.

render.Text(
    "I am a text element",
    font = "5x8",
    color = "#6a5d9d",
),

Review the Fonts in Pixlet page for more information on the available fonts.

Architecture

Tidbyt has a small section in its documentation where Tidby Architecture is explained. This section is sparse, but it conveys important information such as the display size, caching behavior, secrets management, failure handling, and performance profiling. However, as you comb through the documentation, you will find that the information is scattered throughout the site. Below are some key points to keep in mind as you build your applications.

The default application cycle speed is 15 seconds. This means that Tidbyt will display a different application for most end users every 15 seconds. The user can change this value, but it is important to remember that the default value is 15 seconds. In other words, consider the 15-second cycle when designing your applications. If you have an animation that lasts longer than 15 seconds, the animation will be cut off when the application cycle changes, unless the user has changed the cycle speed, or you use the show_full_animation property to override the user’s configuration. Check out the App cycle speed page to learn more about the application cycle speed.
If you use the random module, keep in mind the random seed is updated every 15 seconds. This means that if you use the random module to generate random numbers, the numbers will change every 15 seconds.
If you use caching, remember that the cache is global and unique per application, not per installation. All Tidbyt applications share the same cache. This means that if you cache a value in your application, then all other instances of your application will use the same cached value. This is important to keep in mind when building applications that rely on caching.
Tidbyt pushes a WebP image file to the display. This image file is sent to the display from their servers. During local development, this is simulated through Pixelet. The image file is generated by your local server, which you can preview in a web browser. If you are creating applications where behavior changes, say a clock application that rotates images every 1 minute. You will not observe the change while the local server is active. The reason that Tidbyt and Pixlet send the image file once and only once to the display. In the real world, the application image file is sent from Tidbyt servers to the device right before the application cycle is about to complete for the current application. So, if you expect a new image to be displayed every 1 minute, you must start and stop the Pixelet server to observe the change. In other words, to get a new image to display in development, you must trigger the change with a server restart. There is extensive discussion about this behavior in the following GitHub issue with potential workarounds.
The screen size is 64x32 pixels.

Schema Configuration

Each Tidbyt application can accept configuration values from the user. The configuration values are set in the Tidbyt application settings and passed to the main function as a config object. The config object will contain any schema fields defined in the schema object.

Using the example code from earlier, a function named get_schema returns a schema object that defines the configuration fields that the user can set in the application settings. The schema object contains a list of fields that the user can set. Each field has an id, name, desc, and icon property. The id property is the unique identifier for the field. The name property is the field’s name displayed in the application settings. The desc property is the description of the field that is displayed in the application settings. The icon property is the icon that is displayed next to the field in the application settings.

def get_schema():
    return schema.Schema(
        version = "1",
        fields = [
            schema.Text(
                id = "who",
                name = "Who?",
                desc = "Who to say hello to.",
                icon = "user",
            ),
        ],
    )

Each schema field can support different types of input. For example, the schema.Text field supports text input, the schema.Toggle field supports a toggle switch, and the schema.Option field supports a dropdown menu. The schema object also supports default values for each field. The default value is the value that is set when the user installs the application. The user can change the value in the application settings.

You can also create more advanced workflows through some of the built-in schema fields. For example, you can trigger an OAuth flow to authenticate the user, get the current geolocation, or use dynamic fields to autogenerate values such as an ID.

For a real-world example, check out the Spectro Cloud clock application schema. Users can choose between the following options:

Use a 12-hour format or 24-hour format.
Enable or disable the clock.

Below is the schema configuration for the Spectro Cloud clock application.

def get_schema():
    return schema.Schema(
        fields = [
            schema.Toggle(
                id = "clock",
                name = "Display Clock",
                desc = "Display the clock",
                icon = "clock",
                default = True,
            ),
            schema.Toggle(
                id = "24hour",
                name = "24 Hour Time",
                icon = "clock",
                desc = "Choose whether to display 12-hour time (off) or 24-hour time (on). Requires Display Clock to be enabled.",
                default = False,
            ),
        ],
        version = "1",
    )

Inside the main function, you can inspect the config object to get the configuration values the user sets.The config object contains the configuration values set by the user and other important metadata, such as the timezone.

The config object has a set of methods that you can use to get the configuration values. For example, you can use the config.get function to get a configuration value by specifying its id. The config.get function returns the configuration value as a string. If you know the field type, you can use specific functions such as config.bool to get a boolean value, or config.str to get a string value.

def main(config):
    who = config.str("who", DEFAULT_WHO)
    message = "Hello, {}!".format(who)
    return render.Root(
        child = render.Text(message),
    )

Publish Application

If you aspire to share your application with the world, you can publish it in the Tidbyt application store. To publish an application, you must fork the Tidbyt Community repository. Once you have the repository forked and cloned to your local machine, you can create a new git branch and add your application to the apps directory.

Tidbyt has detailed instructions on how to publish an application in the Publishing Apps guide. Check out past Pull Requests (PR) from the community repository to get an idea of how to structure your PR and what information to include in the PR description. Feel free to check out the PR for the Spectro Cloud clock application.

Additional Help

If you need additional help, you can reach out to the Tidbyt community on the Tidbyt Discord channel. You can also use the Tidbyt Forum to ask questions and get help from the community.

Closing Thoughts

Building applications for Tidbyt can be a fun and rewarding experience. The possibilities are endless, and the community is constantly developing new and innovative applications. Use the knowledge provided in this article to start building your own applications. Remember to experiment with different elements, review the available modules, and check out the Tidbyt community repository for inspiration.

Spectro Cloud Clock App https://github.com/tidbyt/community/tree/main/apps/spectro_cloud_clock

When docs and a dinosaur Git along: enabling versioning in Docusaurus

Wed, 10 Apr 2024 20:08:30 -0700

This blog was originally published on Spectro Cloud’s offical blog site. Click here for a direct link to the original blog.

Rapid innovation — great for the product, a challenge for docs!

Palette is a powerful, versatile product and it changes fast. We issue major releases multiple times per year and there are always minor changes to things like our supported packs and environments.

This is a good thing: it means we’re keeping pace with the needs of customers like you, and with the innovation of the cloud-native ecosystem.

But it creates a challenge for our documentation , too. Users depend on documentation to navigate the many features of Palette, and to get up to speed with what’s changed in each new version. At the time of this writing, our docs code base has over 435 markdown pages containing product information, and it continues to grow.

We love a challenge, and our docs team is always looking at ways to improve not only the depth and quality of the content on our docs site, but also how easy it is to consume. For example, you may have already read about our Mendable chatbot integration in a previous blog.

Setting out on the content versioning mission

In late July 2023, we started the groundwork for a much more fundamental innovation: enabling content versioning on our documentation site.

Before that, we had to manage all of our documentation data together in a single git branch, clarifying what content applied to what product version in various parts of the documentation.

This was difficult for us to manage, but more importantly it made it challenging for our customers to identify what information pertained to specific product versions. This matters, because we give Palette customers using dedicated or self-hosted instances the freedom to stick with older versions of the product until they’re ready to upgrade.

Our goal was to implement a way for users to select the Palette version they’re using, and have the docs site show only the information relevant to that version.

Versioning is an ‘advanced level’ practice — but for us we knew it was the right approach.

In this blog, we’re going to show you how we implemented content versioning with Docusaurus and using git as the source of truth for all versioned content. We’ll also share our solution and explain it in detail.

If you’re a Palette customer, we hope you’ll find this an interesting behind-the-scenes tour of a feature that’s valuable to you.

And if you or your team are looking at content versioning in your own documentation, we hope this article helps you and your team consider using git as the source of truth for all versioned content versus the default Docusaurus behavior of duplicating folders.

To enhance the value of this article to the open source community, and facilitate your understanding of the concepts, we have included a public GitHub repository with all the content code. This repository serves as a practical tool for you to explore and try out our solution. Simply head over to GitHub, click on the green ‘Use this template’ button, and embark on the technical adventure we are about to share.

PS: Review the README in the repository for additional information, such as the FAQ.

The foundation: docs as code

At Spectro Cloud, we follow a Docs as Code philosophy. This means we use the same tooling to create and maintain our documentation as you would use to create, test, deploy, and maintain an application. By following engineering best practices, we are able to deliver complex documentation reliably.

We already used the best open-source documentation framework, Docusaurus , with our codebase in a git repository. Our vision for enabling content versioning was to use different git branches for each minor product release.

Like any engineering effort, we started our versioning project by defining our requirements, both for our users and for our technical authors:

User requirements

It’s easy to find documentation that applies to a specific version of Palette.
I can easily identify and change my version context.
If I need to, I can always access information about prior Palette versions (updates don’t erase old information).

Author requirements

Enabling versioning doesn’t impact the ability of docs content to scale in the future.
Technical authors can target specific versions when updating, creating, and removing content, with minimal overhead.
The capabilities of the Docusaurus framework should be leveraged versus creating a custom solution.
Enabling versioning does not introduce a user-breaking change, such as URLs not working, etc.

The challenge: default Docusaurus behavior

Docusaurus supports content versioning out of the box. The official documentation does a great job of explaining how to enable the feature and what changes you need to make.

The default behavior is simple and lends itself well to small documentation sites. Basically, whenever you create a new version, Docusaurus creates a copy of your entire content folder and increments the version number. Docusaurus exposes a command that handles this for you.

`1`	`npm run docusaurus docs:version 1.1.0`

It looks something like this:

The challenge with this approach is that in large documentation sites (such as Spectro Cloud’s), it can lead to large code bases that consume a lot of storage space.

The large code base impacts interactions with the versioning control system, especially fresh clones. The latter point is challenging for CI/CD pipeline jobs, as code bases are often cloned, and downloading the code base will take longer.

The other challenge is that when there are multiple content folders (one for each version), the folder tree structure becomes more complex. It’s more likely that an author accidentally works on the wrong version folder.

The other factor to consider when implementing content versioning is how to handle future backport changes. Backporting is when you have to change, either inserting or removing content from a previous version.

Keep in mind that docusarus does not handle backports: each team is responsible for creating and maintaining their own implementation.

Overall, the default Docusarus versioning behavior was not ideal for our team as we felt it did not address our requirements.

Git around the challenges

We quickly identified git as the solution to address both our scaling concerns and the ability to better control what information and content belonged to a specific version of Palette.

The main challenge was that Docusaurus does not integrate with git, at least not out of the box.

However, Docusaurus’s simple design for creating versioning content allowed us to create custom logic that built on the out-of-the-box behavior.

The next issue was orchestrating when and how to invoke the Docusaurus version command.

We decided to develop an orchestration mechanism to enable our vision for using git as the source of truth.

After evaluating a range of options, we settled on a bash script, which we named versions.sh, to act as the orchestrator for this logic and overall versioning solution, and we built out a set of actions that the orchestration solution steps through every time we run the script. We used the following decision matrix to help us determine the ideal solution for our team. Your team might select a different option depending your team composition, environment and so on.

If you’re following along using our sample GitHub repo, you can find the overall logic for the orchestrator in the example repository under the scripts/ folder with the name versions.sh .

Orchestrator bashes into action

The orchestrator’s first step is to fetch all version branches from GitHub. The orchestrator needs to ensure it has the latest changes locally to generate up-to-date versioned content. The script contains some filtering logic to ensure that only version branches are worked on. The orchestrator needs to loop through each version branch, so it must know what all the version branches are.
The second step, and the beginning of the loop logic, is to switch git context into each branch.
Once inside a version branch, the orchestrator issues the `npm run docusaurus` command to generate the version content for the current branch.
That versioned content is moved to a staging area…
…along with the respective versions.json file auto-generated by the Docusaurus command. A quick note about versioned content: for each plugin you create a version for, a sidebars and docs folder is generated. The versions.json file informs Docusaurus how many versions of content are expected.
Before exiting the loop (step seven), the orchestrator removes all the versioned content generated. Otherwise, git will complain about uncommitted changes and prevent the orchestrator from…
…switching to a different git branch.

Once the loop logic iterates through each version branch and the content has been gathered in the staging area, additional logic can be applied, such as merging all generated versions.json files into a single file. The versions.json file is required and expected by Docusaurus when versioning is enabled.

Next we move all the versioned content from the staging area back to the root folder of the Docusaurus project. Moving the collective versioned content back to the project root folder along with the versions.json file allows Docusaurus to actually use the versioned content for a build or preview with a local development server.
The last step of the orchestration flow is to modify the docusarus.config.js file. This file expects a configuration definition for each version found in the versions.json file. Docusaurus will refuse to start or compile if a versions.json file is available and no version definitions are provided to the docusarus.config.js .

Streamlining local editing

An important note on that final step. The behavior we describe challenges local development environments, as versioned content is expected. But we needed our technical authors to be able to work on the site locally, including when no versioned content was available.

Our solution was to configure docusarus.config.js with the following default entry and ensure no version.json is available locally. The content in the current branch, either the default branch or a version branch, is simply displayed as the latest content.

This configuration allows our authors to start the local development server in all branches, including our main branch, without having to generate versioned content. This latter point is important, as working with versioned content can be taxing on the local development environment (especially on large sites like ours) and slow things down.

However, the configuration must look like the following image when versioned content is generated, and a versions.json must be available at the root of the project.

Scripting versus manual updates

We wanted to avoid manually updating the docusarus.config.js configuration file every time a new version is introduced or an old version is archived. We also wanted the ability to modify the version label and change the version banner behavior if needed.

To do this, we created a NodeJs script that traverses and updates the docusarus.config.js file. The script finds the entry for a specific plugin ID, and inserts the values for each version branch.

You can find the nodeJs script under scripts/update_docusarus_config.js

We chose a NodeJs script because it was the more straightforward approach to modifying a JavaScript file, and our CI environment also had NodeJs installed and available, therefore removing the need to install new tooling or dependencies.

To manage the displayed version label and banner, a file named versionsOverride.json holds the label and banner configuration . The file contains a small JSON configuration that the update_docusarus_config.js consumes and takes into account when creating the new docusarus.config.js.

Archiving old versions

For a better user experience, and as recommended by the official Docusaurus documentation , we minimize the number of active documentation versions visible to users, and offload older versions from the main build to our archive domain.

To do this, we use the archiveVersions.json file. It contains a reference to a specific version branch and the external URL hosting the archived content — we use Netlify to host all our archived versions under a different domain.

We leverage the branch deploy feature to deliver this experience. From a docusarus.config.js perspective, we simply instruct Docusaurus to read from archiveVersions.json when defining the version dropdown menu for the docs plugin.

With this approach, we can ensure we only support three active versions at any time. All other previous versions become external URLs pointing to the Netlify archive domain.

Abracadabra… watch the magic happen

Once all the orchestration steps are complete, we can either start a build with the command `npm run build` or preview the versioned content with the command `npm run start`.

Below is a short GIF of the end-to-end flow. Take note of how the orchestration logic switches into different git branches and generates the versioned content. The folders versioned_docs and versioned_sidebars are generated throughout the process for each version branch and moved to the staging area.

Handling backports

The last step of our technical journey covers how we decided to tackle backporting changes. We wanted an experience that was relatively straightforward for our team to understand and use. We envisioned a flow where an author created a Pull Request (PR) and could choose where to backport the changes from the PR.

We investigated a few approaches, including developing our own backport solution. Luckily, we stumbled upon the open-source project The Backport Tool . We use this tool in a GitHub Action, and through it, we can offer our authors the experience of controlling backports through GitHub labels in a PR.

By selecting a label corresponding to a specific version branch, the author can trigger a subsequent PR for the particular version branch after merging the PR. The original PR receives a comment containing the status of each backport PR.

In a merge conflict scenario, the generated status comment will display the reasons for the conflict. These scenarios are handled by git cherry-picking the merged commit into each respective version branch and manually resolving the merge conflict.

If you start the local development server in the example repository, you can find more information about this backport workflow by reviewing the tips and tricks page.

Over to you!

So there you have it: a scripted solution to implement git-based versioned documentation complete with archiving and backporting, already deployed and running great here at Spectro Cloud.

We’re pretty proud of what we’ve built, but we know we’re standing on the shoulders of giants. At Spectro Cloud we’re big fans of open source , and over the past five years, we’ve been honored to contribute to projects like LocalAI, Kairos, Validator and SpectroMate. We dedicate this article as a token of appreciation for the Docusaurus project and its hard-working maintainers. Everything you just read builds on their amazing work.

Now it’s your turn. We hope this article and the associated example repository help spark ideas for how you and your team can tackle your own documentation versions. If you have questions, take a look at the example repository and review the README’s FAQ section.

Do you have experience with Docusaurus and git and want to chat about it? Do you have any ideas or suggestions? We would love to hear from you. Join our Slack community , where we discuss everything from Kubernetes to open-source.

And of course, do take a look at how the version functionality works in practice on our docs site – we hope it makes your experience as a Palette user that bit easier!

SpectroMate - An Open-Source Slack integration with Mendable

Thu, 15 Jun 2023 20:08:30 -0700

Innovating the docs experience

Like most in the cloud-native community, we’re passionate about great documentation. We’ve felt the joy when discovering a clear, thoughtful guide that helps us get up and running with a new project in our homelabs… and we’ve certainly felt the pain that bad technical writing can cause.

So you can understand why our docs team here at Spectro Cloud are always working to improve the experience we offer our users (that’s you). Of course, that includes expanding and refining our content itself — but also innovating how we make that content accessible.

SpectroMate is an open-source project I created while working at Spectro Cloud. SpectroMate is an API server with extended functionality designed for Slack integration in the form of a bot. You can use SpectroMate to handle slash commands, and message actions. This article was originally published in Spectro Cloud’s blog. Click on the Article Link to read the original source.

Ready for an AI docs chatbot?

Given all the buzz about ChatGPT (not least the inspirational work that our open source team has been doing with LocalAI), of course we’ve been investigating how we can apply AI innovation and LLMs to the docs experience.

To that end, we’ve partnered with Mendable.ai, who offer state of the art AI Chat Search technology, which we used to create a chatbot for our product documentation. Once we implement the chatbot on our docs site (it’s in testing right now), you’ll be able to ask it a product question, and get an accurate answer pulled from our knowledgebase.

Having an intelligent chatbot for product documentation is a great feature, but we knew it wasn’t enough.

Some of the heaviest power users of our docs, and the ones helping train and refine the chatbot, are our internal architects and engineers. We noticed that many of the technical questions and discussions they have happen in Slack channels.

Instead of navigating out of Slack and visiting our docs site, wouldn’t it be great if our team members could find the information they need, right there in the chat?

And this is where SpectroMate comes in.

SpectroMate: bringing Mendable (and more) to Slack

SpectroMate is a new application that we’ve built to bring the Mendable chat experience into Slack. Essentially, it’s an API server with extended functionality designed for Slack integration. It comes with out-of-the-box support for Mendable.ai chatbots, but can easily be extended.

We’ve been using SpectroMate internally for several weeks, and it’s running great. Users on our internal company Slack can ask a docs question to the Mendable chatbot just by using the /docs ask command in any Slack channel.

Already SpectroMate has helped us improve and fine-tune the Mendable model based on internal usage feedback, all from the comfort of Slack. This gives us a higher degree of confidence in our language model before opening it up to the general public.

SpectroMate is open source!

We ♥️ OSS. So we’re excited to announce we’ve made SpectroMate open source.

If you want to kick the tires, you can use Terraform to deploy it to our Palette Dev Engine environment in under five minutes by following the Getting Started guide. Just be sure to fill in our form to request access to Palette first!

SpectroMate is available as a standalone binary, or you can use the Docker image to deploy the application to any computing environment. If you prefer to deploy SpectroMate to your own Kubernetes environment, you can do so by following the Kubernetes deployment instructions.

The out-of-the-box support for Mendable will be helpful if you want to follow in our footsteps and expose your documentation as an AI chatbot to internal users or community Slack workspaces.

You can customize SpectroMate by adding new API endpoints, new slash commands, or new functionality for your Slack workspace. Fork the GitHub project and start playing! Of course, we also welcome contributions. SpectroMate is written in Go and is designed to be simple to maintain and expand.

If you want to explore the inner workings of SpectroMate, refer to the technical internals document.

And as always, if you have any questions, concerns, or feedback, join our community Slack channel.

Cloud Cost Questions for Engineering Managers

Sat, 06 Nov 2021 12:45:14 -0700

You have assumed the leadership of a team that is operating in a cloud environment. It’s a new beginning, you are excited about the future (hopefully), the team members, and most of all, the thrill of a new challenge. After the excitement settles down you start asking questions to better understand the work and the team. Among the list of questions you have, you should include questions pertaining to cloud cost and cost optimization.

This article was originally published on Medium. Link to the Medium article can be found here.

In this article, you will find a set of questions that are beneficial for you and your team to further explore. These are questions I have found beneficial in the past and I believe they will be beneficial to you too. Without further ado, let’s dive into it.

Q: Do we have any budget alarms established?

This is a simple question but the answer will reveal a lot of information about the team, the organization, and the emphasis placed on cost management. The ideal answer is “yes”, and depending on the maturity of the team, and the organization you might find out that there are several layers of budget alarms. Sometimes, these budgets are for different services and environments. If you are in the ”yes” camp, give the team kudos 👏

For those of you who find yourself in the “no” camp ⛺️ , don’t despair. Yes, there is a lot of work to do here, but it’s also an opportunity to stand out, and raise the standard. All major cloud providers offer the ability to set budget alarms. There are many ways to use the budget alarms, but the primary reason you want to use alarms is for cost awareness and to change behavior. Yes, behavior change. You want to get you and your team to take a moment and ask themselves “what impact will this change have on the budget”. The alarms help remind the team to act more responsibly from a financial perspective. If there is no set budget, then review the billing information for the past three to six months and identify a baseline/average.

Budgets are not a one-and-done kind of deal. Budgets are a moving goal and should be reviewed often. You want to aim for a goal but the reality is that accurately forecasting cost is difficult and often subject to change due to many external factors. As you and your team develop a good understanding of what the major cost drivers are, you can then start having conversations on how to reduce the expenses. But it all starts with measuring. As the saying goes “What gets measured, get’s done”

Q: Is there a tagging policy in place?

Tagging is important for teams to more accurately understand their cost, but it’s critical at the organizational level to understand where financial resources are being allocated. Let’s break this down further, starting at the team level.

By tagging resources, you and your team can more accurately understand expense reports generated by the cloud provider. Let’s use a real-world example. Assume you and your team have a fleet of virtual machines (VMs). A VM can belong to a different part of the application architecture. Without tagging, how would you identify which part of the architecture is costing X amount of dollars in a given month? Take this example a bit further, assume it’s a multi-tenant environment. If various teams are consuming VMs without tagging, it would be very difficult to understand the cost of each team. You could use a naming convention to identify different teams or parts of your application architecture but that will not help you break down the cost of VMs at the end of the month when you are reviewing the bill. Cloud service costs can be broken down by tags. The ability to break down service costs by tags is why tagging is important from a cost management perspective. The two screenshots below illustrate this. The bottom image showcases how the EC2 cost for the month of August is narrowed down to the resources with the tag 12345.

Screenshot of AWS Cost Explorer

The cost of 12345 in relationship to EC2 utilization

Let’s go back to the fleet of VMs example. By understanding the cost for the different components of the architecture, you and your team can now have a meaningful discussion related to the expenses. Perhaps the cost is justified, or maybe there is room for optimization?

Let’s go up a layer and look at it from an organizational perspective. Similar to an application that is made up of numerous components, the same applies to an organization and the teams that make up the organization. Organizations develop budget plans in order to remain profitable and responsibly manage their expenses. From a cloud consumption perspective, this includes understanding how the teams are utilizing cloud resources. Below are a few questions commonly asked by organizations:

Development costs vs production costs
The total storage cost and growth rate
Fixed cloud costs vs team variable cost (primary infrastructure vs application infrastructure)
Compute resource utilization

Without tagging, it’s difficult to break down costs for different environments. Another reason why tagging is important to organizations is to hold leaders accountable for their team’s actions. Leaders play a critical role in helping the organization meet budget goals. If leaders are not held accountable for the cost their team is incurring then it’s hardly surprising if the organization fails to stay within the planned budget. Tagging allows the organization better understand the cost of each team and how much to budget for future expenses.

If organizations have a good grasp on their cloud expenses and resource utilization, they can start researching the purchase of reserved compute instances or pre-pay for resources and receive a discount. This may sound counterintuitive at first but it can go a long way in helping organization reduce their cost.

Tagging is not a perfect solution, but it goes a long way in helping demystify the cost incurred in public cloud environments. There are more benefits to tagging besides financial reporting. Tagging can be used to help drive automation, labeling data, security, and other meta-data purposes. AWS has an example of tagging categories that can be found here.

Q: How are resources primarily provisioned?

How is your team deploying cloud resources? Are they doing “ClickOps”, meaning they utilize a user interface and click their way through deploying the required infrastructure? Or are they writing everything down, and deploying resources through infrastructure as code (IaC)? This could be Terraform, CloudFormation, ARM Templates, or other IaC flavors.

The preferred behavior is to leverage infrastructure as code and avoid manually deploying resources. Manually deploying resources increase opportunities for mistakes to happen during the deployment process and the cleanup process. Someone could forget to deploy a required resource, assign the required permission, or perhaps assign a value to a required environment variable. It’s also likely that something will be missed during the cleanup process. It would be a shame if expensive resources such a managed Kubernetes clusters, data warehouse clusters, or MapReduce clusters were left running over the weekend not utilized

There are many reasons why teams should leverage infrastructures as code, but that’s outside of the scope of this article. Many of the popular IaC tools help with cost management. Such as Terraform Cloud’s cost estimation and Sentinel policies. There are also free solutions available, such as terraform-cost-estimation, aws estimate-template-cost, infracost, to mention a few.

Terraform Console

Terraform Cloud Estimation feature example The neat aspect of these IaC tools is that you can use them with an open-source tool called Open Policy. Open Policy is a framework that allows administrators to write rules for what is allowed and disallowed to be deployed. This can be used to enforce standards in teams but it can also be used to prevent mismanagement of cloud resources. This greatly helps you as the leader of the team prevent accidents or misconfiguration from being deployed.

Q: Is there automation in place to remove idle resources?

This is an investment that all organizations and teams should invest in. Accidents happen, priorities change, and the potential for resources not being cleaned up can happen to the best of us. A simple automation script that pauses compute instances after a specific time (cron based) is a simple investment that can help reduce unnecessary expenses. Below is a simple example for pausing EC2 instances I’ve used in the past. The script below is executed by an AWS Lambda and triggered by a CloudWatch rule.

import boto3
def lambda_handler(event, context):
    client = boto3.client('ec2')
    # ec2_regions = [region['RegionName'] for region in client.describe_regions()['Regions']]
    ec2_regions = ["us-east-1", "us-east-2", "us-west-1", "us-west-2"]
    for region in ec2_regions:
        ec2 = boto3.resource('ec2',region_name=region)
        instances = ec2.instances.filter(Filters=[{'Name': 'instance-state-name', 'Values': ['running']}])
        RunningInstances = [instance.id for instance in instances]
        for i in RunningInstances:
            stoppingInstances = ec2.instances.stop(i)
            print(stoppingInstances)
        else:
            print("No instances stopped")

However, many more powerful tools can help you with this type of automation. The open-source tool Cloud Custodian is an excellent resource that many organizations and teams use to maintain their cloud environments. The key is to be proactive and address the most likely scenario that could lead to unnecessary expenses.

Closing

In this article, we looked at a few cost-related questions that all engineering managers should ask themselves and their teams operating in cloud environments. The questions discussed in this article are only the beginning of the cost optimization journey. It’s a journey as addressing behavior change and changing habits take time and effort. The work may appear mountainous and intimidating in the beginning. Start small and celebrate the early wins. The early successes will help build confidence and encourage behavior changes. If you enjoyed this topic, drop a comment and share ideas of what you would like to learn more about.

Running Duplicate Batch Jobs in HashiCorp Nomad

Wed, 21 Jul 2021 20:58:51 -0700

Two approaches to injecting variability into your Nomad batch job template without having to modify the template in the future.

This article was originally published in HashiCorp’s blog while I was an employee. Click on the Article Link to learn how to inject variability into Nomad jobs.

Go Lambda Cleanup

Fri, 02 Apr 2021 16:47:42 -0700

If you find yourself authoring several AWS lambdas for a serverless application architecture, you might have encountered this error:

An error occurred: mySweetLambda– Code storage limit exceeded. 
(Service: AWSLambda; Status Code: 400; 
Error Code: CodeStorageExceededException; 
Request ID: 05d3ae68-a7c2-a3e8-948e-41c2739638af).

The first time I encountered this error I wasn’t quite sure what was happening, but after some quick web searches I learned that AWS has a limit on Lambda storage that maxes out at 75Gb.

Additionally, I also learned that AWS retains all the previous versions of all my lambdas. That’s all fine, I should probably go do some “spring cleaning” and remove the unused versions. AWS does expose the functionality to remove former versions through the console. However, in my scenario I had over 500+ versions for some of my older lambdas. Clicking through 500+ versions is not how I want to spend my time. So what options are available? Surely there has to be some better options out there.

TLDR: Visit https://github.com/karl-cardenas-coding/go-lambda-cleanup for simple and easy to use solution.

Delete Function

Automation is your friend!

There are a handful of open source solutions available that I stumbled upon early on in my clean up journey.

clear-lambda-storage (python)
aws-lambda-es-cleanup (Cloudformation)
SAR-Lambda-Janitor (CloudFormation)
Serverless framework prune plugin (plugin)

While these options are all great and incredible useful, something didn’t feel right about this approach. I didn’t want to install python on my system (local/CI-CD) unless I absolutely needed it. I also didn’t like the idea of having to deploy infrastructure just for the purpose of cleaning up old lambda versions.

Ideally, I just want to run a single command that cleans up old lambdas, without having to install a language runtime, and/or requiring to setup additional infrastructure for the sole purpose of cleaning up lambdas. Is there such a solution available? The answer is go-lambda-cleanup!

go-lambda-cleanup

Go-lambda-cleanup is distributed as a single binary and it’s open source. The tool is available for Windows, Mac (Including M1 support), and Linux. No complicated install process, no need for additional infrastructure. Simply issue the command glc clean and the tool will start the clean up process.

Getting Started

Download the binary and install go-lambda-cleanup binary in a directory that is in your system’s PATH. /usr/local/bin is the recommended path for UNIX/LINUX environments.

Confirm glc is installed correctly by issuing the version command. If you encounter and error then this is a good indicator that the binary is not found in the system path.

1
2

$ glc version
go-lambda-cleanup v1.0.8

To start cleaning you must have valid AWS credentials. Go-lambda-cleanup utilizes the default AWS Go SDK credentials provider to find AWS credentials.

The glc clean command will by default retain all $LATEST versions and remove the rest.

`1`	`glc clean -r us-east-1`

If you want to retain $LATEST and the last two versions but remove the remaining versions, simply use the -c flag parameter.

`1`	`glc clean -r us-east-1 -c 2`

There is also a dry run option available if you want to get a preview of an actual execution.

`1`	`glc clean -r us-east-1 -d`

Closing

I encourage you to go checkout go-lambda-cleanup if you have been wanting a simpler solution to conduct AWS lambda cleanup. More details can be found in the project README. Feel free to open op issues if you encounter/observe something odd with the tool!

How to use AWS DynamoDB locally…

Thu, 20 Aug 2020 14:37:18 -0700

Chances are most of us have unique situations for wanting to interact with DynamoDB locally, maybe it’s to develop and test different data models, perhaps it’s to develop programmatic functions to interact with the database, perhaps you want to reduce development expenses, or perhaps you’re just doing research. Regardless of your reasons, I want to help you by showing you how to leverage DynamoDB locally. We will use the following tools.

Medium Link

We will walk through setting up the local environment, generating data, uploading data, interacting with the noSQL Workbench, and some neat tips to keep in mind. So with that being said, let’s dive into into it!

Note: If you get lost, simply visit https://github.com/karl-cardenas-coding/dynamodb-local-example to view the end solution. Also, feel free to fork this template project and use it as a starting point.

Setting up the environment

First thing first, ensure that you have Terraform (> v0.12.0), noSQL Workbench, and localstack ( > v0.11.3) installed and working on your system. If you need help installing these resources checkout the three links below. Due to the abundance of resources for getting started available, I will skip ahead and assume you have them installed.

(Alternative) if you don’t want to use localstack, DynamoDB offers a docker image, you may use this option as well.

Localstack

First thing first, fire up localstack. If you installed it through pip then it’s as easy as issuing the command localstack start . Or if you used the localstack docker image then it’s as simple as docker run localstack/localstack . If everything starts up correctly then you should be seeing something similar to the screenshot below.

Note: localstack has plenty of parameters to pass in during startup. We are taking the defaults which starts majority of the mocked AWS services but there are plenty of other options worth checking out.

WSL2 output through pip installation

Terraform

Terraform is a great solution to automate the deployment of the local DynamoDB environment, along with any other AWS resources required to get the desired test environment created. In this example, we’re actually going to use Terraform to seed the database (more on that latter). However, first we need to setup Terraform to leverage localstack.

All that is needed to leverage Terraform with localstack is to modify the aws provider block.

provider "aws" {
  access_key                  = "mock_access_key"
  region                      = "us-east-1"
  s3_force_path_style         = true
  secret_key                  = "mock_secret_key"
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    dynamodb       = "http://localhost:4566"
  }
}


# When using the DynomoDB local docker image
# provider "aws" {
#   access_key                  = "mock_access_key"
#   region                      = "us-east-1"
#   secret_key                  = "mock_secret_key"
#   skip_credentials_validation = true
#   skip_metadata_api_check     = true
#   skip_requesting_account_id  = true

#   endpoints {
#     dynamodb = "http://localhost:8000"
#   }
# }

If you review the code snippet above you will probably notice how on line 10 we are specifying a code block for endpoints. This is where we essentially point Terraform to localhost and the port that localstack is listening on, for the respective mocked AWS service. I have also added the DynomoDB docker image configuration for those of you who took that approach, just remember to ensure that the container port specified is correct.

In the example project I provided, take a peek at the main.tf file. In the example project, a customer order table is being deployed. In addition, I have a local secondary index and global secondary index.

Let’s deploy this Terraform configuration.

`1`	`terraform init && terraform plan -out="myplan"`

What Terraform plan should reveal

If you get a similar output as the picture above, go ahead and issue the command below

`1`	`terraform apply -auto-approve myplan`

Successful terraform apply output

Let us validate that we actually have a table in localstack. We can leverage the AWS CLI for this. We are expecting a table by the name of shipping-south-america

`1`	`aws dynamodb list-tables --endpoint-url http://localhost:4566`

If you got the following output (see below), then you did everything correctly.

The key thing to remember is when using the AWS CLI with localstack OR the DynamoDB docker image, is to leverage the --endpoint-url parameter.

$ aws dynamodb list-tables --endpoint-url http://localhost:4566
{
    "TableNames": [
        "shipping-south-america"
    ]
}

So we now have a mocked DynamoDB table, great! But it’s no good without data, unless you are only planning on working on putting items into the table. So let’s add mock data.

Adding Data to DynamoDB

When it comes to generating mock data I prefer Mockaroo (free). It makes it super easy to come up with all kinds of mock data and at a high volume, plus they offer free mock API endpoints. Seriously, such a neat resource! But I digress. By leveraging Mockarro, I have generated 50 JSON objects that look similar to this:

{
"orderId": "9109737812",
"customerId": "70-774-5972",
"shipped": "12/4/2019",
"email": "[email protected]",
"address": "50503 Corben Plaza",
"cost": "$97.21"
}

The raw JSON content is in a file named raw-data.json. However, we have a problem. We simply cannot upload JSON objects to DynamoDB, we have to convert the JSON content to DynamoDB JSON (yes, that’s a thing).

DynamoDB expects the JSON to be in the following format.

{
  "orderId": {
    "S": "8397763392"
  },
  "customerId": {
    "S": "92-084-2567"
  },
  "email": {
    "S": "[email protected]"
  },
  "address": {
    "S": "08207 Ronald Regan Parkway"
  },
  "cost": {
    "S": "$23.66"
  }
}

You’re probably thinking, Ooofff. This could be tedious to do for large datasets. Currently, the AWS DynamoDB Console and AWS CLI does not offer the ability to import data from a JSON file. The alternative is using the AWS SDK.

Normally, I would recommend using a simple script that reads in the JSON file and uploads it. I have provided a Go script for those of you that want a working example of using such a script. Feel free to leverage this solution for your own need. Instructions can be found in the README. This is hands down the better approach.

However, if you feel uncomfortable using the provided Go script, or perhaps rather just work with the AWS CLI then you can use the approach I will provide below.

You can convert JSON objects to DynamoDB objects using the free tool, DynamoDB JSON Converter. You will however have to change the data format to conform to the format the AWS CLI expects, take a look at the formatted-data.json file in the static folder. The key is to remember that the table name must be the first property and that every object must be wrapped inside an Item {}. It’s easy to change regular JSON to this format with the help of the DynamoDB JSON Converter tool but it is tedious work. Be aware that using the AWS CLI limits you to 25 objects when using the batch-write-item command. That’s why the Go script provided is a better solution as it has no upload limitation.

The next step is having Terraform upload the data, either through the AWS CLI or through the Go binary. Let’s take a peek at how that is accomplished.

Note: If you are using the example project, make sure you uncomment ONLY one of the null_resources . Pick the solution you prefer but if you go with the Go script make sure to compile the binary (see README for directions).

#############################
# DynamoDB
#############################
resource "aws_dynamodb_table" "main-table" {
  name           = var.table-name
  billing_mode   = "PROVISIONED"
  read_capacity  = 2
  write_capacity = 2
  hash_key       = "orderId"
  range_key      = "customerId"

  stream_enabled   = true
  stream_view_type = "NEW_IMAGE"

  attribute {
    name = "orderId"
    type = "S"
  }

  attribute {
    name = "customerId"
    type = "S"
  }

  attribute {
    name = "shipped"
    type = "S"
  }


  local_secondary_index {
    name            = "lsi-orderId-customerId"
    range_key       = "customerId"
    projection_type = "ALL"
  }

    global_secondary_index {
    name               = "gsi-shipped"
    hash_key           = "orderId"
    range_key          = "shipped"
    write_capacity     = 1
    read_capacity      = 1
    projection_type    = "ALL"
  }


  tags = {
    Name        = "${var.table-name}-${var.environment}"
    Environment = var.environment
  }
}

# ############################
#  Execut AWS CLI script
# ############################
resource "null_resource" "init-db" {

  // This will cause the upload script to only execute when the table changes id (recreate). 
  triggers = {
    new = aws_dynamodb_table.main-table.id
  }
  provisioner "local-exec" {
    command = <<EOT
      aws dynamodb batch-write-item --request-items file://static/formatted-data.json --endpoint-url http://localhost:4566
    EOT
  }
  depends_on = [aws_dynamodb_table.main-table]
}


##########################
# Execut Go binary script
###########################
resource "null_resource" "init-db-go" {
  // This will cause the upload script to only execute when the table changes id (recreate). 
  triggers = {
    new = aws_dynamodb_table.main-table.id
  }
  provisioner "local-exec" {
    command = <<EOT
      ./upload-logic
    EOT
    environment = {
      TABLE_NAME = aws_dynamodb_table.main-table.id
      REGION = var.region
      DYNAMODB_ADDR = var.dynamodb-addr
      JSON_PATH = var.json-file-path
    }
  }
  depends_on = [aws_dynamodb_table.main-table]
}

Let’s upload the data by issuing the commands below.

1
2

terraform init && terraform plan -out="myplan"
terraform apply -auto-approve myplan

Validate that you have data in the table by issuing the following command. Don’t forget to use the table name you provided Terraform.

`1`	`aws dynamodb scan --table-name shipping-south-america --endpoint-url http://localhost:4566`

If you see your data in the console output then you have done everything correctly and can move onto the next step of using the NoSQL WorkBench for DynamoDB 👏.

noSQL WorkBench for DynamoDB

This tool is great for interacting with DynamoDB in a development/test environment. It’s really handy when you are trying to identify the proper data model for the table. It comes with a few example data models out of the box. Use these as a learning tool when learning and/or researching what NoSQL data model to use. There are many reasons why you would want to leverage NoSQL Workbench for DynamoDB, to name a few.

Identifying/Creating Queries
Adding Items
Removing Items
Evaluate Indexes usage (Local and Secondary)
Example code for programmatic function (Java, Python, JavaScript)

However, before we can utilize any of these neat functions we need to point NoSQL Workbench for DynamoDB to our mocked table. So let’s get started.

Open up noSQL and click on “Operation builder” (left-hand side navbar)

Select Operation builder

This will take you to yet another screen. Click on the “DynamoDB local” tab and fill out the information required. You should only have to provide a name for this connection and the local port that the mocked DynamoDB is listening on.

If you are using localstack then it will be port 4566 but if you are using a Docker image then use the container port, usually 8000 . Click on the blue button named “Connect”.

The configuration step for setting up local usage

After clicking on “Connect”, you should be on the screen before the configurations steps. Ensure you see your “localhost” connection and click on the “Open” button.

Opening up the localhost connection

If your local mocked environment is up and running then you should be taken to a screen that has your table information. You will have to click on your table’s name in order to see the table content (see image below).

All of our table data

Voila! There you have all of your data available in a nice and clean user interface. A lot of the AWS Console functionality is available in this tool, such as removing an item, modifying an item, adding an item, scans, query, and more. It’s nice to have the option of conducting manual actions versus having to use the AWS CLI or being forced to leverage a programmatic function (when developing). I won’t go into too much more detail about NoSQL Workbench for DynamoDB but before I wrap up this article I do want to share with you this awesome gem that the tool provides 💎.

SDK Help

When using the AWS DynamoDB SDK, regardless of the language, it takes a bit to learn how to interact with DynamoDB. DynamoDB has its own unique quirks and opinionated interactions when using its API.

It’s for these situations where NoSQL Workbench for DynamoDB is extremely useful. Let’s say you want to create a function that queries DynamoDB with a condition check and filter. We want to know if orderID 6076643781 has been shipped.

Let’s leverage the query functionality of this tool. Click on “Build Operations” — -> “Query”.

The query populated

In the image above I have filled out the required information to identify this information. If I click on the “Execute” button, it will take me back to the table view and present the results of the query. If there are no results then the screen will be blank and a little pop up will notify us of no results found. This is super useful when learning and identifying the access patterns for your database. It also comes in handy when deciding on what type of indexes to leverage.

You might have also noticed that in the image above that there is a “Generate code” button. Click on it! You should be seeing the generated code

Ah yeah, completed code!

Now you have the query logic available to you. All you need to do is pick the language of your choice! This is an amazing time saver but also super handy when learning how to use the DynamoDB SDK and interacting with DynamoDB’s API. This functionality works for all “Build Operations” that the tool provides.

To reset the table view, simply hit the “Scan” button.

There is more to this tool but the last trick is perhaps one of the best functionality that comes out of the box with NoSQL Workbench for DynamoDB.

Clean Up

To clean up, simply use Terraform and provide the command below.

`1`	`terraform destroy -auto-approve`

Stop localstack (Ctrl +C) and/or the Docker container that you spun up for DynamoDB.

That’s a wrap! The three tools combined, localstack, Terraform, and NoSQL Workbench for DynamoDB make up the perfect local DynamoDB development experience. It’s pretty much all you need when interacting with DynamoDB in a local setting. You now don’t have to worry about messing up the team’s development instance or corrupting the data. You now have your very own DynamoDB table that you can use however you want to and it’s free.

Again, feel free to use my template project as a starting point, simply use the template button and get started. All I ask is that you pay it forward by helping someone else out in the future 😉

https://github.com/karl-cardenas-coding/dynamodb-local-example

Thanks for reading!

Using a Community Support Model

Thu, 20 Aug 2020 13:34:00 -0700

It’s tough to find an organization that is not leveraging a public cloud platform. With all the SaaS, PaaS, and IaaS providers out there, chances are you’ve used cloud services in some manner. As public cloud utilization continues to ramp up in many industries (e.g., insurance, financial, business), organizations are encountering a new challenge: how to correctly consume these new platforms and technologies. It’s a workforce challenge more so than it is a technical challenge.

This article was originally published in the State Farm Engineering Blog. Link to the original blog can be found here.

It’s a workforce challenge because, at the end of the day, it comes down to technical education and experience. Organizations with a workforce skilled in cloud technologies will have a smoother cloud consumption experience compared to one lacking a workforce with cloud experience. Every organization is competing for talent - we all want that DevSecOps engineer and/or Cloud Architect that can do it all (CI/CD, Programming, Security, Architecting, Data, Test, etc.) - but truth to be told, those individuals are rare to come by, let alone retain. Ideally, placing these individuals among inexperienced teams would be the best approach. They could act as a mentor and guide colleagues through successful application deployments. However, this option is not really scalable for large enterprises that are starting out their cloud journey. So what is the alternative? The Community Support model!

What is the Community Support model?

At State Farm® our public cloud team embraces and continuously invests in the Community Support model. Our belief is that in order to succeed as an organization and at scale, we have to come together as a community and help one another. A big contributor to this mentality is our organization’s shared values of helping those in need.

State Farm is only three years into its public cloud journey and already has observed positive results from this model.

At State Farm, we define the Community Support model as the following:

The promotion of - and reliance on - knowledge sharing for both failures and successes, so that teams may learn from the past in order to succeed at scale in technical endeavors.

There is a lot packed into this definition, but the main takeaway is that individuals and teams need to help each other by leveraging their expertise and sharing their failures and successes. This not only aids in preventing unnecessary duplication and resource waste (time and money), but it also prevents teams downstream that might find themselves in a similar position from having to start over. Other teams can leverage the lessons learned and reapply architectures and reusable code configurations (more on this later).

This is not a novel concept, as history can attest. The Community Support model provides great results time and again. Groups of individuals are a much more potent force when united.

Some of you might be asking: “Where is your Cloud Center of Excellence (CCoE)?” State Farm has a public cloud platform enablement team that fulfills most of the traditional CCoE duties and responsibilities required to support a platform. However, we don’t believe that reliance on one team to solve all of the technical challenges platform consumers might experience is the best approach. Instead, we leverage the platform team for the following (not limited to):

Platform (Cloud Service Providers) ownership and support

Tackle platform level challenges (technical and non-technical)
Enable shared services
Provide technical patterns
Improve process and reduce friction encountered by product teams
Mitigate risk
Foster a technical community
Provide guidance and technical expertise (limited by team bandwidth)

The last bullet and the text in bold “limited by team bandwidth” is why State Farm is an adopter of the Community Support model. We believe in empowering teams to identify the best technical solution for their needs. By empowering teams to create innovative solutions, and not being prescriptive in terms of architecture, our early adopters have created amazing results. Architectural patterns are provided by the platform enablement team and the community of public cloud platform consumers, and lessons learned from the “boots on the ground” are harnessed and distributed through different mediums such as presentations and wiki entries.

Building the Community

Building and fostering a community is hard work! Some ideas will work, others will fail. The key is to remember that this is a long-term solution and to not dwell on the short-term wins and losses.

As a preface to the discussion below, the above statement highlights the fact that, there is no set path to creating a community. Every organization is different and its culture must be taken into consideration. Allow State Farm to share its journey.

Year One

At State Farm, the public cloud community started out in our internal technical forum (similar to Slack). As the public cloud platform was being stood up, we immediately established a strong presence in various internal State Farm communication channels. This was done by creating public cloud specific forums for technical employees to ask questions. In the early days of this channel, the platform team was the main responder to questions. However, as time progressed and people started to gain experience with the platform, others started to chime in and help answer questions from various platform consumers. We took note of those individuals outside of the platform team that were constantly helping others and being positive role models. In addition, we allowed people to have fun in these channels to incorporate a positive spirit where possible. Taking the time to have fun is important. When you see others outside of your team starting to help on a regular basis, that’s a good indication of the community seed growing.

To celebrate our regular participants, we created a “Builder of the Month” award. Every month the platform team nominates an outstanding community member that was helping other platform consumers. The Builder of the Month’s name is displayed on a banner in the internal public cloud forum. In addition, a thank you note is sent to the nominee’s leadership, with a small monetary award presented to the employee as a bonus. The “thank you” note goes a long way, especially when it’s sent to the receipient’s leadership so that they are aware of their employee’s positive contribution, even if they are not active in the technical forums.

In parallel, as the technical forum community was kicking off, another grassroots effort began under the leadership of a motivated analyst - a certification study group. This study group started out with about five individuals meeting every week to study for an AWS certification. Each member would present on a topic they were studying for, such as EC2, IAM, etc. As people caught word of this study group, others started to join, to the point where it’s now a group composed of 1100+ members.

Year Two

State Farm supported the public cloud enablement team and their public cloud adoption efforts from day one. After witnessing how the public cloud community was supporting each other via a distributed knowledge model, the decision to stand up a new team was made, along with the addition of a technical leader who was passionate in supporting the community. At this point, State Farm had officially acknowledged the Community Support model, which started out as a grassroots effort. Two talented Software Developers were added to this team and assigned the role of Developer Evangelist/Cloud Evangelist. Their primary role is to support the community (technical and non-technical) and address issues encountered by the platform consumers.

Several efforts were kicked off after the official support for the community model:

Community Champions

Those individuals noticed by the platform enablement team for constantly helping others and being positive role models were now officially acknowledged (both leaders and analysts). The formal recognition was announced to a large audience of more than 600+ people during the monthly scheduled public cloud platform showcase event. These individuals are continually engaged for consultation, and are critical to help sustain the community. Their voices also carry weight when raising concerns to the platform enablement team. These community leaders are the key to expanding the Community Support model.

Public Cloud Summits

A State Farm internal mini-conference for public cloud platform consumers within a geographical location, the public cloud summit event lasts for two days and introduces various topics, such as security, data, application, ci/cd, data, community, and infrastructure. The main goal is to share knowledge with one another, but it also allows the platform enablement team to meet with internal platform customers and build relationships. Brain storming sessions and action items to improve the platform, process, and the community, are takeaways from these summits. Only two summits are being targeted a year.

Public Cloud Community Challenges

The Public Cloud Community Challenge is a monthly event hosted by the State Farm public cloud platform enablement team. The goal is to promote community participation and help the community invest in itself. Challenges range from technical to non-technical, with the intention of solving common community experience pain points. Those who earn 1st, 2nd, or 3rd place receive small monetary awards.

Amazing products have resulted from these challenges. To mention a few:

S3 Storage Lifecycle Calculator - A UI tool that helps users understand the cost of S3 and which storage lifecycle class to apply for cost optimization.
Public Cloud CLI - A command line interface tool that removes the burden of configuring common tools used for public cloud work (Terraform, AWS CLI, credentials configuration, etc). This tool reduces the time spent configuring workstations from the upwards of 2hrs down to minutes. The ROI on this solution easily outweighs the small amount invested in the monetary award. It also solved a critical pain point experienced by the platform consumers thus improving the customer experience.
AWS News - A tool that fetches daily updates/releases from AWS and sends notifications to social sites. This allows our platform consumers to stay aware of new functionality.
Training Labs - Labs that platform consumers can execute in training environments to further their technical education with a hands-on approach.
Terraform Module for S3 - A module that simplifies the complexity of deploying S3 with all required tags and lifecycle policies required by platform controls.

Public Cloud Guild

The Public Cloud Guild is for State Farm public cloud platform users that want to dive deeper into technical topics, share development experiences, and provide a certain level of oversight for infrastructure patterns. This is a scheduled monthly event that is open to all employees and that lasts an hour. The time is leveraged to share lessons learned, new architectures, and new tools. Attendance is usually upwards of 250 participants.

Cloud Pains

This is a git repository where platform consumers can open up issues that they want the platform enablement team to investigate/address. This allows the public cloud platform enablement team to prioritize work while remaining transparent with platform consumers. A lot of great discussion occur under the various issues comment sections, which helps the team steer towards an optimal solution.

Lessons Learned

As mentioned earlier, some ideas will work better than others. It’s important to conduct review sessions to identify why something didn’t work, and what different choices could had been made. Here are some lessons learned:

Community Challenges - The community challenges have generated some amazing resources, but despite these successes we are still encountering low participation among our platform consumers. The non-technical challenges have the greatest participation. Having a monthly challenge tied with monetary awards is not sufficient to incentivize enough participation. The Community Challenge might be better used as a tactical tool to address technical challenges, as witnessed by the generated solutions. A reevaluation of the community challenges is currently underway.

Certification Study Group - The certification study group is a success story. The volunteer presentation approach works well and the group does a great job celebrating the success of its members when they pass an exam. In addition, the certification study group now has a mentor/mentee program where a mentor meets with its mentees once a week to help them with their certification exam preparation. The certification study group has received positive praises from State Farm executive leadership.

Changing Culture - If you want to see change you have to start with yourself, eventually others will follow, and before you know it, you have a community. Knowledge sharing practices are still not at the point to where they need to be. The goal is for this to become muscle memory amongst the workforce. As a platform enablement team, it’s our responsibility to ensure that there are channels available for knowledge sharing. Once those channels are present, the challenge shifts to identifying presenters and content. Monitoring the technical forums aids greatly in identifying presenters for the Public Cloud Guild.

Next Steps

We are now entering the third year of the Community Support model. The following efforts are currently underway:

Marketing - Increased focus on raising awareness about the community and the resources generated by it. The following marketing materials were created: community posters outlining resources available, certification study group stickers, community champions stickers, and stickers for those delivering internal public cloud related presentations.

AWS DeepRacer Event - This community event challenges teams to compete against one another using AWS DeepRacer. This event was postponed to a later date due to COVID-19.

Cloud My App - An informal interview style of walking through an architecture that is in production. This is inspired by Amazon’s This is My Architecture.

Public Cloud Resource Website - A digital experience that will act as the starting point for onboarding, but also as a reference point for platform consumers, targeting the following topics: education, patterns, community resources, process guidance and more. The goal is to address the challenges encountered with hundreds of internal wiki pages.

Analytics/Metrics - Efforts are currently underway to better understand the patterns of participation among our community members. This includes gathering metrics for technical forums (visits, comments, views, and replies), page views for community resources, and download counts for community tools. The goal is to generate a mathematical model for calculating ROI pertaining to community efforts.

External Knowledge Sharing - In order to help other organizations that might encounter the same challenges we have tackled in the past, we are also promoting external knowledge sharing. It’s our way of paying it forward and contributing back to the technology community. Recent examples of external knowledge sharing from State Farm include:

TechWell Conference
THINK Conference
DevOps Enterprise Summit
Cloud Foundry Summit
ADDO
HashiConf
Dreamforce
Gitlab Commit Conference
Financial Services Exchange

Closing

The idea of creating a community can be daunting, especially if you look at the mountain of work ahead of you. Our advice is to start small, ignore the mountain, and focus on taking things one step at a time. You, the reader, have the power to start a community. All that is required is for someone to start. We mentioned earlier that if you want to see change, start with yourself. Once you have a follower, the rest will take care of itself (think rolling snowball effect). Try a few things and see what works.

How to Create a Digital Portfolio That Is Free and Serverless

Thu, 30 Jul 2020 19:28:30 -0700

Chances are most of us have stumbled into someone’s digital portfolio. This can range from book authors to IT professionals, it’s pretty universal as everyone can benefit from it. Is it needed, probably not but it does help quite a bit in showcasing your skills and who knows, perhaps it could be the difference between you getting an interview and/or a phone call. Let’s say you decided you want a digital portfolio, you’re probably wondering how to go about getting started? Does it cost money? Is it affordable? Do I have to be a programmer? Do I need to maintain a server? What if I told you can do it all for free, with no programming skills, and virtually zero maintenance. All you need is some patience, a little bit of guidance and some spare time. Sounds pretty neat right? Well if that interest you let’s dive into what it takes to make a digital portfolio.

Medium Link

Note: If you get lost or want to look at the final example code, check out the code respository

Getting Started

In order to make this happen we will use the following pieces of technology.

A domain name (optional)
Your favorite static site framework (we will use Hugo)
Netlify
Github or Gitlab
A text editor It helps it if you are familiar with git beforehand and have git configured. Here is a guide for setting up git with Github, and here is one for Gitlab. There are also numerous videos on Youtube that walks you through how to get started if you are a visual learner.

Next we need to make a decision, do we want a domain name, such as example.com or do want to leverage a generic name that might not be as human friendly? I recommend getting a domain name, plus domain names are not too expensive, about $10–12/yr. You can sacrifice two trips to Starbucks this week, and you’ll already have it paid off ☕️

If you want help in acquiring a domain name read the next section, otherwise skip to the “Install Hugo” section.

PS: If you already have a domain, ensure to change the preferred name servers (NS) to Netlify’s name servers. This is demonstrated in the next section.

Getting a Domain Name

What’s awesome these days is that you can buy a domain name from various providers, and better yet, delegate the management of the domain name to another provider. If you haven’t already, log into Netlify and/or create an account (free). Next, click on domains.

This will take you to a landing page. In this landing page there is a search bar, type the domain name you would like to acquire or transfer if you already own one. After you have come up with a domain name, type it in and Netlify will verify if it already exists. If the domain name is available you will be presented with the option to purchase. Keep in mind that you have to add a payment method before you can purchase the domain.

Go ahead and purchase the domain and take the default settings in the following screens. We will revisit the domains page later for HTTPS.

For those of you that already have a domain and want to transfer it, follow the same process and update the name servers. Below is an example of my personal domain that I purchased through Goolge domains. As you can see below, Netlify has four different name servers. These values need to be added in Google domains, or wherever your domain is registered.

Example of a domain registered through an external provider

Example of the name servers being updated in the external provider

Once you have completed this step it might take few minutes to update. I’ve seen it take as short as 30 seconds to 10 minutes. You can verify this through G Suite toolbox , if everything was done correctly you should see the Netlify name servers in the results field.

Install Hugo

At this point we are ready to start playing with Hugo. If you’re not familiar with Hugo, don’t sweat it, just know that it’s a static site framework that does a lot of heavy lifting for us.

To install Hugo, visit https://gohugo.io/getting-started/installing/ . Installing Hugo can be a bit overwhelming if you don’t come from a technical background, start by reading this section of the installation guide. There is also a pretty handy install YouTube video if you are on a Windows, or a Mac.

Open up command prompt, gitbash, or any terminal tool of your preference. You can verify Hugo installed correctly if the version command responds back with version information.

1
2

hugo version
Hugo Static Site Generator v0.74.2-48565DE6 linux/amd64 BuildDate: 2020-07-17T17:25:56Z

With Hugo installed, let’s go ahead and make a Hugo project. Go to a location on your system where you want the Hugo project stored. This part is important as the command we are about to issue will create a folder structure in the current directory.

The site command requires a name parameter as it will create a folder with that name

`1`	`hugo new site new my-portfolio-example`

We now have a folder titled my-portfolio-example. The next step is to get everything ready for git.

Create a git repository

Assuming you have git installed, let’s go ahead change the directory to the Hugo project. If you’re on Windows you can use gitbash, command prompt, or WSL. If you have not configured git yet go ahead and add your user name and email.

1
2

git config --global user.name "John Doe"
git config --global user.email "[email protected]"

Let’s go ahead and create a repository in Gitlab.com. If you have not created a Gitlab account, go ahead and do so now (free). If you prefer Github, that’s fine too, either one works. The end goal is to create a git project.

Click on New Project

Once you click on “New Project” it will take us to a screen where we will be asked to provide a project name and a description followed by visibility settings. Go ahead and set your visibility to Private. Click on “Create project” once you have your name and description finalized.

The next screen is the home of your project. Because there is no content in this project yet, we are presented with some commands to help us get started. We will use the “Push an existing folder” set of commands.

Note: You will be prompted for username and password if you have not configured Gitlab with an SSH key. Here is a job aid for configuring SSH for Gitlab.com

# Example of the commands and how they apply to my project
cd my-portfolio-example
git init
git remote add origin [email protected]/cardenas88karl/my-portfolio-example
git add -A
git commit -m "Initial commit"
git push -u origin master

Example of the what it looks like after the content is uploaded

The next part is selecting a Hugo theme, Hugo has a strong community with creative individuals that have created copious publicly available themes for all of us to consume and customize to our liking. Oh and majority of them are free 🆓

Pick a website theme

This is where the fun begins, picking a theme for your website. Let’s pick a theme for the portfolio website. Visit https://themes.gohugo.io/.

I really like the hello-friend-ng theme, so I’m gonna go with that one. Go into the theme and click on “Download”, this will take us to its Github location, in other words, where the source code resides. Theme creators will normally populate the README file with lots of valuable information, this is important when it comes to customizing your website and will be frequently referenced.

If we go through the README, the author articulates how to consume the theme, in fact the author gives us two options. To either direct copy of the theme folder into our project OR to consume it as a git sub-module. There are pros and cons to both methods but for ease of use, let’s go with the git sub-module option. Issue the following command to add the theme into our existing Hugo project.

`1`	`git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng`

Now that we have the theme available, let’s change the config.toml and update it so that it picks up the new theme. The easiest way for you get started and start to understand how Hugo works is by replacing the content folder and resources folder with the ones found inside theme/hello-freind-ng/exampleSite. Below are the copy steps.

Replace the content/ folder with the folder theme/hello-friend-ng/exampleSite/content
Replace the resources/ folder with the folder theme/hello-friend-ng/exampleSite/resources
Replace the content of config.toml with what is in the config file found in theme/hello-firend-ng/. Inside the config.toml set the baseUrl = "" .

Once you have this done let’s issue hugo server -D and open up our web browser and type in localhost:1313

Tip: Visit the example repo if you got lost here to see the end result

What you should be seeing upon completing all the steps thus far.

Congratulations if you have made this far! I’m sure you’re wondering how to add content, pictures etc. So let’s dive into the Adding Content section.

Adding Content

At this moment, the only content we have is from the original author of the theme. After all, we did copy the content folder from the exampleSite folder inside the theme. So let’s add a new page to the blog category. In order to do that we will leverage a Hugo command but first let’s stop the server Ctrl + C and open up your code editor.

Let’s issue the command hugo new content/posts/new-car.md. This command creates a new file named new-car.md inside the content/posts/ folder. We are creating the new file in this location because that’s where all blog post articles reside. Also, take note of the file extension .md, this is markdown. If you’re not familiar with markdown take comfort in knowing that it’s a syntax that is incredible simple to learn and use for designing documents.

If you open up new-car.md in your text edition you will see that in comes pre-populated with some content

---
title: "New Car"
date: 2020-07-18T15:20:47-07:00
draft: true
---

This content is derived from the archetype dictated in the theme. Archetypes are pre-configured front matter. The important take away here is that the title is defined here, and that the draft setting is set to true. The draft setting should be set to false once the content is finalized. Otherwise, it will not be generated during the build process.

Let’s add the following content:

---
title: "New Car"
date: 2020-07-18T15:20:47-07:00
draft: false
---

# A car for everyone

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum

### How to buy a Car
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nisi nulla, hendrerit a massa sed, blandit aliquam enim. Suspendisse placerat convallis augue eget convallis. Pellentesque ultrices cursus pretium. Donec aliquet auctor sodales. Donec vel finibus libero, ornare commodo leo. Nullam volutpat vel mauris sit amet aliquet. Etiam ultrices arcu nec dignissim maximus. Vestibulum accumsan tellus sit amet porta mattis. Proin egestas vel dui a egestas. Phasellus semper erat orci, et feugiat dui mollis vitae.

Suspendisse auctor velit tempor felis tincidunt, at semper lacus ultrices. Vivamus ac bibendum velit, eu aliquam mauris. In bibendum, lacus id congue elementum, tortor lectus tempor massa, quis semper enim mauris facilisis elit. Maecenas a nibh maximus, tristique urna nec, venenatis ipsum. Morbi lacus tortor, sagittis vitae dapibus eget, tempus non tortor. Phasellus eros lorem, sagittis sit amet commodo vitae, lacinia sit amet odio. Aliquam erat volutpat. Maecenas tincidunt justo nec ex elementum dictum. Nulla elementum massa tortor, vel luctus lorem condimentum sed. Phasellus et tincidunt diam, at sollicitudin nisi. Fusce quis urna nisl. Curabitur ultrices risus nec hendrerit faucibus. Donec luctus eget ipsum vel rutrum. Mauris non odio enim. Mauris aliquet feugiat metus, quis auctor mi maximus id.

All we are adding is a main heading and some random Latin text (Lorem Ipsum) and a link to a YouTube video using Hugo’s build in short-code for Youtube videos. Hugo has some pretty neat build in capabilities called short-code. I recommend becoming familiar with these to make your life easier.

Let’s change the the draft setting to false (at the top of the newly created page) and boot up our server hugo server -D . You should now be able to view your new content by navigating to the posts tab and click on the new entry titled “New Car”.

What your newly added content should look like!

Let’s assume at this point that you are satisfied with the content and have everything you want out of your theme. Let’s push our content up to our Gitlab repository.

`1`	`git add -A && git commit -m "adding last bit of content before deploment" && git push origin master`

And on that note, let’s jump into Netlify to deploy our application!

For demonstration purposes we will not do any customization but the expectation is that you will customize the theme and content for your individual project. Always visit the theme’s Github repo to learn how to customize the theme.

Deploy your application

In Netlify, go ahead and log in and click on “New Site from Git”

After clicking on “New Site” you will be taken to a screen where you will select the Git provider for your code. If you have followed along and used Gitlab then go ahead and select Gitlab. You will be asked to give Gitlab access to your account and will have to log in. Once that is done you will be presented with a list of all your projects. Go ahead and select your project name, in this example my project is called my-portfolio-example.

The next page allows you pick the git branch and and other related settings to our build process. Go ahead and stick with the defaults and click on “Deploy Site”.

Taking the defaults for Hugo

Clicking on the deploy site will launch the build and deploy process. This is one the main benefits of Netlify. The build and deployment process is automated, taking a lot of the technical heavy lifting of your back. The end result will take you you back to the main landing page but this time you will have a link to your new website. Go ahead and click on the link and visit your first portfolio!

Back to main site but with a link to our site!

Working site hosted in Netlify

Important: If the build fails it could be due to the Hugo version Netlify auto selected. Create a netlify.toml and specify the desired Hugo version. Ideally, you would specify the same version that you have installed locally. You can find the latest Hugo release here. In the example repo you can find an example of a netlify.toml configuration.

1
2

[context.production.environment]
  HUGO_VERSION = "0.74.2"

Adding a custom domain name

As you probably have realized by now is that the url name generated by Netlify is not very user friendly. It probably has some random funny names followed by odd numbers and characters, like this one https://romantic-brown-3b847a.netlify.app/ 😝

This is where a custom domain name comes into play, if you don’t want the auto-generated url then we need to provide a custom domain. If you bought a custom domain earlier and followed the registration steps for domain management in Netlify then keep on reading, otherwise I encourage you to re-visit the “Getting a Domain Name” section earlier in the article.

In the main Netlify page, click on “Domain Settings”. If you added a custom domain earlier then make sure that the the domain(s) are listed and available. In the example below, you can see that my domain name crazykarlcodes.dev is listed and available.

Example domain names

In the file config.toml make sure the the baseUrl setting is pointing to your desired domain name. Example: baseURL = "https://crazykarlcodes.dev/" This is an important step because otherwise you might encounter come content failing to load due to invalid CORS settings. If you need to make the change, simply go back to the code editor and open up the config.toml file. Push your changes up to Gitlab when you are done.

`1`	`git add -A && git commit -m "updated baseURL setting in config.toml" && git push origin master`

The last step is to configure the website for HTTPS traffic. This is to make sure the content is encrypted, otherwise most modern web browser will give the user a scary warning advising them to avoid the website due to lacking encryption. This is a good thing in general but bad for our website so let’s make sure we avoid this situation.

In the same settings page for adding a custom domain, scroll down to the bottom. You should see a heading named “HTTPS”. Click on the button to add a TLS certificate. This will use DNS validation to make sure you own the domain. This is normally a pretty quick process but can sometimes take some time ( > 30 min ). Once the certificate is created, go ahead and visit your website using the custom domain. Another great feature of Netlify is that this process is automated and free. This is normally a highly technical process and often cost money. You can thank Netlify and Let’sEncrypt for making this a free feature.

If you encounter some issues checkout Netlify’s debugging site.

This is only the beginning, at this point you have all the tools available to start customizing the content, look and style of your digital portfolio. Go back and visit the documentation for your selected theme and start learning the many amazing features that Hugo provides out of the box. Go look at other themes and example codes to see how others are using Hugo.

If your theme does not have a feature or perhaps does not meets your requirements then checkout other themes. It’s also possible you might have to customize an existing theme or create your very own Hugo theme. Creating your own Hugo theme is certainly a bit of an advanced topic but if you were able to get to this point then I have no doubt you have it takes to learn Hugo and create your own theme.

I hope you found this useful and wish for you new digital portfolio to bring great new opportunities for you! Feel free to checkout my digital portfolio for inspiration, it may look familiar to what we worked on 😉

Karl Cardenas | Portfolio

Using observability to trace agentic AI workflow decisions

Open-source FTW

Enabling tracing

Making sense of a trace

Wrapping up: why observability matters in a ‘black box’ world

Tidbyt Application Development Fundamentals

Where to Start?

Core Concepts

Programming Language

Libraries

Rendering Elements

Images

Size

Pixelate

Animations

Fonts

Architecture

Schema Configuration

Publish Application

Additional Help

Closing Thoughts

When docs and a dinosaur Git along: enabling versioning in Docusaurus

Rapid innovation — great for the product, a challenge for docs!

Setting out on the content versioning mission

The foundation: docs as code

User requirements

Author requirements

The challenge: default Docusaurus behavior

Git around the challenges

Orchestrator bashes into action

Streamlining local editing

Scripting versus manual updates

Archiving old versions

Abracadabra… watch the magic happen

Handling backports

Over to you!

SpectroMate - An Open-Source Slack integration with Mendable

Innovating the docs experience

Ready for an AI docs chatbot?

SpectroMate: bringing Mendable (and more) to Slack

SpectroMate is open source!

Cloud Cost Questions for Engineering Managers

Q: Do we have any budget alarms established?

Q: Is there a tagging policy in place?

Screenshot of AWS Cost Explorer

The cost of 12345 in relationship to EC2 utilization

Q: How are resources primarily provisioned?

Terraform Console

Q: Is there automation in place to remove idle resources?

Closing

Running Duplicate Batch Jobs in HashiCorp Nomad

Go Lambda Cleanup

Delete Function

Automation is your friend!

go-lambda-cleanup

Getting Started

Closing

How to use AWS DynamoDB locally…

Setting up the environment

Localstack

*WSL2 output through pip installation*

Terraform

**What Terraform plan should reveal**

**Successful terraform apply output**

Adding Data to DynamoDB

noSQL WorkBench for DynamoDB

*Select Operation builder*

*The configuration step for setting up local usage*

*Opening up the localhost connection*

*All of our table data*

SDK Help

*The query populated*

Clean Up

Using a Community Support Model

What is the Community Support model?

Building the Community

Year One

Year Two

Community Champions

WSL2 output through pip installation

What Terraform plan should reveal

Successful terraform apply output

Select Operation builder

The configuration step for setting up local usage

Opening up the localhost connection

All of our table data

The query populated

Example of a domain registered through an external provider

Example of the name servers being updated in the external provider