Compositions: A Self-Service Database API

1. 1

   Define the API (XRD)

   Teams choose a size, a version from an allow-list, and backup days within a range. Everything else is the platform's decision.

   apiVersion: apiextensions.crossplane.io/v2
   kind: CompositeResourceDefinition
   metadata:
     name: postgresqlinstances.platform.shoplite.dev
   spec:
     group: platform.shoplite.dev
     names: { kind: PostgreSQLInstance, plural: postgresqlinstances }
     scope: Namespaced
     versions:
       - name: v1alpha1
         served: true
         referenceable: true
         schema:
           openAPIV3Schema:
             type: object
             properties:
               spec:
                 type: object
                 required: [size]
                 properties:
                   size: { type: string, enum: [small, medium, large] }
                   version: { type: string, enum: ["16", "17"], default: "17" }
                   backupDays: { type: integer, minimum: 1, maximum: 35, default: 7 }
               status:
                 type: object
                 properties:
                   endpoint: { type: string }

2. 2

   Implement it (Composition)

   A patch-and-transform pipeline: map size to an instance class, fix the rest to standards, and write the connection details to a Secret in the team's namespace. Namespaced composites compose NAMESPACED managed resources, which live in the *.m.upbound.io API groups and authenticate through the ClusterProviderConfig from Mission 2.1. Subnet and security groups are found by label selectors on resources Terraform created.

   apiVersion: apiextensions.crossplane.io/v1
   kind: Composition
   metadata:
     name: postgresql-aws
   spec:
     compositeTypeRef: { apiVersion: platform.shoplite.dev/v1alpha1, kind: PostgreSQLInstance }
     mode: Pipeline
     pipeline:
       - step: resources
         functionRef: { name: function-patch-and-transform }
         input:
           apiVersion: pt.fn.crossplane.io/v1beta1
           kind: Resources
           resources:
             - name: db
               base:
                 apiVersion: rds.aws.m.upbound.io/v1beta1
                 kind: Instance
                 spec:
                   deletionPolicy: Orphan
                   forProvider:
                     region: ap-south-1
                     engine: postgres
                     allocatedStorage: 20
                     storageType: gp3
                     storageEncrypted: true
                     publiclyAccessible: false
                     deletionProtection: true
                     autoGeneratePassword: true
                     username: app
                     passwordSecretRef: { key: password, name: "" }   # name patched below
                     dbSubnetGroupNameSelector: { matchLabels: { platform.shoplite.dev/network: private } }
                     vpcSecurityGroupIdSelector: { matchLabels: { platform.shoplite.dev/sg: databases } }
                     skipFinalSnapshot: false
                   writeConnectionSecretToRef: { name: "" }
               patches:
                 - type: FromCompositeFieldPath
                   fromFieldPath: spec.size
                   toFieldPath: spec.forProvider.instanceClass
                   transforms:
                     - type: map
                       map: { small: db.t4g.small, medium: db.m7g.large, large: db.m7g.2xlarge }
                 - { type: FromCompositeFieldPath, fromFieldPath: spec.version, toFieldPath: spec.forProvider.engineVersion }
                 - { type: FromCompositeFieldPath, fromFieldPath: spec.backupDays, toFieldPath: spec.forProvider.backupRetentionPeriod }
                 - type: FromCompositeFieldPath
                   fromFieldPath: metadata.name
                   toFieldPath: spec.writeConnectionSecretToRef.name
                   transforms: [{ type: string, string: { type: Format, fmt: "%s-db-conn" } }]
                 - type: FromCompositeFieldPath
                   fromFieldPath: metadata.name
                   toFieldPath: spec.forProvider.passwordSecretRef.name
                   transforms: [{ type: string, string: { type: Format, fmt: "%s-db-password" } }]
                 - { type: ToCompositeFieldPath, fromFieldPath: status.atProvider.address, toFieldPath: status.endpoint }

3. 3

   A team requests a database

   This lives in the team's GitOps folder and deploys through Argo CD. It's reviewed like code, versioned, and the same in every environment (just a different size in the prod overlay).

   apiVersion: platform.shoplite.dev/v1alpha1
   kind: PostgreSQLInstance
   metadata:
     name: wishlist
   spec:
     size: small
     version: "17"
     backupDays: 7

   terminalcopy cmd

   $ kubectl -n wishlist get postgresqlinstance wishlist

   kubectl -n wishlist get secret wishlist-db-conn -o jsonpath='{.data}' | jq 'keys'

   ── expected output ──

   NAME SYNCED READY COMPOSITION AGE

   wishlist True True postgresql-aws 9m

   ["endpoint","password","port","username"]

4. 4

   Offer it in Backstage too

   A small template (Mission 1.2) with a size dropdown whose only step opens a PR adding database.yaml to the team's GitOps folder. Developers who prefer YAML write it directly; others click. Both go through Git review.

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.