• Chapter 3: Platform Notation

• Chapter 4: Segmentation

• Chapter 5: Identity and Access Management

• Chapter 6: Infrastructure

Let’s dig into the details of this update and what it means for the project.

Platform Notation

One of the biggest challenges I faced while writing this book was keeping it as agnostic from specific cloud providers as possible. Every provider—whether AWS, Azure, or GCP—has its own jargon and subtle behavioral differences (like Accounts vs. Subscriptions vs. Projects). To solve this, I decided to abstract the terminology we will use throughout the book by introducing a Platform Notation.

I explicitly didn’t want to use Terraform or other configuration languages because I want to abstract the reader from such complexities. You shouldn’t need to understand Terraform, Helm, or the like to read this book end-to-end. Instead, this notation is loosely based on the Golang type system, which I find simple and easy to read without all the boilerplate. Anyone familiar with a typed language will understand it quickly.

The notation is built on primitives like Types and Coordinates. For example, a type uses a functional syntax like Name(Parameters):

• Group(Tenant = “payments”, Tier = “live”, Role = “admin”)

• Using positional inference, this becomes even cleaner: Group(”payments”, “live”, “admin”)

The most important concept introduced in this chapter is the coordinate. A coordinate acts as an address for every resource in the platform, expressed as a tuple. Since every resource needs to land somewhere, this coordinate system will become extremely relevant in the next chapter (Segmentation) and will be used everywhere to define boundaries and placements. For example:

• (”ecommerce”, “live”, “eu01”, “payments”) — A fully resolved address.

• (”platform”, “live”, _, _) — An address that ignores the regional and tenant dimensions.

I’m still figuring out the Associations part of the notation (how we express relationships between resources). As I write the book and start relating more resources, I’ll see what symbols are easiest to read. For now, we are experimenting with simple operators like in for hierarchy or <→ for connectivity (e.g., Spoke(...) <-> Hub(...)).

Segmentation

Segmentation is actually the reason why I started writing this book. When you read about platform engineering, there isn’t much written about this topic—you usually have to figure it out yourself. In my opinion, it is one of those things you need to put on the table from day one, even if you don’t implement it fully right away. Migrating to a different segmentation model later on is extremely costly, and you want to avoid that pain. You don’t need to over-engineer it, but you absolutely need to design around it as soon as possible.

Segmentation solves critical problems in modern infrastructure: it drastically reduces the blast radius of failures, lowers cognitive load by giving developers a narrower environment to think about, ensures security and compliance, and allows you to apply different rules for different contexts.

In the book, we configure segmentation across four primary dimensions: Sector, Tier, Region, and Tenant. You can mix and match these, or expand them to better align with your organization, but I’ve found these four give enough flexibility for most companies. For example, you might have an internal Sector(”platform”) and a business Sector(”ecommerce”), separated into Tier(”sandbox”) and Tier(”live”) environments.

The key takeaway is that by using these dimensions, we create clear boundaries (what the book calls Core Space and Tenant Space). Everything we build in the following chapters will rely on these boundaries, meaning our platform is segmented by design. We will discuss segmentation and the nuances of these dimensions in more detail in dedicated articles in the near future.

Identity and Access Management

This chapter is still a work in progress, but it already covers the essential building blocks for protecting platform resources. While I’ve left out general user management (which typically falls under the IT team’s responsibilities), I’ve focused on what’s critical for platform engineering: Groups, Roles, and Federated Identity.

To keep things simple and secure, I’ve standardized on four basic roles:

• Role(”reader”): The default standing access for everyone—enough for 90% of daily troubleshooting.

• Role(”contributor”): Used for active troubleshooting or manual operations.

• Role(”admin”): High-privilege access for emergency situations or initial setup.

• Role(”operator”): Reserved exclusively for automation and CI/CD runners (no human members).

A key highlight of this chapter is the Just-in-Time (JIT) access process. We’ve moved away from “standing privileges” where people have permanent write access. Instead, everyone is a “Reader” by default. When you need to escalate your privileges to a Contributor or Admin role, you do so for a limited time window with a mandatory justification. This ensures every elevated action is properly audited and significantly reduces the attack surface of the platform.

We also dive into Federated Identity, which allows our CI/CD runners and applications to authenticate without using long-lived, static API keys. By using short-lived, cryptographically-proven tokens, we eliminate the risk of leaked secrets sitting in your GitHub or GitLab variables for years.

Infrastructure

Finally, the infrastructure chapter. This one is also still a work in progress, but it tackles how we actually land our workloads in the cloud. We focus on using cloud primitives—like Accounts, Subscriptions, and Projects—to create hard isolation boundaries that align perfectly with our Sector, Tier, and Tenant dimensions.

A big part of this chapter is dedicated to Networking. We dive into multi-region setups using the Hub and Spoke model. This architecture ensures that different networks remain isolated by default, while providing a centralized place to route traffic only when absolutely necessary—without having to manage a mess of sophisticated routing tables or brittle firewall rules.

When it comes to Compute, I make a strong case for using Kubernetes as the primary abstraction layer. It provides a well-defined, industry-standard interface that prevents you from “reinventing the wheel” while abstracting away the specifics of your cloud provider. That said, Kubernetes isn’t mandatory; if your organization prefers ECS, ACA, or even Virtual Machines, that’s fine too. The most important thing is that whatever compute model you choose, it must be properly standardized and abstracted so your development teams can focus on building products, not managing servers.

What’s Next?

With 60% of the book completed, the foundation is now solid. We have our notation, our segmentation strategy, our identity layer, and our core infrastructure. In the coming weeks, I’ll be finishing up these chapters and moving into:

• Chapter 7: CI/CD

• Chapter 8: Observability

• Chapter 9: Security and Compliance

• Chapter 10: Developer Experience (DevEx)

That’s all for now!

If you have come this far, here is a gift: book.craftingplatforms.com. You can still purchase the early access to get the ebook, but I am publishing an online version too for everyone to read. Early access buyers will get exclusive Crafting Platform content. This will be announced next week.

Over the last few months, I’ve been balancing my professional life with a degree in physics. It’s been intense, but I’ve kept working on Crafting Platforms at a slow and steady pace. The vision hasn’t changed, but the world around us certainly has.

I am back now, more active than ever, and I have decided to shift direction for how I write this book and who the code is for.

I’ve decided to rely heavily on AI throughout the entire lifecycle of Crafting Platforms: research, writing, review, editing, translation, and publishing. This doesn’t mean the writing is unattended. The ideas, the hard-earned lessons, and the platform engineering experience are entirely my own.

I’ve spent time extracting my voice and writing extensive reference materials to ensure consistency. The AI is an accelerator, not an author. To be completely transparent, I will share the process and code I use for this AI-assisted workflow. If you are interested in how the sausage is made—and how I ensure the materials remain legit—I’ll be opening that up soon.

This shift extends to the source code itself. Crafting Platforms is no longer just a book. It is a product with two distinct audiences.

The book is for humans. The repository is for AI agents.

Instead of providing brittle, vendor-specific Terraform templates that would be outdated the moment they were published, I am building a set of skills, agents, and commands in our repository: github.com/craftingplatforms/ai.

These artifacts teach AI agents the underlying principles of platform craftsmanship, allowing them to build solutions tailored to your unique environment. People and machines consume information in different ways, and we are finally designing for both.

This is just the beginning. I have been working in the background to bring you more content faster, and next week, there are two big releases:

1. The Online Edition: I will be launching the online version of the book, which will be updated regularly as new material is ready.

2. New Chapters: I am releasing Chapter 3 (Segmentation) and Chapter 5 (Infrastructure). There will be a new Chapter 4 (Identity and Access Management), still in draft.

This brings us to a significant milestone: 5 chapters in total (excluding the preface) and more than 100 pages of content. Not bad, right? That’s about 50% of the book.

We are moving from writing boilerplate configuration to defining strategic guidance. The book teaches you—the human—the principles of platform craftsmanship. The accompanying AI artifacts teach your agents how to implement those patterns efficiently.

I believe this dual approach is the future of technical books. On one side, I’ll teach humans how to think about platforms. On the other hand, I’ll teach machines how to build them. It’s funny because it will be like having a virtual me as your platform consultant available 24/7.

That’s all for now.

An Internal Developer Platform (IDP) is a curated set of tools, services, and processes that enable development teams to build, deploy, and manage applications efficiently. More precisely, it integrates an organization's technologies into golden paths that reduce cognitive load and enable self-service. This is not a concept I coined for this book. That’s what people in the industry have been calling it for a few years now. And I think the name captures well the essence of what we are trying to achieve.

You might wonder how an IDP differs from a Platform as a Service (PaaS) offering such as Heroku or Render. The distinction is customization and control. A commercial PaaS is a one-size-fits-all solution —you adapt to it. An IDP is tailored to your organization’s specific needs, technologies, and constraints. You build it, you own it, you evolve it based on feedback from your developers.

In this chapter, I outline my view of an IDP we will build throughout the book and explore the product mindset required to succeed in this journey. Building a platform is not just a technical challenge. It’s a cultural and organizational one. The mindset shift is crucial: the platform team doesn’t provide servers, it enables paths for development teams to do it themselves. The easy path has to be the right path.

I also outline some friction points I have encountered in my experience building platforms. If you don’t build the right thing at the right time, the platform will unavoidably fail. The developers won’t use it, and all your effort will be wasted.

I am pleased with the result of this chapter. It sets the foundation for everything that follows. The remaining chapters will dive into implementation: segmentation, infrastructure, CI/CD, observability, security, and developer experience. Each one builds on the product mindset established here.

That’s all for now.

You can join the early access program to get access to this chapter and the rest of the book as they are published. Visit leanpub.com/crafting-platforms to purchase it and support my work.

If you want a taste before purchasing it, I am giving away the first two chapters FOR FREE to newsletter subscribers. To get your copy, subscribe, and you’ll receive a download link in the welcome email.

Subscribe now

I like to think of self-service as a buffet in a restaurant. You’re presented with a variety of already prepared dishes. You don’t need to know how to cook them. You pick what you want, and it’s ready to eat. The kitchen staff has done the hard work so you can enjoy the results without the hassle.

Now, maybe you’d like a variation of a particular dish. You can ask the cook whether it can be customized, but it might take longer or incur additional costs. Or maybe you want to cook the same dish at home. In that case, you can ask for the recipe and ingredients, but you’re responsible for cooking and handling any mistakes along the way.

In the context of an Internal Developer Platform, we call these dishes golden paths. Golden paths are well-defined, tested (and tasty!), and documented approaches to everyday tasks. They should cover the most frequent use cases and be easy to follow. They’re intentionally opinionated. They guide developers toward best practices and reduce the cognitive load of infrastructure and tooling decisions.

At the same time, flexibility matters. If a developer needs to deviate from the golden path, they should be able to, but with the understanding that they’re taking on more responsibility for the outcome.

Golden paths come in many forms, depending on an organization’s needs and context. Some common examples include:

• Module libraries
  Predefined infrastructure-as-code modules (for example, Terraform modules or Helm charts) that allow developers to provision resources consistently and securely. A PostgreSQL module, for instance, might ask only for a name, size, and region, while handling backups, monitoring, and security by default—yet still allowing advanced customization when needed.

• CI/CD pipelines
  Preconfigured pipelines that automate build, test, and deployment workflows. For example, a pipeline that builds a Docker image for a .NET application, runs tests, and pushes it to a registry on every merge to main. Developers can use it as-is or extend it for more advanced scenarios.

• Service templates
  Standardized templates for deploying services. Think of a Kubernetes-based web application template with autoscaling and monitoring baked in. Developers provide the application code and choose a framework (Node.js, Python, Java, etc.), and the platform handles the rest.

• SDKs
  Well-designed SDKs that abstract infrastructure concerns behind simple interfaces. For example, an SDK for emitting structured logs or telemetry without forcing developers to understand the details of OpenTelemetry.

As platform engineers, our mission is to offload complexity and decision-making from development teams and lower their cognitive load. But it’s essential to be clear that golden paths are not about restricting creativity or autonomy. If we’re too restrictive, the platform becomes a golden cage. Developers will feel constrained and eventually look for ways around it.

This is where guardrails come into play.

Guardrails define the boundaries of acceptable behavior on the platform. They prevent choices that could compromise security, reliability, or maintainability. A guardrail might block deployments to unapproved regions, prevent resource starvation in shared clusters, enforce backups on critical databases, or require security scans before releasing to production.

We don’t implement guardrails to limit developers. We do it to protect the company’s assets, reputation, and compliance posture. Like guardrails on a road, they don’t stop you from reaching your destination. They keep you from veering off the road and crashing.

Guardrails can be implemented at different layers. In general, the higher the layer (e.g., preventive policies enforced by the cloud provider, or admission controllers in Kubernetes), the harder it is to bypass and the more effective it tends to be. Lower-level guardrails (such as defaults in modules) are easier to work around and to evolve.

There is no perfect balance that works for everyone, and you will need to navigate and evaluate trade-offs as you develop and evolve the platform. In the first few iterations, you will be more permissive on what teams can do. But as you mature the platform, you won’t allow certain activities, or if you do, you want to have complete control over them.

That’s all for now.

P.S. Chapter two of Crafting Platforms will be published by the end of this week. Stay tuned!

An Internal Developer Platform (IDP) is a curated set of tools, services, and processes that enable development teams to build, deploy, and operate applications efficiently.

More precisely, it brings together the technologies an organization uses into golden paths that reduce cognitive load and enable self-service. I didn’t coin this term. That’s how the industry has referred to this concept for years, and I think the name captures well the essence of what we’re trying to achieve.

You might wonder how an IDP differs from a Platform-as-a-Service (PaaS) like Heroku or Render. The distinction lies in customization and control. A commercial PaaS is a one-size-fits-all solution —you adapt to it. An IDP, instead, is tailored to your organization’s specific needs, technologies, and constraints. You build it, you own it, and you evolve it based on your developers' feedback.

In this chapter, I explain my view of the IDP we’ll be building throughout the book and explore the product mindset necessary to succeed on that journey. Building a platform isn’t just a technical challenge —it’s a cultural and organizational one. The mindset shift is crucial. The platform team doesn’t provide servers, but it enables development teams to do so themselves. The easy path has to be the right path.

One key insight I discuss is the Engineering Momentum Problem. Even a well-designed platform can fail if you underestimate developer inertia. You can’t enforce adoption overnight. Instead, you apply steady, continuous pressure through documentation, support, golden paths, and quick wins, until the platform stops feeling like an imposition and becomes an obvious improvement.

I’m not a product management expert, but I’ve learned a few lessons the hard way. This chapter isn’t a masterclass about it. It’s a collection of practical insights and recommendations that helped me navigate the complexities of building platforms that developers actually want to use.

The chapter also introduces the fundamentals every platform needs: a clear vision, a strategy (including segmentation decisions that are hard to change later), measurable objectives tied to business outcomes, and a flexible roadmap.

I also briefly touch on capabilities, the building blocks of any IDP. We’ll explore them in depth later in dedicated chapters, but for now, think of them as layers or planes: Infrastructure & Resources, Integration & Delivery (CI/CD), Observability, Security & Compliance, and Developer Experience. You don’t build them all on day one. You start with an MVP that addresses your developers’ most pressing pain points and iterate from there.

Speaking of Developer Experience. A platform with excellent capabilities but poor DevEx will struggle to gain adoption. A platform with modest capabilities but great DevEx will thrive. If developers don’t want to use your platform, it doesn’t matter how technically impressive it is.

Finally, I cover metrics. The DORA metrics: deployment frequency, lead time, change failure rate, and mean time to recovery. They are a good starting point.

This chapter sets the foundation for everything that follows. The next chapters will dive into implementation: segmentation, infrastructure, CI/CD, observability, security, and developer portals. Each one builds on the product mindset established here.

As always, I’d love to hear your thoughts. What challenges have you faced when building internal platforms? What worked, and what didn’t? I read you in the comments.

The second chapter will be released as promised in December. I’ll keep you posted.

That’s all for now.

Note: a reminder that you can still get the first two chapters for free if you subscribe to this newsletter today.

Subscribe now

It doesn’t simply “fill a gap” the engineering team has, like a CI/CD system or an observability tool. A platform appears as a response to the dysfunctions of the engineering organization itself. A tiny startup with three engineers and zero process doesn’t need a platform. The need emerges later, when complexity starts multiplying and the company can’t move fast anymore.

Platform engineering looks great on paper. But in real life? It’s messy.

When you start in your platform journey, you will probably inherit systems, processes, cultural habits, expectations, deadlines, fires to put out. Everything is already in motion. And anything that tries to change that motion will face resistance.

I call this Engineering Momentum.

Understanding Momentum

In physics, momentum (“quantity of motion”) is the product of mass and velocity:

A fully loaded cargo ship traveling at cruising speed has enormous momentum, because of its huge mass. You can’t simply turn the wheel and expect the vessel to pivot sharply. It will fight you. It wants to keep going straight. To change its direction, you need to apply a gentle, continuous force over a long arc —sometimes with the help of a tugboat— to slowly bend its trajectory. There is no such thing as a sudden 90-degree turn in a ship that size.

Engineering is exactly the same.

Teams have mass:

• people

• habits

• inherited processes

• legacy tools

• technology they’ve accumulated

• interdependencies

• historical decisions (that no one fully remembers)

And they also have velocity:

• roadmaps

• deadlines

• commitments already made

• business pressure

• operational load

The bigger the mass and the faster the velocity, the greater the momentum. And the harder it is to change direction.

This isn’t just a cute analogy. It’s physics!. It’s exactly what happens in any technological transformation. And somehow, nobody talks about it explicitly.

Ignore Momentum and You Will Fail

This is, in my opinion, where many platform teams — and many internal improvement initiatives — crash.

There’s this assumption that “if the platform is great, people will naturally adopt it.” But that ignores the thing that dominates everything: engineering momentum.

You don’t walk into an organization, disappear for a year to build “the perfect platform,” and then return saying: “You can migrate now.” Because what you’ll find when you arrive is:

• legacy systems

• tangled processes

• delivery pressure

• competing priorities

• habits cemented over years

And ironically, those are the very reasons the platform needs to exist. You want to simplify, standardize, reduce friction. But you cannot design a platform while pretending the real-world mess doesn’t exist and believing it will magically vanish once everyone migrates.

A platform introduces friction — even when perfectly designed.

No matter how good the platform is, if adopting it demands extra effort during a period of high load, teams will resist.

Sometimes consciously. Sometimes culturally. Sometimes without even noticing.

That’s momentum.

The Correcting Force

I’ve faced this several times, and in retrospective, it’s one of the most fascinating aspects of platform engineering. Sometimes it’s even more rewarding than the technical challenge.

Because a platform changes how teams work. It introduces new workflows, new tools, new rules. And that affects team velocity, mental energy, and psychological safety. It’s no surprise that change fatigue is such a common phenomenon.

This is why disappearing to build the “ideal platform” is a terrible idea. If a month goes by and you’re not helping solve real problems, someone will ask why the company is paying for a platform team. And they won’t be wrong.

A platform must be born with the organization, not in spite of it.

So before preaching “best practices” or pushing migrations, you need to start with something more humble:

Help with real problems. Even when they are not “platform problems.”

Earn credibility. Build trust. Reduce friction. Once teams see you solving issues that actually hurt them, they’ll be much more open to follow your lead.

And that’s when you can apply the “gentle, constant force” that slowly changes direction:

• guidance

• empathy

• clear documentation

• examples

• golden paths

• human support

• collaboration

• small wins

Little by little, momentum bends. The change stops feeling like an imposition and starts feeling like an obvious improvement. Because you’re no longer seen as “the team pushing a new thing,” but the team that helps to reduce the burden.

When that happens, adoption stops being a fight, and you can start introducing new technologies in the stack, new processes, and new culture for building software. Yes, that awesome Kubernetes and Argo CD to fully automate deployments that you want to put in place will come months later in the process.

Conclusion

Listen more than you impose.

Respect the team’s load before asking for effort.

Show value before asking for commitment.

Platform teams are not engineering police. We are strategic partners.

And when trust, consistency, and collaboration compound, something clicks. The engineering momentum stops pushing against you and starts pushing with you.

When that happens, everything flows.

Thanks for reading!

So I decided to share that chapter for free and launch the early access now.

Early access will allow me to gather feedback from readers as I write, validate that the content is relevant and useful, and find motivation to complete the book. I plan to dedicate a significant portion of the coming months to it, and your support will make that possible.

The first chapter walks through the historical context of software development and operations, and how the concept of a “platform” emerged as a response to the challenges organizations have faced over the past decade — especially since the rise of cloud computing and DevOps. Understanding where we’re coming from will make it easier to grasp the concepts and practices explored in the chapters that follow.

Join the Early Access

Visit craftingplatforms.com — a simple landing page I created for the book — to learn more and access the Leanpub page where you can purchase early access.

Or, if you prefer, go directly to: leanpub.com/crafting-platforms

Thank you for your support and encouragement — it truly means a lot.

Get the First Chapter for Free

If you’d rather have a taste before committing, you can download the first chapter for free on Leanpub: https://leanpub.com/crafting-platforms/signup.

Just sign up with your email to get the Community Edition, which includes the first chapter in both PDF and ePub formats. You’ll also receive updates about the book and be subscribed to this newsletter (sorry, it’s just a small price to pay).

Oh! if you subscribed to this newsletter to get the first two chapters for free, I’ll forward a copy to you today of the first chapter, right after this email. Second chapter will be sent out soon.

That’s it for now. I’ll keep you posted.

Subscribe now

Over the past few years, I’ve found myself solving the same problem again and again. With the rise of cloud computing and the shift of infrastructure closer to developers, engineering teams have reshaped the way they work and think about software delivery. We’ve moved from traditional IT and sysadmins managing servers, networks, and infrastructure, to a DevOps culture designed to bridge the gap between development and operations. It’s now clear that developers can — and often should — take more responsibility for the infrastructure powering their applications.

However, in many organizations, developers neither have the time nor the desire to master infrastructure management. They want to focus on building products that deliver business value. While most of us agree that DevOps is the right direction, many organizations still struggle to make it work in practice.

That, in my view, is what gave rise to Platform Engineering. It doesn’t replace DevOps — it enables it at scale. Platform Engineering formalizes the creation of internal platforms that abstract away the underlying complexity of cloud infrastructure, providing developers with paved roads and self-service capabilities that make them more productive and autonomous. Developers can then focus on writing software while the platform takes care of networking, compute, automation, security, compliance, and scalability — the essential scaffolding that keeps everything running smoothly.

I’ve had the opportunity to tackle this challenge in several organizations, and I’ve never solved it the same way twice. There is no “one-size-fits-all” platform. Every company has its own DNA — its own culture, processes, and constraints. That’s why I believe building platforms is an artisanal craft, not an industrial process. Yes, there are universal principles and foundational components — things like automation, observability, and security by default. However, how you combine them and the trade-offs you make will always depend on your specific context.

Cloud infrastructure, IaC, CI/CD, observability, vulnerability scanning, identity and access management, secrets management, developer portals, and more — these are the basic building blocks of modern platforms. Most of us would agree on that. But which clouds should you use? Which CI/CD stack? Do your engineering values align better with Azure, AWS, or GitLab? What are your compliance requirements? Do you need multi-region deployments, hybrid setups, or on-prem integrations? These are the questions that shape your platform — and there’s never a single right answer. You have to craft it.

And, honestly, the hardest part is not even crafting it, but selling it to the rest of the organization. Make it appealing for others to buy in and move their workloads, pipelines, and processes to it.

With this book, I aim to surface those questions and share the concepts, principles, and lessons I’ve learned along the way. It’s an opinionated take — and that’s intentional. Other engineers may have taken different paths, and that’s perfectly fine. Crafting Platforms isn’t meant to be the ultimate how-to guide. It’s a practical, experience-driven exploration of what I believe to be the timeless foundations of building internal platforms. It’s also a good opportunity for me to research some topics to reinforce my understanding or change my perspective. Platform Engineering is a new discipline, and there is a lot to learn from it.

Alongside the book, I’m preparing a public GitHub repository with all the source code used in the examples and chapters. My goal is to make it hands-on — less academic, more practical. Sometimes, the best way to explain an idea is to demonstrate it in code.

And finally, this newsletter will serve as a companion to the book — a place to share its progress, discuss platform engineering practices, and comment on industry trends. Sometimes I’ll share excerpts, other times short essays or reflections.

If that sounds interesting, be sure to subscribe and follow along. Please help me spread the word by sharing this newsletter.

That’s all for today — more soon about Crafting Platforms and the ideas behind it.

You can subscribe now and be part of Crafting Platforms from day one.

Everyone who subscribes during November will receive a free copy of the first two chapters of my upcoming book, Crafting Platforms.

Join early, follow the journey, and get a front-row seat

Subscribe now