Backstage on Kubernetes: Complete Helm Deployment Guide with Security Best Practices

Table of Contents#

Introduction#

Backstage is an open-source developer portal created by Spotify that acts as a centralized hub for infrastructure tooling, documentation, and developer workflows. This guide provides a comprehensive approach to deploying Backstage on Kubernetes using Helm charts, with a focus on production readiness, security, and scalability.

Architecture Overview#

The Backstage deployment architecture consists of multiple components working together to provide a unified developer experience:

1
graph TB
2
    subgraph "External Services"
3
        GIT[Git Provider<br/>GitHub/GitLab]
4
        IDP[Identity Provider<br/>OAuth/SAML]
5
        EXT[External APIs<br/>K8s, AWS, etc.]
6
    end
7

8
    subgraph "Kubernetes Cluster"
9
        subgraph "Ingress Layer"
10
            ING[Ingress Controller<br/>NGINX/Traefik]
11
            CERT[Cert Manager<br/>TLS Certificates]
12
        end
13

14
        subgraph "Application Layer"
15
            BS[Backstage<br/>Frontend & Backend]
16
            TECH[TechDocs<br/>Service]
17
            SEARCH[Search<br/>Service]
18
        end
19

20
        subgraph "Data Layer"
21
            PG[PostgreSQL<br/>Database]
22
            REDIS[Redis<br/>Cache]
23
            S3[Object Storage<br/>TechDocs]
24
        end
25

26
        subgraph "Monitoring"
27
            PROM[Prometheus]
28
            GRAF[Grafana]
29
            LOG[Logging<br/>Stack]
30
        end
31
    end
32

33
    subgraph "Developer Workstation"
34
        DEV[Developer]
35
    end
36

37
    DEV --> ING
38
    ING --> BS
39
    BS --> PG
40
    BS --> REDIS
41
    BS --> GIT
42
    BS --> IDP
43
    BS --> EXT
44
    TECH --> S3
45
    BS --> TECH
46
    BS --> SEARCH
47
    PROM --> BS
48

49
    style BS fill:#e3f2fd
50
    style PG fill:#fff9c4
51
    style ING fill:#e8f5e9
52
    style PROM fill:#f3e5f5

Deployment Workflow#

The deployment process follows a structured approach to ensure proper configuration and security:

1
sequenceDiagram
2
    participant Admin
3
    participant Helm
4
    participant K8s
5
    participant Backstage
6
    participant Database
7
    participant External
8

9
    Admin->>Helm: helm repo add backstage
10
    Admin->>Helm: helm install backstage
11
    Helm->>K8s: Create Namespace
12
    Helm->>K8s: Deploy Secrets
13
    Helm->>K8s: Deploy ConfigMaps
14
    Helm->>K8s: Deploy Database
15
    K8s->>Database: Initialize Schema
16
    Helm->>K8s: Deploy Backstage
17
    K8s->>Backstage: Start Services
18
    Backstage->>Database: Connect
19
    Backstage->>External: Integrate Services
20
    Admin->>Backstage: Access Portal

Security Architecture#

Security is paramount in a Backstage deployment. Here’s the security architecture:

1
graph TB
2
    subgraph "Security Layers"
3
        subgraph "Network Security"
4
            FW[Firewall Rules]
5
            NP[Network Policies]
6
            TLS[TLS Encryption]
7
        end
8

9
        subgraph "Authentication"
10
            OAUTH[OAuth 2.0]
11
            SAML[SAML 2.0]
12
            MFA[Multi-Factor Auth]
13
        end
14

15
        subgraph "Authorization"
16
            RBAC[RBAC Policies]
17
            PERM[Permission Model]
18
            API[API Security]
19
        end
20

21
        subgraph "Data Security"
22
            ENC[Encryption at Rest]
23
            VAULT[Secret Management]
24
            AUDIT[Audit Logging]
25
        end
26
    end
27

28
    subgraph "Backstage Components"
29
        FE[Frontend]
30
        BE[Backend]
31
        DB[Database]
32
        PLUGINS[Plugins]
33
    end
34

35
    TLS --> FE
36
    OAUTH --> BE
37
    RBAC --> BE
38
    ENC --> DB
39
    VAULT --> BE
40
    NP --> BE
41
    AUDIT --> BE
42

43
    style TLS fill:#ffebee
44
    style OAUTH fill:#e3f2fd
45
    style ENC fill:#e8f5e9
46
    style AUDIT fill:#fff9c4

Resource Configuration#

Proper resource allocation ensures optimal performance:

1
graph LR
2
    subgraph "Resource Allocation"
3
        subgraph "Backstage Pod"
4
            CPU1[CPU: 500m-1000m]
5
            MEM1[Memory: 1Gi-2Gi]
6
            DISK1[Disk: 10Gi]
7
        end
8

9
        subgraph "PostgreSQL Pod"
10
            CPU2[CPU: 500m-2000m]
11
            MEM2[Memory: 2Gi-4Gi]
12
            DISK2[Disk: 20Gi-100Gi]
13
        end
14

15
        subgraph "Redis Pod"
16
            CPU3[CPU: 100m-500m]
17
            MEM3[Memory: 512Mi-1Gi]
18
            DISK3[Disk: 1Gi-5Gi]
19
        end
20
    end
21

22
    style CPU1 fill:#e3f2fd
23
    style MEM1 fill:#e8f5e9
24
    style DISK2 fill:#fff9c4

Installation Guide#

Prerequisites#

Before beginning the installation, ensure you have:

Kubernetes Cluster: Version 1.19 or higher
Helm: Version 3.8 or higher
kubectl: Configured to access your cluster
Storage: Persistent storage provisioner
Ingress Controller: NGINX or similar (optional but recommended)
DNS: Domain name for accessing Backstage

Step 1: Add Helm Repository#

1
# Add the Backstage Helm repository
2
helm repo add backstage https://backstage.github.io/charts
3
helm repo update
4

5
# Verify the repository was added
6
helm search repo backstage

Step 2: Create Namespace and Secrets#

1
# Create a dedicated namespace
2
kubectl create namespace backstage
3

4
# Create secret for PostgreSQL
5
kubectl create secret generic backstage-postgresql \
6
  --from-literal=postgres-password=$(openssl rand -base64 32) \
7
  --namespace backstage
8

9
# Create secret for OAuth (if using GitHub)
10
kubectl create secret generic backstage-oauth \
11
  --from-literal=AUTH_GITHUB_CLIENT_ID=your-client-id \
12
  --from-literal=AUTH_GITHUB_CLIENT_SECRET=your-client-secret \
13
  --namespace backstage

Step 3: Create Production Values File#

Create a comprehensive values-production.yaml file:

1
global:
2
  # Set your cluster domain
3
  clusterDomain: cluster.local
4

5
backstage:
6
  # Number of Backstage replicas for HA
7
  replicas: 2
8

9
  image:
10
    registry: ghcr.io
11
    repository: backstage/backstage
12
    tag: latest
13
    pullPolicy: IfNotPresent
14

15
  # Resource limits and requests
16
  resources:
17
    requests:
18
      memory: "1Gi"
19
      cpu: "500m"
20
    limits:
21
      memory: "2Gi"
22
      cpu: "1000m"
23

24
  # Container configuration
25
  containerPorts:
26
    backend: 7007
27

28
  # Extra environment variables
29
  extraEnvVars:
30
    - name: NODE_ENV
31
      value: "production"
32
    - name: LOG_LEVEL
33
      value: "info"
34
    - name: APP_CONFIG_backend_baseUrl
35
      value: "https://backstage.example.com"
36
    - name: APP_CONFIG_backend_cors_origin
37
      value: "https://backstage.example.com"
38

39
  # Extra environment variables from secrets
40
  extraEnvVarsSecrets:
41
    - backstage-oauth
42

43
  # App configuration
44
  appConfig:
45
    app:
46
      title: "My Company Backstage"
47
      baseUrl: https://backstage.example.com
48

49
    organization:
50
      name: "My Company"
51

52
    backend:
53
      baseUrl: https://backstage.example.com
54
      listen:
55
        port: 7007
56
      cors:
57
        origin: https://backstage.example.com
58
        methods: [GET, POST, PUT, DELETE]
59
        credentials: true
60
      database:
61
        client: pg
62
        connection:
63
          host: ${POSTGRES_HOST}
64
          port: ${POSTGRES_PORT}
65
          user: ${POSTGRES_USER}
66
          password: ${POSTGRES_PASSWORD}
67
          database: backstage
68
          ssl:
69
            require: true
70
            rejectUnauthorized: false
71
      cache:
72
        store: redis
73
        connection: redis://backstage-redis:6379
74

75
    integrations:
76
      github:
77
        - host: github.com
78
          token: ${GITHUB_TOKEN}
79

80
    auth:
81
      environment: production
82
      providers:
83
        github:
84
          production:
85
            clientId: ${AUTH_GITHUB_CLIENT_ID}
86
            clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
87

88
    catalog:
89
      import:
90
        entityFilename: catalog-info.yaml
91
        pullRequestBranchName: backstage-integration
92
      rules:
93
        - allow: [Component, System, API, Resource, Location]
94
      locations:
95
        - type: url
96
          target: https://github.com/myorg/software-catalog/blob/main/catalog-info.yaml
97

98
    techdocs:
99
      builder: "external"
100
      generator:
101
        runIn: "docker"
102
      publisher:
103
        type: "awsS3"
104
        awsS3:
105
          bucketName: my-techdocs-bucket
106
          region: us-east-1
107

108
    search:
109
      elasticsearch:
110
        nodes:
111
          - http://elasticsearch:9200
112

113
  # Service Monitor for Prometheus
114
  serviceMonitor:
115
    enabled: true
116
    path: /metrics
117
    interval: 30s
118
    labels:
119
      prometheus: kube-prometheus
120

121
  # Pod Disruption Budget
122
  podDisruptionBudget:
123
    enabled: true
124
    minAvailable: 1
125

126
  # Autoscaling configuration
127
  autoscaling:
128
    enabled: true
129
    minReplicas: 2
130
    maxReplicas: 5
131
    targetCPU: 70
132
    targetMemory: 80
133

134
# PostgreSQL configuration
135
postgresql:
136
  enabled: true
137

138
  auth:
139
    database: backstage
140
    existingSecret: backstage-postgresql
141
    secretKeys:
142
      adminPasswordKey: postgres-password
143
      userPasswordKey: postgres-password
144

145
  primary:
146
    persistence:
147
      enabled: true
148
      size: 20Gi
149
      storageClass: fast-ssd
150

151
    resources:
152
      requests:
153
        cpu: 500m
154
        memory: 2Gi
155
      limits:
156
        cpu: 2000m
157
        memory: 4Gi
158

159
    configuration: |
160
      shared_buffers = 256MB
161
      max_connections = 200
162
      effective_cache_size = 1GB
163

164
    pgHbaConfiguration: |
165
      local all all trust
166
      host all all 0.0.0.0/0 md5
167
      host all all ::1/128 md5
168

169
  metrics:
170
    enabled: true
171
    serviceMonitor:
172
      enabled: true
173

174
# Redis configuration
175
redis:
176
  enabled: true
177

178
  architecture: replication
179

180
  auth:
181
    enabled: true
182
    existingSecret: backstage-redis
183
    existingSecretPasswordKey: redis-password
184

185
  master:
186
    persistence:
187
      enabled: true
188
      size: 5Gi
189

190
    resources:
191
      requests:
192
        cpu: 100m
193
        memory: 512Mi
194
      limits:
195
        cpu: 500m
196
        memory: 1Gi
197

198
  replica:
199
    replicaCount: 2
200
    persistence:
201
      enabled: true
202
      size: 5Gi
203

204
  metrics:
205
    enabled: true
206
    serviceMonitor:
207
      enabled: true
208

209
# Ingress configuration
210
ingress:
211
  enabled: true
212
  className: nginx
213

214
  annotations:
215
    cert-manager.io/cluster-issuer: letsencrypt-prod
216
    nginx.ingress.kubernetes.io/backend-protocol: HTTP
217
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
218
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
219
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
220
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
221

222
  hosts:
223
    - host: backstage.example.com
224
      paths:
225
        - path: /
226
          pathType: Prefix
227

228
  tls:
229
    - secretName: backstage-tls
230
      hosts:
231
        - backstage.example.com
232

233
# Network Policy
234
networkPolicy:
235
  enabled: true
236
  ingress:
237
    - from:
238
        - namespaceSelector:
239
            matchLabels:
240
              name: ingress-nginx
241
      ports:
242
        - protocol: TCP
243
          port: 7007

Step 4: Install Backstage#

1
# Perform a dry run first
2
helm upgrade --install backstage backstage/backstage \
3
  --namespace backstage \
4
  --values values-production.yaml \
5
  --dry-run
6

7
# Install Backstage
8
helm upgrade --install backstage backstage/backstage \
9
  --namespace backstage \
10
  --values values-production.yaml \
11
  --wait \
12
  --timeout 10m
13

14
# Verify the installation
15
kubectl get pods -n backstage
16
kubectl get svc -n backstage
17
kubectl get ingress -n backstage

Step 5: Post-Installation Configuration#

1
# Check Backstage logs
2
kubectl logs -n backstage -l app.kubernetes.io/name=backstage -f
3

4
# Access Backstage locally (for testing)
5
kubectl port-forward -n backstage svc/backstage 7007:7007
6

7
# Get the initial admin password (if configured)
8
kubectl get secret -n backstage backstage-admin -o jsonpath="{.data.password}" | base64 -d

Security Considerations#

Authentication and Authorization#

OAuth/OIDC Integration:

1
auth:
2
  providers:
3
    oidc:
4
      production:
5
        metadataUrl: https://your-idp.com/.well-known/openid-configuration
6
        clientId: ${AUTH_OIDC_CLIENT_ID}
7
        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
8
        scope: "openid profile email groups"
9
        prompt: auto

RBAC Configuration:

1
permission:
2
  enabled: true
3
  rbac:
4
    policies:
5
      - effect: allow
6
        principals:
7
          - group:platform-team
8
        permissions:
9
          - catalog.entity.create
10
          - catalog.entity.delete

API Token Security:

1
# Generate secure API tokens
2
kubectl create secret generic backstage-api-tokens \
3
  --from-literal=token1=$(openssl rand -hex 32) \
4
  --namespace backstage

Network Security#

Network Policies:

1
apiVersion: networking.k8s.io/v1
2
kind: NetworkPolicy
3
metadata:
4
  name: backstage-network-policy
5
  namespace: backstage
6
spec:
7
  podSelector:
8
    matchLabels:
9
      app.kubernetes.io/name: backstage
10
  policyTypes:
11
    - Ingress
12
    - Egress
13
  ingress:
14
    - from:
15
        - namespaceSelector:
16
            matchLabels:
17
              name: ingress-nginx
18
      ports:
19
        - protocol: TCP
20
          port: 7007
21
  egress:
22
    - to:
23
        - namespaceSelector: {}
24
      ports:
25
        - protocol: TCP
26
          port: 5432 # PostgreSQL
27
        - protocol: TCP
28
          port: 6379 # Redis
29
    - to:
30
        - namespaceSelector: {}
31
          podSelector:
32
            matchLabels:
33
              k8s-app: kube-dns
34
      ports:
35
        - protocol: UDP
36
          port: 53
37
    - to: # Allow HTTPS egress
38
        - ipBlock:
39
            cidr: 0.0.0.0/0
40
      ports:
41
        - protocol: TCP
42
          port: 443

TLS Configuration:

1
# Configure TLS for all internal communications
2
backstage:
3
  appConfig:
4
    backend:
5
      https:
6
        certificate:
7
          key: /etc/backstage/tls/tls.key
8
          cert: /etc/backstage/tls/tls.crt

Secrets Management#

External Secrets Operator:

1
apiVersion: external-secrets.io/v1beta1
2
kind: ExternalSecret
3
metadata:
4
  name: backstage-secrets
5
  namespace: backstage
6
spec:
7
  refreshInterval: 1h
8
  secretStoreRef:
9
    name: vault-backend
10
    kind: SecretStore
11
  target:
12
    name: backstage-secrets
13
  data:
14
    - secretKey: github-token
15
      remoteRef:
16
        key: backstage/github
17
        property: token
18
    - secretKey: postgres-password
19
      remoteRef:
20
        key: backstage/database
21
        property: password

Sealed Secrets:

1
# Install Sealed Secrets controller
2
kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.18.0/controller.yaml
3

4
# Create a sealed secret
5
echo -n "mypassword" | kubectl create secret generic backstage-db \
6
  --dry-run=client \
7
  --from-file=password=/dev/stdin \
8
  -o yaml | kubeseal -o yaml > sealed-secret.yaml

Container Security#

Security Context:

1
backstage:
2
  podSecurityContext:
3
    runAsNonRoot: true
4
    runAsUser: 1000
5
    fsGroup: 1000
6
    seccompProfile:
7
      type: RuntimeDefault
8

9
  containerSecurityContext:
10
    allowPrivilegeEscalation: false
11
    readOnlyRootFilesystem: true
12
    runAsNonRoot: true
13
    runAsUser: 1000
14
    capabilities:
15
      drop:
16
        - ALL

Pod Security Standards:

1
apiVersion: v1
2
kind: Namespace
3
metadata:
4
  name: backstage
5
  labels:
6
    pod-security.kubernetes.io/enforce: restricted
7
    pod-security.kubernetes.io/audit: restricted
8
    pod-security.kubernetes.io/warn: restricted

Troubleshooting#

Common Issues and Solutions#

Database Connection Issues#

1
# Check PostgreSQL pod status
2
kubectl get pods -n backstage -l app.kubernetes.io/name=postgresql
3

4
# Check PostgreSQL logs
5
kubectl logs -n backstage -l app.kubernetes.io/name=postgresql
6

7
# Test database connection
8
kubectl run -it --rm --restart=Never postgres-client \
9
  --image=postgres:14 \
10
  --namespace=backstage \
11
  -- psql -h backstage-postgresql -U postgres -d backstage
12

13
# Check connection from Backstage pod
14
kubectl exec -it -n backstage deployment/backstage -- \
15
  nc -zv backstage-postgresql 5432

Authentication Issues#

1
# Check OAuth configuration
2
kubectl get secret -n backstage backstage-oauth -o yaml
3

4
# Verify environment variables
5
kubectl exec -n backstage deployment/backstage -- env | grep AUTH
6

7
# Check Backstage auth logs
8
kubectl logs -n backstage -l app.kubernetes.io/name=backstage | grep -i auth

Performance Issues#

1
# Check resource usage
2
kubectl top pods -n backstage
3

4
# Check horizontal pod autoscaler
5
kubectl get hpa -n backstage
6

7
# Analyze slow queries in PostgreSQL
8
kubectl exec -it -n backstage backstage-postgresql-0 -- \
9
  psql -U postgres -d backstage -c "SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;"

Certificate Issues#

1
# Check certificate status
2
kubectl get certificate -n backstage
3

4
# Describe certificate
5
kubectl describe certificate backstage-tls -n backstage
6

7
# Check cert-manager logs
8
kubectl logs -n cert-manager deployment/cert-manager

Maintenance and Upgrades#

Regular Maintenance Tasks#

Database Maintenance:

1
# Backup database
2
kubectl exec -n backstage backstage-postgresql-0 -- \
3
  pg_dump -U postgres backstage > backstage-backup-$(date +%Y%m%d).sql
4

5
# Vacuum database
6
kubectl exec -n backstage backstage-postgresql-0 -- \
7
  psql -U postgres -d backstage -c "VACUUM ANALYZE;"

Log Rotation:

1
# Configure log rotation in values.yaml
2
backstage:
3
  extraEnvVars:
4
    - name: LOG_FILE_MAX_SIZE
5
      value: "100MB"
6
    - name: LOG_FILE_MAX_FILES
7
      value: "5"

Monitoring Setup:

1
# ServiceMonitor for Prometheus
2
apiVersion: monitoring.coreos.com/v1
3
kind: ServiceMonitor
4
metadata:
5
  name: backstage
6
  namespace: backstage
7
spec:
8
  selector:
9
    matchLabels:
10
      app.kubernetes.io/name: backstage
11
  endpoints:
12
    - port: backend
13
      path: /metrics
14
      interval: 30s

Upgrade Process#

Pre-upgrade Checklist:

1
# Backup current installation
2
helm get values backstage -n backstage > backstage-values-backup.yaml
3

4
# Backup database
5
kubectl exec -n backstage backstage-postgresql-0 -- \
6
  pg_dump -U postgres backstage > pre-upgrade-backup.sql
7

8
# Check for breaking changes
9
helm show readme backstage/backstage --version <new-version>

Perform Upgrade:

1
# Update Helm repository
2
helm repo update
3

4
# Check changes
5
helm diff upgrade backstage backstage/backstage \
6
  --namespace backstage \
7
  --values values-production.yaml
8

9
# Perform upgrade
10
helm upgrade backstage backstage/backstage \
11
  --namespace backstage \
12
  --values values-production.yaml \
13
  --wait \
14
  --timeout 10m

Post-upgrade Validation:

1
# Check pod status
2
kubectl get pods -n backstage
3

4
# Verify application health
5
curl -s https://backstage.example.com/api/health | jq .
6

7
# Check for errors in logs
8
kubectl logs -n backstage -l app.kubernetes.io/name=backstage --tail=100

Best Practices#

Development Workflow#

GitOps Integration:

1
apiVersion: argoproj.io/v1alpha1
2
kind: Application
3
metadata:
4
  name: backstage
5
  namespace: argocd
6
spec:
7
  project: default
8
  source:
9
    repoURL: https://github.com/myorg/backstage-config
10
    targetRevision: main
11
    path: overlays/production
12
  destination:
13
    server: https://kubernetes.default.svc
14
    namespace: backstage
15
  syncPolicy:
16
    automated:
17
      prune: true
18
      selfHeal: true

Multi-Environment Setup:

1
# Directory structure
2
backstage-config/
3
├── base/
4
│   ├── kustomization.yaml
5
│   └── values.yaml
6
├── overlays/
7
│   ├── development/
8
│   │   ├── kustomization.yaml
9
│   │   └── values.yaml
10
│   ├── staging/
11
│   │   ├── kustomization.yaml
12
│   │   └── values.yaml
13
│   └── production/
14
│       ├── kustomization.yaml
15
│       └── values.yaml

Plugin Management#

Custom Plugin Deployment:

1
# Dockerfile for custom Backstage image
2
FROM node:16-bullseye-slim as build
3

4
WORKDIR /app
5

6
# Copy and install dependencies
7
COPY package.json yarn.lock ./
8
COPY packages ./packages
9
RUN yarn install --frozen-lockfile
10

11
# Build the application
12
RUN yarn build
13

14
# Runtime stage
15
FROM node:16-bullseye-slim
16

17
WORKDIR /app
18

19
# Copy built application
20
COPY --from=build /app/packages/backend/dist ./
21
COPY --from=build /app/packages/app/dist ./app
22

23
# Install production dependencies
24
COPY package.json yarn.lock ./
25
RUN yarn install --production --frozen-lockfile
26

27
EXPOSE 7007
28
CMD ["node", "packages/backend"]

Plugin Configuration:

1
# values.yaml plugin configuration
2
backstage:
3
  appConfig:
4
    app:
5
      plugins:
6
        - id: "@backstage/plugin-kubernetes"
7
          config:
8
            clusters:
9
              - name: production
10
                url: https://k8s-prod.example.com
11
                authProvider: serviceAccount
12
        - id: "@backstage/plugin-sonarqube"
13
          config:
14
            baseUrl: https://sonarqube.example.com
15
            apiKey: ${SONARQUBE_API_KEY}

Monitoring and Observability#

Grafana Dashboard:

1
{
2
  "dashboard": {
3
    "title": "Backstage Monitoring",
4
    "panels": [
5
      {
6
        "title": "Request Rate",
7
        "targets": [
8
          {
9
            "expr": "rate(http_request_duration_seconds_count{job=\"backstage\"}[5m])"
10
          }
11
        ]
12
      },
13
      {
14
        "title": "Error Rate",
15
        "targets": [
16
          {
17
            "expr": "rate(http_request_duration_seconds_count{job=\"backstage\",status=~\"5..\"}[5m])"
18
          }
19
        ]
20
      },
21
      {
22
        "title": "Response Time",
23
        "targets": [
24
          {
25
            "expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket{job=\"backstage\"}[5m]))"
26
          }
27
        ]
28
      }
29
    ]
30
  }
31
}

Alert Rules:

1
apiVersion: monitoring.coreos.com/v1
2
kind: PrometheusRule
3
metadata:
4
  name: backstage-alerts
5
  namespace: backstage
6
spec:
7
  groups:
8
    - name: backstage
9
      rules:
10
        - alert: BackstageDown
11
          expr: up{job="backstage"} == 0
12
          for: 5m
13
          annotations:
14
            summary: "Backstage is down"
15
            description: "Backstage has been down for more than 5 minutes"
16

17
        - alert: BackstageHighErrorRate
18
          expr: rate(http_request_duration_seconds_count{job="backstage",status=~"5.."}[5m]) > 0.05
19
          for: 10m
20
          annotations:
21
            summary: "High error rate in Backstage"
22
            description: "Error rate is above 5% for 10 minutes"
23

24
        - alert: BackstageHighMemoryUsage
25
          expr: container_memory_usage_bytes{pod=~"backstage-.*"} / container_spec_memory_limit_bytes > 0.9
26
          for: 10m
27
          annotations:
28
            summary: "High memory usage in Backstage"
29
            description: "Memory usage is above 90% for 10 minutes"

References#

Conclusion#

Deploying Backstage on Kubernetes with Helm provides a scalable, secure, and maintainable developer portal solution. By following this guide and implementing the security best practices, you can create a production-ready Backstage deployment that serves as a central hub for your engineering organization.

Remember to:

Regularly update Backstage and its dependencies
Monitor performance and security metrics
Backup your data regularly
Test disaster recovery procedures
Keep documentation updated
Engage with the Backstage community for support and contributions

The flexibility of Backstage, combined with Kubernetes’ orchestration capabilities and Helm’s package management, creates a powerful platform for improving developer experience and productivity.