DEV Community: Khanh Nguyen

Building Calm in Complex Interfaces

Khanh Nguyen — Tue, 22 Sep 2026 03:22:04 +0000

Complex interfaces do not need to feel complicated.

Give every detail a place

The most useful systems create calm through repetition: a small set of spacing rules, clear type roles, and components that behave predictably when the content gets difficult.

The goal is not to remove detail.
The goal is to give every detail a place to land.

I feel the difference most strongly in administrative tools and dashboards.
These products often need to hold a lot of information, but density does not have to mean that every control competes for the first glance.
The hierarchy can tell me what matters now, what I can inspect next, and what is available only when I need it.

That hierarchy starts with language.
Clear headings, useful labels, and consistent status names reduce the amount of translation a person has to do before acting.
Spacing and type then reinforce the same structure so the interface does not depend on color or decoration alone.

Calm is not quiet

I have also learned that calm is not the same as quiet.
A strong warning should be visible, a destructive action should feel different, and a changing value should give me enough feedback to trust what just happened.
The goal is not to flatten every moment into the same tone.
The goal is to make the difference between moments intentional.

Make the next decision easier

When a complex screen feels calm, I can focus on the decision in front of me instead of managing the interface around it.
That is the standard I return to when a system starts accumulating one more panel, one more option, or one more exception.

Working in Public

Khanh Nguyen — Tue, 22 Sep 2026 03:21:33 +0000

Sharing unfinished thinking makes the finished work stronger.

Share the useful context

I do not mean publishing every rough thought or turning the work into a performance.
For me, working in public is a lightweight habit of leaving enough context behind for someone else to understand how the work changed.

Writing down the constraint, the discarded direction, and the reason behind a decision creates a useful record for future collaborators and for the person doing the work.
It also makes my own reasoning more honest because vague instincts become easier to question once they are written down.

Keep the notes small

The most useful notes are often small.
I might share why I chose one layout, what failed during a deployment, or which assumption changed after seeing a real user try the flow.
These notes do not need to sound finished to be valuable.

Build a record over time

The blog is a place to keep those notes alive.
Over time, they become more than a collection of posts.
They become a map of the decisions, tradeoffs, and lessons that would otherwise disappear as soon as the next project begins.

The blog is a place to keep those notes alive.

The Small Details Ship with You

Khanh Nguyen — Tue, 22 Sep 2026 03:21:32 +0000

The small details are not small once they are repeated across a whole product.

Notice what repeats

A one-pixel alignment, a useful empty state, or a button that responds clearly can turn a technically complete interface into a considered one.
The opposite is true as well.
One confusing state repeated across a checkout, a dashboard, and an onboarding flow becomes a steady tax on trust.

I notice these details most when I return to a screen after spending time away from the code.
The implementation tells me what I built, but the interface tells me what the user has to carry in their head.
That distance often reveals a missing loading state, an awkward label, or a layout that only worked because I knew where to look.

Treat craft as a habit

Craft is the habit of noticing those moments before the user has to.
It is not endless polishing or an excuse to delay shipping.
It is the discipline of fixing the small points that will be encountered again and again.

Make the attitude visible

The last ten percent is where the product's attitude becomes visible.
Does it explain itself when something goes wrong?
Does it respect the user's time?
Does it make the next action feel clear?
Those questions are small on a ticket and large in the experience.

Craft is the habit of noticing those moments before the user has to.

Ship the First Draft

Khanh Nguyen — Tue, 22 Sep 2026 03:21:01 +0000

The first version is not a verdict on the idea.

It is a question sent into the real world.

Make the question concrete

Shipping early creates better feedback than polishing in isolation, especially when the work sits at the intersection of product, design, and code.
The first draft gives people something concrete to react to, and concrete reactions are usually more useful than another round of private speculation.

This does not mean shipping carelessly.
I still want the first version to be safe, understandable, and honest about what it can do.
The point is to keep the scope small enough that the team can learn before the assumptions become expensive to change.

Notice the perfectionism loop

I have noticed that perfectionism often disguises itself as responsibility.
It sounds like, "we should make this complete before anyone sees it," but sometimes it is really a way to avoid the uncertainty that comes with feedback.
The draft interrupts that loop.

Let reality answer

After shipping, I look for the gap between what I expected and what people actually do.
That gap is not a failure of the idea.
It is the most valuable material for the next version.

Designing for the In-Between

Khanh Nguyen — Tue, 22 Sep 2026 03:21:00 +0000

Transitions, loading states, and empty moments are part of the product, not gaps around it.

Design the pause

I used to treat these moments as cleanup work for the end of a project.
That usually meant a spinner, a generic empty message, and a transition that technically worked but gave no sense of what was happening.

The in-between is where people decide whether a product feels trustworthy.
If a save takes a moment, the interface should explain that work is happening.
If there is no data yet, the empty state should help someone understand what belongs there and what they can do next.

When these edges receive the same care as the main path, an interface begins to feel calm and considered.
The experience does not become slower or more elaborate; it simply becomes easier to read.

Include the real journey

Now, when I sketch a flow, I include the pause after the action, the first visit before there is data, the failed request, and the return journey after an interruption.
Those are not edge cases to hide from the design.
They are part of the real product.

Keep the Surface Simple

Khanh Nguyen — Tue, 22 Sep 2026 03:20:30 +0000

Every extra control asks someone to spend attention.

Complexity belongs behind the surface

I have learned this most clearly when working on screens that started small and slowly collected exceptions.
Each new toggle felt reasonable on its own, but the combined surface became a quiet negotiation with the user.

The job of a design system is not to hide capability, but to give each decision a clear place and a consistent shape.
That means naming the primary action, moving secondary actions out of the way, and resisting the urge to expose every possible state at once.

Simple surfaces are not empty surfaces.
They are the result of making a lot of decisions before asking the user to make one.

When I remove an option, I try to ask whether I am removing useful power or just removing visual noise.
That distinction matters because good simplicity should make the next step easier, not make the product less capable.

Leave room for focus

I still get this wrong sometimes.
The useful habit is to come back to the screen later, look at it without the context of implementation, and notice where my own attention starts to scatter.

Notes from a Brutalist Portfolio

Khanh Nguyen — Tue, 22 Sep 2026 03:20:28 +0000

A portfolio should make a point before it makes a promise.

Make the visual language clear

For this site, that point is directness: strong contrast, visible structure, and enough visual tension to make the work memorable without hiding it behind decoration.
I wanted the first impression to feel like a clear opinion rather than a neutral template.

The hard borders and oversized type are not there only to look bold.
They create a visible frame around the work, which makes the hierarchy easier to feel and gives each project a stronger place on the page.
The friction is intentional too.
Not every element is softened into a rounded card or animated into view, because a little resistance can make the important parts easier to notice.

Let the work stay visible

The system is intentionally opinionated so the projects can feel more distinct.
That decision comes with a responsibility to keep the interface usable.
Strong contrast still needs readable contrast, movement still needs restraint, and a visual idea still needs to survive on a small screen.

I am still learning where the line is between character and noise.
The useful test is whether the visual language helps someone remember the work and find their way through it.
If the style becomes the only thing they remember, the portfolio has started talking over the projects.

A Better Way to Review

Khanh Nguyen — Tue, 22 Sep 2026 03:19:56 +0000

Good reviews make the work clearer without making the author smaller.

Start with what is visible

I try to separate questions, observations, and decisions so a review can move forward instead of becoming a debate about taste.
That one distinction has changed the tone of my reviews more than any clever checklist.

An observation describes what is visible: the button is hard to find, the error message appears below the fold, or the interaction behaves differently from the rest of the product.
A question opens a door: what happens if this request fails, or could this action be available earlier in the flow?
A decision closes a loop: we will keep this layout, use the existing component, or revisit the problem in a separate task.

When all three are mixed together, feedback can feel like a verdict.
When they are separated, the author can respond to the actual issue instead of trying to decode the reviewer's mood.

Review against the goal

I also try to review the work against its goal, not against my personal taste.
The goal might be clarity, speed, accessibility, or a reliable way to recover from an error.
That gives the conversation something more useful than preference to hold onto.

Make room for honesty

Kindness matters here, but kindness is not the same as avoiding difficult feedback.
The kindest review I can give is specific enough to help someone make the work better and respectful enough to keep the collaboration open.

Accessible by Default

Khanh Nguyen — Tue, 22 Sep 2026 03:19:54 +0000

Accessibility is part of the composition, not a final layer of polish.

Reduce guesswork

Good focus states, meaningful labels, readable contrast, and predictable navigation give more people a clear path through the same experience.
They also make the interface easier for everyone to understand when attention is divided, the room is bright, the connection is slow, or the device is unfamiliar.

I think about accessibility as a series of invitations.
A visible focus state says, "you are here."
A useful label says, "this is what will happen."
A clear error message says, "you can recover from this."
Those details reduce guesswork, which is one of the most expensive forms of friction in an interface.

Keep the character

The work is rarely about choosing between a distinctive visual language and an accessible one.
It is usually about being more deliberate with the language: using contrast as structure, typography as hierarchy, and motion only when it helps someone understand a change.

Check the experience directly

The best implementation is often the one that feels invisible because it simply works.
I still check the details directly with a keyboard, a screen reader, and reduced-motion settings because assumptions are not a substitute for experiencing the interface differently.

The best implementation is often the one that feels invisible because it simply works.

A Cross-Platform Terminal Setup Built on a Shared Mental Model

Khanh Nguyen — Tue, 08 Sep 2026 16:45:22 +0000

I use a Windows laptop at work and a MacBook at home.
I do not need their terminals to behave identically, but I need them to organize my work in the same way.

My work laptop uses WezTerm with PowerShell or Nushell.
My MacBook uses Ghostty with tmux and either zsh or Nushell.
Neovim is my editor on both machines.

Making every shortcut identical would require extra configuration without solving the main problem.
What matters is giving projects, tasks, and commands predictable places.

The tools can differ as long as the workflow remains familiar.

One structure across both machines

I organize my terminal workspace around three levels:

Level	Purpose	Example
Project workspace	Keep related work together	application project
Window or tab	Separate tasks and contexts	editor, Git, server, logs
Pane	Show related commands at the same time	server beside test output

On the Mac, tmux adds a session around this structure.
Each session contains windows, and each window contains one or more panes.
A session can be detached and reattached while its programs continue running.

On Windows, WezTerm handles tabs and panes directly.
Although the tools differ, I can organize both environments using the same hierarchy.

A typical project session on the Mac begins with:

cd path/to/project
tmux new-session -A -s project
nvim .

From there, I can keep the editor in one window, Git commands in another, the development server in a third, and tests or logs in a fourth.

I reserve panes for commands that belong to the same immediate task.
A server and its logs make sense together, while an editor and an unrelated deployment session usually deserve separate windows.

Working rule: Use a window for a different context.
Use a pane when two views need to remain visible together.

Give each tool one clear responsibility

This structure stays manageable because each tool has a focused role:

Ghostty and WezTerm provide the terminal interface.
tmux manages detachable sessions, windows, and panes on the Mac.
PowerShell, Nushell, and zsh provide the command-line environment.
Neovim handles code editing.

These boundaries also make problems easier to diagnose.
The terminal, multiplexer, and shell are separate layers, so a failure in one does not necessarily mean the others are broken.

Understanding which layer owns a behavior is more useful than accumulating fixes across configuration files.

Match actions instead of keystrokes

Switching between operating systems was challenging at first.
The turning point was applying the same principle to shortcuts: keep the actions consistent even when the key sequences differ.

Action	Windows with WezTerm	Mac with tmux
Split right	`Ctrl-Shift-D`	`Ctrl-b`, then `\|`
Split down	`Ctrl-Shift-S`	`Ctrl-b`, then `-`
Move between panes	`Alt-Arrow`	`Ctrl-b`, then `h/j/k/l`
Resize a pane	`Ctrl-Shift-Arrow`	`Ctrl-b`, then `H/J/K/L`
Create a window or tab	`Ctrl-Shift-T`	`Ctrl-b`, then `c`
Close a pane	`Ctrl-Shift-W`	`Ctrl-b`, then `x`
Reload the configuration	`Ctrl-Shift-R`	`Ctrl-b`, then `r`

The physical shortcuts differ, but their purposes remain consistent.
I create a window when I need another task context, split a pane when I need a related view, and resize the layout when it no longer fits the work.

tmux uses a prefix model, so most commands begin with Ctrl-b.
This approach is more dependable than forcing every WezTerm shortcut through Ghostty and into tmux.
Some direct key combinations depend on how the outer terminal encodes and forwards them, which makes exact shortcut parity fragile.

A reliable two-step shortcut is better than a clever shortcut that works with only one combination of terminal, shell, and configuration.

My setup respects the differences between Windows and macOS while giving both environments a familiar structure.
I can move between machines and focus on the work because the editor, server, tests, and logs still have predictable places.

Key takeaway: Standardize the mental model first.
Standardize individual shortcuts only when they remain reliable.

AI Made Coding Faster. Now the Bottleneck Has Moved.

Khanh Nguyen — Tue, 08 Sep 2026 15:41:17 +0000

The code is being produced faster than I can confidently review, validate, and ship it.

Old workflow vs. new workflow

The biggest change in my workflow is not simply that AI writes code faster. It is that my role is gradually moving away from manually implementing every detail and toward designing, orchestrating, reviewing, and validating the overall result.

That sounds like a small shift, but it changes where I spend most of my engineering effort.

Coding is no longer the slowest part

Working with coding agents has changed how I think about development productivity. I can define a task, let an agent explore the codebase, implement the change, add tests, and return a working diff much faster than I could build everything manually.

But implementation is only one stage of software delivery.

flowchart LR
    A[Requirement] --> B[Design] --> C[Implementation] --> D[Review] --> E[Test] --> F[Deploy]

AI can compress the implementation stage dramatically, but review, testing, integration, security, and deployment still have their own limits. When those stages cannot keep up, faster coding does not remove the bottleneck. It simply moves it downstream.

This is also the point Red Hat recently raised in Why faster coding isn't making delivery any faster: generating code and delivering reliable software are not the same thing.

I have started to notice this more clearly in my own workflow. An agent can produce a fairly large change while I am still building the mental model needed to judge whether that change is actually good.

More code is not the same as more productivity

Suppose I used to complete two meaningful changes in a day and AI now helps me produce six. Calling that a 3x productivity increase sounds reasonable at first, but only if the rest of the engineering system can absorb those six changes.

They still need to be understood, reviewed, tested, integrated, and eventually operated in production. If review capacity or CI becomes the constraint, I have not created three times more value. I have created more work waiting to be validated.

This is why metrics such as lines of code, commits, or even pull requests become less useful in an AI-assisted workflow. AI can increase all of them very easily without necessarily improving reliability or delivery speed.

A question I find more useful is:

How quickly can an idea become reliable software in production?

That shifts the focus from output to outcome.

My workflow is shifting from writing to validating

This is probably the biggest change I notice personally.

When I write code manually, I build context as I go. I know why a function exists, why I chose one abstraction over another, and which trade-offs I made along the way.

With an agent, the implementation can arrive before I have built that same mental model.

So instead of spending most of my time asking How should I implement this?, I increasingly find myself asking:

Does this approach fit the architecture?
Did the agent reuse the right abstractions?
Are the tests validating the behavior that actually matters?
Did the change introduce unnecessary coupling?
Is this something I would still want to maintain six months from now?

My workflow is starting to look less like:

flowchart LR
    A[Design] --> B[Write] --> C[Debug] --> D[Review]

and more like:

flowchart LR
    A[Design] --> B[Delegate] --> C[Validate] --> D[Integrate] --> E[Observe]

I do not see this as engineering becoming less important.

I see it as engineering judgment becoming more important than code production itself.

The agent can produce an implementation quickly. I am still responsible for deciding whether that implementation belongs in the system.

Faster agents need stronger guardrails

The more autonomy I give agents, the more obvious another requirement becomes: the repository needs to communicate its rules clearly.

An agent can generate perfectly valid code while still making a poor engineering decision. It might duplicate business logic, bypass an existing abstraction, introduce an unnecessary dependency, cross a package boundary, or create coupling that becomes painful later.

Some of those problems will be caught by tests. Others will not.

That is why I increasingly see things such as AGENTS.md, architecture boundaries, dependency rules, contract tests, static analysis, security checks, and CI/CD validation as part of the agentic development workflow rather than just supporting tooling.

The goal is not to add more process. It is to make predictable engineering constraints machine-verifiable.

If an agent can produce a bad implementation in seconds, I want the system to reject obvious problems just as quickly.

That leaves human attention for the things that still require judgment: architecture, trade-offs, product context, maintainability, and whether we are solving the right problem in the first place.

The interesting part comes after the agent writes the code

A lot of attention today goes toward which coding agent produces the best code or completes a task fastest.

I think that matters, but I am becoming more interested in a different question:

What happens after the implementation is generated?

Can automated checks validate it? Can another agent review the diff? Can CI enforce architectural boundaries? Can security tooling identify risky changes? Can production observability tell us whether the feature actually behaves as expected?

A more mature workflow starts to look like this:

flowchart LR
    A[Human Defines Intent]
    --> B[Agent Implements]
    --> C[Automated Validation]
    --> D[AI + Human Review]
    --> E[CI/CD]
    --> F[Production]
    --> G[Observe & Improve]

This is where I think the larger productivity opportunity is.

Not just making the coding agent faster, but designing an engineering system that can safely absorb the speed the agent creates.

That shift is already changing how I work. I spend less time manually producing every implementation detail and more time designing the approach, orchestrating agents, validating decisions, and improving the system around them.

AI has made writing code faster.

Now the rest of the engineering workflow has to catch up.

Because the goal was never to generate more code.

The goal is to ship better software, with confidence, faster.

Inspired by Red Hat's Why faster coding isn't making delivery any faster and my own experience working with increasingly agentic development workflows.

Deploy Grafana to Azure with Azure CLI : From Local Docker to Durable Dashboards

Khanh Nguyen — Wed, 12 Aug 2026 20:04:12 +0000

Grafana turns data from sources such as PostgreSQL, Prometheus, and Azure Monitor into shared dashboards, charts, and alerts. While it queries that operational data, it also needs to persist its own dashboards, users, alert rules, and data-source configuration.

I usually use IaC for shared Azure environments. For this deployment, I used Azure CLI first to understand and validate each dependency directly: private networking, PostgreSQL persistence, ACR image pulls, managed identity, and Container Apps secrets.

This guide deploys Grafana on Azure Container Apps with Azure Database for PostgreSQL Flexible Server and a pinned image in ACR. By the end, you will have managed HTTPS ingress, private database connectivity, persistent Grafana state, and no registry password in the deployment.

This is a production-minded lab: no latest tag, anonymous access disabled, and no database password baked into the image. After validating the design, capture it in Bicep, Terraform, or your preferred IaC tool for repeatable deployments.

The architecture: separate what changes from what must persist

The service responsibilities are deliberately separate:

Service	Responsibility
Azure Container Apps	Runs Grafana, provides HTTPS ingress, and manages revisions
Azure Database for PostgreSQL	Stores Grafana's users, dashboards, alerting configuration, and settings
ACR	Provides a private, deployable copy of the Grafana image
User-assigned managed identity	Lets Container Apps pull from ACR without registry credentials

Grafana's internal database is different from the reporting database that dashboards query. This distinction is easy to miss: the internal database preserves Grafana itself, while data sources provide the metrics and business data displayed in a dashboard. Give Grafana a dedicated database and role; give dashboards a separate, read-only data-source account where possible.

Before you start: prepare the Azure CLI session

You need an Azure subscription, Docker, and the Azure CLI. The commands use Bash or zsh; use a shell such as Azure Cloud Shell, macOS Terminal, or WSL.

az login
az extension add --name containerapp --upgrade

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights
az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.ContainerRegistry
az provider register --namespace Microsoft.DBforPostgreSQL

Set names that are unique where Azure requires them. Keep secrets out of your shell history and Git repository.

RESOURCE_GROUP=rg-grafana-dev
LOCATION=canadacentral

VNET_NAME=vnet-grafana-dev
ACA_SUBNET=snet-containerapps
POSTGRES_SUBNET=snet-postgres
PRIVATE_DNS_ZONE=grafana.private.postgres.database.azure.com

POSTGRES_SERVER=pg-grafana-dev
POSTGRES_ADMIN=pgadmin
GRAFANA_DB=grafana
GRAFANA_DB_USER=grafana_app

ACR_NAME=<globally-unique-acr-name>
IDENTITY_NAME=id-grafana-acr-pull
ACA_ENV=cae-grafana-dev
APP_NAME=grafana

# Pin the version that you tested. Do not deploy :latest.
GRAFANA_VERSION=13.1.3

Collect secret values interactively. Replace these with Azure Key Vault references for a shared or production environment.

read -rsp "PostgreSQL admin password: " POSTGRES_ADMIN_PASSWORD; echo
read -rsp "Grafana database password: " GRAFANA_DB_PASSWORD; echo
read -rsp "Grafana admin password: " GRAFANA_ADMIN_PASSWORD; echo
GRAFANA_SECRET_KEY="$(openssl rand -base64 48)"

The server name, ACR name, and PostgreSQL administrator shown above are examples. Do not reuse the sample passwords or enable anonymous access from a local experiment.

Optional: validate Grafana locally

This optional check proves the image and database configuration before Azure resources are created. If PostgreSQL runs on your host, Docker Desktop exposes it as host.docker.internal.

Create a local-only .env file. Never commit it.

GF_DATABASE_TYPE=postgres
GF_DATABASE_HOST=host.docker.internal:5432
GF_DATABASE_NAME=grafana
GF_DATABASE_USER=grafana_app
GF_DATABASE_PASSWORD=replace-me
GF_DATABASE_SSL_MODE=disable
GF_SECURITY_ADMIN_PASSWORD=replace-me
GF_SECURITY_SECRET_KEY=replace-with-a-long-random-value
GF_AUTH_ANONYMOUS_ENABLED=false
GF_PANELS_DISABLE_SANITIZE_HTML=false

Run the pinned image and check its health endpoint:

docker pull "grafana/grafana:${GRAFANA_VERSION}"
docker run --detach --name grafana --publish 3000:3000 \
  --env-file .env "grafana/grafana:${GRAFANA_VERSION}"

curl --fail http://localhost:3000/api/health
docker logs grafana

On Linux Docker Engine, add --add-host=host.docker.internal:host-gateway if needed. This hostname is local-only; Azure uses the PostgreSQL server FQDN.

1. Give Grafana durable, private state

Create the resource group, VNet, and two dedicated subnets. The Container Apps environment requires its own subnet. PostgreSQL Flexible Server requires a separate subnet delegated to Microsoft.DBforPostgreSQL/flexibleServers.

az group create --name "$RESOURCE_GROUP" --location "$LOCATION"

az network vnet create \
  --resource-group "$RESOURCE_GROUP" \
  --name "$VNET_NAME" \
  --location "$LOCATION" \
  --address-prefixes 10.0.0.0/16

az network vnet subnet create \
  --resource-group "$RESOURCE_GROUP" --vnet-name "$VNET_NAME" \
  --name "$ACA_SUBNET" --address-prefixes 10.0.0.0/21 \
  --delegations Microsoft.App/environments

az network vnet subnet create \
  --resource-group "$RESOURCE_GROUP" --vnet-name "$VNET_NAME" \
  --name "$POSTGRES_SUBNET" --address-prefixes 10.0.8.0/24 \
  --delegations Microsoft.DBforPostgreSQL/flexibleServers

Create and link the private DNS zone. The link allows workloads in the VNet to resolve the database server to its private address.

az network private-dns zone create \
  --resource-group "$RESOURCE_GROUP" --name "$PRIVATE_DNS_ZONE"

az network private-dns link vnet create \
  --resource-group "$RESOURCE_GROUP" --zone-name "$PRIVATE_DNS_ZONE" \
  --name grafana-vnet-link --virtual-network "$VNET_NAME" \
  --registration-enabled false

PRIVATE_DNS_ZONE_ID=$(az network private-dns zone show \
  --resource-group "$RESOURCE_GROUP" --name "$PRIVATE_DNS_ZONE" \
  --query id --output tsv)

Now create PostgreSQL and the Grafana database. PostgreSQL 18 is used here because it is currently supported by Flexible Server; choose a supported version approved by your organization.

az postgres flexible-server create \
  --resource-group "$RESOURCE_GROUP" \
  --name "$POSTGRES_SERVER" --location "$LOCATION" \
  --admin-user "$POSTGRES_ADMIN" --admin-password "$POSTGRES_ADMIN_PASSWORD" \
  --version 18 --tier Burstable --sku-name Standard_B1ms --storage-size 32 \
  --vnet "$VNET_NAME" --subnet "$POSTGRES_SUBNET" \
  --private-dns-zone "$PRIVATE_DNS_ZONE_ID"

az postgres flexible-server db create \
  --resource-group "$RESOURCE_GROUP" --server-name "$POSTGRES_SERVER" \
  --name "$GRAFANA_DB"

POSTGRES_FQDN=$(az postgres flexible-server show \
  --resource-group "$RESOURCE_GROUP" --name "$POSTGRES_SERVER" \
  --query fullyQualifiedDomainName --output tsv)

Create a least-privileged Grafana role

For a private database, run the following from a trusted machine that has network access to the VNet, such as a jump host. It creates an application role and makes it owner of the Grafana database, which lets Grafana run its own schema migrations without using the server administrator at runtime.

psql "host=$POSTGRES_FQDN port=5432 dbname=postgres user=$POSTGRES_ADMIN sslmode=require" \
  -v ON_ERROR_STOP=1 \
  -v db_name="$GRAFANA_DB" \
  -v db_user="$GRAFANA_DB_USER" \
  -v grafana_password="$GRAFANA_DB_PASSWORD" <<'SQL'
SELECT format('CREATE ROLE %I LOGIN PASSWORD %L', :'db_user', :'grafana_password') \gexec
SELECT format('ALTER DATABASE %I OWNER TO %I', :'db_name', :'db_user') \gexec
SQL

The FQDN is read from the provisioned server instead of assumed. In a production environment, manage this database setup through a reviewed migration or infrastructure workflow instead of typing credentials into an interactive terminal.

2. Prepare a private image and passwordless pull access

ACR can import the public image directly, so your deployment does not depend on Docker Hub at runtime.

az acr create --resource-group "$RESOURCE_GROUP" --name "$ACR_NAME" \
  --location "$LOCATION" --sku Basic --role-assignment-mode rbac

# Required for managed-identity pulls by Azure Container Apps.
az acr config authentication-as-arm update --registry "$ACR_NAME" --status enabled

ACR_LOGIN_SERVER=$(az acr show --resource-group "$RESOURCE_GROUP" --name "$ACR_NAME" \
  --query loginServer --output tsv)

az acr import --name "$ACR_NAME" \
  --source "docker.io/grafana/grafana:${GRAFANA_VERSION}" \
  --image "grafana:${GRAFANA_VERSION}"

Pinning 13.1.3 avoids the ambiguity of latest. Tags can still be moved, so for an immutable production release, record and deploy the imported image digest. When you upgrade, test the new version, import it, and deploy it as a new Container Apps revision.

Create a user-assigned managed identity and grant it pull-only access to this registry.

az identity create --resource-group "$RESOURCE_GROUP" \
  --name "$IDENTITY_NAME" --location "$LOCATION"

IDENTITY_ID=$(az identity show --resource-group "$RESOURCE_GROUP" --name "$IDENTITY_NAME" \
  --query id --output tsv)
IDENTITY_PRINCIPAL_ID=$(az identity show --resource-group "$RESOURCE_GROUP" --name "$IDENTITY_NAME" \
  --query principalId --output tsv)
ACR_ID=$(az acr show --resource-group "$RESOURCE_GROUP" --name "$ACR_NAME" --query id --output tsv)

az role assignment create \
  --assignee-object-id "$IDENTITY_PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role AcrPull --scope "$ACR_ID"

If your registry uses the newer RBAC + ABAC repository-permission mode, use Container Registry Repository Reader instead of AcrPull, ideally scoped to the grafana repository.

3. Run Grafana with secrets outside the image

Retrieve the Container Apps subnet ID, then attach it when you create the environment.

ACA_SUBNET_ID=$(az network vnet subnet show \
  --resource-group "$RESOURCE_GROUP" --vnet-name "$VNET_NAME" --name "$ACA_SUBNET" \
  --query id --output tsv)

az containerapp env create \
  --resource-group "$RESOURCE_GROUP" --name "$ACA_ENV" --location "$LOCATION" \
  --infrastructure-subnet-resource-id "$ACA_SUBNET_ID"

Create the app with external HTTPS ingress. Secrets are stored by Container Apps and referenced with secretref:. They are not image labels, plain environment-variable values in source control, or ACR credentials. This lab passes secret values through the CLI; use Key Vault references for production to avoid exposing secret values to the local process environment.

az containerapp create \
  --resource-group "$RESOURCE_GROUP" --name "$APP_NAME" --environment "$ACA_ENV" \
  --image "${ACR_LOGIN_SERVER}/grafana:${GRAFANA_VERSION}" \
  --user-assigned "$IDENTITY_ID" \
  --registry-server "$ACR_LOGIN_SERVER" --registry-identity "$IDENTITY_ID" \
  --ingress external --target-port 3000 --transport auto \
  --cpu 0.5 --memory 1Gi --min-replicas 1 --max-replicas 1 \
  --secrets \
    grafana-db-password="$GRAFANA_DB_PASSWORD" \
    grafana-admin-password="$GRAFANA_ADMIN_PASSWORD" \
    grafana-secret-key="$GRAFANA_SECRET_KEY" \
  --env-vars \
    GF_DATABASE_TYPE=postgres \
    "GF_DATABASE_HOST=${POSTGRES_FQDN}:5432" \
    "GF_DATABASE_NAME=${GRAFANA_DB}" \
    "GF_DATABASE_USER=${GRAFANA_DB_USER}" \
    GF_DATABASE_PASSWORD=secretref:grafana-db-password \
    GF_DATABASE_SSL_MODE=require \
    GF_SECURITY_ADMIN_USER=admin \
    GF_SECURITY_ADMIN_PASSWORD=secretref:grafana-admin-password \
    GF_SECURITY_SECRET_KEY=secretref:grafana-secret-key \
    GF_AUTH_ANONYMOUS_ENABLED=false \
    GF_PANELS_DISABLE_SANITIZE_HTML=false

The app is intentionally fixed at one replica. Grafana's application state lives in PostgreSQL, but a multi-replica Grafana design still needs deliberate consideration for plugins, sessions, provisioning, alerting, and load balancing. Start with one replica; scale only after validating those behaviours for your Grafana version and plugins.

4. Confirm the deployment and persistence

Retrieve the endpoint and open it in a browser:

GRAFANA_FQDN=$(az containerapp show --resource-group "$RESOURCE_GROUP" --name "$APP_NAME" \
  --query properties.configuration.ingress.fqdn --output tsv)
echo "https://${GRAFANA_FQDN}"

Sign in with admin and the password supplied as GRAFANA_ADMIN_PASSWORD on Grafana's first start. Grafana applies GF_SECURITY_ADMIN_PASSWORD only when it creates the initial admin user; later changes require Grafana's supported password-management path. If the revision does not become healthy, tail the container logs:

az containerapp logs show --resource-group "$RESOURCE_GROUP" \
  --name "$APP_NAME" --type console --follow

The most common failures are straightforward:

Symptom	Likely cause	First check
Image pull fails	Identity role has not propagated or has the wrong ACR role	Verify the role assignment and wait briefly before retrying
`no such host` / DB connection fails	Private DNS zone is not linked or the FQDN is wrong	Confirm the zone link and use the server's Azure FQDN
TLS or authentication failure	Database SSL or credentials are incorrect	Keep `GF_DATABASE_SSL_MODE=require` and rotate/reapply the secret
Grafana starts but settings disappear	Grafana is using SQLite or the wrong database	Check `GF_DATABASE_*` variables and startup logs

For a quick persistence check, create a throwaway dashboard, trigger a new Container Apps revision with the same image, and confirm that the dashboard remains after the revision becomes active. If it disappears, stop and fix the database configuration before inviting users.

Production next steps

The CLI workflow makes the Azure relationships visible. Before using it for a shared production environment, codify the deployment as IaC and add:

Azure Key Vault references and a secret-rotation process.
Microsoft Entra ID, a custom domain, and restricted ingress or a WAF.
PostgreSQL backups, a restore test, and a production-appropriate compute tier. Consider verify-full for the Grafana-to-PostgreSQL TLS connection after validating the container's CA trust.
Diagnostics and alerts for revision failures, database capacity, and authentication issues.
Versioned Grafana provisioning, plugin governance, and tested image upgrades.

Clean up

For a disposable lab, delete the resource group after confirming it contains no shared resources:

az group delete --name "$RESOURCE_GROUP" --yes --no-wait

Deletion stops the ongoing costs for resources in that group. Check your subscription afterward for any separately scoped diagnostics, backups, or retained resources you intentionally created.