Each engineering platform will evolve uniquely based on the organization's specific needs. However, most internal engineering platforms incorporate several fundamental capability domains, including those below:
- An internal developer portal
- Repository templates
- Paved and golden paths
- A software/service catalog
- A documentation repository
- Scorecards
- GenAI capabilities "as a Service"
Figure 3: Overview of platform engineering capabilities
Self-Service Developer Portal
Developer portals streamline operations with internal developer platforms (IDPs), making it easier for teams to discover and leverage platform resources and services effectively. According to Gartner, by 2026, 75% of organizations with platform engineering teams will offer developer portals to enhance the developer experience and accelerate innovation.
Developer portals typically consist of the following key components:
- Universal software and service catalog
- Software templates based on existing practices
- Technical auto-documentation
- Access management via RBAC
Developer portals offer self-service and automation capabilities, allowing development teams to independently perform routine tasks such as automatically provisioning environments, deploying applications, discovering services, and requesting permissions. Tools embedded in the portal can automate tasks like triggering alerts, terminating temporary environments, and managing permissions, therefore ensuring consistency and improving the efficiency of development workflows. Portals also provide platform engineering and development teams with access to dashboards that display platform performance, status, and adoption metrics.
Developer Portal Example: Backstage.io
One of the earliest and most widely adopted developer portals is Backstage.io, an open-source framework originally developed by Spotify. Rather than being a standalone portal, Backstage serves as a framework that allows platform engineers to create customized developer portals. This flexibility is due to Backstage's plugin-based architecture, which makes it highly extensible and adaptable for various use cases, allowing development teams to customize their experience.
However, Backstage lacks enterprise-level features such as RBAC, dedicated customer support, extended lifecycle management, certifications, and support for legacy versions. This gap is filled by enterprise-grade internal developer portals, which either extend Backstage or offer more comprehensive enterprise solutions. These platforms provide advanced features like RBAC, integration with container platforms, dynamic and verified plugins, orchestration for configuration and infrastructure, data aggregation, and scalable infrastructure.
Repository Templates
Repository templates allow development teams to share boilerplate code across codebases. This capability enables efficient project bootstrapping with preferred tools and directory structures, significantly reducing manual configuration and compatibility issues. By standardizing the initial set-up process, repository templates ensure consistency across projects, making it easier for developers to transition between different codebases and maintain a uniform development environment.
Platforms provide a centralized way to store these templates, offering a streamlined method for accessing and utilizing them in each repository's pipelines. This centralization simplifies template management and enhances collaboration among development teams. By storing repository templates and reusable workflows in a centralized repository, they can be used across multiple repositories while being managed in a central location. This approach ensures that development teams consistently follow best practices and organizational standards, improving efficiency and reducing potential errors.
Additionally, it provides predefined structures for bug reports, feature requests, and discussions, further streamlining the development process. Finally, repository templates are the foundation upon which golden paths are built.
Paved and Golden Paths
One of the key ways platform engineering reduces cognitive load and complexity is via self-service templates for common tasks that streamline the development process, called paved paths or golden paths. Golden paths are designed to provide a single, clear method to accomplish specific tasks so that teams don't have to reinvent the wheel. They reduce the cognitive load on developers by using abstractions and comprehensive documentation. Essentially, golden paths are configurable, extensible templates that offer transparency, making it easy for developers to understand, customize, and add additional capabilities if required.
In practice, golden paths typically include clear instructions for developers, a clearly defined audience, a repository template, platform integrations with services and tooling, templated CI/CD pipelines, deployment manifests, observability capabilities, and IaC configurations for both staging and production environments. The self-service nature of golden paths, along with the internal developer portal, allow development teams to discover and use them without the need for a ticketing system.
Platform engineering teams build, document, and maintain the golden path templates. They also set KPIs and quantitative goals and create dashboards to track golden path adoption within the organization.
Example Golden Path Use Case
Let's see a typical example of how golden paths can help development teams. The workflow starts with the platform engineering team creating a golden path for development teams who need to deploy microservices using Kubernetes. This golden path includes a pre-configured Kubernetes Deployment template integrated with the company's existing managed Kubernetes cloud service, along with automated security policies and observability tools like Prometheus for monitoring and Grafana for visualization.
Each golden path is typically associated with an intent-based statement, and for this particular use case, the statement could be:
"I want to deploy a scalable Spring Boot microservice on Kubernetes and have automated monitoring, logging, and security policies integrated."
A development team working on a new microservice can use the internal developer portal and select the specific golden path template, which automatically provisions the infrastructure (e.g., staging and production environments) and applies the necessary CI/CD pipeline for continuous deployment. The golden path applies built-in best practices for security and compliance, such as RBAC, container image scanning, and static code analysis.
By following this predefined golden path, the development team can reduce the time spent on configuring environments and troubleshooting infrastructure issues, allowing them to focus on building and improving the microservice itself.
Figure 4: Abstract illustration of the golden path example use case
Software/Service Catalog
Service catalogs help organizations avoid duplicated efforts by making projects and resources visible across teams. As projects, products, and teams evolve, projects can become orphaned. Inventories help address these issues by acting as a single source of truth. Inventories improve security, promote reuse, and make discovery easier. An inventory is a tool or system used to track, manage, and organize an organization's technical assets, including code, templates, APIs, containers, virtual machines (VMs), and team permissions. The open-source portal framework, Backstage.io, refers to this capability as a software catalog while other products may use terms like service or software inventory.
Not keeping track of assets leads to technical sprawl because existing resources are not easily discoverable. For example, an organization might have numerous containers and VM instances running without knowing which ones can be safely deleted. Proper tagging and tracking can help identify the owners or teams responsible for these assets, ensuring decisions about the resource's lifecycle are well informed.
Simple software catalog implementations (e.g., wiki pages) can help track relationships between assets, but they quickly become outdated and require significant manual effort. In platform engineering, service catalogs are typically maintained dynamically through platform integrations.
Software Catalog Example: Backstage.io
In Backstage, the catalog is kept up to date via a data ingestion process. This process involves using entity providers or processors that fetch raw entity data from external sources. When a developer creates Kubernetes resources using one of the available golden paths in Backstage, the new resources automatically generate entries in the software catalog. This is achieved through the Backstage entity provider plugin, which reads Kubernetes objects as Backstage entities. This dynamic maintenance ensures that the catalog remains current, provides a holistic view of the infrastructure, and reduces the manual effort required to keep it updated.
Documentation Repository
While development teams write documentation as part of their operations, they often face challenges, particularly in the areas of discoverability, completeness, and consistency. Platform engineering addresses these issues by integrating the "Docs-like-Code" or "Docs-as-Code" approach into the IDP. Engineers write documentation in Markdown, or sometimes AsciiDoc files, which reside alongside their code, commonly referred to as TechDocs. Repository templates provide everything needed to set up a documentation site with minimal configuration, resulting in a well-organized and easy-to-find doc site within the portal.
TechDocs is a Docs-as-Code solution (e.g., Backstage's TechDocs) that retrieves documentation from service repositories and displays it in an easy-to-read and searchable format. This approach removes guesswork for developers as the IDP automatically pulls compatible documentation files (e.g., Markdown) from the repository, generates the HTML pages, and displays them on the appropriate service page. IDPs also provide powerful search functionality, making it easy to find and access documentation.
The documentation generation process typically involves:
- A CI/CD pipeline that fetches Markdown files from the source code hosting provider (e.g., GitHub, GitLab).
- The TechDocs generator then builds static HTML pages, including stylesheets (CSS files) and scripts (e.g., JavaScript), using static site generators like MkDocs.
- The TechDocs publisher uploads the generated files to a cloud storage, which can be any of the public cloud providers.
Managing access to documentation in cloud storage is very important for the security of the developer portal. As a best security practice, IDPs restrict access to the cloud storage and allow only the IDPs' documentation component to fetch files. Authorized IDP users should have read-only access to the generated documentation while the CI/CD pipeline requires write permissions to publish the generated site files. Additionally, to protect against XSS attacks, TechDocs use XSS sanitizer libraries, such as DOMPurify, to sanitize the generated HTML.
Scorecards
Scorecards have become a core capability within internal developer platforms. They establish engineering standards and help ensure that software meets expectations around security, reliability, operations, production readiness, compliance, and deployment. By defining standards such as production readiness and development quality, scorecards eliminate the need for custom scripts and spreadsheets, enabling development and operations teams to track metrics based on service properties effectively.
The essence of scorecards lies in their checks, which are configured and evaluated against the services to produce a score. Each scorecard consists of a set of rules, with each rule defining one or more conditions that must be met. This structured approach allows organizations to establish meaningful standards as well as helps developers improve and measure their progress. By ingesting data via the software catalog and integrations with services, scorecards enable the programmatic evaluation of these standards, providing teams with the insights and motivation needed to achieve better compliance with policies. Checks run against source code and the APIs exposed by services and tools, identifying components that do not meet expectations and reporting these issues to the appropriate personnel.
Scorecards use the checks to evaluate the maturity, production readiness, and engineering quality of any entity in the software catalog. For instance, they can determine whether:
- A service has an on-call defined
- Grafana is set up for the Kubernetes cluster
- The relationships of certain entities are empty
- Services are ready for production deployment
Scorecards can verify:
- Presence of runbooks
- Dashboards
- Logs
- On-call escalation policies
- Monitoring/alerting setups
- Accountable owners
Scorecards can also group checks into higher-level abstractions, such as "Security OWASP Top 10 compliance - Level 1" or "Production SRE requirements - Level 3." This makes it easier for teams to comprehend the level of maturity of their services and receive guidance on how to improve their scores.
When scores are degraded, scorecards serve as an alert mechanism. This is particularly useful when software migrations or upgrades are performed to ensure they are completed correctly. By grading all entities within the IDP, scorecards help prioritize attention and alert relevant teams when necessary. The real-time reporting of scorecards provides a clear and up-to-date picture of progress and areas needing attention, ensuring that software remains reliable, secure, and compliant with organizational standards.
GenAI Capabilities "as a Service"
Although generative AI (GenAI) is not yet a core capability of IDPs, it is rapidly evolving into one. GenAI capabilities are giving rise to intelligent IDPs that offer GenAI-driven services. By providing AI-based copilot and companion services — such as AI-driven code generation, code review and analysis, AI-generated documentation, and AI-augmented DevSecOps — these platforms streamline SDLC workflows and boost productivity by reducing manual effort.
Another significant value of intelligent IDPs is the ability to share large language model (LLM) prompts among development teams and across different lines of business within the organization. This capability enables teams to leverage collective expertise and insights. By sharing prompts, developers can quickly access and implement best practices and innovative solutions, leading to more efficient use of LLMs and accelerated development cycles.
Also, enabling AI to access the developer environment helps platform teams create a more compelling IDP. These intelligent platforms promise a frictionless, self-service developer experience with minimal overhead and are rapidly becoming the backbone of digital transformation.
{{ parent.title || parent.header.title}}
{{ parent.tldr }}
{{ parent.linkDescription }}
{{ parent.urlSource.name }}