├── LICENSE ├── README.md ├── evaluating-backstage-1-why-backstage.md ├── evaluating-backstage-2-how-backstage-works.md ├── evaluating-backstage-backstage-vs-competitors.md ├── implementing-backstage-1-getting-started-with-backstage-cli.md ├── implementing-backstage-2-core-components.md ├── implementing-backstage-3-integrating-with-existing-tools-using-plugins.md ├── implementing-backstage-4-security-and-compliance.md ├── implementing-backstage-5-kubernetes-plugins.md ├── implementing-backstage-6-kubernetes-deployment.md ├── succeeding-with-backstage-1-customizing-the-look-and-feel-of-backstage.md ├── succeeding-with-backstage-2-building-and-maintaining-custom-plugins.md ├── succeeding-with-backstage-3-improving-adoption.md └── succeeding-with-backstage-4-backstage-as-part-of-a-broader-developer-productivity-engineering-dpe-initiative.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Kosli 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # backstage-guide 2 | A series of articles to help you evaluate, implement and succeed with Backstage 3 | -------------------------------------------------------------------------------- /evaluating-backstage-1-why-backstage.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Evaluating Backstage Part 1: Why Backstage? 3 | authors: 4 | - Carlos Eduardo Inocencio Alanis 5 | --- 6 | This article is the first part of the "Evaluating Backstage" series. It covers all the basics around developer portals, introduces Backstage development, and explores how it can help your organization to be more efficient and secure. 7 | 8 | Backstage is a developer portal that acts as a centralized hub for your organization, providing access to documentation, infrastructure, tooling, and code standards. It gives developers everything they need to create and manage their projects in a consistent and standardized manner. To understand why Backstage exists, and why you should care about it at all, you must first understand the pain points it's trying to alleviate. 9 | 10 | Picture this: you're working on a project that needs to talk to some service, but no one is entirely sure who owns it anymore. Asking around only leads you to out-of-date documentation, and eventually you realize the code owner left the company months ago. You reverse engineer enough to identify the necessary infrastructure changes and raise a ticket. It takes days to get a response, only for you to find out that some crucial data is missing. And now your manager is asking when your project will be ready. 11 | 12 | Stories like this are all too common in the developer world and are the inevitable result of growing organizations. There is no magic bullet for these issues, but developer portals such as Backstage can help to alleviate them. 13 | 14 | ![Example layout of Backstage developer portal](https://i.imgur.com/GbVl0mZ.png) 15 | 16 | With a developer portal, individual team members no longer have to solve every challenge they face on their own because the portal enables better collaboration and communication across the whole team. For example, the portal allows administrators to define and enforce standardized practices for all projects. This way, developers can focus on problem-solving without having to worry about managing processes and adhering to different standards. To give a second example, if a new developer joins the organization and needs to create a simple function, the portal guides them on best practices, monitoring tools, code standardization, and accessing necessary resources like database secrets. 17 | 18 | ## What Is Backstage? 19 | 20 | [Backstage](https://backstage.io/docs/overview/what-is-backstage) is an open source developer portal originally created by Spotify for its internal use. It was designed to allow their developers to maintain the [highly dynamic and autonomous](https://blog.crisp.se/wp-content/uploads/2012/11/SpotifyScaling.pdf) development flow Spotify has become known for. Backstage does this by helping you to organize and manage all the software your company produces. Recounting the entire history of Backstage is beyond the scope of this article, but it has been extensively [documented](https://engineering.atspotify.com/2020/04/how-we-use-backstage-at-spotify/) in [other places](https://backstage.io/docs/overview/background/). The tl;dr is that Spotify donated its developer portal to the Cloud Native Computing Foundation in 2020, making it open source. It's designed from the ground up to be flexible and allow every organization to adapt it to their own needs. In Spotify's own words: 21 | 22 | > "It's a developer portal powered by a centralized software catalog—with a plugin architecture that makes it endlessly extensible and customizable." 23 | 24 | Backstage provides a central place where you can find a registry of all deployed services, APIs, and infrastructure, as well as their documentation, and see how they interact with each other. 25 | 26 | You no longer have to wonder who owns specific pieces of code, ask around only to be directed to out-of-date Confluence pages, or find that the dev you need to speak to no longer works at the company. You can view all your components in one central space and easily see which components are dependent on one another. Additionally, you'll have access to the source code's location and the name of its owner. 27 | 28 | ![Example of Backstage-generated documentation](https://i.imgur.com/OybFRMJ.png) 29 | 30 | All of that is great by itself, but what really makes Backstage shine is another of its core functionalities: software templating. The core component of Backstage that deals with this is called Scaffolder. It provides a series of guidelines and restrictions that allow you to create templates that developers can use to deploy code. In these templates, you can bake in whatever your organization deems valuable for every type of component you want to create. 31 | 32 | For example, you might want every serverless function to incorporate a specific monitoring tool, or you may want to ensure that developers don't forget to include a README file in their repositories. With software templates, developers can simply fill out a form and follow a few clicks to create their projects. The templates will automatically enforce the guidelines you defined, publish the repository to the appropriate workspace, and register the project in the software catalog. 33 | 34 | ![Example template catalog page inside Backstage](https://i.imgur.com/OuT2tON.png) 35 | 36 | In the example provided earlier, this means you could create a template for the new developer to use, and they would simply log in to Backstage using your organization's LDAP. Once in there, they would locate the relevant template and provide it with all the data it requests. Backstage would then create a new GitHub repository that contains all the base code you usually need for such cases: layers, libraries, the CI/CD pipeline configuration file, automatically generated documentation, and so on, all within minutes. 37 | 38 | ![Example of component template in Backstage](https://i.imgur.com/62Vv29t.png) 39 | 40 | Additionally, as time passes, a large open source community continues to grow behind Backstage. There are plenty of [plugins](https://backstage.io/plugins/) that make it easier to have your first working proof-of-concept app by providing open source solutions to common scenarios like resource visualization or cost reports. 41 | 42 | This kind of flexibility has made Backstage a very attractive tool for many [high-profile companies and startups alike](https://github.com/backstage/backstage/blob/master/ADOPTERS.md), like Expedia, CVS Health, Siemens, LinkedIn, and Fiverr. Netflix also uses Backstage for its internal operations. If you would like to take a more in-depth look at how companies use Backstage, you can explore the [Expedia example](https://www.youtube.com/watch?v=rRphwXeq33Q&t=1508s). 43 | 44 | ## Adopting Backstage 45 | 46 | This all sounds really good so far, right? Well, it's not as easy as it seems. If you have been reading about Backstage, you might have already come across different tutorials on how to make a simple application run locally and how to install plugins created by other people. Getting started is pretty straightforward. However, as soon as you start to move away from the out-of-the-box functions and try to implement more custom use cases, it starts to become a bit (or a lot) more confusing. 47 | 48 | Backstage is not just an application or [SaaS](https://en.wikipedia.org/wiki/Software_as_a_service) that you can purchase and expect to work right out of the box. You have to think of Backstage as more like a framework than a fully-fledged application to implement in your organization. To implement it successfully, you will have to treat it like a product that requires support and an active team of developers. It's a project that will need your team's full engagement. 49 | 50 | You have to write code, modify the existing app code, and make it yours so it adapts to your use case—but at the same time, this is what makes Backstage powerful. As you progress, it will become yours and be tailored exactly to what your organization needs. All the effort put into it, plus the fact that no one knows your processes better than you do, means that it will tackle exactly the pain points you care most about. You can then contribute back to the [open source project](https://github.com/backstage/backstage) and help grow its ecosystem even more. 51 | 52 | When adopting Backstage, it's also very important to think beyond technical details and code. As a developer, it's natural to get excited by the framework's endless possibilities and start going wild, implementing every impressive feature you can think of. However, it's essential to remember that there is little to no value in creating an awesome, shiny tool that no one will ever use because the user experience is bad. The portal must align seamlessly with the current workflow and be easily understandable. In a sense, you must do internal marketing and evangelize other teams about its usefulness if you want them to buy in. This means you need to think about *their* needs, user experience, and goals when you are building your portal. 53 | 54 | Become familiar with Backstage, read the documentation, read some articles explaining how to do things you would like to do - we will have lots of ideas to share with you as the series develops - and define specific metrics of success from the beginning. These will be useful for how you'll judge if Backstage is working well for your organization. Metrics like adoption rate, enhanced productivity, and automated processes will be specific to your organization, but measuring these will provide insights to guide you and keep you focused on what really matters to you. They will also make it easier to explain to management the added value you are bringing to the organization with this Backstage thing you keep talking about. 55 | 56 | ## Conclusion 57 | 58 | In this introductory article, you've learned about the basics of developer portals and Backstage as a modular open source framework that allows extensions with your own or third-party plugins. On top of all this, if you've already dipped into the Backstage documentation, you might be feeling overwhelmed. The documentation sometimes assumes you already know what you're doing and can be complicated for Backstage newcomers. 59 | 60 | Don't be too hard on yourself if you don't get it right away. The rest of this series will break down the various elements of Backstage to make them a bit easier to digest. As you follow along, everything will start making sense, and you'll soon be contributing to the Backstage community yourself and helping to enhance this great framework. 61 | 62 | If this article has piqued your interest, you can continue your journey with the second installment, [Evaluating Backstage: How Backstage Works](https://www.kosli.com/blog/evaluating-backstage-how-backstage-works/). 63 | -------------------------------------------------------------------------------- /evaluating-backstage-2-how-backstage-works.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Evaluating Backstage 2: How Backstage Works" 3 | authors: 4 | - Alexandre Couedelo 5 | --- 6 | At its core, Backstage excels at bringing together an array of diverse tools, services, and essential information, all under one roof. This unified and customizable UI streamlines development workflows, improving productivity and empowering developers to thrive in their roles. 7 | 8 | As an internal developer platform, Backstage fulfills the dream of a central hub with all the tools and information developers need. The days of platform engineers struggling to maintain their custom-made platforms may be over. But before throwing yourself single-mindedly into adopting Backstage, this article invites you to look at its inner workings and evaluate its offerings. 9 | 10 | This is the second installment of the "Evaluating Backstage" series. The first article focused on [how and why Backstage was developed](https://www.kosli.com/blog/evaluating-backstage-why-backstage/). This article focuses on how Backstage works. You'll learn about Backstage's essential concepts and core offerings, and you'll also delve into Backstage's plugin architecture. Finally, as no evaluation is complete without addressing security concerns, the last section explores Backstage's security model. 11 | 12 | ## Backstage's Essential Concepts 13 | 14 | Backstage is a software catalog, or a central repository that lists and categorizes software components your company develops or uses. You could compare Backstage to a phone book listing all microservices, desktop apps, mobile apps, and web applications, but it's actually much more than that. Backstage also serves as a frontend for all your developer tools, thanks to a modular plugin ecosystem that gathers your tools in a central place within the catalog so you can easily find them. 15 | 16 | ![Backstage software catalog](https://i.imgur.com/Q9yhKPH.png) 17 | 18 | Backstage is highly customizable, so companies can adapt it to their exact needs. The code is open source, and when [installing Backstage](https://backstage.io/docs/getting-started/), you generate a template application that you can customize and extend with plugins. Backstage is not a black-box application where you install plugins; rather, you maintain your own source code and can modify it as needed. 19 | 20 | Backstage is also a developer-centric platform that uses contemporary configuration management best practices, namely [GitOps](https://www.redhat.com/en/topics/devops/what-is-gitops#:~:text=GitOps%20uses%20Git%20repositories%20as,set%20for%20the%20application%20framework.). The catalog's definition is stored in Git repositories in YAML format (using a Kubernetes-style manifest). Owners of each Git repository are expected to write catalog configurations for the software they are building or maintaining, following the [Backstage system model](https://backstage.io/docs/features/software-catalog/system-model/). 21 | 22 | ### Backstage System Model 23 | 24 | The system model is a conceptual representation of the data inside the Backstage software catalog. It defines all the high-level concepts (system, component, resource, API, and so on) that constitute the catalog and the possible relationships between its constituents. The following diagram illustrates the system model: 25 | 26 | ![Backstage system model by Spotify](https://i.imgur.com/rjV5wUX.png) 27 | *[Image courtesy of Backstage](https://backstage.io/docs/features/software-catalog/system-model/)* 28 | 29 | In a way, the system model is similar to a class diagram or a database schema. Understanding the model will help you configure the software catalog. 30 | 31 | ### Backstage Software Catalog 32 | 33 | A software catalog allows you to manage your software assets (such as your frontend and backend applications as well as databases) in a structured and consistent manner, providing transparency and accountability throughout your company's ecosystem. Backstage allows you to easily locate all systems, resources, components, and features and see how they relate. Understanding these relationships helps you navigate the system and identify dependencies between applications. Ultimately, the services catalog can clearly show an overview of how a company's ecosystem works. It's important to keep track of who is responsible for each item in the catalog, so Backstage lets you assign ownership to a department, team, or even a person, and add ways to contact them. 34 | 35 | ![Backstage discoverability and accountability](https://i.imgur.com/78ZnreI.png) 36 | 37 | When troubleshooting an issue, Backstage allows you to find the owner of a service and contact them quickly. On the other hand, as a developer, you can find out what systems your colleagues are working on and learn more about those systems. 38 | 39 | The central component defined in the catalog is a *system*. A system is a set of elements that work together to provide some features. The following snippet is an example of how a system can be defined in the catalog: 40 | 41 | ```yaml 42 | # Defining a system 43 | apiVersion: backstage.io/v1alpha1 # Kubernetes-style manifests 44 | kind: System 45 | metadata: # Provide context 46 | name: audio-playback 47 | description: Audio playback system 48 | spec: # Define relations 49 | owner: team-c # Define accountability 50 | domain: playback 51 | ``` 52 | 53 | Once you define the system, you must complete the catalog with more information about that system. A system can be part of a group of systems called domains. A system has components (pieces of software) and resources (services it needs to run). Both components and resources represent the structure of a system. A system also provides or consumes various APIs that define what it offers and its dependencies on other systems. 54 | 55 | You can define all entities described in the diagrams in the same way. The following example defines a component for the `audio-playback` system above. In this example, let's imagine that this component provides an API (`playback-order-api`) and consumes a database (`playback-db`): 56 | 57 | ```yaml 58 | # Defining a component 59 | apiVersion: backstage.io/v1alpha1 # Kubernetes-style manifests 60 | kind: Component 61 | metadata: # Provide context 62 | name: playback-order 63 | description: Playback Order 64 | tags: 65 | - java 66 | - playback 67 | spec: # Define relations 68 | type: service 69 | lifecycle: production 70 | owner: team-c # Define ownership 71 | system: audio-playback # Define the service relationship 72 | dependsOn: 73 | - resource:default/playback-db # This component uses a DB 74 | providesApis: 75 | - playback-order-api # The component is providing an API 76 | ``` 77 | 78 | The next step is to define the resource (`playback-db`) and API (`playback-order-ap`). If you're interested, you can find those configurations in detail [on GitHub](https://github.com/xNok/backstage-demo/blob/main/backstage/examples/audio-playback.yaml). But the most important thing is that you can see the model in Backstage once those entities are ingested in the catalog. The following is the Catalog Graph page, where you can see the described model system: 79 | 80 | ![Backstage Catalog Graph page](https://i.imgur.com/eO8CenM.png) 81 | 82 | Once you define all the entities (system, components, resources, APIs, and so on), you get a broad overview of your company's ecosystem. 83 | 84 | ## What Does Backstage Offer? 85 | 86 | Backstage comes with a few really interesting features right out of the box. 87 | 88 | ### Technical Documentation Hub 89 | 90 | Backstage enhances the notion of a service catalog by offering the option to host documentation as code. Specifically, developers are encouraged to write their documentation using Markdown inside their code repository. Backstage will then render and host those pages in the service catalog: 91 | 92 | ![Backstage TechDocs](https://i.imgur.com/xkqKpEx.png) 93 | 94 | Backstage's technical documentation feature (TechDocs for short) is built on top of [MkDocs](https://www.mkdocs.org/), a popular documentation as code static website generator. When writing documentation, you can leverage many preexisting [MkDocs plugins](https://github.com/mkdocs/catalog) and beautify your documentation with additional styling (not supported by traditional Markdown) and diagrams. 95 | 96 | ### Resource Search Engine 97 | 98 | When you combine documentation with a service catalog, you have all the information you need in one place. To help sort through it, Backstage includes a powerful search engine that allows developers to easily find the resources and information they need. This search engine can search the service catalog, documentation hub, and other resources such as Confluence or Stack Exchange via plugins. Backstage's search engine can index multiple sources of information, so it can provide exhaustive results from those sources. Having a single search engine in Backstage makes it easier to find information quickly, reduces the time wasted navigating between different sources of information, and helps developers work more efficiently and effectively. 99 | 100 | ![Backstage search engine](https://i.imgur.com/9IFYMZK.png) 101 | 102 | ### Software Templates and Golden Paths 103 | 104 | Backstage provides a self-service [software template](https://backstage.io/docs/features/software-templates/) solution for a developer to start a project with the necessary tools and resources. For instance, a template could allow a developer to quickly create a Git repository with a skeleton application in a chosen programming language. 105 | 106 | Software templates aim to provide the key set of steps that developers should follow when starting new projects, and most steps can be automated. Those key steps are referred to as [Golden Paths](https://engineering.atspotify.com/2020/08/how-we-use-golden-paths-to-solve-fragmentation-in-our-software-ecosystem/) and aim to ensure developer autonomy (no gatekeeping to start a project) while ensuring standards and best practices are followed (a template is provided). 107 | 108 | ![Backstage software template](https://i.imgur.com/WbftMh4.png) 109 | 110 | You can also create a software template to automate infrastructure tasks and provide on-demand databases, event queues, Kubernetes clusters, and so on. The software template feature offers a UI for developers to say, "I need something." Behind the curtain, the team maintaining the template (most likely the infrastructure team) can implement some mechanism to process that request automatically. For instance, choosing a software template can result in a pull request to a repository with a Terraform configuration, Kubernetes manifest, or Crossplane manifest. 111 | 112 | The software template feature can turn Backstage into an internal developer platform (IDP) that provides self-service capabilities for developers to independently obtain anything they require to create and run their applications. 113 | 114 | ## Adopting Backstage: Understanding Plugins 115 | 116 | Backstage is a web application with a [Node.js](https://nodejs.org/en) backend and a [React](https://react.dev/) frontend. A basic understanding of those two ecosystems, including TypeScript, is required to be able to customize the application and integrate plugins. 117 | 118 | All plugins are Node modules that can be installed on the Backstage application. When you first start your Backstage journey, you generate a template app that's built using the core plugins mentioned in the previous section. 119 | 120 | The frontend part of Backstage is built using React components provided by plugins. Similarly, the backend registers API endpoints provided by backend plugins. So, any third-party integration needs two or more plugins, typically at least a frontend one and a backend one. The endpoints provided by the backend plugin are used by the frontend plugin to fetch the information to display. 121 | 122 | ![Backstage composable architecture](https://i.imgur.com/Es4W5Sc.png) 123 | 124 | ### Backstage Community Plugins 125 | 126 | You can find the list of plugins on the [Plugin Marketplace](https://backstage.io/plugins/), and you should browse the list to discover more about what features Backstage can offer. You may notice that the four features discussed above (software catalog, technical documentation, search engine, and software templates) are plugins. Indeed, in Backstage, everything is a plugin. 127 | 128 | ![Backstage Plugin Marketplace](https://i.imgur.com/59WHIOR.png) 129 | 130 | The following are a few examples of notable plugins: 131 | 132 | * You can extend the search engine with sources such as [Stack Exchange](https://github.com/backstage/backstage/tree/master/plugins/stack-overflow) or [Confluence](https://github.com/K-Phoen/backstage-plugin-confluence) 133 | * You can integrate CI/CD to see the state of your pipeline using plugins from [Jenkins](https://github.com/backstage/backstage/tree/master/plugins/jenkins), [CircleCI](https://github.com/backstage/backstage/tree/master/plugins/circleci), or [GitLab](https://github.com/immobiliare/backstage-plugin-gitlab) 134 | * You can integrate deployment tools and platforms such as [Kubernetes](https://backstage.io/docs/features/kubernetes/) and/or [Argo CD](https://roadie.io/backstage/plugins/argo-cd/) 135 | 136 | The list of plugins keeps growing. Spotify, which develops Backstage, has a dedicated team working on plugins. The project maintains open source plugins and recently announced a new set of [premium plugins](https://backstage.spotify.com/plugins/) under development. 137 | 138 | In many cases, you should consider creating your own plugins to extend Backstage and integrate seamlessly with your ecosystem. Generally, with custom plugins, you can add new functionality, modify existing features, customize the UI, integrate with third-party systems, and set up custom workflow steps with the software templates plugin. 139 | 140 | ### Backstage Custom Plugins 141 | 142 | The goal here is not to teach you how to create your own plugins, but to provide an overview of how plugins work so you can evaluate the effort it takes to create your own. 143 | 144 | There are two main reasons you would create your own plugins: being able to customize the UI—especially dashboards and pages of the catalog—and being able to integrate with external systems via APIs. In the first case, all you need to do is create a frontend plugin. As mentioned, third-party integrations require both a backend plugin and a frontend plugin since you need to call external APIs and display that information in Backstage. 145 | 146 | On the frontend side, writing a custom plugin is equivalent to writing a [React](https://react.dev/) component library. A page is an aggregation of React components. When opening a catalog page, you can see four cards, each of which is a React component: About, Relations, Links, and Has subcomponents. Each tab (CI/CD, APIs, Dependencies, and so on) will display more components from various plugins to compose a page. 147 | 148 | For instance, you can see this on the `playback-order` page below: 149 | 150 | ![Backstage Catalog Page decrypted](https://i.imgur.com/CeilU05.png) 151 | 152 | Even if you are not a React expert, understanding how this page is defined should be straightforward. The Overview tab definition you saw above looks like this: 153 | 154 | ```js 155 | const overviewContent = ( 156 | 157 | {entityWarningContent} 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | ); 176 | ``` 177 | 178 | In the code above, a `Grid` system is used to organize, display, and define the page structure and the four components evoked earlier (`EntityAboutCard`, `EntityCatalogGraphCard`, `EntityLinksCard`, and `EntityHasSubcomponentsCard`). 179 | 180 | Composing new tabs and pages using the frontend components of plugins is a task for the platform engineering team or developers maintaining Backstage. As you can see, you have to write some code (piece together code would be more accurate), but in return you get a lot of control over what your instance of Backstage looks like, meaning your company's experience with Backstage will be tailored specifically to your needs. 181 | 182 | On the backend side, plugins are mostly used to fetch information to create third-party integrations. For example, with the [Kubernetes plugin](https://backstage.io/docs/features/kubernetes/), which is listed as a core plugin, the UI needs to access information about the cluster: 183 | 184 | ![Backstage Kubernetes plugin](https://i.imgur.com/Y0WvlCg.png) 185 | 186 | The Kubernetes React component first needs to discover the URI of its backend counterpart. When initializing, the plugin uses the discovery API that provides the endpoint for the requested backend (steps 1, 2, and 3 in the diagram below). Once the frontend knows about the backend URI, it can make a call to fetch the data. The request is sent to the application and handled by the router that dispatched the request to the right backend component (steps 4 and 5). Finally, the backend handles communication with the third-party API and returns the requested data. In the case of the Kubernetes plugin, this means the dedicated backend plugins are responsible for communicating with the Kubernetes API. 187 | 188 | ![How third-party integration works in Backstage](https://i.imgur.com/QNUF6Uq.png) 189 | 190 | Backend plugins provide a reliable and efficient mechanism for frontend components to interact with backend services, enabling seamless integration with third-party APIs and retrieving necessary data. The backend plugins can also integrate some authorization mechanisms to control users' access. 191 | 192 | This concludes the tour of how to customize Backstage applications and integrate plugins to create a tailored experience. The frontend uses React components from plugins, while the backend registers API endpoints for fetching and displaying information. With its composable architecture, Backstage offers customizable dashboards and third-party integrations, providing control over the platform's appearance and facilitating data collection and aggregation in the UI. 193 | 194 | ## Adopting Backstage: Security Concerns 195 | 196 | Security for an internal developer platform is very important, as the platform is a central hub or collection of much of the company's internal information. As Backstage is based on plugins pulling and processing information from various other systems, it can also be subject to security risks. 197 | 198 | Generally, a threat model helps identify and mitigate potential security threats. It protects sensitive information, ensures secure access, addresses infrastructure security, fosters secure development practices, and helps you meet [compliance requirements](https://www.kosli.com/audit-compliance/). Backstage's [threat model](https://backstage.io/docs/overview/threat-model/) includes a trust model, which identifies the following three actors: 199 | 200 | * An **integrator** deploys, operates, and configures Backstage and is fully trusted. 201 | * **Internal users** (authenticated users who are part of the company) are partially trusted. This means that although they have access to company resources, they cannot be fully trusted to maintain the confidentiality and integrity of the data. Internal user access should be restricted to only the data needed, and their inputs/configurations should be validated. 202 | * **External users** (anyone else not part of the company) are not trusted and should not have any access to Backstage. 203 | 204 | ![Backstage trust model](https://i.imgur.com/W4FtCwI.png) 205 | 206 | ### Security Recommendations for Authentication 207 | 208 | Internal users must be identified before being granted access to Backstage. The authentication process for Backstage relies on using the [auth plugin](https://backstage.io/docs/auth/) that supports various OAuth 2.0 provider integrations like GitHub, GitLab, Azure, and Google. The Backstage auth plugin doesn't protect against unauthorized access from external users and only focuses on internal users. 209 | 210 | So, the main threat comes from external users. It's recommended to deploy Backstage behind identity-aware proxies such as GCP IAP, Cloudflare Access, or AWS's ALB to prevent all access from external users to Backstage. The Backstage API should be secured using Backstage's JWT tokens that assert a user's identity, and all backend-to-backend communication should also use JWT tokens with a pre-shared signing secret, especially when exchanging information with third-party APIs. 211 | 212 | ### Security Recommendations for Core Plugins 213 | 214 | Backstage offers authentication and authorization and emphasizes that it's the integrator's responsibility to manage that configuration when deploying a Backstage instance. The model assumes that Backstage is deployed securely, preventing external access, and that internal users can be trusted and have access by default to all resources in the catalog. 215 | 216 | The integrator needs to restrict permissions if needed and validate that the recommendation of the threat model is enforced for the core plugins. The threat model and integrator are particularly important for implementing security measures in the following areas of Backstage: 217 | 218 | * **Software catalog:** Registering user and group entities should not be allowed to be delegated to identity providers via provisioners. Ideally, you should apply rules to limit the allowed entity kinds and validate configurations, protecting against the creation of many resources or compromising data integrity. 219 | * **Software templates:** You should be especially cautious when using the [Scaffolder plugin](https://backstage.spotify.com/learn/onboarding-software-to-backstage/setting-up-software-templates/10-scaffolder-actions/), as it may have elevated permissions to create resources on behalf of users. Backstage also suggests auditing and verifying installed scaffolding actions (automated steps for templates). 220 | * **TechDocs:** The TechDocs frontend applies strict sanitization to generated HTML content, so the risk is more on the backend side if you use external storage such as Google Cloud Storage, Amazon S3, or Azure Blob Storage (the recommended setup for companies with a lot of documentation). In that case, the integrator is responsible for securing access to the storage. 221 | * **Proxy:** Backstage offers the option to configure proxies so the frontend can access data from third parties. This is a simple alternative to creating backend plugins for Backstage. However, it comes with the risk of exposing too much of the third-party API and not providing identity-based access control. To prevent that issue, you should create backend plugins to ensure the principle of least privilege is applied and offer better authorization workflows with third parties. 222 | 223 | Community plugins should be assessed carefully and not blindly trusted, as no default restrictions are in place to restrain what a plugin can access from the catalog. 224 | 225 | ## Conclusion 226 | 227 | You should now have a good grasp of how Backstage works and how its pieces fit together. Backstage’s system model is the core representation of the catalog configuration and serves as the platform's backbone. It dictates how information is presented, accessed, and managed by users. While simple, every user should understand this model to ensure the catalog is appropriately structured. 228 | 229 | Backstage goes beyond a service catalog by integrating technical documentation and a search engine, offering developers a self-service solution with software templates. The platform also provides modularity through plugins, though they require some programming knowledge to implement. However, you don't need to be a React expert to assemble a UI component, and you have complete control over what to display where. You also learned about some security concerns you should consider before going live with the platform. 230 | 231 | If you’ve followed along since part one, you’ve seen the "why" and the "how" behind Backstage. Maybe you’re already sold on the platform and want to start implementing it immediately. However, you can’t fully evaluate a tool until you see how it compares to its competitors. If you’re curious to see how it stacks up, you can continue your journey with the third installment, [Evaluating Backstage: Backstage vs. Competitors](https://www.kosli.com/blog/evaluating-backstage-backstage-vs-competitors/). -------------------------------------------------------------------------------- /evaluating-backstage-backstage-vs-competitors.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Evaluating Backstage: Backstage vs. Competitors" 3 | authors: 4 | - Artem Oppermann 5 | --- 6 | Developer portals are no longer a novelty but a necessity for organizations that offer software services. The portals centralize and streamline the developer experience with essential tools, including API documentation, SDKs, sample code, and technical support. Backstage is one example of a developer portal, but it's not the only option. Before deciding if you'd like to adopt Backstage, it's crucial that you consider how it compares to its competitors. 7 | 8 | This is the third part of the "Evaluating Backstage" series. The [first article covered the "why,"](https://www.kosli.com/blog/evaluating-backstage-why-backstage/) and the [second article focused on the "how."](https://www.kosli.com/blog/evaluating-backstage-how-backstage-works/) This third installment explores how Backstage compares to some other platforms for building developer portals: 9 | 10 | * [OpsLevel](https://www.opslevel.com/) 11 | * [Port](https://www.getport.io/) 12 | * [Cortex](https://www.cortex.io/) 13 | 14 | Each of the platforms is assessed based on its core features, ease of use in terms of user interface (UI) and user experience (UX), learning curve and complexity, integration capabilities with existing infrastructure, customizability and extensibility, collaboration and communication features, quality of documentation and support, and resource requirements. These criteria reflect the daily practicalities of these platforms. 15 | 16 | ## Backstage 17 | 18 | ![Backstage](https://i.imgur.com/QKhnxYv.png) 19 | 20 | [Backstage](https://backstage.io/) is an open source platform that facilitates the creation of developer portals. The platform acts as a centralized catalog for all software assets. It's designed to bring structure to the often chaotic world of microservices and infrastructure, which should ultimately help development teams maintain code quality and enable them to ship code more quickly. 21 | 22 | ### Core Features 23 | 24 | Backstage works particularly well in large companies with substantial developer tooling. Its core feature, the [Backstage software catalog](https://backstage.io/docs/features/software-catalog/), can effectively manage a wide array of software, including but not limited to microservices, websites, and machine learning models. This tool provides a uniform overview of the entire software landscape of an organization, along with readily available metadata. This makes it easier to discover and manage software components—a significant advantage for large-scale operations. 25 | 26 | Backstage's [software templates](https://backstage.io/docs/features/software-templates/) allow developers in large companies to create software components in a consistent and standardized manner. This enhances overall efficiency and cohesion in expansive development environments. 27 | 28 | Backstage also features [TechDocs](https://backstage.io/docs/features/techdocs/), a tool that streamlines the creation, maintenance, and usage of technical documentation—an often complex task for large organizations. TechDocs adopts a "docs like code" approach that allows documentation to be created using the same principles as coding. This makes the documentation process more intuitive and straightforward. This further enhances the benefits for large companies with extensive developer tooling. 29 | 30 | ### UX/UI 31 | 32 | In terms of UX/UI, Backstage follows an iterative design approach, which means the platform is continually evolving and improving. The design team behind Backstage is also very collaborative and transparent. The team works closely with the community to make sure that the platform meets the needs of its users. On the other hand, however, some users have reported that the UI and UX of Backstage could be more visually appealing and still need some maintenance. For instance, inconsistencies in the platform's navigation across different sections are often highlighted. Some users have found it difficult to locate certain features due to the inconsistent placement of navigation elements, which interrupts the user flow and makes the experience less intuitive. 33 | 34 | ### Learning Curve and Complexity 35 | 36 | Backstage is engineered with a focus on user-friendliness and ease of use. It has a variety of features, such as a software catalog, software templates, and technical documentation, all strategically designed to facilitate developers in swiftly starting and operating their projects. Despite the platform's robust feature set, there’s lots of help when it comes to getting started with Backstage, thanks to comprehensive documentation, intuitive tutorials, and informative blog posts. These resources help reduce the learning curve, ensuring developers can leverage the platform's capabilities right from the get-go. 37 | 38 | ### Ease of Integration with Existing Infrastructure 39 | 40 | Backstage is quite versatile in terms of ease of integration with existing infrastructure. Not only does Backstage provide tooling to build Docker images, facilitating deployment on a wide range of infrastructures, but it can also be installed as a Node.js package. This dual capability further broadens the range of hosting services it can be deployed to. The platform is designed to be deployed in the same way as other software at your organization, which makes it easy to integrate with your existing infrastructure. 41 | 42 | ### Customizability and Extensibility 43 | 44 | Backstage's customizability is one of its strongest advantages. The platform has a growing [ecosystem of open source plugins](https://backstage.io/plugins/) that expand its customizability and functionality. These plugins allow platform engineers to easily integrate new tools and services, such as Jenkins for continuous integration, Grafana for data visualization, or Kubernetes for container orchestration. It also provides the capability to extend the functionality of existing plugins, creating a more robust, custom, and efficient infrastructure. 45 | 46 | ### Collaboration and Communication 47 | 48 | Backstage also has the capacity to foster improved communication and collaboration among developers. Its software catalog feature allows developers to understand the software landscape within the organization. This can reduce duplicate efforts and enhance team cooperation. Its software templates promote the use of best practices, streamlining project initiation and enforcing consistency across the organization. 49 | 50 | Backstage's plugins can create a unified platform for developers to interact with a myriad of tools and services, which directly improves collaboration and communication. While other tools might offer certain standalone features, Backstage excels at seamlessly integrating these functionalities. 51 | 52 | ### Documentation and Support 53 | 54 | The platform offers a variety of resources to assist users and developers. These include a [Discord server](https://discord.com/servers/backstage-687207715902193673) for support and project discussions, a [Stack Overflow section](https://stackoverflow.com/questions/tagged/backstage) for browsing or asking questions, and a list of ["good first issues"](https://github.com/backstage/backstage/contribute) for those who wish to contribute to the project. An [FAQ](https://backstage.io/docs/FAQ/) is available for quick reference. Updates and announcements are shared via a [blog](https://backstage.io/blog/) and an [email newsletter](https://info.backstage.spotify.com/newsletter_subscribe). The [Backstage community hub](https://backstage.io/community/) provides additional resources, including community sessions and recordings. 55 | 56 | #### Resource Requirements 57 | 58 | Backstage has several prerequisites for getting started. These include access to a Unix-based operating system such as Linux, macOS, or Windows Subsystem for Linux; an account with elevated rights to install dependencies; and having [curl](https://curl.se/) or [Wget](https://www.gnu.org/software/wget/) installed. Once you have these in place, Backstage can be deployed using [npm](https://www.npmjs.com/) packages and run with a SQLite in-memory database and demo content. However, it's important to note that running Backstage in a real environment typically involves containerizing the components. This may require additional effort and resources to set up. All of this means that getting started with Backstage can be a little complicated. 59 | 60 | ## OpsLevel 61 | 62 | ![OpsLevel](https://i.imgur.com/gpMQXeQ.png) 63 | 64 | [OpsLevel](https://www.opslevel.com/) is a developer portal designed to enhance the efficiency and standards of high-performing engineering teams. The portal provides a centralized location for cataloging all microservices, systems, teams, and tools, which offers visibility into the entire architecture at a glance. 65 | 66 | ### Core Features 67 | 68 | One of the core features of OpsLevel is the ability to build a complete software catalog in minutes just by connecting your Git forge. Teams can quickly gain an understanding of the services that exist in their ecosystem. Another core feature of OpsLevel is its ability to track every software object running in production and the team responsible for it. This provides 69 | visibility into the software architecture and can help teams understand its current health and maturity at a glance. OpsLevel also centralizes technical and API documentation, which makes it easier for developers to breeze through feature development and code fixes. 70 | 71 | ### UX/UI 72 | 73 | OpsLevel's UI and UX are designed with clarity and functionality in mind. The UI is sleek and intuitive, which makes navigation pretty simple, even for new users. The arrangement of data and controls contributes to a positive UX. This allows users to find and manage microservices efficiently. On the flip side, the richness of information and controls that OpsLevel provides can potentially lead to information overload, particularly for those who are new to the system. 74 | 75 | ### Learning Curve and Complexity 76 | 77 | OpsLevel offers a suite of features that facilitate microservice management. It includes a centralized [catalog](https://www.opslevel.com/microservice-catalog) that provides a database of all the microservices in your organization, along with vital information like ownership, technology stack, and health metrics. However, this breadth of functionality can result in a steep learning curve. Users may find OpsLevel's extensive feature set overwhelming initially, especially those unfamiliar with microservice architectures. The platform's reliance on multiple external service integrations for optimal functionality can further add to its complexity. Such integrations include commonly used CI/CD tools like [Jenkins](https://plugins.jenkins.io/opslevel/) and [GitHub Actions](https://docs.opslevel.com/docs/github-actions-integration), alerting and incident management systems like [PagerDuty](https://docs.opslevel.com/docs/pagerduty), and version control platforms like [GitHub](https://docs.opslevel.com/docs/github-integration). Despite its potential advantages, teams must consider their preparedness to navigate this learning curve and embrace its complexity before deciding to adopt OpsLevel. 78 | 79 | ### Ease of Integration with Existing Infrastructure 80 | 81 | OpsLevel can also integrate with existing infrastructure, such as Kubernetes, and popular Git providers like GitHub, GitLab, Azure DevOps Git, and Bitbucket. However, setting up these integrations may require some effort. For example, to [set up the GitHub integration](https://docs.opslevel.com/docs/github-integration), users must go to the Integrations tab in OpsLevel, hit the "New Integration" button, click the GitHub integration card, choose the GitHub App option, and follow the instructions within GitHub to install the OpsLevel GitHub App. 82 | 83 | ### Customizability and Extensibility 84 | 85 | OpsLevel features can be tailored to match specific workflows, and the ability of the platform to integrate with various external services bolsters its extensibility. All in all, this makes OpsLevel a versatile tool for microservice management, but this customization does come with challenges. Notably, the requirement to tailor the tool to the specific needs of the company can demand significant initial setup time. Moreover, its extensibility, while providing enhanced functionality, depends on integration with other services. For development teams that are not currently using these services or those who resist adopting them, this can be a barrier to fully utilizing OpsLevel's capabilities. As a result, development teams should evaluate their resources and readiness for such customization and integration efforts before implementing OpsLevel. 86 | 87 | ### Collaboration and Communication 88 | 89 | OpsLevel significantly enhances collaboration and communication within DevOps teams. It serves as a unified platform for tracking and managing microservices, which provides increased visibility across the team and fosters a shared understanding of the system's state. By centralizing information and promoting clear communication, OpsLevel supports cohesive team operations. This ultimately facilitates a more efficient and responsive DevOps workflow. 90 | 91 | ### Documentation and Support 92 | 93 | OpsLevel centralizes technical and API documentation that developers need to breeze through feature development and code fixes. OpsLevel also provides a [Getting Started](https://docs.opslevel.com/docs/getting-started) section on its website that includes explanations for various features and integrations, like setting up single sign-on, setting up checks for services, and interacting with the GraphQL API. 94 | 95 | ### Resource Requirements 96 | 97 | OpsLevel is a web-based software-as-a-service (SaaS) platform that runs on the cloud and is accessible via a web browser. The primary resources you need to utilize OpsLevel are a stable internet connection and a current web browser. There are typically no specific system requirements beyond what's needed to efficiently run a modern web browser. To leverage OpsLevel to its fullest potential, you would need a software infrastructure that OpsLevel supports, like microservices or APIs, and the capacity to integrate OpsLevel with your existing systems, such as version control systems, CI/CD pipelines, and alerting and monitoring tools. 98 | 99 | ## Port 100 | 101 | ![Port](https://i.imgur.com/cIGMNeV.png) 102 | 103 | [Port](https://www.getport.io/) is a developer portal designed to streamline and enhance the software development process. It provides a context-rich software catalog, maturity and quality scorecards, and comprehensive developer self-service actions. Port is designed to automate DevOps routines, reduce clutter around infrastructure, and save time spent on understanding, communicating, and managing DevOps assets. 104 | 105 | ### Core Features 106 | 107 | The key features of Port include a software catalog, live data inclusion, Kubernetes visibility, and self-service developer actions. The software catalog is populated via an API and allows you to create your own data model with unlimited blueprints and dependencies between any data model elements. It includes rich properties, facilitating data modeling with no coding involved. 108 | 109 | Additionally, Port includes a Kubernetes catalog, providing visibility for Kubernetes objects and support for multiple clusters and custom resource definitions (CRDs) like [Argo CD](https://argo-cd.readthedocs.io/en/stable/) and [Istio](https://istio.io/). Port also empowers workflow automation with event-based subscriptions, TTL cron jobs, scorecards, and live integration with tools such as Datadog, Jira, and PagerDuty. It supports native integration with CI/CD data. 110 | 111 | [Self-service experiences](https://docs.getport.io/create-self-service-experiences/) are designed to drive developer productivity by allowing developers to perform actions like scaffolding a service or provisioning a cloud resource independently. These actions bring consistency and repeatability. This ensures that developers follow best practices intuitively and clearly. 112 | 113 | However, it's important to note that Port lacks a built-in, docs-like-code solution (like TechDocs in Backstage) to enable developers to write their documentation in Markdown files that live together with their code—and get a nice-looking doc site in Port. This means that teams who prioritize integrated, easily accessible documentation may find Backstage more suitable for their needs. 114 | 115 | ### UX/UI 116 | 117 | Port offers an aesthetically pleasing user interface with a modern design and layout. On the flip side, it can potentially be overwhelming for some users. The platform is packed with features and tools, which can lead to a complex and dense user experience. The multitude of options and settings, combined with the extensive cataloging capabilities, might be especially confusing for new users or those not familiar with such comprehensive platforms. 118 | 119 | ### Learning Curve and Complexity 120 | 121 | While Port offers a comprehensive suite of features and a high degree of customizability, it has been reported that the platform can be quite challenging to learn, especially for beginners. The complexity of the system, combined with the multitude of options and settings, can make the initial learning curve steep. Users might find themselves daunted by the array of integrations, the process of setting up custom workflows, and the task of tailoring the platform to their specific needs. 122 | 123 | ### Ease of Integration with Existing Infrastructure 124 | 125 | Integrating third-party tools into Port can be a complex process, as you can see from the steps required for [AWS integration](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/aws/Installation/). Users must first ensure they have their Port credentials and necessary software installed, such as the AWS CLI and AWS SAM CLI. The integration process involves running scripts in the terminal, cloning the Terraform template, initializing Terraform requirements, and deploying the AWS exporter. Users must also set up EventBridge rules, invoke the AWS exporter Lambda function, and modify various parameters. This process requires a deep understanding of both Port and AWS systems, making it a potentially challenging task for those unfamiliar with these platforms. 126 | 127 | ### Customizability and Extensibility 128 | 129 | Port provides out-of-the-box integrations with a wide range of tools and also supports the creation of custom integrations, making it highly adaptable to various workflows and systems. This includes integrations with Git, CI/CD systems, Kubernetes, cloud platforms like AWS and GCP, and much more. 130 | 131 | ### Collaboration and Communication 132 | 133 | Port promotes collaboration and communication through various strategies. It encourages active information sharing via presentations and internal conferences, fostering a positive and productive team environment. Its developer portal consolidates processes into a self-service model, reducing the need for constant communication. However, Port does not offer out-of-the-box solutions for knowledge exchange and surveys regarding developer experience. Knowledge exchange is an important component of collaboration, as it allows team members to share insights, learn from one another, and avoid duplicating efforts. Similarly, surveys are an effective way to gauge the developer experience, understand developers' needs, and make necessary improvements. The absence of these features in Port could potentially lead to gaps in understanding and communication within the team, which could impact productivity and overall team synergy. 134 | 135 | ### Documentation and Support 136 | 137 | Port is committed to providing comprehensive and robust support to its users. This includes user-friendly documentation containing detailed guides, release notes, and blog articles. Beyond these resources, Port also maintains an active community where users can directly interact with engineers for support, provide input on product development, and connect with fellow users. 138 | 139 | ### Resource Requirements 140 | 141 | Port is a hosted solution that simplifies the resource requirements for its users by eliminating the need for individual hardware infrastructure and complex software maintenance. However, users must still maintain a stable internet connection, operate compatible devices capable of running Port's web browser or application interface, and secure adequate user licenses based on the size of the team and the nature of the projects. Additionally, considerations around data storage, including backup and archival needs, as well as user training for proficiency in the platform, are important. These resource commitments are essential for fully leveraging the benefits of this SaaS solution. 142 | 143 | ## Cortex 144 | 145 | ![Cortex](https://i.imgur.com/5HlvuEF.png) 146 | 147 | [Cortex](https://www.cortex.io/) is a developer portal designed to help engineering teams adopt and maintain microservices best practices. 148 | 149 | ### Core Features 150 | 151 | Cortex offers several core features designed to streamline the software development process. It includes a developer portal that provides engineering teams with visibility into their services, thus enabling the delivery of high-quality software. The platform allows for integration with third-party Git and APM tools, facilitating the setup of a robust GitOps workflow to keep the system updated. 152 | 153 | Additionally, Cortex provides an API that supports automation using Cortex as the definitive source for a [service catalog](https://www.cortex.io/products/service-catalog) and [scorecards](https://docs.cortex.io/docs/reference/basics/scorecards). This feature can help speed up the development of a resilient information architecture. 154 | 155 | ### UX/UI 156 | 157 | Cortex's design includes an intuitive user interface that prioritizes ease of use and user experience. The layout of the platform is clean and organized, which makes navigation straightforward and allows users to quickly locate the tools and features they need. 158 | 159 | ### Learning Curve and Complexity 160 | 161 | Cortex's documentation has a quick crash course on how to get started with Cortex, including how to connect to your third-party tools and set up a powerful GitOps workflow. Cortex also provides documentation on how to integrate with all of your favorite Git and APM tools, among others. This ensures that getting started with Cortex is not overly complicated for beginners. 162 | 163 | ### Ease of Integration with Existing Infrastructure 164 | 165 | Cortex provides a broad range of integrations with popular data sources and third-party tools, including AWS, Bitbucket, and GitHub, to name a few. The platform aims to integrate smoothly with your existing infrastructure and tools. However, the complexity of integration can vary depending on the specific third-party tool involved. For example, integrating Cortex with AWS can be quite intricate due to the multiple steps required. This process demands a comprehensive understanding of both AWS and Cortex systems. It's important to note that while Cortex strives for seamless integrations, the level of difficulty can fluctuate based on the tool you're integrating with. 166 | 167 | ### Customizability and Extensibility 168 | 169 | A significant disadvantage of Cortex is its limited customizability and extensibility due to the absence of plugin support. The lack of a plugin system restricts users from extending the functionality of the platform beyond its built-in features. This limitation can be a hindrance for teams that require specific functionalities or integrations that are not natively supported by Cortex. Without the ability to add plugins, users may find it challenging to tailor the platform to their unique needs or adapt it to evolving requirements. This lack of customizability and extensibility can limit the versatility of the platform and potentially impact its long-term suitability for some teams. 170 | 171 | ### Collaboration and Communication 172 | 173 | Cortex is engineered to boost communication and collaboration within businesses. It serves as a hub for each team that fosters collective service ownership, speeds up developer onboarding, and improves cross-team collaboration. Beyond just facilitating communication, Cortex also emphasizes the celebration of team achievements and organizational progress by recognizing top-performing teams through awarding badges and notifying the team of wins. This can contribute to a positive work environment. 174 | 175 | ### Documentation and Support 176 | 177 | Cortex provides documentation and support to streamline user onboarding and optimize the use of its features. This includes a quick start guide that helps users connect to third-party tools and establish a GitOps workflow. However, there can be instances where the documentation lacks detail. The lack of comprehensive instructions can make it challenging for users to fully understand how to properly integrate and use Cortex and third-party tools within their own systems. Such gaps can lead to potential misconfigurations, inefficiencies, and even security risks. 178 | 179 | ### Resource Requirements 180 | 181 | Cortex can be deployed on-prem into your own Kubernetes cluster. To operate Cortex in a self-managed setup, specific resource requirements must be met. This includes two instances of the backend container, each needing 3.5 GB of memory and, ideally, two cores. Additionally, a single instance of the frontend container is required, which has a low memory demand of less than 500 MB since it functions as a static Nginx proxy. A crucial component is a Postgres database, version 9 or higher, equipped with 15 GB of storage and 4 GB of memory. 182 | 183 | ## Conclusion 184 | 185 | As you can see, Backstage isn't your only option if you want to implement a developer platform. This article compared Backstage with three other notable developer tools: OpsLevel, Port, and Cortex. 186 | 187 | Backstage stands out for its robust customizability and growing ecosystem of open source plugins, making it an attractive option for larger companies with extensive developer tooling. However, some users have expressed concerns about its UI/UX and perceived complexity. OpsLevel and Port offer solid integrations with existing infrastructure and considerable customizability. However, they have potential challenges, such as a steep learning curve and substantial setup and management requirements. On the other hand, Cortex is designed for ease of use and promoting collaboration but lacks plugin support, resulting in limited customizability and extensibility. 188 | 189 | If you've followed along since the start of this series, you now know the why and how behind Backstage and seen how it compares to some other developer platforms. At this stage, you should know if Backstage is the right developer platform for you. If you're convinced, you can begin exploring its implementation in the first part of the next series, Implementing Backstage: Getting Started. 190 | -------------------------------------------------------------------------------- /implementing-backstage-1-getting-started-with-backstage-cli.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Implementing Backstage Part 1: Getting started with Backstage CLI" 3 | authors: 4 | - Erik Burger 5 | --- 6 | Backstage is a platform for building developer portals. Originally developed internally at Spotify, it's now open source and available through GitHub. Backstage allows DevOps teams to create a single-source, centralized web application for sharing and finding software (through the software catalog feature), as well as templates and documentation. Furthermore, by using plugins, you can connect a large number of existing tools to Backstage, such as [Google Analytics](https://github.com/backstage/backstage/blob/master/plugins/analytics-module-ga/README.md), [Azure Pipelines](https://github.com/backstage/backstage/blob/master/plugins/azure-devops/README.md), [Grafana](https://github.com/K-Phoen/backstage-plugin-grafana/), and many more. You can even [write your own plugins](https://backstage.io/docs/plugins), completely customizing the way your teams use Backstage. 7 | 8 | This article is the introduction to our "Implementing Backstage" series. In this first installment, you'll learn how to set up your own Backstage server from scratch, hosted in Azure. You'll also connect Backstage to a PostgreSQL database, set up authentication, and learn how to create and register new components in the software catalog. Finally, the article provides some guidance on keeping Backstage up-to-date and in sync with the latest platform features. 9 | 10 | If you're not quite ready to get started and are still trying to figure out if Backstage is right for you, the Evaluating Backstage series provides a great entry point. 11 | 12 | ## Getting Started with Backstage 13 | 14 | For this tutorial, you'll install Backstage on an Azure VM instance. Step-by-step instructions for creating a VM are out of the scope of this article, but if you follow the instructions here, you'll end up with the same basic VM used in this guide (though note that for this tutorial, the VM instance is called `Backstage` instead of `myVM`). 15 | 16 | After logging into the VM using SSH, your terminal should look something like this: 17 | 18 | ![Logged in to the Backstage VM with SSH](https://i.imgur.com/r1L2xdH.png) 19 | 20 | ### Prerequisites 21 | 22 | To complete the tutorial, you'll need: 23 | 24 | * The `make` and `build-essentials` packages to build the Backstage software. 25 | * [Node.js](https://nodejs.org/), as Backstage is built with Node. The recommended way to install Node.js is using `nvm`, a tool that allows for quick installation and switching between different Node.js versions. You can follow the [installation instructions](https://github.com/nvm-sh/nvm#installing-and-updating) to install `nvm`, then use `nvm` to [install Node.js](https://github.com/nvm-sh/nvm#usage). 26 | * The [Yarn](https://classic.yarnpkg.com/en/docs/install) package manager to create the Backstage project. 27 | * [Docker](https://www.docker.com/get-started). After you install it, you should run `sudo chmod o+rw /var/run/docker.sock` to ensure that Backstage is able to access Docker. If you forget this step, you're likely to run into an `Error connect EACCES /var/run/docker.sock` message while using Backstage. 28 | 29 | ### Opening Ports for Backstage 30 | 31 | As you are installing Backstage on an Azure VM, you'll need to open up ports 3000 and 7007 to make sure the Backstage app is accessible through the internet. 32 | 33 | > **Note:** This step is not necessary when you are installing Backstage on your own device. 34 | 35 | To do this, navigate to the **Networking** tab of the Backstage VM in the Azure portal: 36 | 37 | ![Networking tab in the Azure portal](https://i.imgur.com/gkL3cOo.png) 38 | 39 | Then, using the **Add inbound port rule** button, add the ports shown in the image below: 40 | 41 | ![Opening up ports 3000 and 7007](https://i.imgur.com/ErQaUVa.png) 42 | 43 | > **Note:** When creating the ports, you can specify **Source** to be **My IP address** to only allow your own device access to Backstage. This is more secure than using **Any**, which allows any IP address access. 44 | 45 | You're now ready to install the Backstage app. 46 | 47 | ### Installing the Backstage App 48 | 49 | To install the Backstage app, you need to run `create-app` from the `@backstage` package in the [npm](https://www.npmjs.com/) package registry. You can use `npx` for this, which, like `npm`, comes installed with Node.js: 50 | 51 | ```bash 52 | npx @backstage/create-app@latest 53 | ``` 54 | 55 | The installer will ask you to name your app. The default is `backstage`, which is fine for the purposes of the tutorial: 56 | 57 | ![Creating the Backstage app](https://i.imgur.com/GH6CGBv.png) 58 | 59 | It will then create a folder with the same name, copy several files, and run `yarn install` to install any dependencies for the project. 60 | 61 | After a few minutes, Backstage should be ready to go: 62 | 63 | ![Successful installation of Backstage](https://i.imgur.com/JUURNWI.png) 64 | 65 | Because you are running on an Azure VM, you need to make a few changes to the `app-config.yaml` file. Change into the `backstage` folder by typing `cd backstage`, and use your preferred editor to edit the following configurations: 66 | 67 | | Key | Value | 68 | | --------------------- | ------------------------------------- | 69 | | `app.baseUrl` | `http://0.0.0.0:3000/` | 70 | | `backend.baseUrl` | `http://:7007` | 71 | | `backend.cors.origin` | `http://:3000` | 72 | 73 | For ``, insert the IP address you used to SSH into your Azure VM. 74 | 75 | These settings make sure that the app can be opened in a browser using the IP address of your virtual machine. 76 | 77 | Run the app by typing `cd backstage` and `yarn dev`. This may take a little while. When successful, the message `webpack compiled successfully` will appear in your terminal. 78 | 79 | Once it's complete, you can open a browser and visit `http://:3000`: 80 | 81 | ![Visiting Backstage for the first time](https://i.imgur.com/46o3HtT.png) 82 | 83 | The application is prefilled with demo data, so you can start exploring right away. 84 | 85 | ### Connecting to a PostgreSQL Database 86 | 87 | Because the default installation of Backstage comes configured with an in-memory database, any changes you make will disappear when you restart your server or the application. That's not ideal, so you'll now connect Backstage to a newly installed PostgreSQL database. 88 | 89 | #### Installing PostgreSQL 90 | 91 | First, use the following code to install the `postgresql` package: 92 | 93 | ```bash 94 | sudo apt install postgresql 95 | ``` 96 | 97 | Open a connection to the PostgreSQL database: 98 | 99 | ```bash 100 | sudo -u postgres psql 101 | ``` 102 | 103 | Your terminal should look something like this: 104 | 105 | ![Logged in to PostgreSQL](https://i.imgur.com/VJx2BP4.png) 106 | 107 | Lastly, create a user named `backstage` by running the following at the `postgres=#` prompt: 108 | 109 | ```bash 110 | create user backstage with encrypted password 'supersecretpassword'; 111 | alter user backstage CREATEDB; 112 | ``` 113 | 114 | #### Connecting Backstage 115 | 116 | To enable Backstage to connect to the PostgreSQL database, you need to install the `backend` package for PostgreSQL. From the `backstage` folder, run the following: 117 | 118 | ```bash 119 | yarn add -cwd packages/backend pg --ignore-workspace-root-check 120 | ``` 121 | 122 | Then, in the `app-config.yaml` file, you need to modify the `database` section. 123 | 124 | In the `database` section, find this code: 125 | 126 | ```yaml 127 | client: better-sqlite3 128 | connection: ':memory:' 129 | ``` 130 | 131 | Replace it with the following: 132 | 133 | ```yaml 134 | client: pg 135 | connection: 136 | host: 127.0.0.1 # Because you're running locally 137 | port: 5432 # The standard PostgreSQL port (could be 5433) 138 | user: backstage # The user you created earlier 139 | password: supersecretpassword # The password for the 'backstage' user 140 | ``` 141 | 142 | Run the Backstage app again (using `yarn dev`). While booting up, you should see a line that says `catalog info Performing database migration`, and no errors. This means that everything is working as it should, and Backstage has just initialized the database. 143 | 144 | ### Setting Up Authentication 145 | 146 | In a standard installation, Backstage doesn't use any kind of authentication. Instead, a `guest` identity is created, and all users share this identity. This means that anyone with access to the URL of your installation can go in and make changes. And because all users share the same identity, it's impossible to know who made those changes and why. 147 | 148 | To ensure that users are required to log in, Backstage supports a long list of authentication providers. For example, [Auth0](https://backstage.io/docs/auth/auth0/provider), [Azure](https://backstage.io/docs/auth/microsoft/provider), and [GitHub](https://backstage.io/docs/auth/github/provider) are all supported out of the box. In this tutorial, you'll use GitHub. 149 | 150 | First, register your Backstage application with GitHub by [creating an OAuth application](https://github.com/settings/applications/new) using the information in the table below: 151 | 152 | | Field | Value | 153 | | -------------------------- | ------------------------------------------------------------------- | 154 | | Application name | Backstage | 155 | | Homepage URL | `http://:3000/` | 156 | | Authorization callback URL | `http://:7007/api/auth/github/handler/frame` | 157 | 158 | Again, for ``, insert the IP address of your Azure VM. 159 | 160 | In the Backstage application screen, click **Generate a new client secret** to create a client secret. You'll need this in the following steps, along with the client ID. 161 | 162 | You'll need to make some more changes to the `app-config.yaml` file. Under the `auth` section, find the following code: 163 | 164 | ```yaml 165 | providers: {} 166 | ``` 167 | 168 | Replace that code with the following: 169 | 170 | ```yaml 171 | experimentalExtraAllowedOrigins: [ 'http://:3000' ] 172 | environment: development 173 | providers: 174 | github: 175 | development: 176 | clientId: 177 | clientSecret: 178 | ``` 179 | 180 | Replace `` with the client ID and `` with the client secret from your Backstage application on GitHub. 181 | 182 | > **Note:** The `experimentalExtraAllowedOrigins` configuration is required to make authentication work, or you'll get **Origin not allowed** errors. For more details, see the [Troubleshooting Auth](https://backstage.io/docs/auth/troubleshooting/) page in the Backstage documentation. 183 | 184 | The last step for enabling GitHub authentication is adding the login page. To do this, you need to edit the `App.tsx` file, which lives in the `packages/app/src` folder. 185 | 186 | Add the following after the last `import` line: 187 | 188 | ```tsx 189 | import { githubAuthApiRef } from '@backstage/core-plugin-api'; 190 | import { SignInPage } from '@backstage/core-components'; 191 | ``` 192 | 193 | Then, in `const app = createApp({`, add the following under the `apis` line: 194 | 195 | ```tsx 196 | components: { 197 | SignInPage: props => ( 198 | 208 | ), 209 | }, 210 | ``` 211 | 212 | This registers the `SignInPage` component and configures it to use GitHub as the authentication provider. 213 | 214 | To apply your changes, stop Backstage with **Ctrl+C** and start it again using `yarn dev`. In the boot messages, you should see a line that says `auth info Configuring auth provider: github`. 215 | 216 | Now, when you open Backstage in the browser, you'll be asked to sign in using GitHub: 217 | 218 | ![Backstage sign-in screen and GitHub sign-in pop-up](https://i.imgur.com/Vm8Y7mH.png) 219 | 220 | After you log in, go to the **Settings** tab. You should see your GitHub profile displayed: 221 | 222 | ![Profile screen after logging in](https://i.imgur.com/AMNXE4Y.png) 223 | 224 | Under **Authentication Providers**, you'll see that GitHub is enabled as an available auth provider: 225 | 226 | ![Available authentication providers showing GitHub](https://i.imgur.com/vzb5HuM.png) 227 | 228 | ### Creating and Registering New Components 229 | 230 | The [software catalog](https://backstage.io/docs/features/software-catalog/) feature is one of the main components of Backstage. It's a central location for storing and getting information about all the services, APIs, resources, and other software components that make up your software development ecosystem. 231 | 232 | #### Registering a Component 233 | 234 | To add a component to the software catalog, you need to register its metadata, which is stored in source control (such as GitHub) in Backstage's own [YAML format](https://backstage.io/docs/features/software-catalog/descriptor-format). 235 | 236 | In the [GitHub repo](https://github.com/erikbrgr/backstage-getting-started) for this tutorial, there's an example `catalog-info.yaml` file for a to-do website built in React. It looks like this: 237 | 238 | ```yaml 239 | apiVersion: backstage.io/v1alpha1 240 | kind: Component 241 | metadata: 242 | name: todo-react 243 | title: To-do in React 244 | description: A web-based To-do application, written in React. For demonstration purposes only! 245 | tags: 246 | - react 247 | - website 248 | spec: 249 | type: service 250 | lifecycle: experimental 251 | owner: dev-support 252 | ``` 253 | 254 | To register this component in Backstage, go to the **Create** tab, click the **Register Existing Component** button, and step through the wizard. 255 | 256 | First, enter the URL to the `catalog-info.yaml` file (`https://github.com/erikbrgr/backstage-getting-started/blob/main/catalog-info.yaml`) and click **ANALYZE**: 257 | 258 | ![Selecting a URL](https://i.imgur.com/GfV1hRB.png) 259 | 260 | Then, review the entities that will be added to the catalog and click **IMPORT**: 261 | 262 | ![Reviewing entities](https://i.imgur.com/vCcTzeu.png) 263 | 264 | After importing, you can either view the component you just added or add another component: 265 | 266 | ![Registering a new component](https://i.imgur.com/PvaHAbz.png) 267 | 268 | If you navigate to the **Home** tab, you can see your component has been added: 269 | 270 | ![Software catalog showing your newly added component](https://i.imgur.com/dODik7g.png) 271 | 272 | The information in Backstage is automatically updated whenever the `catalog-info.yaml` file is updated. 273 | 274 | #### Using Templates to Create a New Component 275 | 276 | Backstage allows you to register and use templates for quickly scaffolding new apps, services, and other components in your GitHub repo. 277 | 278 | To use templates, you'll first need to create a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) (PAT). Alternatively, you can set up a [GitHub App](https://backstage.io/docs/integrations/github/github-apps), but that is outside of the scope of this tutorial. 279 | 280 | You can do the following to create a GitHub PAT: 281 | 282 | * Navigate to the [GitHub PAT creation page](https://github.com/settings/tokens/new). 283 | * In the **Note** field, enter the name of the token, such as `backstage-token`. 284 | * Choose a value for **Expiration** and select the scope of your token. When creating a template, you'll need to select at least the **repo** scope. 285 | 286 | ![Creating a personal access token](https://i.imgur.com/hULP5FZ.png) 287 | 288 | In your `app-config.yaml` file, replace `${GITHUB_TOKEN}` with the value of your PAT. 289 | 290 | You can now create your first component. In the **Create** tab, choose the **Example Node.js Template**. Complete the following details: 291 | 292 | * Enter a name for your new component, such as `getting-started`. 293 | * For **Owner**, enter your GitHub username. 294 | * For **Repository**, enter the name of the repository you want the component to be created in. This should be a nonexistent repository (for example, `backstage-getting-started-with-nodejs`). 295 | 296 | Then, review your settings and click **Create**. After a few moments, the creation process should complete: 297 | 298 | ![Successfully create a component](https://i.imgur.com/SYKanYC.png) 299 | 300 | If you click **Repository**, you'll be taken to the private GitHub repository that was just created for you: 301 | 302 | ![GitHub repo created by Backstage](https://i.imgur.com/w5Rmy4u.png) 303 | 304 | Of course, your new component is also registered with the Backstage software catalog, so you can track it from there. 305 | 306 | ### Keeping Backstage Up to Date 307 | 308 | Because Backstage is open source, it's continually being improved and updated. Backstage provides the Backstage CLI to perform updates to its packages and dependencies. `backstage-cli` is installed when you install Backstage. 309 | 310 | #### Updating Backstage Packages 311 | 312 | Backstage releases a main release every month. To update Backstage to this release, use: 313 | 314 | ```bash 315 | yarn backstage-cli versions:bump 316 | ``` 317 | 318 | There is also a weekly release, which you can upgrade to by using the `--release next` parameter: 319 | 320 | ```bash 321 | yarn backstage-cli versions:bump --release next 322 | ``` 323 | 324 | Finally, if you are using plugins, you can include them in the update by using the `--pattern` parameter. For example: 325 | 326 | ```bash 327 | yarn backstage-cli versions:bump --pattern '@{backstage,lighthouse}/*' 328 | ``` 329 | 330 | #### Updating the Backstage App Templates 331 | 332 | When you install Backstage using the `@backstage\create-app` command, it uses a template to create the initial app structure. Using `backstage-cli` to update the Backstage packages does not update the app template. This makes sense because you might have made changes to the app yourself. 333 | 334 | To keep track of updates to the app template, you should regularly check out the [changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md) for Backstage. In the changelog, any changes to the app template are documented, and you can integrate these changes into your own app if and when needed. 335 | 336 | ## Conclusion 337 | 338 | In this article, you learned how to set up your own Backstage server from scratch, hosted in an Azure VM instance. You set up a PostgreSQL database for Backstage to connect to, set up authentication, and learned how to create and register new components in the software catalog. Finally, you learned how to ensure that Backstage is up-to-date and supports the latest features. 339 | 340 | You now know how to get Backstage up and running. To find out how to use its core features, continue reading part two of this series. 341 | -------------------------------------------------------------------------------- /implementing-backstage-3-integrating-with-existing-tools-using-plugins.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Implementing Backstage 3: Integrating with Existing Tools Using Plugins" 3 | authors: 4 | - Carlos Eduardo Inocencio Alanis 5 | --- 6 | This third part of the "Implementing Backstage" series explains how to integrate Backstage with existing tools and plugins. 7 | 8 | If you’re at an earlier stage of your Backstage implementation, the two previous installments in this series focus on [getting started](https://www.kosli.com/blog/implementing-backstage-getting-started/) and [using the core features](https://www.kosli.com/blog/implementing-backstage-using-the-core-features/). If you're looking for a more general introduction to Backstage, you can read the [first article](https://www.kosli.com/blog/evaluating-backstage-why-backstage/) in the "Evaluating Backstage" series. 9 | 10 | Plugins allow you to take advantage of the open source community that has formed around Backstage. You can navigate to the [plugin directory](https://backstage.io/plugins/) and see the ever-growing list of ready-to-implement solutions. Plugins can extend your Backstage app without investing many resources in coding solutions from scratch. 11 | 12 | In this article, you'll build and deploy a simple app to the cloud. Since this article focuses on integrating an app with Backstage rather than deploying it, the tech stack has been chosen specifically to simplify deployment and reduce operational costs. 13 | 14 | ## How to Integrate with Existing Tools Using Plugins 15 | 16 | The app you'll deploy is a simple wedding website that uses S3 static web hosting. This website includes a "Who's Coming?" button. When a user clicks the button, a Lambda function is triggered that retrieves and shows the list of attendees on the website. You'll integrate the app with plugins for GitHub, Datadog, and HashiCorp Vault. After you complete the integrations, you'll see all of them working together within Backstage. 17 | 18 | All the relevant code can be found on [GitHub](https://github.com/CarlosIA12/backstage-plugins-tutorial), and detailed instructions will be provided later in the article. 19 | 20 | ### Setting Up Your Workspace: Creating a Backstage App 21 | 22 | You need a working Backstage app to complete this tutorial. All the details of deploying a new Backstage app are beyond the scope of this article, but if you've followed along from the previous installments, you should have one already. If you don't have an app, [part one](https://www.kosli.com/blog/implementing-backstage-getting-started/) of this series is a great place to start. Let's go over the main steps here. 23 | 24 | Run the following command and follow the instructions after: 25 | 26 | ```bash 27 | npx @backstage/create-app@latest 28 | ``` 29 | 30 | After you create the new app instance, [set up GitHub authentication](link_to_secure_your_application_article). Ensure you have a publicly visible email in your GitHub account, or you'll receive an error while logging in. 31 | 32 | ### Setting Up a HashiCorp Vault Instance 33 | 34 | As mentioned earlier, Vault will serve as a secret store for the application. There are many ways you can deploy a Vault instance. Since the focus of this article is on the integrations with Vault and not on how to deploy Vault, you'll use the easiest approach: create a local Vault dev instance and write a simple secret there. 35 | 36 | You'll first need to [install the Vault CLI](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install). Once you have it set up, you can run: 37 | 38 | ```bash 39 | vault server -dev 40 | ``` 41 | 42 | This will initialize a preconfigured server, which is ideal for testing Vault functionalities. This deployment is not suitable for production environments but will suffice for this tutorial. The output from the previous command will give you the needed endpoint and admin token to connect to your Vault instance. It will look something like this: 43 | 44 | ```bash 45 | # ... other logs 46 | WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory 47 | and starts unsealed with a single unseal key. The root token is already 48 | authenticated to the CLI, so you can immediately begin using Vault. 49 | 50 | You may need to set the following environment variables: 51 | 52 | $ export VAULT_ADDR='http://127.0.0.1:8200' 53 | 54 | The unseal key and root token are displayed below in case you want to 55 | seal/unseal the Vault or re-authenticate: 56 | 57 | Unseal Key: Sm0PKEBQ8gJXXXXXXXXXXXb1t1Wena3y1gBkefAM= 58 | Root Token: hvs.CVIuRB4tX8IXXXXXXXXXXX 59 | 60 | Development mode should NOT be used in production installations! 61 | ``` 62 | 63 | Save the root token and Vault address as environmental variables called `$VAULT_TOKEN` and `$VAULT_ADDR`, respectively. Also, copy them to your clipboard. You'll need them to access the UI in the next step. 64 | 65 | Open a web browser, navigate to the Vault address, enter the root token, and click **Sign In**. 66 | 67 | After the UI loads, you'll see two default folders: `cubbyhole` and `secret`. Click the `secret` folder, which functions as a key-value secret engine, and then **Create secret** in the upper-right corner. 68 | 69 | You'll be presented with a form to create a new secret. There is one important caveat to mention here, which is that the Backstage plugin uses the [`LIST`](https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#list-secrets) method to connect to your instance, so your secret has to be inside a folder. This means that when filling in the **Path for this secret** field, you need to include at least one subpath using `/`. This tutorial uses `backstage/backstage-plugins-tutorial` for said path, a key called `attendees`, and comma-separated names for values: 70 | 71 | ![New secret setup](https://i.imgur.com/4v0oRkC.png) 72 | 73 | Take note of the path where your secret is saved. You'll need it later. 74 | 75 | ### Creating a Lambda Function for Event Handling 76 | 77 | As mentioned, S3 will handle the web hosting. However, before deploying the website to S3, you need to generate a Lambda endpoint for the function that listens and responds to clicks on your website. Go to your AWS account and [create a new Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html), then add a [Lambda function URL](https://docs.aws.amazon.com/lambda/latest/dg/urls-configuration.html) with `Auth type=NONE`. Take note of the resulting Lambda endpoint. 78 | 79 | In the [repository for this article](https://github.com/CarlosIA12/backstage-plugins-tutorial), there is a ZIP file you can use to create an [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-package.html#gettingstarted-package-zip). The ZIP files contain the `requests` library and the following Lambda code: 80 | 81 | ```python 82 | import json 83 | import os 84 | import requests 85 | 86 | def lambda_handler(event, context): 87 | 88 | # Define the Vault API endpoint and headers 89 | vault_url = os.environ.get('VAULT_URL') 90 | vault_token = os.environ.get('VAULT_TOKEN') 91 | vault_namespace = "admin" 92 | 93 | headers = { 94 | "X-Vault-Token": vault_token, 95 | "X-Vault-Namespace": vault_namespace, 96 | } 97 | 98 | # Define the path to the secret 99 | secret_path = "/v1/secret/data/backstage-plugins-tutorial" 100 | 101 | # Make the HTTP GET request to Vault 102 | response = requests.get(vault_url + secret_path, headers=headers) 103 | 104 | # Check if the request was successful (status code 200) 105 | if response.status_code == 200: 106 | # Parse the JSON response 107 | data = response.json() 108 | 109 | # Extract the "data" field 110 | secret_data = data.get("data") 111 | 112 | if secret_data: 113 | secret_data['data']['attendees'] = secret_data['data']['attendees'].split(',') 114 | attendees = {"attendees": secret_data['data']['attendees']} 115 | return { 116 | 'statusCode': 200, 117 | 'body': json.dumps(attendees) 118 | } 119 | else: 120 | print("Secret data not found.") 121 | else: 122 | print("Error: Request to Vault failed with status code", response.status_code) 123 | ``` 124 | 125 | This code requires that you set up an environmental variable for the Lambda with the endpoint and token you created earlier to access the HashiCorp Vault instance. In a production environment, you must save those access codes securely with a service like [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/). Since your focus is elsewhere, you can put them as plain text environmental variables for this tutorial, but remember to delete them afterward. 126 | 127 | ### Using S3 for Static Web Hosting 128 | 129 | You'll use S3 to [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html). You'll need to follow the instructions for setting up static web hosting, give your bucket a name, and configure static website access and permissions. 130 | 131 | Once you are done setting up the bucket, upload an `index.html` file with the following code: 132 | 133 | ```html 134 | 135 | 136 | 137 | 138 | 139 | Super Secret Wedding Site 140 | 224 | 225 | 226 |
227 | 228 | Wedding Image 229 | 230 | 231 |
232 |
Super Secret Wedding Site
233 |
234 | 235 | 236 |
237 | 238 |
239 | 240 | 241 |
242 |
243 | 244 |
245 |
246 |
247 | 248 | 278 | 279 | ``` 280 | 281 | Then, upload an `error.html` file with the following code: 282 | 283 | ```html 284 | 285 | 286 | 287 | 288 | 289 | Error - Oopsie! 290 | 312 | 313 | 314 |
315 |

Oopsie!

316 |

There seems to be an error on our side.

317 |

We'll look into that and try to fix it as soon as possible.

318 |
319 | 320 | 321 | ``` 322 | 323 | You'll also need to upload an image called `wedding-background.jpg`. You can use any image you want as long as it has that name, but a [small example image](https://github.com/CarlosIA12/backstage-plugins-tutorial/blob/main/wedding-background.jpg) is provided in the repository. 324 | 325 | With all these pieces in place, you can navigate to the **Properties** tab of the S3 bucket hosting the website and scroll down until you find the URL for your website: 326 | 327 | ![Example of S3 endpoint](https://i.imgur.com/jIIGIL0.png) 328 | 329 | That URL should take you to your demo app. The rest of the article will use all the resources created in this section for the integrations. 330 | 331 | ### Creating a Datadog Account for Resource Monitoring 332 | 333 | You'll use [Datadog](https://www.datadoghq.com/) to monitor the app that you just deployed. Go to the [Datadog sign-up page](https://us5.datadoghq.com/signup) and provide all the necessary information to create a new account. Note that you do not need to set up an agent for this tutorial. 334 | 335 | First, create a new IAM user in your AWS account [using this resource](https://docs.datadoghq.com/getting_started/integrations/aws/). Then, go to the **Integrations** page in Datadog, select **Amazon Web Services**, and select **Add New AWS Account(s)**. On the **Add a Single AWS Account** tab, select **Automatically using CloudFormation**. Choose an API key, opt to send AWS logs to Datadog, and don't enable Cloud Security Posture Management: 336 | 337 | ![Datadog config](https://i.imgur.com/4FbGcd1.png) 338 | 339 | Hit **Launch CloudFormation Template**. You'll be redirected to your AWS CloudFormation page. Leave any data that was automatically filled in, confirm the checkboxes asking for acknowledgement of resource creation, and click **Create stack**: 340 | 341 | ![AWS quick stack config](https://i.imgur.com/NZAGsib.png) 342 | 343 | Once the stack is created, you'll have a new integration with your account. If you navigate back to your Datadog account, you'll now see the AWS integration: 344 | 345 | ![AWS integration](https://i.imgur.com/haSPj60.png) 346 | 347 | You now need to create a new dashboard and include the services relevant to the app. In this case, that means AWS Lambda and Amazon S3. On your Datadog home page, go to the left panel and click **Dashboards**. Then, in the top-right corner, select **New Dashboard** to open a window where you can name your dashboard: 348 | 349 | ![Create dashboard](https://i.imgur.com/dw0bBeq.png) 350 | 351 | After clicking **New Dashboard**, you'll be presented with an empty area. To build the dashboard, click the empty card that reads either **Click a tray item to add it here** or **Add Widgets or Powerpacks**, then drag a **Query Value** widget to the area. 352 | 353 | ![Example query metric](https://i.imgur.com/aYOQkyl.png) 354 | 355 | After selecting the metric you are interested in, click **Save**. For this tutorial, the dashboard includes two Query Value widgets for the values `aws.lambda.invocations` and `aws.s3.bucket_size_bytes`. 356 | 357 | ![Example dashboard](https://i.imgur.com/8AXoeyc.png) 358 | 359 | When you are happy with the metrics and the look of your dashboard, click the **Share** button at the top of the dashboard, and then **Generate public URL**: 360 | 361 | ![Sharing your dashboard](https://i.imgur.com/1IO5fSj.png) 362 | 363 | Set it up as a public dashboard, and save the dashboard URL for later. 364 | 365 | ### Integrating Backstage with the GitHub Plugin 366 | 367 | You'll now integrate Backstage with a plugin to [monitor and visualize pull requests](https://roadie.io/backstage/plugins/github-pull-requests/) to help you manage your project easier. You can learn how to set up plugins for static code analysis in the [next installment](__link_to_security_article__) of this series. 368 | 369 | First, you need to install the plugin by running this command at the root of your project: 370 | 371 | ```bash 372 | yarn add --cwd packages/app @roadiehq/backstage-plugin-github-pull-requests 373 | ``` 374 | 375 | Go to the catalog code at `packages/app/src/components/catalog/EntityPage.tsx` and find `serviceEntityPage` and `overviewContent`. Add the following code alongside the other routes and cards: 376 | 377 | ```typescript 378 | // ... other imports 379 | import { EntityGithubPullRequestsOverviewCard } from '@roadiehq/backstage-plugin-github-pull-requests'; 380 | // ... rest of the code 381 | 382 | const overviewContent = ( 383 | 384 | {entityWarningContent} 385 | 386 | 387 | 388 | 389 | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | ); 398 | 399 | const serviceEntityPage = ( 400 | 401 | 402 | 403 | 404 | 405 | 406 | ); 407 | ``` 408 | 409 | That's all the setup needed for the plugin to work. To see it in action, you need to register a component. You'll do that after setting up all the plugins later in this article. 410 | 411 | ### Integrating Backstage with the Vault Plugin 412 | 413 | You'll use the Vault plugin to visualize available secrets. Following the same pattern as before, the first thing to do is install the plugin: 414 | 415 | ```bash 416 | yarn add --cwd packages/app @backstage/plugin-vault 417 | ``` 418 | 419 | Again, find the `packages/app/src/components/catalog/EntityPage.tsx` code. You must include a new import. Then locate `overviewContent` and modify it to use the Vault plugin with the following code: 420 | 421 | ```typescript 422 | import { EntityVaultCard } from '@backstage/plugin-vault'; 423 | // Other code 424 | const overviewContent = ( 425 | 426 | 427 | 428 | 429 | 430 | ); 431 | ``` 432 | 433 | Next, install the backend plugin for Vault and run the following: 434 | 435 | ```bash 436 | yarn add --cwd packages/backend @backstage/plugin-vault-backend 437 | ``` 438 | 439 | When the installation is ready, go to `packages/backend/src/plugins` and create a new file called `vault.ts`. Paste the following code: 440 | 441 | ```typescript 442 | import { createRouter } from '@backstage/plugin-vault-backend'; 443 | import { Router } from 'express'; 444 | import { PluginEnvironment } from '../types'; 445 | 446 | export default async function createPlugin( 447 | env: PluginEnvironment, 448 | ): Promise { 449 | return await createRouter({ 450 | logger: env.logger, 451 | config: env.config, 452 | scheduler: env.scheduler, 453 | }); 454 | } 455 | ``` 456 | 457 | Locate the `packages/backend/src/index.ts` file and modify it as follows: 458 | 459 | ```typescript 460 | // Include a new import 461 | import vault from './plugins/vault' 462 | // ... 463 | // Find the main() funcion 464 | async function main() { 465 | const config = await loadBackendConfig({ 466 | argv: process.argv, 467 | logger: getRootLogger(), 468 | }); 469 | const createEnv = makeCreateEnv(config); 470 | const vaultEnv = useHotMemoize(module, () => createEnv('vault')); 471 | // ... 472 | // Find where the other routes are being generated 473 | apiRouter.use('/vault', await vault(vaultEnv)); 474 | // ... rest of the code 475 | ``` 476 | 477 | You then need to change the app configuration in `app-config.yaml` to include the following block: 478 | 479 | ```yaml 480 | vault: 481 | baseUrl: ${VAULT_ADDR} 482 | token: ${VAULT_TOKEN} 483 | secretEngine: secret # This is the name of your secrets engine. By default, vault uses "secrets" 484 | kvVersion: 2 485 | ``` 486 | 487 | After you finish the plugin setup, you'll register a component using this configuration. 488 | 489 | ### Integrating Backstage with the Datadog Plugin 490 | 491 | To integrate the Datadog account into Backstage, the next step is to install the appropriate plugin, similar to the rest, and run this command: 492 | 493 | ```bash 494 | yarn add --cwd packages/app @roadiehq/backstage-plugin-datadog 495 | ``` 496 | 497 | Next, find the `packages/app/src/components/catalog/EntityPage.tsx` file and include the following code: 498 | 499 | ```typescript 500 | import { 501 | EntityDatadogContent, 502 | EntityDatadogGraphCard, 503 | isDatadogGraphAvailable 504 | } from '@roadiehq/backstage-plugin-datadog'; 505 | 506 | // Find the service entity page and add this card 507 | const serviceEntityPage = ( 508 | 509 | 510 | 511 | 512 |