Open Service Portal Workflow Documentation

Overview

The Open Service Portal orchestrates multiple workflows that enable teams to develop, release, and consume infrastructure and service templates. This document explains the complete platform workflow - from initial template development through automated release processes (including GitHub Actions) to GitOps deployment and resource provisioning via Backstage.

High-Level Platform Workflow

The platform operates through three main workflow phases with PR reviews as critical checkpoints:

Architecture Components

Repository Structure

Pull Request Workflows

The platform uses pull requests at three critical points as quality gates, with different roles responsible for reviews:

PR Review Points Summary

Repository	PR Created By	Reviewed By	Purpose	Auto-merge
template-*	Developers	Team members	Code review, testing	No
catalog	GitHub Actions	Platform Admin	Template governance	No
catalog-orders	Backstage Scaffolder	Bot/Platform Admin	Resource validation	Configurable

PR Checkpoints Overview

1. Template Development PRs (template-* repositories)

2. Catalog Release PRs (catalog repository)

3. Resource Order PRs (catalog-orders repository)

Release Workflows

GitHub Actions Automation

GitHub Actions serves as the automation engine for the release process, connecting template developers with platform administrators:

The GitHub Actions workflow (/.github/workflows/release.yaml) handles:

• Building Crossplane configuration packages
• Publishing container images
• Versioning templates
• Creating GitHub releases
• Opening PR to catalog repository (requires review)

Catalog PR Review Process

GitOps Deployment Workflows

1. Template Release Flow

This flow shows how infrastructure templates are developed, released, and made available in the cluster.

2. Resource Ordering Flow

This flow shows how developers use Backstage to create infrastructure resources that are deployed via GitOps.

3. Multi-Repository Pattern

Repository Structure Details

Catalog Repository (catalog/)

templates/
├── dns-record/
│   ├── xrd.yaml
│   └── composition.yaml
├── cloudflare-dnsrecord/
│   ├── xrd.yaml
│   └── composition.yaml
└── ...

Catalog-Orders Repository (catalog-orders/)

clusters/
├── db-cluster/                    # Managed by Database Platform Team
│   ├── platform-services/
│   │   └── postgres-operators/
│   │       └── postgres-operator.yaml
│   └── customer-databases/
│       ├── project-1-db.yaml
│       └── project-2-db.yaml
├── infra-cluster/                 # Managed by Infrastructure Team
│   ├── dns-management/
│   │   └── external-dns.yaml
│   └── certificates/
│       └── cert-manager.yaml
├── project-1-dev/                 # Project 1's development cluster
│   ├── backend-team/
│   │   └── applications/
│   │       └── api-service.yaml
│   └── frontend-team/
│       └── applications/
│           └── web-app.yaml
├── project-1-prod/                # Project 1's production cluster
│   ├── backend-team/
│   │   └── applications/
│   │       └── api-service.yaml
│   └── frontend-team/
│       └── applications/
│           └── web-app.yaml
└── project-2-cluster/             # Project 2's single cluster
    └── team-gamma/
        ├── applications/
        │   └── monolith.yaml
        └── databases/
            └── local-postgres.yaml

Cluster Organization Patterns:

• Service Clusters (db-cluster, infra-cluster): Managed by platform teams, provide services to other clusters
• Project Clusters (project-1-dev, project-1-prod): Owned by project teams, may have multiple environments
• Shared Clusters (project-2-cluster): Single cluster for smaller projects or teams

Detailed Component Interactions

Backstage Integration Points

Flux GitOps Watchers

End-to-End Workflow Examples

Example 1: Creating a DNS Record

Example 2: Deploying an Application

Versioning Strategy

Template Versioning Flow

Version flow:

1. Developer creates git tag (e.g., v1.2.3)
2. GitHub Actions builds and releases
3. Version added to XRD label: openportal.dev/version: "1.2.3"
4. Package pushed to ghcr.io/template:v1.2.3
5. Backstage displays as "Template v1.2.3"

Cluster and Namespace Organization

catalog-orders Repository Structure

Platform Service Model

Crossplane v2 Architecture

Namespaced XR Flow (No Claims)

Error Handling and Recovery

GitOps Error Recovery Flow

Monitoring and Observability

Status Flow

Best Practices

1. Template Development

• Always use Crossplane v2 with namespaced XRs
• Include comprehensive examples
• Add proper RBAC permissions
• Use semantic versioning

2. GitOps Repository Management

• Keep catalog organized by template type
• Use clear directory structure in catalog-orders
• Enable branch protection on main
• Set up automated PR validation

3. Backstage Integration

• Ensure XRDs have required labels
• Keep Kubernetes Ingestor polling interval reasonable
• Cache template data appropriately
• Provide clear template descriptions

4. Production Considerations

• Pin provider versions in production
• Implement proper RBAC for namespaces
• Set up monitoring and alerting
• Plan for disaster recovery

Summary

The Open Service Portal workflow orchestrates multiple processes to deliver a complete platform experience:

1. Development Workflows

• Local development with immediate feedback
• Template creation following standards
• PR-based collaboration and review
• Testing before release

2. Release Automation

• GitHub Actions automate the release pipeline
• Semantic versioning throughout
• Automatic catalog updates
• Container registry publishing

3. GitOps Deployment

• Flux ensures desired state
• Two-repository pattern (catalog + orders)
• Continuous reconciliation
• Drift detection and correction

4. Platform Integration

• Backstage provides the developer portal
• Kubernetes hosts all resources
• Crossplane manages infrastructure
• Everything connected via APIs

Key Benefits

1. Developer Experience

   • Self-service infrastructure provisioning
   • Visual forms generated from templates
   • Real-time status monitoring
   • No direct kubectl needed

2. Operational Excellence

   • Every change tracked in Git
   • Automated deployment pipeline
   • Consistent environments
   • Rollback capabilities

3. Governance & Compliance

   • Template approval process
   • RBAC at every level
   • Audit trail in Git history
   • Policy enforcement via Crossplane

4. Scalability

   • Multi-team support via namespaces
   • Template reusability
   • Automated processes reduce toil
   • GitOps scales with Git

This comprehensive workflow enables teams to move fast while maintaining safety and control, bridging the gap between development velocity and operational stability.