Forem: Tosin Akinosho

Stop Using CI Scripts to Validate Jupyter Notebooks. Use a Kubernetes Operator Instead.

Tosin Akinosho — Wed, 25 Mar 2026 13:00:57 +0000

jupyter nbconvert --execute tells you the notebook ran. It doesn't tell you:

Whether it ran with the right GPU, memory limits, or node type
Whether the secrets it needs are actually accessible
Whether the model endpoint it calls is returning correct predictions
Whether cell outputs regressed from last week's golden baseline

That gap is why notebooks keep breaking in production despite green CI. The Jupyter Notebook Validator Operator closes it by running validation inside Kubernetes — same environment, same resources, same model endpoints as production.

Quick Start

# Clone and install CRDs
git clone https://github.com/tosin2013/jupyter-notebook-validator-operator.git
cd jupyter-notebook-validator-operator
make deploy IMG=quay.io/tosin2013/jupyter-notebook-validator-operator:latest

# Verify the controller is running
kubectl get pods -n jupyter-notebook-validator-operator-system

Then submit a validation job:

apiVersion: mlops.mlops.dev/v1alpha1
kind: NotebookValidationJob
metadata:
  name: my-notebook-validation
  namespace: mlops-staging
spec:
  notebook:
    git:
      url: "https://github.com/your-org/ml-models"
      ref: "main"
      path: "notebooks/inference.ipynb"
  podConfig:
    containerImage: "quay.io/jupyter/scipy-notebook:latest"
    resources:
      limits:
        memory: "8Gi"
  validation:
    goldenNotebook:
      enabled: true

kubectl apply -f validation-job.yaml
kubectl get notebookvalidationjob my-notebook-validation -w

How It Works

When you submit a NotebookValidationJob, the controller:

Clones your repo into an ephemeral volume (no manual file staging)
Schedules a validation pod with your exact resource spec — GPU nodes, memory limits, node selectors
Executes the notebook via Papermill — cell-by-cell, full output capture
Diffs outputs against the golden baseline (catches silent regressions)
Calls your model serving endpoint and validates predictions
Writes results back to the CR status — queryable with kubectl, Prometheus metrics included
Pod terminates

No persistent services. No management overhead.

Model-Aware Validation

💡 This is the differentiator. Most validators check for exceptions. This checks whether your model is actually behaving correctly.

Connect a validation job directly to your serving infrastructure:

validation:
  goldenNotebook:
    enabled: true
  modelEndpoints:
    - name: "fraud-model"
      type: "kserve"
      url: "http://fraud-model.kserve-inference.svc.cluster.local/v1/models/fraud-model:predict"

Supported serving platforms: KServe, OpenShift AI, vLLM, TorchServe, TensorFlow Serving, Triton Inference Server, Ray Serve, Seldon, BentoML.

Authentication via Kubernetes Secrets, External Secrets Operator, or HashiCorp Vault — no plaintext credentials in notebooks.

GPU Workloads

For GPU-dependent notebooks, set the resource limits and the scheduler handles the rest:

podConfig:
  containerImage: "quay.io/jupyter/pytorch-notebook:cuda12-latest"
  resources:
    limits:
      memory: "32Gi"
      nvidia.com/gpu: "1"
  nodeSelector:
    nvidia.com/gpu.product: "A100-SXM4-80GB"

The validation pod lands on a GPU node. Your CI runner doesn't need CUDA anywhere near it.

Debugging Failed Validations

When a job fails, check the CR status first:

kubectl describe notebookvalidationjob my-notebook-validation -n mlops-staging

The status.conditions block will show where it failed — clone, execution, golden diff, or model endpoint check.

For deeper inspection, grab the validation pod logs before they terminate (or increase the TTL in spec):

# Get the pod name from the CR status
kubectl logs -n mlops-staging <validation-pod-name> -c notebook-executor

💡 Tip: If the model endpoint check fails but execution passes, check your Kubernetes Secret first. The operator surfaces auth errors in the CR status under modelValidation.error.

Security

RBAC with minimal required permissions — controller only has the API access it needs
Pod Security Standards compliant validation pods
External Secrets Operator integration for secret rotation
Resource quotas to prevent runaway notebooks consuming cluster capacity
Runs safely in multi-tenant clusters without granting data scientists cluster-admin

Try It

⭐ Star the repo: github.com/tosin2013/jupyter-notebook-validator-operator

This is v0.1.0 — early days. If you're running notebooks in production and have opinions on the CRD design, serving platform integrations, or validation patterns, open an issue or drop a comment below.

Drop a ❤️ or 🦄 if this was useful — helps more platform engineers find it.

Escaping the "Blind Phase": How to Debug OpenShift 4 LDAP & Active Directory Logins

Tosin Akinosho — Fri, 13 Mar 2026 16:15:45 +0000

If you manage an OpenShift 4 cluster, you’ve likely stared down this exact scenario: A user pings you saying they can’t log into the web console. You confidently pull up the logs for the oauth-openshift pods, fully expecting to see a typo in a password or an expired LDAP bind account.

Instead, you see... absolutely nothing.

The logs show a generic HTTP 401 Unauthorized response, but there is zero trace of the actual LDAP network handshakes, TLS negotiations, or payload exchanges.

Welcome to the "Blind Phase" of OpenShift troubleshooting.

Because OpenShift 4 relies on a declarative Authentication Operator, the default logging intent (Normal) deliberately suppresses verbose directory traffic. This is great for saving your Elasticsearch PVCs from filling up with noisy logs and preventing credential leakage, but it makes diagnosing a basic LDAP outage nearly impossible.

A firewall drop (I/O Timeout) looks exactly the same in the logs as an Active Directory account lockout (Result Code 49).

Here is the exact, systematic workflow to pierce the blind phase, expose the root cause, prove it to your network team, and clean up afterward.

Step 1: Turn on the "X-Ray" (Enable Debug Logging)

You can't fix what you can't see. You must temporarily mutate the cluster's global authentication resource to force the oauth-openshift pods into Debug mode.

Execute this merge patch:

oc patch authentications.operator.openshift.io/cluster --type=merge -p '{"spec":{"logLevel":"Debug"}}'

The operator will immediately trigger a rolling restart of your authentication pods with the new verbosity injected. Once they are ready, tail the logs (filtering out the noisy health checks):

oc logs -f -l app=oauth-openshift -n openshift-authentication | grep -v -e healthz -e metrics

Step 2: Look for the "Holy Trinity" of LDAP Failures

With the X-Ray on, every LDAP transaction is exposed in real-time. Watch the logs for failures in these three sequential phases. A failure in phase 1 prevents phase 2, and so on.

1. Connectivity (Network & Cryptography)

The Symptom: dial tcp 10.X.X.X:389: i/o timeout
- The Fix: This is a pure network block. Check your OVN-Kubernetes egress IPs, EgressNetworkPolicies, and external enterprise firewalls.
The Symptom: x509: certificate signed by unknown authority
- The Fix: The Active Directory server is using an internal CA. You must provide a ConfigMap containing the Base64 PEM-encoded CA bundle and reference it in the ca.name field of your OpenShift OAuth configuration.

2. Binding (Authentication)

The Symptom: error binding to ou=abc... for search phase: LDAP Result Code 49 "Invalid Credentials"
- The Fix: Your Service Account (the bindDN OpenShift uses to search the directory) has a bad password, the wrong DN, or is locked out.
The Symptom: Error authenticating login "user_name"... LDAP Result Code 49 "Invalid Credentials"
- The Fix: The Service Account is fine. The specific End User just typed their password wrong.

3. Mapping (Schema Translation)

The Symptom: The logs show a successful bind, but the user is still denied access.
- The Fix: OpenShift authenticated the password but couldn't map the user to an internal Identity object. This is usually an Active Directory schema mismatch. Make sure you are mapping id and preferredUsername to sAMAccountName (Active Directory), NOT uid (RFC-2307 LDAP).

Step 3: The Ultimate "It's Not OpenShift's Fault" Test

Sometimes, network teams insist the firewall is open, or identity teams insist the service account works. You need to isolate OpenShift's Go-based LDAP client from the underlying infrastructure.

You do this by bypassing the oauth-openshift pods entirely and running a raw ldapsearch directly from an administrative Linux jumpbox that has line-of-sight to the directory network.

# 1. From your administrative jumpbox, install the standard LDAP utilities
yum install -y openldap-clients # (or apt-get install ldap-utils)

# 2. Execute the raw LDAP query mirroring your OAuth config
ldapsearch -x -D "CN=ocp-svc,OU=ServiceAccounts,DC=example,DC=com" -W -H ldaps://ldaphost.example.com -b "ou=Users,dc=office,dc=example,DC=com" -s sub '(sAMAccountName=user1)'

If ldapsearch times out, it's a network issue. If it throws an invalid credential error, the AD team gave you the wrong password. If it returns the full user payload, OpenShift's mapping configuration is the culprit. You now have definitive proof to attach to your support tickets.

Step 4: The Cleanup (CRITICAL)

Do not leave your cluster in Debug mode.

Running oauth-openshift at elevated verbosity in a production environment will generate an exponential amount of log spam. It will chew through your OpenShift Logging (Elasticsearch/Loki) PVCs, potentially causing cluster-wide logging aggregation failures and risking the exposure of sensitive directory payloads.

Once you have solved the login issue, safely revert to the default operational state:

oc patch authentications.operator.openshift.io/cluster --type=merge -p '{"spec":{"logLevel":"Normal"}}'

By understanding the operator intent model and systematically navigating the blind phase, you can turn a frustrating "Login Failed" screen into a precise, actionable root-cause analysis in minutes.

Learn More & Dive Deeper

Want to master the intricacies of OpenShift authentication and RBAC? Check out the official resources:

📖 OpenShift Docs: Configuring an LDAP Identity Provider
📖 OpenShift Docs: Syncing LDAP Groups
🔧 Red Hat Knowledgebase: Troubleshooting LDAP Authentication in OpenShift 4 (Requires Red Hat Login)

Migrating from DAS to DRA in OpenShift: The Pragmatic Guide

Tosin Akinosho — Wed, 11 Mar 2026 13:25:59 +0000

Migrating from DAS to DRA in OpenShift: The Pragmatic Guide

If you are running high-density AI/ML workloads on OpenShift 4.20 or later, it's time to have a serious talk about your GPU partitioning strategy.

For a long time, we relied on the Dynamic Accelerator Slicer (DAS)—usually via the InstaSlice operator—to dynamically carve out NVIDIA MIG partitions. It worked, but it was essentially a set of webhooks and custom scheduler plugins hacking the legacy device plugin model.

With the introduction of Dynamic Resource Allocation (DRA) as a native Kubernetes standard, Red Hat is officially deprecating DAS. DRA isn't just an upgrade; it is a total "cut-over" replacement that moves away from treating GPUs as dumb integer counts (nvidia.com/gpu: 1) to treating them as complex objects you can query using CEL.

Here is the pragmatic, step-by-step guide to ripping out DAS and implementing the NVIDIA DRA Driver in OpenShift.

Prerequisites for the DRA Stack

Before you start tearing things down, verify your software stack. DRA is a complex orchestration of the container runtime and hardware:

Kubernetes Version: v1.34.2+ (Foundational support for stable DRA APIs. Note: OpenShift 4.20 aligns with Kubernetes ~1.33, but full DRA support matures in the 4.21/1.34+ timeframe.)
NVIDIA Driver: v580+ (Required for CDI and dynamic reconfiguration)
GPU Operator: v25.10.0+
Runtime: CRI-O with Container Device Interface (CDI) enabled.

Phase 1: Scorched Earth (Decommissioning DAS)

Because DAS and DRA use fundamentally different scheduling logic, they cannot co-exist. You must completely nuke the DAS environment. This isn't just deleting the operator pod; you have to clean the cluster state.

# File: scripts/cleanup-das.sh
# Lines: 1-14
#!/bin/bash

# 1. Stop Existing Workloads (Find and terminate pods using DAS resources)
# Add --dry-run or echo before xargs in production to verify targets first.
# Note: This checks primary containers. Adjust the jq path if your initContainers also request MIG slices.
oc get pods --all-namespaces -o json | \
  jq '.items[] | select(.spec.containers[].resources.requests["mig.das.com"] != null) | .metadata.name' | \
  xargs -I {} oc delete pod {}

# 2. Delete all legacy AllocationClaims (Note: verify the exact CRD name for your InstaSlice version)
oc delete allocationclaims --all -n das-operator

# 3. Verify the blast radius is clear
oc get crd | grep allocationclaim

# 4. (Manual Step) Remove the DAS subscription, OperatorGroup, and the das-operator namespace.

Phase 2: Deploying the DRA Driver

Once the nodes are clean, you need to prepare the workers and deploy the NVIDIA GPU Operator differently than you used to.

First, label your DRA-targeted nodes to prevent the driver manager from evicting critical plugins during reconfiguration:
oc label node <node-name> nvidia.com/dra-kubelet-plugin=true

When installing the GPU Operator, you must disable the legacy device plugin. If you don't, you'll end up with resource advertisement conflicts.

# File: values/gpu-operator-values.yaml
# Lines: 1-10
# GPU Operator Helm Values for DRA
devicePlugin:
  enabled: false # Critical: hands control over to DRA

# When installing the separate DRA Driver chart (conceptual illustration):
nvidiaDriverRoot: /run/nvidia/driver
gpuResourcesEnabledOverride: true # Required for full GPU & MIG allocation support via DRA

Gotcha warning: If you are running A100s, changing the MIG partition layout via DRA currently requires a manual restart of the DRA kubelet plugin pod (e.g., oc delete pod -l app.kubernetes.io/name=nvidia-dra-driver-kubelet-plugin -n gpu-operator). The manager doesn't auto-evict the plugin during reconfiguration yet.

Phase 3: Rewriting Your Pod Manifests

This is the biggest change for developers. You can no longer request resources.limits. Everything moves to resources.claims.

The Old Way (DAS):

# File: legacy-pod.yaml
# Lines: 1-10
apiVersion: v1
kind: Pod
metadata:
  name: gemma-inference-legacy
spec:
  containers:
  - name: llm
    resources:
      requests:
        mig.das.com/1g.5gb: 1

The New Way (DRA):
You now reference a ResourceClaimTemplate. Instead of just a single snippet, let's look at what a full, multi-container pod manifest actually looks like when interacting with DRA:

# File: dra-pod.yaml
# Lines: 1-28
apiVersion: v1
kind: Pod
metadata:
  name: gemma-inference-dra
spec:
  containers:
  - name: llm-worker
    image: my-registry/vllm:latest
    resources:
      claims:
      - name: gpu-primary
  - name: monitoring-sidecar
    image: my-registry/gpu-telemetry:latest
    resources:
      # Sidecars don't need the GPU claim, they run alongside the workload
      requests:
        cpu: "100m"
        memory: "128Mi"
  resourceClaims:
  - name: gpu-primary
    source:
      resourceClaimTemplateName: standard-mig-template

This structural shift ensures the hardware is partitioned, reserved, and healthy before the pod is even scheduled.

Operator Dependencies

When managing this lifecycle, you must ensure the NVIDIA GPU Operator (v25.10.0+) is orchestrating the DRA Driver components correctly. If you've been managing GPU operators through the Red Hat OpenShift OperatorHub via OLM (Operator Lifecycle Manager), be aware that the transition requires explicit Subscription and CSV (ClusterServiceVersion) awareness. You can't just apply the new driver and hope OLM understands the state change.

Debugging DRA Allocations

What happens when your pod is pending and you aren't sure why? In the old DAS days, you checked the AllocationClaim objects. In DRA, the nodes advertise their capacity via the ResourceSlice API.

Here is the exact workflow for figuring out why your GPU hasn't attached:

# 1. Check if the cluster even sees your node's physical GPUs
oc get resourceslices

# 2. Check the specific status of your pod's claim
oc get resourceclaim -n my-ai-namespace
# Look for STATUS: Pending or Allocated

# 3. If Pending, describe the claim to see the K8s scheduler's CEL evaluation
oc describe resourceclaim my-gpu-claim-abc12 -n my-ai-namespace

If the scheduler cannot match your pod's hardware request (e.g., you asked for device.attributes.vram >= 80GB but only have 40GB A100s), the describe output will explicitly tell you the CEL evaluation failed on all available nodes.

The NVLink Bonus: ComputeDomains

While dynamic MIG slicing is the primary DAS replacement, DRA brings a massive upgrade for folks running NVIDIA GB200 or HGX systems: ComputeDomains.

Instead of just dividing a single GPU, ComputeDomains allow you to securely share GPU memory across multiple nodes via Multi-Node NVLink (MNNVL). By specifying a computeDomainName in your pod claims, the DRA driver handles all the heavy lifting to establish connectivity among pods in that domain. This keeps them isolated from other namespaces while operating at full NVLink speeds. For large-scale distributed training, this alone is worth the migration effort.

Summary

Moving from DAS to DRA is a paradigm shift. It requires coordination between platform teams and developers to rewrite manifests, but the payoff is a native, stable, and highly expressive hardware scheduling API. Open up your ResourceSlices API, watch your devices get cleanly allocated, and enjoy the deprecation of hacky mutating webhooks.

External References

DNS Governance for OpenShift Beginners: A Friendly Guid

Tosin Akinosho — Tue, 24 Feb 2026 20:22:54 +0000

Wait, Why Should I Care About DNS?

Let me start with a story. Early in my career, I got paged at 2 AM because "nothing was working." Applications were timing out, users couldn't access services, and my monitoring was completely useless. After hours of panic, we discovered someone had accidentally modified the DNS configuration, and the entire cluster couldn't resolve internal service names.

That night changed how I think about DNS. It's the foundation everything else builds on, and when it breaks, nothing works.

In this guide, I'll walk you through how to set up DNS governance for OpenShift using Red Hat Advanced Cluster Management (RHACM). Don't worry if you're new to this - I'll explain everything from scratch.

What Even Is DNS in OpenShift?

First, let's talk about what DNS does in your cluster. You can think of DNS as the phonebook of the internet. When your application wants to talk to another service (like a database or API), it needs to know the IP address. DNS translates service names to IP addresses.

In OpenShift, this is handled by CoreDNS - a DNS server that runs on every node in your cluster. Each node has its own DNS resolver, which means your pods don't need to go far to resolve names.

Here's the cool part: OpenShift automatically creates DNS entries for your services. If you create a service called my-app in the namespace production, other pods can reach it just by using my-app.production.svc.cluster.local. No manual configuration needed.

The DNS Operator in OpenShift manages all of this. It watches for services you create and automatically updates the DNS records. Pretty handy, right?

What's RHACM and Why Do I Need It?

Now, let's talk about RHACM. If you're managing multiple OpenShift clusters (like a development cluster, staging, and production), RHACM is like a "hub" that lets you control all of them from one place.

One of RHACM's superpowers is policies. A policy is basically a rule that says "this is how things should be configured." You define the policy on your hub cluster, and RHACM makes sure all your managed clusters comply with it.

For DNS governance, we want policies that:

Check if DNS is healthy
Verify the configuration hasn't drifted
Alert us if something goes wrong

The Four Things We Need to Monitor

Here's my simple framework for DNS governance. We're going to check four things:

1. Is the DNS Operator Happy?

The DNS Operator is the thing that manages CoreDNS. If it's sad (degraded), nothing else will work properly. We monitor this using something called a ClusterOperator resource.

2. Is the Corefile Correct?

The Corefile is the configuration file for CoreDNS. It tells DNS what plugins to use and how to handle queries. We want to make sure critical plugins are always present.

3. Are All DNS Pods Running?

CoreDNS runs as a DaemonSet (one pod per node). Sometimes pods show as "Running" but aren't actually working. We need to verify all expected pods are truly available.

4. Do We Get Alerted?

If something goes wrong, we need to know about it. We'll set up alerts that page us when DNS has problems.

Let's Build It: Step-by-Step

Ready to see how this works? Here's how to set up DNS governance on your cluster.

Prerequisites

You'll need:

An OpenShift cluster with RHACM installed
Access to the oc command line tool
Permission to create policies on the hub cluster

Step 1: Clone the Repository

First, grab the policy templates from my repository:

git clone https://github.com/tosin2013/dns-policy-config.git
cd dns-policy-config

Step 2: Create the Policy Namespace

On your RHACM hub cluster, create a namespace to hold your DNS policies:

oc apply -f demo/namespace.yaml

This creates a namespace called dns-governance-policies.

Step 3: Bind Your ClusterSet

Next, connect your managed cluster to this namespace:

oc apply -f demo/clusterset-binding.yaml

This tells RHACM which clusters should receive these policies.

Step 4: Apply the DNS Policies

Now let's add the four DNS governance policies:

# Monitor DNS Operator health
oc apply -f policies/dns/operator-health-check.yaml

# Check Corefile configuration
oc apply -f policies/dns/corefile-integrity.yaml

# Verify all DNS pods are running
oc apply -f policies/dns/resource-exhaustion.yaml

# Set up alerting
oc apply -f policies/observability/dns-alerting-rule.yaml

Step 5: Point to Your Cluster

Edit the demo/placement.yaml file to target your managed cluster. Look for the cluster name and change it to match yours:

apiVersion: cluster.open-cluster-management.io/v1beta1
kind: Placement
metadata:
  name: dns-policy-placement
  namespace: dns-governance-policies
spec:
  predicates:
  - requiredClusterSelector:
      labelSelector:
        matchExpressions:
        - key: name
          operator: In
          values:
          - your-cluster-name  # Change this!

Then apply it:

oc apply -f demo/placement.yaml
oc apply -f demo/placement-binding.yaml

Step 6: Check Compliance

Let's see if everything is working:

oc get policy -n dns-governance-policies

You should see something like:

NAME                              REMEDIATION   COMPLIATION
policy-dns-operator-health        inform        Compliant
policy-dns-corefile-integrity    inform        Compliant
policy-dns-resource-exhaustion   inform        Compliant
policy-dns-alerting-rule         enforce       Compliant

All four policies should show "Compliant"!

What Does Each Policy Actually Do?

Let me break down each policy in plain English:

Policy 1: operator-health-check

This watches the DNS Operator and makes sure it's not degraded. If the operator has problems, this policy will tell you.

Policy 2: corefile-integrity

This checks that your CoreDNS configuration has the essential plugins: forward, errors, health, and cache. If any are missing, you'll know.

Policy 3: resource-exhaustion

This verifies that the number of DNS pods actually running matches what should be running. Sometimes pods can be in a weird state - this catches that.

Policy 4: dns-alerting-rule

This creates Prometheus alerts that will page you when DNS has problems. This is the only policy that uses "enforce" mode because it creates new alerting rules.

Why "Inform" Instead of "Enforce"?

You might notice most policies use "inform" mode instead of "enforce." Here's why that's intentional:

Inform means "tell me if something is wrong, but don't fix it automatically"
Enforce means "automatically fix things"

For DNS, automatic fixes are risky. Imagine if a policy accidentally overwrote your DNS configuration - you'd have a cluster-wide outage. By using "inform" mode, we get alerted to problems but don't risk making things worse automatically.

The only exception is the alerting rule, which creates new alert definitions - that's safe to enforce.

Wrapping Up

And that's it! You've now got DNS governance set up for your OpenShift cluster. Here's what you've accomplished:

Created policies that monitor your DNS Operator
Verified your CoreDNS configuration is correct
Ensured all DNS pods are actually running
Set up alerts for when things go wrong

DNS might seem like background infrastructure, but it deserves attention. With these policies in place, you'll know about DNS problems before they become cluster-wide outages.

Remember: the best time to set up governance was when you deployed your cluster. The second best time is now.

Quick Reference

Commands used:

git clone https://github.com/tosin2013/dns-policy-config.git
oc apply -f demo/namespace.yaml
oc apply -f demo/clusterset-binding.yaml
oc apply -f policies/dns/operator-health-check.yaml
oc apply -f policies/dns/corefile-integrity.yaml
oc apply -f policies/dns/resource-exhaustion.yaml
oc apply -f policies/observability/dns-alerting-rule.yaml
oc apply -f demo/placement.yaml
oc apply -f demo/placement-binding.yaml

What to check:

oc get policy -n dns-governance-policies

Questions? Want to learn more? Check out the full repository at github.com/tosin2013/dns-policy-config

How to Automate ADR Reviews and Keep Your Architectural Decisions in Sync with Your Codebase

Tosin Akinosho — Sun, 25 Jan 2026 15:56:52 +0000

The Problem Nobody Talks About

If you've been in software architecture for any time, you know the pain. You carefully document an architectural decision in an ADR (Architectural Decision Record). You link it to pull requests, reference it in code reviews, and feel good about having actual documentation for once. Six months later, that ADR describes a system architecture that hasn't existed for two years.

I've seen this pattern repeat across dozens of teams. ADRs start as living documents and end up as digital dust collectors. New team members read them and make decisions based on outdated information. Code reviews reference constraints that were removed ages ago. And nobody notices until something breaks.

The core issue is that maintaining ADRs manually is time-consuming and easy to skip when deadlines loom. But what if you could automate it? What if an AI agent could review your ADRs against your actual codebase and tell you exactly what needs to be updated?

That's exactly what the ADR Review and Synchronization Prompt enables. Let me walk you through how it works.

Prerequisites

Before you begin, you'll need access to the MCP ADR Analysis Server:

MCP ADR Analysis Server: https://github.com/tosin2013/mcp-adr-analysis-server
ADR Aggregator: https://adraggregator.com/ (for managing multiple ADRs)

Your ADRs should follow the standard format with status fields (Proposed, Accepted, Deprecated, Superseded, Implemented) stored in a directory like docs/adrs/ or adr/.

Full Prompt

# ADR Review and Synchronization Prompt

## Persona

You are an expert Senior Software Architect responsible for maintaining the integrity and accuracy of our project's Architectural Decision Records (ADRs). Your primary goal is to ensure that ADRs are not just historical documents, but living artifacts that accurately reflect the current state of the codebase.

**Current Date:** 2026-01-24 20:02:21 EST

## Core Task

Your task is to perform a comprehensive review of all ADRs within the project located at `{PROJECT_PATH}`. You will use the `mcp-adr-analysis-server` to analyze the codebase and compare it against each ADR. The ultimate goal is to synchronize the ADRs with the code, updating their status and content as necessary.

## Step-by-Step Instructions

1.  **Initiate the Review:**
    *   Invoke the `reviewExistingAdrs` tool from the `mcp-adr-analysis-server`.
    *   Set `projectPath` to the root of the project you are analyzing.
    *   Use `analysisDepth: 'comprehensive'` and `includeTreeSitter: true` to ensure the most accurate and in-depth analysis.
    *   Set `generateUpdatePlan: true` to get actionable recommendations.
    *   Example call:

        ```

json
        {
          "tool": "reviewExistingAdrs",
          "args": {
            "projectPath": "{PROJECT_PATH}",
            "adrDirectory": "docs/adrs",
            "analysisDepth": "comprehensive",
            "includeTreeSitter": true,
            "generateUpdatePlan": true
          }
        }


        ```

2.  **Analyze Each ADR:**
    For each ADR returned by the `reviewExistingAdrs` tool, perform the following analysis based on the `complianceScore`, `gaps`, and `recommendations`:

    *   **Case 1: Full Implementation (Compliance Score >= 8.0)**
        *   **Action:** Update the ADR status to `Implemented`.
        *   **Justification:** The code fully implements the decision recorded in the ADR.

    *   **Case 2: Partial Implementation (5.0 <= Compliance Score < 8.0)**
        *   **Action:** Do not change the status. Create a `todo.md` file or update an existing one with tasks to address the identified `gaps`.
        *   **Justification:** The ADR is not fully implemented, and the remaining work needs to be tracked.

    *   **Case 3: Code is a Better Solution**
        *   **Condition:** The analysis indicates that the code has evolved beyond the ADR, implementing a different, but superior, solution.
        *   **Action:**
            1.  Update the ADR content to reflect the new implementation. Clearly state that the original decision was superseded by a better approach and describe the new approach.
            2.  Set the ADR status to `Implemented`.
        *   **Justification:** The ADR should reflect the current, superior state of the architecture.

    *   **Case 4: Not Implemented (Compliance Score < 5.0)**
        *   **Action:** Do not change the status. Review the ADR to determine if it is still relevant. If not, propose to supersede or deprecate it in a separate action.
        *   **Justification:** The decision has not been implemented, and its relevance needs to be re-evaluated.

3.  **Generate Final Report:**
    *   Produce a summary report of the actions taken.
    *   For each ADR, list the file name, original status, new status, and a brief justification for the change.
    *   If a `todo.md` was created or updated, include its content in the report.

## Output Format

Your final output should be a single markdown document containing:

1.  A summary table of all reviewed ADRs with their old and new statuses.
2.  A "Justification" section detailing the reasoning for each change.
3.  The content of the `todo.md` file, if any tasks were generated.

### Example Summary Table

| ADR File | Original Status | New Status | Justification |
| --- | --- | --- | --- |
| `adr-001.md` | Accepted | Implemented | Code fully aligns with the ADR. |
| `adr-002.md` | Accepted | Implemented | Code implements a superior solution; ADR updated. |
| `adr-003.md` | Accepted | Accepted | Partial implementation; tasks added to `todo.md`. |

Step 1: Initiate the ADR Review

The first step is invoking the analysis server to examine your ADRs against your codebase. Here's the core invocation:

{
  "tool": "reviewExistingAdrs",
  "args": {
    "projectPath": "/path/to/your/project",
    "adrDirectory": "docs/adrs",
    "analysisDepth": "comprehensive",
    "includeTreeSitter": true,
    "generateUpdatePlan": true
  }
}

Parameter explanations:

projectPath: Root directory of your project
adrDirectory: Where your ADRs are stored (e.g., docs/adrs)
analysisDepth: Use "comprehensive" for thorough analysis
includeTreeSitter: Enables deep code parsing for accurate verification
generateUpdatePlan: Produces actionable recommendations

The server analyzes your codebase structure, dependencies, and implementations, then compares findings against each ADR to calculate a compliance score (0-10 scale).

Step 2: Interpret Compliance Scores

The compliance score tells you how well your code matches your documentation:

Score Range	Meaning	Action
≥ 8.0	Full Implementation	Update status to "Implemented"
5.0 - 7.9	Partial Implementation	Don't change status; add tasks to `todo.md`
< 5.0	Not Implemented or Superseded	Review relevance; may need to deprecate

Step 3: Handle Each Case

Case 1: Full Implementation (Score ≥ 8.0)

When code fully implements a documented decision:

Update the ADR status to Implemented
Justification: "Code fully aligns with the ADR"

Example:

## Status

- [x] Accepted
- [x] Implemented
- [ ] Deprecated
- [ ] Superseded

Case 2: Partial Implementation (5.0 ≤ Score < 8.0)

When some aspects are implemented but gaps remain:

Keep the current status (typically "Accepted")
Create or update todo.md with tasks to complete implementation

Example todo.md:

# ADR Implementation Tasks

## adr-003.md - API Gateway Integration
- [ ] Implement rate limiting middleware
- [ ] Add circuit breaker configuration
- [ ] Document error handling patterns

Case 3: Code Implements a Better Solution

When the codebase has evolved beyond the ADR with a superior approach:

Update the ADR content to reflect the new implementation
Explain that the original decision was superseded
Set status to Implemented

Update format:

## Status

- [x] Accepted
- [x] Implemented
- [ ] Deprecated
- [x] Superseded by ADR-XXX

**Note:** This ADR was originally accepted for [original approach].
However, during implementation, we discovered [reason for change]
and adopted [new approach] instead. See ADR-XXX for the current implementation.

Case 4: Not Implemented (Score < 5.0)

When an ADR hasn't been implemented and may no longer be relevant:

Do NOT change the status
Review whether the ADR is still relevant
Propose to supersede or deprecate if needed

Step 4: Generate the Final Report

, generateAfter completing your review a summary report documenting changes:

Summary Table Template

ADR File	Original Status	New Status	Justification
`adr-001.md`	Accepted	Implemented	Code fully aligns with the ADR
`adr-002.md`	Accepted	Implemented	Code implements a superior solution; ADR updated
`adr-003.md`	Accepted	Accepted	Partial implementation; tasks added to todo.md

Full Example Workflow

Here's a complete example of the review process:

{
  "tool": "reviewExistingAdrs",
  "args": {
    "projectPath": "/workspace/my-api-project",
    "adrDirectory": "docs/adrs",
    "analysisDepth": "comprehensive",
    "includeTreeSitter": true,
    "generateUpdatePlan": true
  }
}

Sample response from the server:

{
  "adrs": [
    {
      "file": "adr-001.md",
      "title": "Use GraphQL for API Layer",
      "currentStatus": "Accepted",
      "complianceScore": 9.2,
      "gaps": [],
      "recommendations": ["Update status to Implemented"]
    },
    {
      "file": "adr-002.md",
      "title": "Event-Driven Architecture",
      "currentStatus": "Accepted",
      "complianceScore": 6.5,
      "gaps": [
        "Event schema registry not implemented",
        "Dead letter queue configuration missing"
      ],
      "recommendations": ["Create implementation tasks for remaining gaps"]
    },
    {
      "file": "adr-003.md",
      "title": "Monolithic Database",
      "currentStatus": "Accepted",
      "complianceScore": 2.1,
      "gaps": [
        "Codebase has migrated to microservices with separate databases"
      ],
      "recommendations": ["Supersede this ADR with new microservice data patterns"]
    }
  ]
}

Actions taken:

adr-001.md: Status updated to "Implemented"
adr-002.md: Created todo.md with event architecture tasks
adr-003.md: Updated ADR to document microservices migration, status set to "Superseded"

Integration Tips

Here are some practical ways to integrate ADR reviews into your workflow:

Schedule Regular Reviews

Add ADR review to your sprint tasks
Run before major releases
Include in quarterly architecture audits

CI/CD Integration

Trigger ADR analysis on significant architectural changes
Add compliance checks to pull request automation
Fail builds if ADR gaps exceed thresholds

Team Workflow

Make ADR updates explicit tasks in story estimation
Include ADR review in code review checklists
Celebrate teams that keep ADRs synchronized

Benefits of Automated ADR Synchronization

When you make ADR maintenance an ongoing practice rather than an occasional cleanup, you get:

Trustworthy onboarding: New team members can rely on ADRs being accurate
Effective code reviews: Reviewers can reference current architectural constraints
Visible technical debt: Gaps in ADR implementation highlight unfinished work
Cultural shift: Documentation becomes valuable rather than optional

Conclusion

ADRs only work when they're accurate. The drift between documentation and implementation is the silent killer of architectural integrity. But with tools like the MCP ADR Analysis Server and a systematic review process, you can keep your ADRs synchronized with reality.

The tools are available at:

What remains is making ADR maintenance an ongoing commitment. Start with one review. See what you find. Then decide how to make it part of your regular workflow.

A Deep Dive into Multi-Transport Protocol Abstraction in Python

Tosin Akinosho — Tue, 04 Nov 2025 15:09:10 +0000

As developers, we often build clients to communicate with servers. But what happens when that server can speak multiple languages? Not human languages, but transport protocols. One moment you're talking over stdio, the next over Server-Sent Events (SSE), and tomorrow it might be raw HTTP or WebSockets. This is a common challenge in modern infrastructure, and it's one we tackled head-on in our ansible-collection-mcp-audit project.

In this post, we'll go deep on the design patterns we used to build a clean, transport-agnostic client in Python. We'll look at how an async context manager, a simple factory, and a well-defined class structure can tame the complexity of multi-protocol communication. This isn't just about the Model Context Protocol (MCP); these patterns are applicable to any project that needs to support multiple ways of talking to a service.

The Challenge: One Client, Three Protocols

The goal was to create a single, unified client that could communicate with an MCP server regardless of the underlying transport. The initial requirements were:

stdio: For local, process-based communication. Ideal for testing local scripts and servers.
SSE (Server-Sent Events): For persistent, one-way communication over HTTP. Great for remote servers that push updates.
HTTP: For standard request/response communication. A common requirement for web-based services.

The naive approach would be to write a bunch of if/elif/else statements every time we need to make a call. You've seen that code. We've all written that code. It quickly becomes a tangled mess that's impossible to maintain.

We needed an abstraction. A clean interface that would hide the messy details of each protocol and present a simple, consistent set of methods to the rest of the application.

The Solution: The `MCPClient` Class

The heart of our solution is the MCPClient class. It serves as the single entry point for all interactions with an MCP server. Here's the core design philosophy:

Initialize with Configuration: The client is initialized with all the necessary configuration for all supported transports.
A Single connect Method: A powerful connect method, implemented as an async context manager, handles the protocol-specific connection logic.
Consistent API: Once connected, all other methods (list_tools, call_tool, etc.) don't need to know or care about the underlying transport.

Let's look at the __init__ method to see how this is set up.

# File: plugins/module_utils/mcp_client.py
# Lines: 73-121

class MCPClient:
    SUPPORTED_TRANSPORTS: ClassVar[list[str]] = ["stdio", "sse", "http"]

    def __init__(
        self,
        transport: str = "stdio",
        server_command: str | None = None,
        server_args: list[str] | None = None,
        server_url: str | None = None,
        server_headers: dict[str, str] | None = None,
        timeout: int = 30,
    ) -> None:
        if transport not in self.SUPPORTED_TRANSPORTS:
            raise MCPClientError(f"Unsupported transport '{transport}'")

        self.transport = transport
        self.timeout = timeout
        self.session: ClientSession | None = None

        # Validate transport-specific parameters
        if transport == "stdio":
            if not server_command:
                raise MCPClientError("server_command is required for stdio transport")
            self.server_command = server_command
            self.server_args = server_args or []
        elif transport in ("sse", "http"):
            if not server_url:
                raise MCPClientError(f"server_url is required for {transport} transport")
            self.server_url = server_url
            self.server_headers = server_headers or {}

Notice how the constructor takes all possible parameters but only validates and stores the ones relevant to the selected transport. This keeps the initialization logic clean and ensures that the client is in a valid state from the moment it's created.

The Magic of the Async Context Manager

The real power of this abstraction comes from the connect method. We implemented it as an asynccontextmanager, which is a perfect fit for managing the lifecycle of a network connection.

Here's a simplified view of the implementation:

# File: plugins/module_utils/mcp_client.py
# Lines: 122-171

from contextlib import asynccontextmanager
from mcp.client.stdio import stdio_client
from mcp.client.sse import sse_client
from mcp import ClientSession

@asynccontextmanager
async def connect(self):
    """Establish connection to the MCP server as an async context manager."""
    try:
        if self.transport == "stdio":
            server_params = StdioServerParameters(command=self.server_command, args=self.server_args)
            async with stdio_client(server_params) as (read, write):
                async with ClientSession(read, write) as session:
                    self.session = session
                    await session.initialize()
                    yield self

        elif self.transport == "sse":
            async with sse_client(self.server_url, self.server_headers) as (read, write):
                async with ClientSession(read, write) as session:
                    self.session = session
                    await session.initialize()
                    yield self

        elif self.transport == "http":
            raise MCPTransportError("HTTP transport not yet implemented")

    except Exception as e:
        raise MCPConnectionError(f"Failed to connect via {self.transport}: {e!s}") from e
    finally:
        self.session = None # Ensure session is cleared on exit

This pattern is incredibly powerful. Let's break down what it's doing:

Protocol-Specific Logic: The if/elif block contains the only protocol-specific connection logic in the entire client.
Leveraging the SDK: It uses the appropriate client function from the MCP Python SDK (stdio_client or sse_client).
Session Management: It creates a ClientSession and performs the initial handshake (session.initialize()).
Yielding Control: The yield self is the crucial part. It passes the connected, ready-to-use client instance to the calling code.
Guaranteed Cleanup: The finally block ensures that the session is torn down and resources are released, no matter what happens inside the with block. This prevents resource leaks, which are notoriously hard to debug.

A Clean and Consistent API

With the connection handled by the context manager, the rest of the client's methods become beautifully simple. They don't need to know anything about the transport; they just use the self.session object that was set up during the connection.

# File: plugins/module_utils/mcp_client.py
# Lines: 173-213

async def list_tools(self) -> list[Tool]:
    """List all tools available on the MCP server."""
    if not self.session:
        raise MCPClientError("Not connected to MCP server")

    try:
        response = await self.session.list_tools()
        return response.tools
    except Exception as e:
        raise MCPClientError(f"Failed to list tools: {e!s}") from e

async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None = None) -> Any:
    """Call a tool on the MCP server."""
    if not self.session:
        raise MCPClientError("Not connected to MCP server")

    try:
        response = await self.session.call_tool(tool_name, arguments or {})
        return response
    except Exception as e:
        raise MCPClientError(f"Failed to call tool '{tool_name}': {e!s}") from e

This is the payoff for our architectural efforts. The code is clean, readable, and easy to test. Adding a new method is trivial, and it will automatically work with all supported transports.

Visualizing the Abstraction

Here's a diagram that illustrates the abstraction layers:

graph TD
    subgraph "Application Layer"
        A[Ansible Module]
    end

    subgraph "Abstraction Layer (MCPClient)"
        B(connect() Context Manager)
        C(list_tools(), call_tool(), etc.)
    end

    subgraph "Transport Layer"
        D[stdio_client]
        E[sse_client]
        F[http_client (future)]
    end

    subgraph "Protocol Layer"
        G[MCP Python SDK]
    end

    A --> B
    A --> C
    B --> D
    B --> E
    B --> F
    C --> G
    D --> G
    E --> G
    F --> G

The application layer (our Ansible modules) only ever talks to the MCPClient. The connect method acts as a gateway to the transport layer, and all subsequent calls go through the consistent API provided by the protocol layer. It's a clean separation of concerns that makes the entire system robust and extensible.

Conclusion: Patterns for Maintainable Code

Building a multi-transport client doesn't have to be a nightmare of nested if statements. By applying a few key design patterns, we were able to create a solution that is:

Maintainable: Protocol-specific code is isolated in one place.
Extensible: Adding a new transport (like WebSockets) would involve modifying only the connect method.
Robust: The context manager ensures that connections are always cleaned up properly.
Easy to Use: The rest of the application interacts with a simple, consistent API.

I've found this pattern to be incredibly effective in a variety of projects. Whether you're working with different database drivers, message queues, or cloud APIs, the core principles of configuration-driven initialization and a context-managed connection lifecycle can save you from a world of technical debt.

What are your favorite patterns for handling multi-protocol or multi-provider clients? Share your thoughts in the comments below!

Building Better Documentation: My Journey with DocuMCP and the Model Context Protocol

Tosin Akinosho — Wed, 29 Oct 2025 14:28:27 +0000

What I've learned over the years is that great documentation isn't just about the words on the page—it's about making complex technical concepts accessible while maintaining accuracy and depth. In my experience working with various documentation tools and frameworks, I've found that the intersection of AI and traditional technical writing presents both exciting opportunities and unique challenges.

The Challenge of Modern Documentation Deployment

In most cases, setting up documentation for open-source projects feels like reinventing the wheel every single time. From what I've observed, developers often struggle with choosing the right static site generator, structuring content effectively, and maintaining consistency across projects. It's worth noting that this complexity might behave differently depending on your team's technical background and the scope of your project.

Consider a scenario where you're leading a team that's just launched a new microservice architecture. You have multiple repositories, each needing its own documentation, and you want consistency across all of them. Picture this situation: your developers are spending more time figuring out Jekyll configurations than actually writing meaningful documentation content.

This is where the Model Context Protocol (MCP) and tools like DocuMCP come into play, though your mileage may vary based on your specific use case.

[DIAGRAM: Traditional vs MCP-Powered Documentation Workflow]

Traditional Approach:
Developer → Manual Tool Selection → Manual Setup → Manual Deployment
    ↓              ↓                   ↓              ↓
Time Lost    Configuration Hell    Inconsistency   Maintenance

MCP-Powered Approach:
Developer → AI Analysis → Automated Setup → GitHub Pages
    ↓            ↓             ↓             ↓
Quick Start  Smart Choices   Consistency   Automation

Understanding the Model Context Protocol

Let me share what I've discovered about MCP during my exploration of AI-assisted development workflows. The Model Context Protocol is essentially a standardized way for AI models to interact with external tools and data sources. Think of it as creating a universal language that allows AI assistants to understand and manipulate your development environment.

In my experience, MCP addresses a fundamental problem: the fragmentation of AI tool integrations. Before MCP, every AI application needed custom code to interact with different services. What I've found particularly interesting is how MCP creates a bridge between the conversational nature of AI and the structured requirements of development tools.

The DocuMCP Approach

Imagine a scenario where you could simply tell an AI assistant: "analyze my repository and deploy documentation to GitHub Pages." That's the vision behind DocuMCP—an intelligent MCP server specifically designed for documentation deployment.

From what I've observed in the project structure and implementation, DocuMCP follows the Diataxis framework for organizing documentation. This approach, which I've used in various projects, separates content into four categories:

Tutorials (learning-oriented)
How-to guides (task-oriented)
Reference (information-oriented)
Explanation (understanding-oriented)

{
  "mcpServers": {
    "documcp": {
      "command": "npx",
      "args": ["documcp"]
    }
  }
}

The Technical Architecture Behind DocuMCP

Let's say you're working with a team that needs to understand how DocuMCP actually works under the hood. Based on my analysis of the project, it appears to follow a client-server architecture typical of MCP implementations.

[DIAGRAM: DocuMCP Architecture Flow]

User Input
    ↓
Claude Desktop (MCP Client)
    ↓
DocuMCP Server
    ↓
Repository Analysis → Static Site Generator Selection → GitHub Pages Deployment
    ↓                        ↓                              ↓
README.md            Framework Choice                 Automated Setup
Code Structure       (Jekyll/Hugo/etc.)             Documentation Site
Documentation        Template Generation              Live URL

In most cases, this should work smoothly, though your experience might vary depending on your repository structure and existing documentation assets. What I've learned is that the intelligence lies in the analysis phase—the system examines your codebase, identifies documentation patterns, and makes informed decisions about the best deployment strategy.

Setting Up Your Documentation Pipeline

Consider a team that wants to implement DocuMCP in their workflow. The setup process, from what I've gathered, is refreshingly straightforward compared to traditional approaches.

The installation involves adding the MCP server configuration to your Claude Desktop setup. In my experience with similar tools, this type of configuration management has become much more standardized, which is a welcome improvement from the fragmented approaches of the past.

Practical Implementation Steps

Picture this scenario: you're tasked with standardizing documentation across multiple repositories in your organization. Here's the approach I'd recommend based on the DocuMCP methodology:

Repository Analysis Phase: The system analyzes your existing content structure
Framework Recommendation: Based on project characteristics, it suggests the optimal static site generator
Template Generation: Creates a professional documentation structure
Automated Deployment: Sets up GitHub Pages integration

From what I've observed, this automated approach tends to produce more consistent results than manual setup, though it's worth noting that complex projects might require some manual refinement.

The Human Element in AI-Assisted Documentation

What I've found particularly interesting about tools like DocuMCP is how they change the relationship between technical writers and their tools. Instead of being documentation architects, we become documentation curators and reviewers.

In my experience, the most successful AI-assisted documentation workflows maintain a balance between automation and human insight. The AI handles the structural and repetitive aspects—choosing frameworks, setting up deployment pipelines, ensuring consistency—while humans focus on content strategy, user experience, and the nuanced communication that makes technical writing effective.

Challenges and Considerations

Let's be honest about the limitations. While MCP and DocuMCP represent significant steps forward, they're not silver bullets. In most cases, these tools work best with well-structured projects that follow common patterns. If your repository has unique organizational requirements or non-standard documentation needs, you might find yourself needing to customize the output.

From what I've observed, the success of automated documentation deployment depends heavily on the quality of your source material. If your README files are sparse or your code comments are minimal, even the most sophisticated AI won't be able to generate comprehensive documentation.

Looking Forward: The Future of Documentation Workflows

What excites me most about developments like DocuMCP is how they're democratizing good documentation practices. Picture this: a junior developer who's never set up a documentation site before can now create professional, well-structured documentation with minimal friction.

In my experience, tools that lower the barrier to entry for best practices tend to have the most significant impact on overall quality across an organization. When it's easier to do the right thing than the wrong thing, teams naturally gravitate toward better practices.

The integration of AI into documentation workflows isn't about replacing technical writers—it's about amplifying our ability to create clear, consistent, and accessible technical content. What I've learned is that the most powerful applications of AI in documentation are those that handle the mechanical aspects while preserving space for human creativity and insight.

As we continue to explore these new possibilities, I remain optimistic about the potential for AI-assisted documentation tools to help us communicate technical concepts more effectively. The key, as always, is maintaining our focus on the end user while leveraging these powerful new capabilities to create better experiences for everyone involved in the documentation lifecycle.

Resources and Further Reading

If you're interested in exploring DocuMCP further, here are the key resources:

DocuMCP GitHub Repository - The main project repository with source code, installation instructions, and contribution guidelines
DocuMCP Documentation - Comprehensive documentation following the Diataxis framework, including tutorials, how-to guides, and reference materials

What I've found is that having both the technical implementation details and well-structured documentation makes it much easier to get started with any new tool. The documentation site itself is actually a great example of what DocuMCP can help you achieve—clean, organized, and automatically deployed.

Feel free to explore the project, contribute if you find it useful, or reach out if you have questions about implementing similar documentation workflows in your own projects.

How to Keep Your Python Package Metadata in Sync with GitHub Release Tags

Tosin Akinosho — Wed, 26 Mar 2025 14:43:02 +0000

Keeping versions aligned across setup.py, pyproject.toml, and GitHub tags is critical for maintaining a healthy Python project. It prevents mismatches, enables CI/CD automation, and ensures seamless releases.

In this guide, you'll learn best practices for versioning Python packages and syncing metadata with GitHub release tags using bump-my-version, GitHub Actions, and automation scripts.

📌 Table of Contents

Why Versioning is Crucial
The Right Way to Define Your Version
Aligning Versions with GitHub Tags
Keeping Dependencies in Sync
Using bump-my-version for Automated Versioning
Validating Versions in CI/CD
Mistakes to Avoid
Final Checklist
FAQs

Why Versioning is Crucial

Imagine deploying a package and realizing later that the version in setup.py differs from pyproject.toml. 🤦‍♂️ This breaks automation, confuses users, and complicates debugging.

When you keep versions in sync, you:

Ensure smooth CI/CD deployments
Reduce version conflicts in dependencies
Automate and streamline release workflows

Following best practices prevents the dreaded "version mismatch" error and keeps your project organized.

The Right Way to Define Your Version

A common pitfall is defining the version in multiple places. Instead, define it in a single source of truth.

1️⃣ Store Version in `version.py`

Create a __version__.py file inside your package:

# my_package/__version__.py
__version__ = "1.2.3"

2️⃣ Use It in `setup.py`

Instead of manually entering a version, import it dynamically:

from my_package.__version__ import __version__

setup(
    name="my_package",
    version=__version__,
    ...
)

3️⃣ Sync with `pyproject.toml` (for Poetry)

If you're using Poetry, manually update pyproject.toml:

[tool.poetry]
name = "my-package"
version = "1.2.3"

📌 Poetry does not support dynamic version imports—so keeping this updated manually (or via automation) is necessary.

Aligning Versions with GitHub Tags

To ensure GitHub releases match your code, follow this release process:

Update the version in __version__.py and pyproject.toml.
Commit the change:

   git commit -am "Release version 1.2.3"

Create a tag matching the version:

   git tag v1.2.3
   git push origin main --tags

Ensure the tag and package version match before deploying.

🚨 If the tag and package version don’t match, CI/CD should catch the issue and stop the release.

Keeping Dependencies in Sync

Beyond versioning, managing dependencies properly prevents unexpected failures.

Lock Dependencies in `requirements.txt`

For reproducible builds, lock dependencies:

pip freeze > requirements.txt

Separate Dev Dependencies

Use a separate file for development dependencies:

pip install -r requirements-dev.txt

Alternatively, if using Poetry, do:

poetry add pytest --dev

This ensures production installs don’t pull unnecessary dev dependencies.

Using `bump-my-version` for Automated Versioning

What is `bump-my-version`?

bump-my-version is the modern replacement for bump2version (which is no longer maintained).

It updates version numbers across all necessary files (e.g., __version__.py, setup.py, pyproject.toml).

How to Install It

pip install bump-my-version

How to Use It

Increment version numbers automatically:

bump-my-version patch   # Updates 1.2.3 → 1.2.4
bump-my-version minor   # Updates 1.2.3 → 1.3.0
bump-my-version major   # Updates 1.2.3 → 2.0.0

This ensures versioning consistency, preventing human errors in updates.

Validating Versions in CI/CD

To prevent mismatched versions between GitHub tags and your package metadata, add a validation step to GitHub Actions.

CI Workflow to Validate Versions

Create .github/workflows/version-check.yml:

name: Version Check

on:
  push:
    tags:
      - 'v*'  # Runs only on version tags

jobs:
  check-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate package version consistency
        run: |
          TAG_VERSION=${GITHUB_REF#refs/tags/v}
          PACKAGE_VERSION=$(python -c "import my_package.__version__ as v; print(v.__version__)")

          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
            echo "Version mismatch! GitHub tag is $TAG_VERSION but package version is $PACKAGE_VERSION."
            exit 1
          fi

✅ If the versions don’t match, the pipeline will fail, preventing a broken release.

Mistakes to Avoid

🚨 Hardcoding Versions in Multiple Files – Instead, use __version__.py

🚨 Pushing GitHub Tags Without Updating Files First

🚨 Ignoring Dependency Locking (requirements.txt)

🚨 Manual Version Updates Instead of Automation (bump-my-version)

Avoid these, and your releases will be smooth! 🚀

Final Checklist

✅ Keep version centralized in __version__.py

✅ Always sync pyproject.toml (for Poetry users)

✅ Automate with bump-my-version

✅ Validate version consistency in CI/CD

✅ Lock dependencies for reliable builds

FAQs

1. Why is `bump2version` no longer recommended?

bump2version is no longer maintained. bump-my-version is the modern alternative with active support.

2. How do I ensure my GitHub release matches my package version?

Use GitHub Actions to verify that the Git tag matches __version__.py before releasing.

3. Should I use `setup.py` or Poetry?

If you use setuptools, update setup.py
If you use Poetry, manually update pyproject.toml

4. Do I still need `requirements.txt` if using Poetry?

No! Poetry manages dependencies internally, so requirements.txt is unnecessary.

5. Is `bump-my-version` required?

No, but it automates versioning, preventing human mistakes.

Conclusion

Keeping your Python packaging metadata in sync with GitHub release tags prevents deployment issues, enables automation, and ensures smooth releases.

By following best practices like centralized versioning, GitHub Actions validation, and automated version bumps, you'll create a robust, foolproof versioning system!

Want to take it a step further? Integrate this workflow into your CI/CD pipeline today! 🚀

How to Use Migration Toolkit for Virtualization 2.7 with OpenShift Internal Registry

Tosin Akinosho — Wed, 19 Feb 2025 18:03:54 +0000

Introduction

Migration Toolkit for Virtualization (MTV) 2.7 provides a comprehensive solution to migrate virtual machines (VMs) from VMware to OpenShift Virtualization. This guide outlines the steps required to install and configure MTV 2.7 while leveraging OpenShift's internal registry.

Prerequisites

Before proceeding, ensure you have met the following requirements:

Review VMware Prerequisites: Familiarize yourself with the VMware prerequisites as outlined in the official documentation.
Creating a VDDK Image: Follow the steps for creating a VDDK image for VMware disk introspection.
OpenShift Cluster Requirements:
- A functional OpenShift Container Platform (OCP) cluster with OpenShift Virtualization enabled.
- Access to the OpenShift internal registry.
- Sufficient resources (CPU, Memory, and Storage) to accommodate migrated workloads.

Step 1: Install Migration Toolkit for Virtualization

MTV 2.7 can be installed via the OperatorHub in OpenShift.

Login to OpenShift:

   oc login --server=<OCP_API_SERVER> --token=<TOKEN>

Install MTV Operator:
- Navigate to Operators > OperatorHub in the OpenShift Web Console.
- Search for Migration Toolkit for Virtualization.
- Click Install and follow the guided setup.
Verify Installation:

   oc get pods -n openshift-mtv

Ensure all pods in the openshift-mtv namespace are running.

Step 2: Configure OpenShift Internal Registry for MTV

MTV needs access to OpenShift’s internal image registry to store migrated VM images.

Expose the Internal Registry:

   oc patch configs.imageregistry.operator.openshift.io cluster \
   --type=merge -p '{"spec":{"defaultRoute":true}}'

Retrieve the internal registry route:

   oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}'

Authenticate with the Registry:

   podman login -u kubeadmin -p $(oc whoami -t) \
   $(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')

Step 3: Download and Save the VDDK Archive

Download the required VDDK archive from VMware and save it in a temporary directory. After downloading, extract the archive:

Create and Configure the VDDK Image

Migration Toolkit for Virtualization requires a VMware Virtual Disk Development Kit (VDDK) image for efficient data transfer.

Prepare the VDDK Libraries:

In a browser, navigate to the VMware VDDK version 8 download page.
Select version 8.0.1 and click Download.
Note: In order to migrate to OpenShift Virtualization 4.12, download VDDK version 7.0.3.2 from the VMware VDDK version 7 download page.

Extract the tar file

tar -xzf VMware-vix-disklib-\<version>.x86\_64.tar.gz

Build the Container Image:

# Create Dockerfile
cat > Dockerfile <<EOF
FROM registry.access.redhat.com/ubi8/ubi-minimal
COPY vmware-vix-disklib-distrib /vmware-vix-disklib-distrib
RUN mkdir -p /opt
ENTRYPOINT ["cp", "-r", "/vmware-vix-disklib-distrib", "/opt"]
EOF

# Build the VDDK container image
podman build -t vddk-image:latest .

Tag the VDDK Image for OpenShift's Internal Registry:
This will go in the openshift-mtv namespace

   podman tag vddk-image:latest $(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')/openshift-mtv/vddk-image:latest

Push the VDDK Image to OpenShift's Internal Registry:

   podman push $(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')/openshift-mtv/vddk-image:latest

Give image pull permissions to openshift-mtv namespace

oc adm policy add-role-to-group system:image-puller system:serviceaccounts:openshift-mtv -n openshift-image-registry

Configure MTV to Use the VDDK Image:

Navigate to Operators > Installed Operators in OpenShift Web Console.
Locate the ForkliftController resource and edit its configuration.
Specify the VDDK image location:

   spec:
     vddkInitImage: 'image-registry.openshift-image-registry.svc:5000/openshift-mtv/vddk-image:latest'

Save and apply the changes.

Step 4: Configure Migration Plan

Access the MTV Web UI:
- Navigate to Operators > Installed Operators in OpenShift.
- Click Migration Toolkit for Virtualization and select Open Console.
Define a Migration Plan:
- Add VMware as a source provider.
- Select OpenShift Virtualization as the destination.
- Map VM workloads accordingly.
Start Migration:
- Validate VM connectivity.
- Initiate migration and monitor the process via OpenShift logs:
```
 oc logs -f <mtv-pod-name> -n openshift-mtv
```

Conclusion

By following these steps, you have successfully migrated virtual machines from VMware to OpenShift Virtualization using Migration Toolkit for Virtualization 2.7 while leveraging the OpenShift internal registry. Ensure to monitor workloads post-migration and optimize resources accordingly.

Turbocharge Your OpenDevin Development: A Deep Dive into a Time-Saving Bash Script

Tosin Akinosho — Fri, 14 Jun 2024 00:42:04 +0000

Introduction

Embarking on your OpenDevin journey? This innovative platform opens doors to endless possibilities, but the initial setup can sometimes be a time sink. What if I told you there's a way to skip the tedious configuration and dive straight into coding? Meet our Bash script, your new best friend in the world of OpenDevin development.

What This Script Does (and Why You'll Love It)

Let's break down the magic behind this script and how it can supercharge your workflow:

Effortless Dependency Management:

Say goodbye to manual installations: The script does the heavy lifting by automatically checking for and installing essential tools like Docker, Node.js, Conda (a package and environment manager), and Poetry (a Python dependency manager).
Why this matters: No more scouring the web for installation instructions or troubleshooting compatibility issues. Your development environment is ready to roll in minutes.

Seamless Environment Configuration:

Your OpenDevin sanctuary: The script sets up a dedicated Conda environment exclusively for OpenDevin. This keeps your project dependencies organized and prevents conflicts with other projects.
Git integration: It effortlessly clones the OpenDevin repository (if you don't already have it), saving you a manual step.
Ollama LLM setup (optional): For those interested in working with Large Language Models (LLMs), the script can even help you get started with Ollama, a powerful LLM service.
Why this matters: You get a clean, isolated workspace where you can experiment and build without worrying about messing up your system.

Configuration and Workspace Automation:

No more missing files: The script ensures you have the essential configuration files (config.toml) and a designated workspace directory.
Why this matters: You won't waste time tracking down missing components or wondering where to store your project files.

Dockerized Development Bliss:

Build and run with a single command: The script leverages the power of Docker to build and launch your OpenDevin application within a container.
Consistency is key: Docker guarantees that your development environment mirrors the production environment, minimizing those frustrating "it works on my machine" bugs.
Why this matters: Docker streamlines testing and deployment, giving you the confidence that your application will behave as expected wherever it runs.

Unleash the Script's Potential

Getting started is a breeze:

Grab the Script: Head over to https://raw.githubusercontent.com/tosin2013/OpenDevin/live/opendevin.sh and download it.
Make it Executable: Open your terminal and run chmod +x opendevin.sh.
Command Your Environment: Execute the script with different flags to perform specific actions:
- ./opendevin.sh -i -b (Install dependencies and build)
- ./opendevin.sh -r (Run the project)
- ./opendevin.sh -h (View all options)

Who Should Use This Script?

OpenDevin Newcomers: Hit the ground running without getting bogged down in setup.
Seasoned Developers: Automate repetitive tasks and reclaim your precious time.
Teams: Ensure everyone on your team has a consistent development environment, leading to smoother collaboration.

Going Beyond the Basics

Ready to customize? This script is your starting point. Dive into the code, tweak it to match your preferences, and even contribute back to the OpenDevin community!

Let's Get Developing!

Don't let setup slow you down. Let this Bash script be your trusty sidekick as you explore the exciting world of OpenDevin development.

What are you waiting for? Share your OpenDevin creations in the comments below!

Ansible Vault Secrets Documentation

Tosin Akinosho — Fri, 19 Apr 2024 17:48:17 +0000

This post outlines the necessary secrets required for Ansible playbooks. It includes details on how to use the ansiblesafe tool to manage these secrets securely.

Red Hat Subscription Manager (RHSM) Variables

These variables are used to register the Ansible Automation Platform instance with Red Hat Subscription Manager and attach the necessary subscriptions.

rhsm_username: The username for your Red Hat account. (More info)
rhsm_password: The password for your Red Hat account. (More info)
rhsm_org: The ID of the organization to register the system to. (More info)
rhsm_activationkey: The activation key used to register the system. (More info)

Admin User Variables

admin_user_password: The password for the admin user in Virtual Machines using kcli-pipelines. (More info)

Offline Token Variables

offline_token: The offline token used for Red Hat Subscription Manager. (More info)
automation_hub_offline_token: The offline token used for Automation Hub. (More info)

OpenShift Pull Secret

openshift_pull_secret: The pull secret used to deploy OpenShift Clusters. (More info)

FreeIPA Server Admin Password

freeipa_server_admin_password: The password for the FreeIPA server admin user using the freeipa-workshop-deployer. (More info)

Managing Secrets with Ansiblesafe

ansiblesafe is a Go script that facilitates the encryption and decryption of YAML files using the Ansible Vault CLI. It supports various operations such as encrypting, decrypting, and syncing secrets with HashiCorp Vault.

Installation

dnf install ansible-core -y 
curl -OL https://github.com/tosin2013/ansiblesafe/releases/download/v0.0.8/ansiblesafe-v0.0.8-linux-amd64.tar.gz
tar -zxvf ansiblesafe-v0.0.8-linux-amd64.tar.gz
chmod +x ansiblesafe-linux-amd64 
sudo mv ansiblesafe-linux-amd64 /usr/local/bin/ansiblesafe

Usage

If you do not pass any flags everything wil be auto generated for you

$ ansiblesafe -h
Usage of /tmp/go-build1657505477/b001/exe/ansiblesafe:
  -f, --file string     Path to YAML file (default: $HOME/vault.yml)
  -o, --operation int   Operation to perform (1: encrypt, 2: decrypt, 3: Write secrets to HashiCorp Vault, 4: Read secrets from HashiCorp Vault, 5: skip encrypting/decrypting)

To use ansiblesafe, navigate to the cloned directory and perform the following commands based on your needs:

Encrypt a YAML file:

  ./ansiblesafe -f path_to_your_file -o 1

Decrypt a YAML file:

  ./ansiblesafe -f path_to_your_file -o 2

Hasicorp Examples

Write secrets to HashiCorp Vault

$ export VAULT_ADDRESS=http://127.0.0.1:8200/
$ export VAULT_TOKEN=token
$ export SECRET_PATH=ansiblesafe/example
$ ansiblesafe -o 3

Read secrets from HashiCorp Vault and safe to vault.yaml

$ export VAULT_ADDRESS=http://127.0.0.1:8200/
$ export VAULT_TOKEN=token
$ export SECRET_PATH=ansiblesafe/example
$ ansiblesafe -o 4
$ ansiblesafe -o 1 # Optional encrypt the file

Security Considerations

Instructions to use ansiblesale without a password prompt

$ touch ~/.vault_password
$ chmod 600 ~/.vault_password
# The leading space here is necessary to keep the command out of the command history
$  echo password >> ~/.vault_password
# Link the password file into the current working directory
$ ln ~/.vault_password .
# Set the environment variable to the location of the file
$ export ANSIBLE_VAULT_PASSWORD_FILE=.vault_password

Remember to keep your vault password and tokens secure and limit access to authorized users only.

More Information

For more details on ansiblesafe and its capabilities, visit the GitHub repository.

Streamlining Git Repository Management with Bash

Tosin Akinosho — Wed, 03 Apr 2024 00:25:24 +0000

Managing multiple Git repositories can be a challenging task, especially when it comes to keeping track of their status, merging changes, and ensuring everything is up to date. However, with the power of Bash scripting, you can streamline this process and save valuable time and effort. In this article, we'll delve into how a Bash script can simplify Git repository management, focusing on automating status checks, merging changes, and discussing potential enhancements to the script.

Challenges of Manual Git Repository Management

Manually managing multiple Git repositories involves several challenges. Firstly, keeping track of the status of each repository, including whether there are uncommitted changes, untracked files, or incoming changes from remote branches, can be time-consuming. Moreover, performing repetitive tasks like merging changes between repositories or pushing updates can lead to errors and inconsistencies.

Automating Git Repository Management with Bash

To address these challenges, a Bash script can be incredibly useful. Let's take a look at a sample script that automates the process of merging changes from a source repository to a target repository.

#!/bin/bash

# Source repository configuration (HTTPS)
source_repo_url="https://github.com/SOURCE_REPO_OWNER/SOURCE_REPO_NAME.git"
source_branch="main"

# Target repository configuration (SSH)
target_repo_url="git@gitea.example.com:TARGET_REPO_OWNER/TARGET_REPO_NAME.git"
target_branch="main"

# Temporary directory for cloning repositories
temp_dir=$(mktemp -d)

# Clone the source repository
git clone --branch "$source_branch" "$source_repo_url" "$temp_dir/source_repo"

# Clone the target repository
git clone --branch "$target_branch" "$target_repo_url" "$temp_dir/target_repo"

# Navigate to the target repository
cd "$temp_dir/target_repo"

# Add the source repository as a remote
git remote add source "$source_repo_url"

# Fetch the latest changes from the source repository
git fetch source

# Create a new branch for merging
git checkout -b "merge-from-source"

# Merge the changes from the source branch
git merge "source/$source_branch"

# Push the merged changes to the target repository
git push origin "merge-from-source"

# Clean up the temporary directory
rm -rf "$temp_dir"

echo "Merge completed successfully!"

This script automates the process of merging changes from a specified branch (main in this case) of a source repository to a target repository. It clones both repositories into a temporary directory, fetches the latest changes from the source repository, creates a new branch for merging, performs the merge, pushes the changes to the target repository, and finally cleans up the temporary directory.

Key Components of the Script

Let's break down the key components of the script:

Repository Configuration: The script begins by defining the URLs and branches for the source and target repositories.
Temporary Directory: It creates a temporary directory (temp_dir) to store the cloned repositories and perform the merge operation.
Cloning Repositories: The script clones the source and target repositories into the temporary directory using the specified branch (main).
Merging Changes: After adding the source repository as a remote, fetching the latest changes, and creating a new branch for merging, the script performs the actual merge operation.
Pushing Changes: Once the merge is successful, the script pushes the merged changes to the target repository's branch (main).
Cleanup: Finally, the script cleans up by removing the temporary directory.

Benefits of Using the Script

Using this Bash script offers several benefits:

Time Savings: Automating the merge process saves time compared to manual intervention.
Reduced Errors: The script reduces the risk of errors that can occur during manual repository management.
Consistency: By automating repetitive tasks, the script ensures consistency across repositories.

Potential Enhancements and Additional Features

While the provided script streamlines basic Git repository management tasks, several enhancements and additional features can be added to further improve its functionality:

Error Handling: Incorporate error handling mechanisms to gracefully handle failures during cloning, merging, or pushing.
Branch Selection: Allow users to specify source and target branches dynamically rather than hardcoding them in the script.
Interactive Mode: Implement an interactive mode that prompts users for inputs such as repository URLs, branches, and confirmation before proceeding with actions.
Logging: Add logging capabilities to track the execution of the script and capture relevant information for troubleshooting.
Parallel Processing: For large repositories or multiple merges, consider implementing parallel processing to improve performance.

By incorporating these enhancements, the script can become more robust, user-friendly, and suitable for a wider range of use cases.

Conclusion

In conclusion, Bash scripting offers a powerful way to streamline Git repository management tasks. By automating processes like checking status, merging changes, and pushing updates, scripts like the one discussed in this article can significantly save time, reduce errors, and improve overall efficiency. With the potential for further enhancements and customization, Bash scripts become invaluable tools for developers and teams managing multiple Git repositories.

Forem: Tosin Akinosho

Stop Using CI Scripts to Validate Jupyter Notebooks. Use a Kubernetes Operator Instead.

Quick Start

How It Works

Model-Aware Validation

GPU Workloads

Debugging Failed Validations

Security

Try It

Escaping the "Blind Phase": How to Debug OpenShift 4 LDAP & Active Directory Logins

Step 1: Turn on the "X-Ray" (Enable Debug Logging)

Step 2: Look for the "Holy Trinity" of LDAP Failures

1. Connectivity (Network & Cryptography)

2. Binding (Authentication)

3. Mapping (Schema Translation)

Step 3: The Ultimate "It's Not OpenShift's Fault" Test

Step 4: The Cleanup (CRITICAL)

Learn More & Dive Deeper

Migrating from DAS to DRA in OpenShift: The Pragmatic Guide

Migrating from DAS to DRA in OpenShift: The Pragmatic Guide

Prerequisites for the DRA Stack

Phase 1: Scorched Earth (Decommissioning DAS)

Phase 2: Deploying the DRA Driver

Phase 3: Rewriting Your Pod Manifests

Operator Dependencies

Debugging DRA Allocations

The NVLink Bonus: ComputeDomains

Summary

External References

DNS Governance for OpenShift Beginners: A Friendly Guid

Wait, Why Should I Care About DNS?

What Even Is DNS in OpenShift?

What's RHACM and Why Do I Need It?

The Four Things We Need to Monitor

1. Is the DNS Operator Happy?

2. Is the Corefile Correct?

3. Are All DNS Pods Running?

4. Do We Get Alerted?

Let's Build It: Step-by-Step

Prerequisites

Step 1: Clone the Repository

Step 2: Create the Policy Namespace

Step 3: Bind Your ClusterSet

Step 4: Apply the DNS Policies

Step 5: Point to Your Cluster

Step 6: Check Compliance

What Does Each Policy Actually Do?

Policy 1: operator-health-check

Policy 2: corefile-integrity

Policy 3: resource-exhaustion

Policy 4: dns-alerting-rule

Why "Inform" Instead of "Enforce"?

Wrapping Up

Quick Reference

How to Automate ADR Reviews and Keep Your Architectural Decisions in Sync with Your Codebase

The Problem Nobody Talks About

Prerequisites

Full Prompt

Step 1: Initiate the ADR Review

Step 2: Interpret Compliance Scores

Step 3: Handle Each Case

Case 1: Full Implementation (Score ≥ 8.0)

Case 2: Partial Implementation (5.0 ≤ Score < 8.0)

Case 3: Code Implements a Better Solution

Case 4: Not Implemented (Score < 5.0)

Step 4: Generate the Final Report

Summary Table Template

Full Example Workflow

Integration Tips

Schedule Regular Reviews

CI/CD Integration

Team Workflow

Benefits of Automated ADR Synchronization

Conclusion

A Deep Dive into Multi-Transport Protocol Abstraction in Python

The Challenge: One Client, Three Protocols

The Solution: The MCPClient Class

The Magic of the Async Context Manager

A Clean and Consistent API

Visualizing the Abstraction

The Solution: The `MCPClient` Class

1️⃣ Store Version in `version.py`

2️⃣ Use It in `setup.py`

3️⃣ Sync with `pyproject.toml` (for Poetry)

Lock Dependencies in `requirements.txt`

Using `bump-my-version` for Automated Versioning

What is `bump-my-version`?

1. Why is `bump2version` no longer recommended?

3. Should I use `setup.py` or Poetry?

4. Do I still need `requirements.txt` if using Poetry?

5. Is `bump-my-version` required?