<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ozgur Demir on Medium]]></title>
        <description><![CDATA[Stories by Ozgur Demir on Medium]]></description>
        <link>https://medium.com/@ozgurcd?source=rss-315f32aecc78------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*SNEnZaIoTjcd7r1nfGVTug.jpeg</url>
            <title>Stories by Ozgur Demir on Medium</title>
            <link>https://medium.com/@ozgurcd?source=rss-315f32aecc78------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 08:42:50 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@ozgurcd/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Following up on last week’s launch of gograph — I decided to run the tool on its own source code to…]]></title>
            <link>https://medium.com/@ozgurcd/following-up-on-last-weeks-launch-of-gograph-i-decided-to-run-the-tool-on-its-own-source-code-to-4b787104ebb5?source=rss-315f32aecc78------2</link>
            <guid isPermaLink="false">https://medium.com/p/4b787104ebb5</guid>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[developer-tools]]></category>
            <category><![CDATA[static-analysis]]></category>
            <dc:creator><![CDATA[Ozgur Demir]]></dc:creator>
            <pubDate>Sun, 24 May 2026 15:38:07 GMT</pubDate>
            <atom:updated>2026-05-24T15:38:07.166Z</atom:updated>
            <content:encoded><![CDATA[<p>Following up on last week’s launch of gograph — I decided to run the tool on its own source code to demo what gograph can actually do and how you can use it to slash token waste, trace error flows, and map codebases instantly.</p><p>What happens when a static analysis engine indexes itself?</p><p>The parsing completed in under 350ms, producing a complete queryable mathematical graph:<br>16 Go Packages | 70 Files | 518 AST Symbols | 5,443 Call Edges</p><p>The results perfectly demonstrate why structured call-graph mapping is a major leap forward from primitive text searches (like standard grep) when onboarding, debugging, or feeding context to AI coding agents (Claude Code, OpenCode, Cursor, Windsurf, Google Antigravity).</p><p>By analyzing gograph with itself, we captured insights that usually take hours of manual navigation:<br>* Mapped the most highly-coupled structural hotspots (gograph hotspot)<br>* Isolated the precise return and wrap sites for a specific error in &lt;10ms (gograph errorflow)<br>* Calculated the exact transitive downstream blast radius of a signature change (gograph plan)<br>* Synthesized a symbol’s entire architectural narrative in 6 clean lines of text (gograph explain)</p><p>If you are looking to drastically reduce token bloat for your coding agents or secure deterministic codebase navigation, this case study shows the tool in action.</p><p>Check out the full technical deep-dive and command logs:<br><a href="https://ozgurcd.github.io/gograph/posts/analyzing-go-codebase-with-gograph/">https://ozgurcd.github.io/gograph/posts/analyzing-go-codebase-with-gograph/</a></p><p>#golang #staticanalysis #softwareengineering #developerproductivity #mcp #opensource</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4b787104ebb5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Gograph, a Token-Optimized Codebase Map for Go Developers]]></title>
            <link>https://medium.com/@ozgurcd/gograph-a-token-optimized-codebase-map-for-go-developers-01570027ab77?source=rss-315f32aecc78------2</link>
            <guid isPermaLink="false">https://medium.com/p/01570027ab77</guid>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[developer-tools]]></category>
            <category><![CDATA[vibe-coding]]></category>
            <category><![CDATA[golang]]></category>
            <dc:creator><![CDATA[Ozgur Demir]]></dc:creator>
            <pubDate>Sat, 09 May 2026 17:01:23 GMT</pubDate>
            <atom:updated>2026-05-09T17:50:58.124Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Why I Built GoGraph: Giving AI Coding Agents Their Vision Back</strong></p><p>If you’ve spent any time pair-programming with AI coding agents like Claude Desktop, Cursor, or Cline, you know the cycle: It starts out amazing. You ask it to build a new feature, and it executes perfectly. But as your repository grows to dozens of files and hundreds of functions, the agent starts to slip. It forgets how your authentication middleware is wired, it hallucinates struct fields, or it completely misses an interface implementation.</p><p>When you peek into the agent’s internal logs to see what’s going wrong, you almost always see the same frantic behavior:</p><pre>grep -r &quot;ValidateUser&quot; .<br>cat internal/auth/user.go<br>grep -r &quot;Database&quot;</pre><p>Agents aren’t bad at coding — they are just functionally blind. They are forced to explore modern codebases the way humans did in 1995: by blind text search. When an agent runs <em>grep</em>, it usually pulls in hundreds of irrelevant lines. It quickly hits its context window limit, drops half of your project from its active memory, and begins writing broken, contextually unaware code.</p><p><strong>The Search for Context</strong></p><p>I knew I needed a tool to map my Go codebase and feed it to the AI as a structural map. I looked around at the ecosystem. There are several amazing “repo mapping” tools out there. However, many of them involve setting up external vector databases, managing heavy dependencies, or firing off embeddings APIs over the network.</p><p>While those approaches are incredibly powerful and probably the right choice for massive enterprise scale, I just wanted something simple, static, and local. I wanted a fast CLI tool I could drop into my repository that would generate a map without any network overhead or heavy setup.</p><p>When I couldn’t find exactly what I was looking for, I decided to build it myself.</p><p>Enter <strong>gograph</strong>.</p><p><strong>What is GoGraph?</strong></p><p><strong>gograph</strong> is a local, AST-based repository context indexer specifically designed for Go. It doesn’t use regular expressions to guess your structure, nor does it use embeddings. Instead, it relies on the Go standard library’s <strong>go/ast</strong> parser to deeply analyze your repository and map out exactly how everything connects.</p><p>When you run:</p><p><strong>gograph build</strong></p><p>It parses your <em>.go</em> files and produces a highly compressed, token-optimized set of Markdown reports in a <em>.gograph/</em> folder. Instead of grepping blindly, your AI agent can just read <em>.gograph/GRAPH_REPORT.md</em> and instantly understand the shape of your project.</p><p><strong>What Does the AI Actually See?</strong></p><p>Instead of reading raw code, the AI gets a clean, tabular view of your architecture. For example, it automatically extracts <strong>External Dependencies</strong></p><pre>| Module | Version |<br>| - - - - | - - - - -|<br>| github.com/gin-gonic/gin | v1.9.1 |<br>| github.com/jackc/pgx/v5 | v5.5.5 |<br>It also maps out Important Symbols:<br>| Symbol | Kind | File | Line | Calls out |<br>| - - - - | - - - | - - - | - - - | - - - - - -|<br>| (Server).Start | method | server.go | 42 | 18 |<br>| ValidateAuth | function | auth.go | 12 | 14 |</pre><p>But it goes much deeper than just listing functions. By parsing the AST, <em>gograph</em> extracts context that usually requires reading dozens of files:</p><p>- <strong>HTTP Routes:</strong> It finds where you define <strong>GET /api/users</strong> and maps it to the exact handler function.</p><p>- <strong>SQL Queries:</strong> It extracts raw database queries and ties them to the function that executes them.</p><p>- <strong>Concurrency:</strong> It maps goroutine spawns, channel usages, and Mutex locks (crucial for an AI trying to debug a race condition!).</p><p>- <strong>Tests:</strong> It maps which test functions exercise which production symbols.</p><p>- <strong>Environment Variables:</strong> It surfaces every <strong>os.Getenv</strong> or <strong>viper.Get</strong> call so the AI knows your config surface.</p><p><strong>Why Go is Uniquely Hard for AI: Implicit Interfaces</strong></p><p>If you program in Java or TypeScript, an AI can simply grep for the word <em>implements</em> to figure out what a class does. Go doesn’t work like that. Go uses <em>duck typing </em>— if a struct has the right methods, it implicitly satisfies the interface.</p><p>Because there is no keyword to search for, AI agents are notoriously terrible at figuring out which structs implement which interfaces in Go.</p><p><strong>gograph</strong> solves this. Because it builds an AST map of all methods and signatures, it can perform best-effort duck-typing analysis completely statically. An agent can simply run:</p><pre>gograph implementers &quot;UserRepository&quot;</pre><p>And instantly see every struct in the codebase that satisfies that interface, without ever needing to run the Go compiler.</p><p><strong>Real-World Example: “The Blast Radius”</strong></p><p>Imagine you ask your AI to change the signature of the <em>ValidateUser</em> function. Usually, the AI successfully updates the function itself, but it forgets to update the 5 other packages that call it. You go to compile, and your build is broken.</p><p>With <strong>gograph</strong>, the AI agent can query the “<em>blast radius</em>” of its changes before it makes them:</p><pre>gograph impact &quot;ValidateUser&quot;</pre><p>This command recursively traces the call graph and returns every downstream caller. The AI instantly knows exactly which 5 files it needs to modify to keep the build green.</p><p><strong>Solving Token Exhaustion with Categorical Splits</strong></p><p>Originally, I dumped all this information into one giant Markdown file. But I quickly realized I was recreating the exact problem I set out to solve: if I give the AI a 30KB map, I’m burning precious context tokens on HTTP routes when the AI is just trying to debug a database query.</p><p>So <strong>gograph</strong> uses a categorical split. It generates a tiny index file and 8 highly targeted files:</p><pre>- graph-symbols.md<br>- graph-routes.md<br>- graph-sql.md<br>- graph-concurrency.md<br>- graph-tests.md<br>- graph-deps.md<br>- graph-errors.md<br>- graph-config.md</pre><p>The AI reads the index, realizes it only needs to look at `graph-sql.md`, and completely ignores the rest. It gets the exact context it needs for a fraction of the token cost.</p><p><strong>The Token Cost Breakdown</strong></p><p>To put it in perspective, here is what it costs to answer a simple architectural question like <em>*”What functions call IssueToken?”*</em> in a mid-sized Go service (~50 files):</p><pre>| Approach | Approximate Tool Calls | Approximate Tokens Consumed |<br>| - -| - -| - -|<br>| The Old Way (Grep + read raw files) | 6–12 | ~15,000 to 25,000 |<br>| GoGraph (gograph callers IssueToken) | 1 | &lt; 100 tokens |</pre><p>This doesn’t just prevent hallucination; it literally saves API costs and keeps the context window wide open for the actual code generation.</p><p><strong>The “Capabilities” Trick</strong></p><p>The best part of `gograph` is how you integrate it with your AI. You don’t need a massive, complex system prompt anymore. You just tell your agent to run:</p><pre>gograph capabilities</pre><p>The tool intercepts the agent and prints a strict, system-prompt style cheat sheet directly to the AI’s standard output:</p><pre>gograph: AST-aware Repository Navigation Tool for AI Agents<br>INSTRUCTIONS FOR AI AGENTS:<br>Use gograph first for repo navigation; use grep/raw reads only when the graph lacks detail or exact source is needed.<br>Use gograph to understand repository structure, dependencies, and call graphs.<br>COMMANDS (token-optimized):<br>build . : parse AST, gen GRAPH_REPORT.md &amp; .gograph/*<br>query &lt;str&gt; : search symbols/files/pkgs<br>focus &lt;pkg&gt; : isolate context for a package<br>callers &lt;fn&gt; : who calls fn<br>callees &lt;fn&gt; : what fn calls<br>impact &lt;sym&gt; : blast radius (downstream callers)<br>source &lt;sym&gt; : exact code of sym<br>node &lt;sym&gt; : AST info of sym<br>fields &lt;struct&gt; : fields/types of struct<br>embeds &lt;struct&gt; : structs embedding this struct<br>interfaces &lt;struct&gt; : duck-type interface check<br>implementers &lt;iface&gt; : structs implementing iface<br>public &lt;pkg&gt; : exported API of pkg<br>routes : HTTP REST routes<br>sql : raw SQL queries mapped<br>errors : custom errors/panics<br>envs [str] : os.Getenv/viper reads<br>concurrency [str] : goroutines/channels/mutexes<br>tests &lt;sym&gt; : tests exercising sym<br>orphans : 0 incoming calls (dead code)<br>imports &lt;pkg&gt; : trace external/internal usage</pre><p>The AI reads this, instantly understands it shouldn’t be using <em>grep</em> blindly anymore, and switches to using <strong>gograph</strong>’s native CLI commands to explore the AST.</p><p><strong>The Ultimate Setup: Native MCP Integration</strong></p><p>If you use a client like Claude Desktop or Cursor, you don’t even have to make the AI type commands in a terminal. `gograph` includes a built-in <strong>Model Context Protocol (MCP)</strong> server.</p><p>By adding a simple configuration to your client:</p><pre>gograph mcp .</pre><p>The AI instantly gets all of `gograph`’s capabilities exposed as native, clickable “Tools.” It can query your call graph, extract SQL, and check interface satisfactions autonomously over standard I/O — without any external network connections.</p><p><strong>I Could Be Wrong</strong></p><p>I built `gograph` to scratch my own itch, and it has drastically improved how I work with AI agents in Go. That said, I am well aware that my approach might not be the best. AST parsing has limitations, “best-effort” duck-typing isn’t perfect, and there might be much better ways to inject context into LLMs that I haven’t considered.</p><p>If you think I’ve gotten something wrong, or if you know of a better approach to solving agent token exhaustion, I would love to hear from you. Please reach out, open an issue, or drop a comment!</p><p>If you want to try it out yourself, the tool is completely open-source. Grab the binary and drop it in your path:</p><pre>go install github.com/ozgurcd/gograph@latest</pre><p>Give your AI the context it needs.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=01570027ab77" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing Kamaji: A new CLI tool for DevOps.]]></title>
            <link>https://medium.com/@ozgurcd/introducing-kamaji-a-new-cli-tool-for-devops-2fc2363fe900?source=rss-315f32aecc78------2</link>
            <guid isPermaLink="false">https://medium.com/p/2fc2363fe900</guid>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[bazel]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[sre]]></category>
            <category><![CDATA[terraform]]></category>
            <dc:creator><![CDATA[Ozgur Demir]]></dc:creator>
            <pubDate>Mon, 17 Feb 2025 01:29:39 GMT</pubDate>
            <atom:updated>2025-02-17T01:33:11.446Z</atom:updated>
            <content:encoded><![CDATA[<p>In several of the organizations I’ve worked with, we’ve leveraged <strong>Bazel</strong> beyond its traditional role as a build system — using it as a powerful <strong>DevOps automation tool</strong>. While Bazel is primarily designed for building and testing software, its <strong>extensibility</strong> allows it to serve as a <strong>unified wrapper around multiple CLI tools</strong>, making it possible to <strong>inject authentication, dynamically configure environments, and pass CLI arguments seamlessly</strong> — all while streamlining complex infrastructure workflows.</p><p>By defining tasks declaratively and leveraging Bazel’s robust caching and dependency management, we’ve been able to orchestrate everything from provisioning cloud resources to managing Kubernetes deployments with <strong>reproducibility and efficiency</strong>.</p><p>I previously wrote an article detailing how we leveraged <strong>Bazel’s extensibility</strong> for <strong>DevOps and infrastructure management</strong>, which you can find here: <a href="https://medium.com/@ozgurcd/bazel-for-devops-and-infrastructure-management-60ce39a76d72">Bazel for DevOps and Infrastructure Management</a>.</p><p>One of the challenges we faced in our workflows was <strong>updating Terraform files</strong> whenever we upgraded Terraform versions. With Bazel, we solved this by <strong>declaring Terraform versions in the BUILD file for each directory</strong>, allowing us to <strong>use different Terraform versions in separate directories</strong> without modifying the actual Terraform files.</p><p>While Bazel worked well for this purpose and served us reliably for a long time, it <strong>was never designed with DevOps automation in mind</strong> — making it <strong>a heavyweight solution for tasks outside of its original scope</strong>. Additionally, major version changes introduced breaking changes that forced us to make adjustments <strong>just to keep Bazel working</strong>, which felt like an unnecessary burden.</p><p>This led me to create <strong>Kamaji</strong> — a tool <strong>inspired by Bazel</strong>, but <strong>tailored specifically for DevOps workflows</strong>. Unlike Bazel, <strong>Kamaji</strong> <strong>adapts only the necessary features</strong> and provides a <strong>lightweight, streamlined alternative</strong> without the overhead of a full-fledged build system. It retains the benefits of <strong>declarative task execution, caching, and extensibility</strong>, but in a way that is more <strong>intuitive, maintainable, and purpose-built</strong> for infrastructure automation.</p><p>You can find <strong>Kamaji</strong> on GitHub: <a href="https://github.com/ozgurcd/kamaji">https://github.com/ozgurcd/kamaji</a>.</p><p>Inside the repository, you’ll find a <strong>rules directory</strong>, which serves as the <strong>extensions directory</strong> for Kamaji. While the core tool is built in <strong>Go</strong>, the <strong>extensions are written in Python</strong> — allowing for flexibility and ease of development.</p><p>To demonstrate how Kamaji simplifies infrastructure management, I’ll be sharing a <strong>sample extension for Terraform</strong>. In the future, I plan to add more extensions for <strong>kubectl, kubeseal, and Helm</strong>, making Kamaji even more versatile for Kubernetes workflows.</p><p>I hope you find <strong>Kamaji</strong> useful and that it helps streamline your <strong>DevOps workflows</strong>. Your <strong>feedback, contributions, and suggestions</strong> are highly welcome! Feel free to <strong>try it out</strong>, explore the repository, and let me know your thoughts</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2fc2363fe900" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Bazel for DevOPS and Infrastructure Management]]></title>
            <link>https://medium.com/@ozgurcd/bazel-for-devops-and-infrastructure-management-60ce39a76d72?source=rss-315f32aecc78------2</link>
            <guid isPermaLink="false">https://medium.com/p/60ce39a76d72</guid>
            <category><![CDATA[infrastructure-as-code]]></category>
            <category><![CDATA[kubernetes]]></category>
            <category><![CDATA[bazel]]></category>
            <category><![CDATA[devops-tool]]></category>
            <category><![CDATA[devops]]></category>
            <dc:creator><![CDATA[Ozgur Demir]]></dc:creator>
            <pubDate>Wed, 17 Apr 2024 22:06:53 GMT</pubDate>
            <atom:updated>2024-04-17T22:06:53.459Z</atom:updated>
            <content:encoded><![CDATA[<p>Bazel, a tool developed by Google, is best known for its ability to handle large and complex software builds quickly and accurately, especially in multi-language monorepos. However, this article will show that Bazel has much more to offer for DevOPS Engineers.</p><p>Bazel is well-known for managing software builds, but it also simplifies using other tools, like Terraform, which manages infrastructure through code. By automating essential tasks such as setting up authentication and streamlining configuration settings, Bazel enhances system efficiency, simplifies management and ensures standardization.</p><h3><strong>Understanding Bazel’s Basics</strong></h3><p>At its core, Bazel is designed to support large-scale software builds with speed and accuracy. It achieves this by utilizing a highly efficient incremental build process. Bazel operates by constructing a directed acyclic graph (DAG) that maps out all the dependencies within the project. This graph allows Bazel to precisely determine which parts of the project need to be rebuilt when a change is made, thus minimizing build time.</p><p>Bazel’s build configurations are defined in files called BUILD.bazel or simply BUILD, where each file specifies a set of build rules. These rules describe how to produce outputs from inputs and can include anything from compiling a piece of software to packaging deployable containers.</p><p>Let’s create a custom Bazel rule, with the purpose of creating ephemeral containers in a Kubernetes cluster, leveraging Kubernetes (kubectl) and AWS configurations.</p><p><strong>Setting Up the WORKSPACE File</strong></p><p>First, we need to create a directory that will house our project. This directory will also include a file named WORKSPACE as well as other Bazel configurations.</p><pre>mkdir ExtendingBazel<br>cd ExtendingBazel<br>touch WORKSPACE</pre><p>Now we need to initialize WORKSPACE file since it is essential for a Bazel project. It is being used to mark the root directory of our project as well as managing external dependencies. Open the WORKSPACE file in your favorite text editor and put the following content.</p><pre>workspace(name=&quot;extending-bazel&quot;)<br><br># As Bazel generally manages all dependencies, using locally installed tools like kubectl<br># is not standard. However, for tasks like deploying to Kubernetes with existing tools,<br># it&#39;s acceptable to use system-installed binaries for simplicity and ease of integration.<br><br># At this stage, no external Bazel-managed dependencies are defined here.<br># This setup acknowledges that kubectl is pre-installed on the local system<br># and Bazel is being used mainly as an orchestrator rather than a build tool.</pre><p>Using kubectl directly from your local installation is definitely contrary to Bazel&#39;s principles, which typically emphasize having a completely reproducible build environment by managing all dependencies. However, in this case, we are leveraging Bazel as a wrapper for operational and deployment tasks rather than for building software from source.</p><p>This approach simplifies the setup and uses Bazel to orchestrate deployment processes, thus maintaining the benefits of Bazel’s efficient execution environment without complicating your setup with additional toolchain management overhead. It’s a practical solution when you are managing infrastructure where the environment consistency provided by Bazel for builds is less critical compared to the deployment commands being executed.</p><p><strong>Create the Custom Rules Directory</strong></p><p>Now we will create a directory that house our custom Bazel rule definitions (.bzl files) that we will create. Keeping these separate from others parts of software we would use helps in maintaining clarity and modularity.</p><pre>mkdir -p bazel/ephemeral-containers</pre><p>We will create a top-level (under our project directory) directory named bazel, then we will create another one (ephemeral-containers) under it.</p><p><strong>Prepare a Custom Rule File</strong></p><p>Within the ephemeral-containers directory, start by creating a .bzl file which will contain the Starlark code for our custom Bazel rule focused on ephemeral container management.</p><pre>touch bazel/ephemeral-containers/ephemeral.bzl</pre><p>So, what is Starlark?</p><p>Starlark is a dialect of Python designed specifically for the Bazel build system. It is used for writing Bazel build and configuration files. The language is intentionally limited in some aspects to ensure builds are reproducible, hermetic, and deterministic. For example, it lacks some Python features like recursion and certain built-in functions, which could introduce non-determinism in the build process.</p><p><strong>Basic Rule Definition</strong></p><p>Open the ephemeral.bzl file and write the basic structure of our Bazel custom rule.</p><pre># bazel/ephemeral-containers/ephemeral.bzl<br><br>&quot;&quot;<br>def _create_ephemeral_impl(ctx):<br>    ctx.actions.expand_template(<br>        template = ctx.file._template,<br>        output = ctx.outputs.executable,<br>        substitutions = {<br>            &quot;%{KUBECTL_CONFIG}&quot;: ctx.attr.kubectl_config,<br>            &quot;%{NAMESPACE}&quot;: ctx.attr.namespace,<br>            &quot;%{AWS_PROFILE}&quot;: ctx.attr.aws_profile,<br>            &quot;%{CONTAINER_IMAGE}&quot;: ctx.attr.container_image,<br>        },<br>        is_executable = True,<br>    )<br>    return []<br><br>create_ephemeral = rule(<br>    attrs = {<br>        &quot;kubectl_config&quot;: attr.string(mandatory = True),<br>        &quot;namespace&quot;: attr.string(mandatory = True),<br>        &quot;aws_profile&quot;: attr.string(),<br>        &quot;container_image&quot;: attr.string(default = &quot;ubuntu:latest&quot;),<br>        &quot;_template&quot;: attr.label(<br>            default = Label(&quot;//bazel/ephemeral-containers/templates:ephemeral.py.tpl&quot;),<br>            allow_single_file = True,<br>        ),<br>    },<br>    executable = True,<br>    implementation = _create_ephemeral_impl,<br>)</pre><p>Let’s decipher all these fuzz.</p><p>We begin by defining a rule named “create_ephemeral” using the rule() constructor:</p><pre>create_ephemeral = rule()</pre><p>Here’s what each component does:</p><ul><li><strong>implementation </strong>This is a reference to the function _create_ephemeral_impl, which contains the logic that Bazel executes when this rule is invoked. The function uses the provided attributes to configure and crate and executable script by using a template.</li><li><strong>attr, attributes <br> kubectl_config: </strong>A mandatory attribute that expects a string. This string should specify the path to the Kubernetes config file used by <em>kubectl. </em>This configuration enables the script to interact with our Kubernetes cluster.<br><strong>namespace: </strong>A mandatory attribute that expects a string. This string should specify the namespace the ephemeral container will be created in.<br><strong>aws_profile: </strong>An optional attribute that also expects a string. It specifies the AWS profile to use, which configures access credentials for AWS services, including EKS if applicable. If our Kubernetes cluster is not on AWS, we don’t need to set it.<br><strong>container_image: </strong>This attribute defaults to “ubuntu:latest” but can be overriden to specify a Linux container image. This image will be used when deploying our ephermeral container.<br><strong>_template: </strong>The hidden attribute (_ prefix indicates that it’s not indented for external use) references a template file. This file is expected to be a single file (as indicated by <em>allow_single_file = True) </em>and contains the Python script template that will be converted into an executable.</li><li><strong>executable </strong>This flag tells Bazel that the output of this rule is an executable file. When you run this rule via Bazel, it generates an executable based on the “_template”, with the attributes substituted into the template’s placeholders.</li></ul><p>The purpose of using these attributes is to pass dynamic configurations into the script, allowing for flexible deployments without hardcoding values directly into the script. The template mechanism ensures that the core deployment logic can remain stable even as the deployment parameters change, such as switching Kubernetes clusters, AWS profiles, or container images.</p><p>By encapsulating the deployment logic in a Bazel rule, we standardize the process of deploying ephemeral containers and make it repeatable across different environments or stages of development, testing, and production. This approach leverages Bazel’s strengths in managing build and deployment environments in a consistent and reproducible manner.</p><p>This file forms the backbone of our ephemeral container deployment strategy, integrating closely with both Kubernetes and AWS effectively. With this setup, users can simply update the attributes in their Bazel BUILD files to reflect the desired deployment configuration, making the process both efficient and error-resistant.</p><p><strong>Breaking Down _create_ephemeral_impl Function</strong></p><p>Our rule implements a Starlark function called _create_ephemeral_impl if you remember. Let’s take a look at it.</p><ul><li><strong>ctx Parameter</strong> <em>ctx</em> is a context object that populated by Bazel and contains information about rule’s invocation, including attributes, files and dependencies. It is passed to the implementation function by Bazel.</li><li><strong>ctx.actions.expand_template </strong>This is a method provided by Bazel to generates files from a given template. It’s especially useful for creating configuration files, scripts, or any other type of file where you need to inject values in a predefined format.</li><li><strong>Parameters of <em>expand_template<br></em>template: </strong>This is the template file that the function will use as a base to generate the output. <em>ctx.file_template</em> references the template file defined in the rule attributes. In this case, it points to a Python script template (ephemeral.py.tpl under the directory //bazel/ephemeral-containers/templates directory. // means the root directory of your project)<br><strong>output: </strong>This is the file that will produces by the function. <em>ctx.output.executable </em>tells Bazel that the output of expanding the template will be an executable file, when this rule is run. <br><strong>substitutions: </strong>A dictionary of placeholder values in the template that will be replaced with the actual values. These values are pulled from the attributes of the rule (<em>kubectl_config</em>, <em>namespace</em>, <em>aws_profile</em> and <em>container_image</em>). Placeholder format is %{PLACEHOLDER} in this template to ensure they are distinctly recognizable and unlikely to clash with any other text.<br><strong>is_executable: </strong>This boolean flag, when set to True, makes the output file executable. This is important for script files that need to be run as commands.</li><li><strong>Return Value </strong>The function returns an empty list, indicating that it does not provide any additional information to Bazel about the output beyond what was specified in the rule’s definition. In more complex scenarios, this could return other type of information needed by Bazel to handle files or dependencies created by the rule such as configuration files.</li></ul><p>The primary purpose of this implementation function is to automate the creation of an executable script that can perform our main business logic based on parameters specified when the rule is invoked.</p><p><strong>Directory Structure</strong></p><p>Now we need to create the specified template file in given directory</p><pre>mkdir -p bazel/ephemeral-containers/templates<br>touch  bazel/ephemeral-containers/templates/ephemeral.py.tpl</pre><p>then, using fill the file with the following content</p><pre>#!/usr/bin/env python3<br># bazel/ephemeral-containers/templates/ephemeral.py.tpl<br><br>import argparse<br><br>def _main():<br>    parser = argparse.ArgumentParser(allow_abbrev=False)<br>    parser.add_argument(&#39;--kubectl_config&#39;, default=&#39;%{KUBECTL_CONFIG}&#39;)<br>    parser.add_argument(&#39;--namespace&#39;, default=&#39;%{NAMESPACE}&#39;)<br>    parser.add_argument(&#39;--aws_profile&#39;, default=&#39;%{AWS_PROFILE}&#39;)<br>    parser.add_argument(&#39;--container_image&#39;, default=&#39;%{CONTAINER_IMAGE}&#39;)<br><br>    flags, args = parser.parse_known_args()<br><br>    print(f&#39;kubectl config: {flags.kubectl_config}&#39;)<br>    print(f&#39;namespace: {flags.namespace}&#39;)<br>    print(f&#39;aws profile: {flags.aws_profile}&#39;)<br>    print(f&#39;container image: {flags.container_image}&#39;)<br><br>if __name__ == &#39;__main__&#39;:<br>    _main()</pre><p>As you can understand, this is a template file for a Python script. When our bazel rule is invoked, the rule will use this template and replace all the placeholders with given attributes and generates this script, make it an executable then run it.</p><p>Before going ahead, we need to make sure to create an empty BUILD file in each one of the directories we create under //bazel directory except the one in bazel/ephemeral-containers/templates. The content of the BUILD file in this directory should be:</p><pre>exports_files(glob(<br>    [&quot;*.py.tpl&quot;,<br>    &quot;*.py&quot;]<br>    ))</pre><p>This command tells Bazel to export all Python template files (.py.tpl) and any Python files (.py). This setup allows these files to be used across the Bazel workspace, particularly by the rule that generates the executable.</p><p>At this stage our directory structure should be as below:</p><pre>bazel/<br>├── BUILD (empty, unless specific rules or dependencies are defined here)<br>├── ephemeral-containers/<br>│   ├── BUILD<br>│   ├── ephemeral.bzl  # Contains the Bazel rule definition<br>│   └── templates/<br>│       ├── BUILD  # Contains exports_files to make templates available<br>│       └── ephemeral.py.tpl  # Python script template</pre><p>Now, let’s create another directory under the top level as our working area while using the rule we created.</p><pre>mkdir work<br>touch work/BUILD</pre><p>This BUILD file will have the following content</p><pre>load(&quot;//bazel/ephemeral-containers:ephemeral.bzl&quot;, &quot;create_ephemeral&quot;)<br><br>create_ephemeral(<br>    name = &quot;dev-ephemeral-container&quot;,<br>    kubectl_config = &quot;~/.kube/dev-kubeconfig.yaml&quot;,<br>    aws_profile = &quot;test-profile&quot;,<br>    namespace = &quot;test-ns&quot;,<br>)<br><br>create_ephemeral(<br>    name = &quot;staging-ephemeral-container&quot;,<br>    kubectl_config = &quot;~/.kube/staging-kubeconfig.yaml&quot;,<br>    aws_profile = &quot;staging-profile&quot;,<br>    namespace = &quot;test-ns&quot;,<br>)</pre><p>The work/BUILD file in our Bazel project is strategically setup to manage the deployment of ephemeral containers across different environments using the custom Bazel rule we’ve defined previously. This file is crucial for organizing our deployment workflows distinctly for dev and staging environments, ensuring each environment is configured appropriately.</p><p>Let’s take a look what’s going on in this file.</p><p><strong>load()</strong> keyword loads the custom Bazel rule from the given path, in our case the custom rule name is “create_ephemeral” and the given path is //bazel/ephemeral-containers:ephemeral.bzl. Again, // means the top level directory of our project, which contains the WORKSPACE file. This path means ephemeral.bzl file under the //bazel/ephemeral-containers directory.</p><p>then, we use the loaded <em>create_ephemeral </em>rule and create a target with the name “dev-ephemeral-container”, also we are providing the necessary attributes kubectl_config, aws_profile, namespace and container_image.</p><p>Similarly, we also crate another target with the same rule with the name “staging-ephemeral-container”.</p><p>Please notice that each target has different set of attributes and the rule being used will act differently according to these different values.</p><p>Now take a look at the directory structure again:</p><pre>bazel/<br>├── BUILD (empty, unless specific rules or dependencies are defined here)<br>└── ephemeral-containers/<br>    ├── BUILD<br>    ├── ephemeral.bzl  # Contains the Bazel rule definition<br>    └── templates/<br>        ├── BUILD  # Contains exports_files to make templates available<br>        └── ephemeral.py.tpl  # Python script template<br><br>work/<br>└── BUILD (our custom target are defined here)<br></pre><p>At this stage, we can now run and test our custom rule.</p><p>While in any directory under the project, open a shell and issue the following commands and see their outputs:</p><pre>$ bazel run :dev-ephemeral-container<br>INFO: Analyzed target //work:dev-ephemeral-container (0 packages loaded, 0 targets configured).<br>INFO: Found 1 target...<br>Target //work:dev-ephemeral-container up-to-date:<br>  bazel-bin/work/dev-ephemeral-container<br>INFO: Elapsed time: 0.083s, Critical Path: 0.00s<br>INFO: 2 processes: 2 internal.<br>INFO: Build completed successfully, 2 total actions<br>INFO: Running command line: bazel-bin/work/dev-ephemeral-container<br>kubectl config: ~/.kube/dev-kubeconfig.yaml<br>namespace: test-ns<br>aws profile: test-profile<br>container image: ubuntu:latest<br><br><br>$ bazel run :staging-ephemeral-container<br>INFO: Analyzed target //work:staging-ephemeral-container (0 packages loaded, 1 target configured).<br>INFO: Found 1 target...<br>Target //work:staging-ephemeral-container up-to-date:<br>  bazel-bin/work/staging-ephemeral-container<br>INFO: Elapsed time: 0.097s, Critical Path: 0.01s<br>INFO: 5 processes: 5 internal.<br>INFO: Build completed successfully, 5 total actions<br>INFO: Running command line: bazel-bin/work/staging-ephemeral-container<br>kubectl config: ~/.kube/staging-kubeconfig.yaml<br>namespace: test-ns<br>aws profile: staging-profile<br>container image: ubuntu:latest</pre><p>As you can see, our custom rule created the python script and executed it. Our Python template script did read the arguments of this executable provided by Bazel and dumped them to the console.</p><p>Now that we created our boilerplate project, we can expand the template more to implement our business logic.</p><p>First, let’s detect if we have kubectl installed.</p><pre>#!/usr/bin/env python3<br><br># bazel/ephemeral-containers/templates/ephemeral.py.tpl<br><br>import argparse<br>import subprocess<br><br>def getKubectlPath():<br>    try:<br>        path = subprocess.check_output([&#39;which&#39;, &#39;kubectl&#39;]).decode(&#39;utf-8&#39;).strip()<br>    except subprocess.CalledProcessError as e:<br>        print(&quot;Error: kubectl not found in path, please install and add to PATH&quot;)<br>        exit(1)<br>    <br>    return path<br><br>def _main():<br>    parser = argparse.ArgumentParser(allow_abbrev=False)<br>    parser.add_argument(&#39;--kubectl_config&#39;, default=&#39;%{KUBECTL_CONFIG}&#39;)<br>    parser.add_argument(&#39;--namespace&#39;, default=&#39;%{NAMESPACE}&#39;)<br>    parser.add_argument(&#39;--aws_profile&#39;, default=&#39;%{AWS_PROFILE}&#39;)<br>    parser.add_argument(&#39;--container_image&#39;, default=&#39;%{CONTAINER_IMAGE}&#39;)<br><br>    flags, args = parser.parse_known_args()<br><br>    kubectl_path = getKubectlPath()<br>    print(f&#39;kubectl path: {kubectl_path}&#39;)<br><br>if __name__ == &#39;__main__&#39;:<br>    _main()</pre><p>We created the getKubectlPath() function to detect if our PATH variable contains the <em>kubectl</em> executable, if not exit the program since we can’t work without it. Similarly, we need to check if our PATH variable contains the <em>tmux</em> executable. In the next iteration, we will create a common function <em>getPathOfTool </em>and use it for both <em>kubectl</em> and <em>tmux</em>.</p><p>Let’s run our bazel target at the moment and see the output.</p><pre>$ bazel run :staging-ephemeral-container<br>INFO: Analyzed target //work:staging-ephemeral-container (0 packages loaded, 0 targets configured).<br>INFO: Found 1 target...<br>Target //work:staging-ephemeral-container up-to-date:<br>  bazel-bin/work/staging-ephemeral-container<br>INFO: Elapsed time: 0.072s, Critical Path: 0.00s<br>INFO: 2 processes: 2 internal.<br>INFO: Build completed successfully, 2 total actions<br>INFO: Running command line: bazel-bin/work/staging-ephemeral-container<br>kubectl path: /opt/homebrew/bin/kubectl</pre><p>Let’s add all the business logic in our template Python file, it’s final state is as the following:</p><pre>#!/usr/bin/env python3<br># bazel/ephemeral-containers/templates/ephemeral.py.tpl<br><br>import argparse<br>import subprocess<br>import os<br>import json<br>from datetime import datetime, timezone<br>from pathlib import Path<br>import logging<br><br>logging.basicConfig(level=logging.INFO, format=&#39;%(asctime)s - %(levelname)s - %(message)s&#39;)<br><br>class KubeController:<br>    def __init__(self, kubeconfig, namespace, aws_profile, container_image, target_pod):<br>        self.kubeconfig = Path(kubeconfig).expanduser()<br>        if not self.kubeconfig.exists():<br>            logging.error(f&quot;Error: kubeconfig file not found at {self.kubeconfig}&quot;)<br>            exit(1)<br><br>        self.kubectl_path = self.getPathOfTool(&quot;kubectl&quot;)<br>        self.tmux_path = self.getPathOfTool(&quot;tmux&quot;)<br>        self.namespace = namespace<br>        self.aws_profile = aws_profile<br>        self.container_image = container_image<br>        self.target_pod = target_pod<br><br>        self.pod = self.getPodFromTargetNamespace()<br><br>    def runCommand(self, inShell, command):<br>        envs = {}<br>        org_env = os.environ.copy()<br><br>        envs[&quot;PATH&quot;] = org_env[&quot;PATH&quot;]<br>        envs[&quot;HOME&quot;] = org_env[&quot;HOME&quot;]<br>        envs[&quot;AWS_PROFILE&quot;] = self.aws_profile<br>        envs[&quot;KUBECONFIG&quot;] = self.kubeconfig<br><br>        try:<br>            if inShell:<br>                output = subprocess.check_output(command, shell=True, env=envs, stderr=subprocess.STDOUT)<br>            else:<br>                output = subprocess.check_output(command.split(), shell=False, env=envs, stderr=subprocess.STDOUT)<br>        except subprocess.CalledProcessError as e:<br>            logging.error(f&quot;Failed to execute command: {e}&quot;)<br>            return e.output.decode()<br><br>        return output.decode()<br><br>    def createEphemeralContainer(self):<br>        podName = self.pod[&quot;metadata&quot;][&quot;name&quot;]<br>        session_name = f&quot;ephemeral-{self.pod[&#39;metadata&#39;][&#39;name&#39;]}&quot; + datetime.now(timezone.utc).strftime(&quot;%Y%m%d%H%M%S&quot;)<br><br>        cmdLine = f&quot;{self.tmux_path} new-session -d -s {session_name} {self.kubectl_path} debug -it {podName} -n {self.namespace} -c {session_name} --kubeconfig {self.kubeconfig} --image={self.container_image} &quot;<br>        self.runCommand(True, cmdLine)<br>        print(f&quot;Please run the following command to attach to the debug container:&quot;)<br>        print(f&quot;tmux attach-session -t {session_name}&quot;)<br><br>    def getPodFromTargetNamespace(self):<br>        cmd = f&quot;{self.kubectl_path} get pods --kubeconfig {self.kubeconfig} -n {self.namespace} -o json&quot;<br>        pod_list = self.runCommand(False, cmd)<br>        pod_list = json.loads(pod_list)<br>        if len(pod_list[&quot;items&quot;]) == 0:<br>            logging.error(f&quot;No pods found in namespace: {self.namespace}&quot;)<br>            exit(1)<br><br>        if len(pod_list[&quot;items&quot;]) &gt; 1:<br>            if self.target_pod == &quot;&quot;:<br>                logging.error(&quot;Multiple pods found in namespace: {self.namespace}, please provide --target_pod&quot;)<br>                exit(1)<br>            for pod in pod_list[&quot;items&quot;]:<br>                if pod[&quot;metadata&quot;][&quot;name&quot;] == self.target_pod:<br>                    return pod<br>            logging.error(f&quot;Pod not found: {self.target_pod}&quot;)<br>            exit(1)<br>        else:<br>            return pod_list[&quot;items&quot;][0]<br>        <br>    def getPathOfTool(self, tool):<br>        path = &quot;&quot;<br>        try:<br>            path = subprocess.check_output([&quot;which&quot;, tool]).decode(&quot;utf-8&quot;).strip()<br>        except subprocess.CalledProcessError as e:<br>            logging.error(f&quot;Could not find executable for tool: {tool}, exiting&quot;)<br>            exit(1)<br><br>        return path<br>    <br>def _main():<br>    parser = argparse.ArgumentParser(allow_abbrev=False)<br>    # Following arguments are set by Bazel rule<br>    parser.add_argument(&#39;--kubectl_config&#39;, default=&#39;%{KUBECTL_CONFIG}&#39;)<br>    parser.add_argument(&#39;--namespace&#39;, default=&#39;%{NAMESPACE}&#39;)<br>    parser.add_argument(&#39;--aws_profile&#39;, default=&#39;%{AWS_PROFILE}&#39;)<br>    parser.add_argument(&#39;--container_image&#39;, default=&#39;%{CONTAINER_IMAGE}&#39;)<br>    # Following argument(s) are set by user<br>    parser.add_argument(&#39;--target_pod&#39;, default=&#39;&#39;)<br><br>    flags, args = parser.parse_known_args()<br><br>    if flags.container_image == &quot;&quot;:<br>        logging.error(&quot;Error: container image not provided&quot;)<br>        exit(1)<br><br>    if flags.namespace == &quot;&quot;:<br>        logging.error(&quot;Error: namespace not provided&quot;)<br>        exit(1)<br><br>    k = KubeController(flags.kubectl_config, flags.namespace, flags.aws_profile, flags.container_image, flags.target_pod)<br>    k.createEphemeralContainer()<br><br><br>if __name__ == &#39;__main__&#39;:<br>    _main()</pre><p>Now we can run our custom Bazel target and see the result:</p><pre>bazel run :staging-ephemeral-container<br>INFO: Analyzed target //work:staging-ephemeral-container (0 packages loaded, 0 targets configured).<br>INFO: Found 1 target...<br>Target //work:staging-ephemeral-container up-to-date:<br>  bazel-bin/work/staging-ephemeral-container<br>INFO: Elapsed time: 0.080s, Critical Path: 0.00s<br>INFO: 2 processes: 2 internal.<br>INFO: Build completed successfully, 2 total actions<br>INFO: Running command line: bazel-bin/work/staging-ephemeral-container<br>Please run the following command to attach to the debug container:<br>tmux attach-session -t ephemeral-test-ns-7b4c7769dc-b9sq720240417215847</pre><p>As you can see, Bazel target, successfully created an ephemeral container in a tmux session and printed the necessary command to attach it.</p><p>If you issue the command, you will see that you will access the shell inside the created ephemeral container.</p><pre>$ tmux attach-session -t ephemeral-test-ns-7b4c7769dc-b9sq720240417215847<br><br>If you don&#39;t see a command prompt, try pressing enter.<br>root@test-ns-7b4c7769dc-b9sq7:/#</pre><h3>Conclusion</h3><p>Throughout this guide, we’ve detailed how to leverage Bazel for deploying ephemeral containers in Kubernetes environments, emphasizing automation, reproducibility, and configurability. We’ve set up a custom Bazel rule, crafted a Python script as a templated action, and structured the project to handle different deployment scenarios across development and staging environments.</p><h4>Key Takeaways</h4><p>Custom Bazel Rule: We developed a create_ephemeral rule that dynamically configures and deploys ephemeral containers based on specified parameters. This rule simplifies complex deployment commands into manageable, reproducible Bazel targets.</p><p>Python Scripting: The Python script we created serves as an executable template, performing critical tasks such as interacting with Kubernetes to manage pods and using tmux for session management. It handles command execution securely and logs important actions, providing a robust foundation for deployment automation.</p><p>By adopting Bazel for managing Kubernetes deployments, we leverage a powerful toolchain that brings precision and efficiency to operational workflows. This guide serves as a foundation upon which more complex and tailored automation solutions can be built, aligning with the evolving needs of modern software development and infrastructure management.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=60ce39a76d72" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>