Setup an application

First and foremost the application name should be decided. There are some basic conventions around naming.

• the github repository name is usually <my-application>-service for emarsys services
• other references of the application (domain, gap.yaml) must not use the -service postfix
• if an ingress is used with the default domain the length of the application name must not exceed 31 characters, see next section on CNAME creation
• [GCP] project naming

Skip this if the application won’t be exposed to the public internet.

If the application name exceeds 31 characters

• provided you’ll have an ingress, you must use a custom ingress host instead of the default application name that does not exceed 64 characters
• it’s a limitation of the SSL certificates, that a domain name’s length must not exceed 64 characters
• the longest fixed part of the naming convention for an application running on GAP staging cluster is 33 characters long us1-01..gap.cloud.sap.emarsys.net

On us1 clusters as long as the us1-01.<app-name>.gap.s.sap.emarsys.com & us1-01.<app-name>.gap.cloud.sap.emarsys.net pattern is followed the domain will be picked up from the Ingress host. Customer facing domains need review, so please request it in a GAP ticket.

For eu1 please follow the these steps:

The standard host url formats are:

• staging: <my-application>-staging.gservice.emarsys.com
• production: <my-application>.gservice.emarsys.net

You can register domain names for your application at the Tooling Portal

Please register your application address BEFORE the first deployment, otherwise Cloud Platform Team will receive an alert that the certificate for your domain cannot be issued. The only way we can resolve this issue is to manually delete your ingress.

Please note that the CNAME requests have a time to live of 24 hours, therefore please do avoid creating CNAME requests Friday afternoons in CET time zone as they will expire before the next working day.

To describe your application, in your repository create a gap.yaml file in the gap folder, see the example below. (If the application does not have a web component the ingress object can be skipped)

name: "<my-application>"
namespace: "<my-team-namespace>"
image:
  repository: sap-ems-base-infra-package-p/gap-images/<my-application>
deployments:
  web:
    ingress:
      enabled: true
    command: ["command", "to", "run", "in", "web"]

By convention the word service should not appear in the name.

The image.repository field points to the Artifact Registry repository. The registry is automatically calculated per region, and the image tag will be set automatically by the update-image-tag workflow step (see Deployment pipeline below).

For more information see how to Set up your GAP configuration file

If you need different configuration for different instances (e.g. different resource requests p-us1-01), you can create instance-specific override directories inside the gap folder using the instance names:

• s-eu1-01 — EU staging
• p-eu1-01 — EU production
• s-us1-01 — US staging
• p-us1-01 — US production

If you need different configuration per environment (e.g. different resource requests for staging vs production), you can create environment-specific override directories inside the gap folder using the cluster names:

Example folder structure:

gap/
├── gap.yaml                  # main configuration (applies to all environments)
├── staging-defaults/         # overrides for all staging clusters
│   └── gap.yaml
├── production-defaults/      # overrides for all production clusters
│   └── gap.yaml
├── s-eu1-01/                 # EU staging per-cluster overrides
│   └── gap.yaml
├── p-eu1-01/                 # EU production per-cluster overrides
│   └── gap.yaml
├── s-us1-01/                 # US staging per-cluster overrides
│   └── gap.yaml
└── p-us1-01/                 # US production per-cluster overrides
    └── gap.yaml

The merge order is: gap.yaml (base) → staging-defaults / production-defaults (environment type defaults) → per-cluster folder (e.g. s-eu1-01). Each layer patches the previous one — only include the fields you want to override. See the Staging and Production Defaults section for details.

See configuration overrides for details.

Staging environments typically use far fewer resources than production. Take advantage of per-environment overrides to set appropriate resource requests for each cluster — this avoids paying for capacity your application doesn’t actually need. Check the resource details guide to learn how to use the Grafana/GCP dashboards to determine resource request/limit values.

Prerequisite: gap-cli

Before deployment the secret must exist, otherwise the pods will fail to start. Run the following command for each cluster your application will be deployed to:

gap-cli config:init -a your-app-name -n your-team-namespace

If the application does not use any environment config this should be enough.

After the initialization, you can add your config variables:

gap-cli config:edit -a your-app-name -n your-team-namespace

Your default editor is showing up. In there, you need to add your configs in a KEY=VALUE format.

After you save it, you can see your config differences. To confirm these changes, you need to type yes, and you are good to go.

For more commands, type gap-cli --help, or visit the gap-cli repo

Set up your CI/CD pipeline to build, push, and deploy your application. The full setup involves:

1. A GitHub Actions workflow to build and push your container image
2. The GAP-Workflow GitHub App to commit image tags
3. An update-image-tag workflow step to trigger deployments via ArgoCD
4. An entry in the gap-registry to connect your app to ArgoCD

See the Deployment Pipeline guide for complete instructions and workflow examples.

If your application needs to access GCP resources (e.g. databases), configure workload identity using this guide.

If your application needs to make calls to external (non-GCP) services, refer to the egress proxy documentation.

After your PR to gap-registry is merged, verify that the application appears in ArgoCD (it can take a few minutes). Staging environments will be auto-synced unless autoSyncToStaging was set to false.

For production, check the diff in ArgoCD and sync the application manually.

Promoting your application to production can be done with two clicks via ArgoCD.

Connect your service to Laas with the LaaS Configurator

More info

See this guide for the details

Using your team’s established method (usually Pingdom or Google Cloud Monitoring).

To improve upon the basic application setup, use workers, jobs, pre- and post-deploy hooks etc. refer to the pages under the Application configuration menu.

If you have problems with your application starting up, please refer to this troubleshooting document.