DES - New Service Creation Guide

This guide describes the standard process for creating and onboarding a new service within DES.

Following this process helps:

keep naming consistent
avoid deployment pipeline issues
simplify service setup
make onboarding easier for other engineers

Throughout this guide, <service> is used as a placeholder for your service name.

Reference example

If you want a concrete example while reading this guide, think of a service such as des-recommendations.

Step 1: Understand the naming convention

DES uses different naming formats in different places. This is expected and important.

Important

The deployment pipeline automatically prefixes DES applications with des-.

If you include des- in the wrong place, you may end up with names like:

des-des-<something>

Naming rules

Context	Format	Example
Repository folder	`des-<service>`	`des-recommendations`
GitHub workflow files	`des-<service>-*`	`des-recommendations-build.yml`
Manifest `applicationName`	`<service>-<env>`	`recommendations-qa`
ECR repository	`des/<service>`	`des/recommendations`

Why this matters

The deployment pipeline (SPUD / ArgoCD) automatically prefixes application names with:

des-

If you set the manifest like this:

application:
  applicationName: des-recommendations-qa

the final deployed name becomes:

des-des-recommendations-qa

which is incorrect.

Correct approach

Set applicationName without the des- prefix:

application:
  applicationName: recommendations-qa

This results in the correct final deployment name:

des-recommendations-qa

Naming summary

Repository / code / workflow names: include des-
Manifest applicationName: do not include des-
ECR repository: use des/<service>

Step 2: Create the base service

Start by creating a minimal service that can be deployed successfully.

Minimum requirements

Use the team-approved stack
Language: Java or another supported language
Java version: use the latest stable version unless the team specifies otherwise
Expose a basic endpoint such as Hello World

Step 3: Enable Security Jobs

Create a PR inssecr-configrepo-aws-ppb and include ssecr-configrepo-aws-ppb to enable security jobs for the new service.

It needs to be reviewed and merged by the #inner-source team.

Step 4: Enable ECR image creation

Create a PR in: - ssecr-configrepo-aws-ppb - Example: PR #129

We will need ask #inner-source team to review and merge the PR.

Add the new service under the des section in cdk/repositories.yml.

Example

des:
  application-repo: des-service
  additional-images:
    # existing services
    - application-repo: des-service
      image: <service>

This change will also update:

cdk/test/__snapshots__/tooling-stage.test.ts.snap

So the PR will usually contain two changed files.

ECR naming rule

Use the following format for the image repository:

des/<service>

Example:

des/recommendations

Success

Once this step is complete, the service image can be built and pushed to the correct ECR repository.

The ECR repository can be found in the AWS console at: https://eu-west-1.console.aws.amazon.com/ecr/repositories/private/677925254674/des/recommendations-decision/_/details?region=eu-west-1

Step 5: Create GitHub workflows

After the base service and ECR configuration are ready, add the required GitHub Actions workflows in the service repository.

Required files

.github/workflows/
├── des-<service>-build.yml
└── des-<service>-pr-to-main.yml

Workflow naming rules

Always use the full DES service name with the des- prefix
Keep workflow names aligned with the repository folder name

Example

des-recommendations-build.yml
des-recommendations-pr-to-main.yml

Tip

If the repository folder is des-recommendations, the workflow files should use the same des-recommendations prefix.

Step 6: Add smoke test setup for blue/green deployment

If your service requires blue/green smoke test support, add the related workflow and chart files.

The charts file should be added under the charts folder in the des-configrepo-aws-ppb repository.

For example, for des-recommendations: https://github.com/Flutter-Global/des-configrepo-aws-ppb/tree/main/charts/recommendations-decision-analysis

Create a PR to add the analysis folder (Chart and values YAML file) as shown in the URL above. After merging the PR, run the workflow to publish the chart: https://github.com/Flutter-Global/des-configrepo-aws-ppb/actions/workflows/release-charts.yaml

Step 7: Create the deployment manifest

After verifying that the chart is published successfully, add the manifest for the service in the relevant environment folder in the des-configrepo-aws-ppb repository.

For example, for QA you would add the environment-specific manifest and values for your service using the conventions already used in that repository.

An example manifest for recommendations-decision-<env><brand> can be found at: https://github.com/Flutter-Global/des-configrepo-aws-ppb/tree/main/manifests/recommendations-decision-qasbg

Create a PR in:

des-configrepo-aws-ppb
Example: PR #1124

Note

This is not necessarily the final PR. Further manifest changes are common as requirements become clearer.

Key manifest rule

Do not include des- in application.applicationName.

application:
  applicationName: recommendations-qa

Not:

application:
  applicationName: des-recommendations-qa

Tip

.github/workflows/update-image-<service>.yaml is used to promote the image version by creating QA PRs.

Step 8: Verify the deployment

After the manifest is merged and deployed, confirm that the service is running correctly in the cluster.

Verify that:

the application appears in ArgoCD
the correct image is deployed in the cluster
the service starts successfully

The above checks can be verified in ArgoCD and by checking: https://argocd.platformservices-tools.aws.private/applications/des-recommendations-decision-\<env>\<brand>

the endpoint is reachable
logs and health checks are working

Success

At this point, you should be able to see the service running in the cluster and accessible through its configured endpoint.

The deployment follows a step-by-step promotion starting from qa → nxt → drk → prd. A successful deployment in one environment will trigger a PR in the next environment containing the new image tag. These PRs need to be reviewed and approved by the team before they can be merged and deployed.

Step 9: Continue with feature development

Once the service has been deployed successfully, continue with implementation.

Recommended next steps

implement the business logic
add structured logging
expose metrics at /metrics
add health checks
confirm observability requirements are covered

Naming summary

Component	Example value
Folder name	`des-recommendations`
Workflow file	`des-recommendations-build.yml`
ECR repository	`des/recommendations`
Manifest `applicationName`	`recommendations-qa`
Final deployed application	`des-recommendations-qa`

Final checklist

[ ] Service name agreed: des-<service>
[ ] Repository folder created with the correct name
[ ] Base service created and deployed successfully
[ ] ECR configuration added
[ ] GitHub workflows created
[ ] des-<service>-build.yml
[ ] des-<service>-pr-to-main.yml
[ ] Deployment manifest created
[ ] applicationName uses <service>-<env> without des-
[ ] Smoke test / chart setup added if required
[ ] Deployment verified in the target environment

Troubleshooting tip

If you ever see:

des-des-<something>

you have almost certainly added des- where it should not be used — usually in application.applicationName.