Tips on Creating a Reference Architecture

Introduction

Before embarking on your journey of creating a reference architecture, it’s important to completely understand the development process. This includes knowing what tools are involved, all necessary processes, and the steps that follow. Without this understanding, it’ll be difficult to create a standardized path.

Intent-Based Creation

There are different ways to create a reference architecture, and the approach we’ll discuss is “intent-based.” This approach involves articulating the intention in a structured format from a developer’s point of view in the following way:

“I want to [verb][adjective][noun]”

For example:

“I want to deploy a scalable Node.js, MongoDB application on Kubernetes.”

This intent-based statement precisely articulates the objective, desired outcome, and specific technologies for deploying a scalable web application. It’s a foundational step towards outlining a standardized reference architecture and leads to the next stages of building your reference architecture.

---

Steps

1. Define Goals: Understand the end goal of your reference architecture. What do you want to achieve? For instance, we aimed to deploy a Node.js, MongoDB application to Kubernetes using Jenkins. For instance, aim to deploy a Node.js, MongoDB application to Kubernetes using Jenkins.
2. Choose Your Tools: Engage with your end users (developers) to understand the tools they use daily. Decide on containerization tools like Docker, orchestration tools like Kubernetes, and CI/CD tools like Jenkins.
3. Research Best Practices: Research industry standards and best practices for using the chosen tools and processes. Gather insights on optimal practices for developing, testing, and deploying applications.
4. Create a Prototype: Using the gathered tools and best practices, create an initial version of the reference architecture. This could involve building a simplified version of the deployment process, setting up basic configurations, and testing the workflow.
5. Documentation: Create detailed documentation of each step, tool usage, configuration settings, and best practices. Include clear instructions, code snippets, explanations and architecture decision records.
6. Get Feedback and Iterate: Share the prototype and documentation with your developers to gather feedback. Use this feedback to refine the reference architecture and update the documentation until a final version is reached.
7. Deploy to Product Central: Once ready, deploy the reference architecture to Product Central as a template or guided walkthrough. Developers can use it to create workload specifications, which can be passed to the platform to provision the necessary resources.

Considerations While Building Reference Architectures

1. Long-Term View: Building a reference architecture is like developing a city's infrastructure. It's essential to take a long-term view rather than focusing on immediate needs.

   • Avoid building for day one. Developers often enhance existing services rather than build new ones. Therefore, focus on creating paths for day two operations, such as integrating additional features, security, and testing.

2. Prioritization: Not everything needs a reference architecture. Prioritize tasks that will have the most significant impact.

   • Interact with developers to understand their critical tasks and monitor recent deployments to identify processes that need addressing. Focusing on these will yield the highest impact and ROI.