From b040d1f474c06ff818cebccf132fefd0d1b0bfb1 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 20 May 2026 09:40:18 +0200 Subject: [PATCH 01/41] draft: Team onboarding guide --- guides/deploy/_menu.md | 1 + guides/deploy/team-onboarding.md | 135 +++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 guides/deploy/team-onboarding.md diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index 0e0704ed25..a3401f792d 100644 --- a/guides/deploy/_menu.md +++ b/guides/deploy/_menu.md @@ -1,4 +1,5 @@ +# [Team Onboarding](team-onboarding) # [Deploy to Cloud Foundry](to-cf) # [Deploy to Kyma/K8s](to-kyma) # [Deploy with CI/CD](cicd) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md new file mode 100644 index 0000000000..204b68247d --- /dev/null +++ b/guides/deploy/team-onboarding.md @@ -0,0 +1,135 @@ +--- +synopsis: > + Step-by-step guide for onboarding a new team to CAP on SAP BTP, from creating a global account, through provisioning subaccounts via Terraform, to deploying a CAP application with a UI via a production-grade CI/CD pipeline. +status: released +--- + +# Team Onboarding + +{{ $frontmatter.synopsis }} + +[[toc]] + +## Overview + +You'll end up with three subaccounts (_Sandbox_, _Staging_, _Production_) provisioned via Terraform, and a release flow where pushes to `main` auto-deploy to _Staging_ and tagged GitHub releases roll out to _Production_. + +The topology mirrors what `cds add github-actions` produces, so the Terraform infrastructure and CI/CD workflows fit together without further glue. + +## 1. Create the Global Account + +Global account creation is a one-time, manual step. Request one via your BTP admin or [SAP for Me](https://me.sap.com). + +You also need an admin user with permissions to create subaccounts. + +Once the global account exists, note its **subdomain** (e.g. `my-team`) and pick a **region** (`eu12`, `us10`, …). The same region is used for all three subaccounts. + +[Learn more about SAP BTP global accounts.](https://help.sap.com/docs/btp/sap-business-technology-platform/global-accounts){.learn-more} + +### Set Up Identity + +Authentication for your subaccounts and apps goes through **SAP Cloud Identity Services (IAS)**. Set this up once at the global-account level so every subaccount inherits the same trust: + +1. Provision an IAS tenant for your team if you don't already have one. Request via your BTP admin or [SAP for Me](https://me.sap.com). +2. In the BTP cockpit, open your global account → **Security** → **Trust Configuration** → **Establish Trust** and select the IAS tenant. This makes IAS the identity provider for the global account. +3. Note the IAS **origin key** (e.g. `sap.custom`). Terraform uses it to wire IAS trust into each subaccount and to assign admin role collections. + +[Learn more about IAS trust configuration.](https://help.sap.com/docs/btp/sap-business-technology-platform/establish-trust-and-federation-with-ui){.learn-more} + +## 2. Install Local Tooling + +Make sure the basic CAP tools are installed. In addition, you'll need [Terraform](https://developer.hashicorp.com/terraform/install). + +[Learn more in Get Started.](../../get-started/){.learn-more} + +## 3. Set Up the Landscape with Terraform + +Use the bundled Terraform template to provision a consistent _Sandbox + Staging + Production_ landscape in one shot: + +```sh +mkdir +cd +cds init +cds add terraform +``` + +You'll be prompted for `globalAccountId`, `region`, and `idp_origin_key`. Three files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`. + +The result: + +```zsh +Global Account (‹my-team›) +├── Subaccount: Sandbox +├── Subaccount: Staging +└── Subaccount: Production +``` + +Each subaccount gets the same baseline entitlements, a Cloud Foundry environment instance, a default CF space, and a HANA Cloud instance. + +::: tip Why three subaccounts? +The split matches the CI/CD flow created by `cds add github-actions`: + +- **Sandbox** for individual developers to experiment. +- **Staging** auto-deployed on every push to `main`. +- **Production** deployed only when a GitHub release is published. +::: + +::: details Baseline entitlements per subaccount + +| Service | Plan | Purpose | +|----------------------|---------------|----------------------------------| +| `xsuaa` | `application` | Authentication | +| `destination` | `lite` | Outbound destinations | +| `hana-cloud` | `hana` | Managed HANA | +| `hana` | `hdi-shared` | HDI containers | +| `saas-registry` | `application` | Multitenant scenarios | +| `alert-notification` | `standard` | Operational alerts | +| `application-logs` | `lite` | Log aggregation | + +IAS trust is configured per subaccount, and admins listed in `sandbox_admin_emails` / `staging_admin_emails` / `production_admin_emails` are assigned the admin role collection. + +::: + +### Apply + +Authenticate via env vars and provision: + +```sh + export BTP_USERNAME='you@example.com' + export BTP_PASSWORD='********' + export CF_USER='you@example.com' + export CF_PASSWORD='********' + export TF_VAR_hana_system_password='********' + +cd .terraform +terraform init +terraform plan +terraform apply +``` + +HANA Cloud provisioning takes 20–30 minutes per instance, so expect this `terraform apply` to run for a while. + +::: details Customizing variables + +Create a `terraform.tfvars` next to `main.tf` to assign admins: + +```hcl +sandbox_admin_emails = ["alice@example.com"] +staging_admin_emails = ["alice@example.com"] +production_admin_emails = ["alice@example.com"] +``` + +Other overrides (region, subdomains, role collection name, HANA memory, IP allowlist) are documented in `variables.tf`. + +::: + +## 4. Bootstrap, Deploy, and Wire Up CI/CD + +Pick **one** deployment guide depending on your runtime choice: + +- [Deploy to Cloud Foundry](to-cf): an opinionated, app-centric runtime where the platform manages buildpacks, routing, and bound services. Best when you want to focus on code over infrastructure. +- [Deploy to Kyma/K8s](to-kyma): a managed Kubernetes runtime where you own the container images, manifests, and networking. Best when you need fine-grained control or are already invested in the K8s ecosystem. + +Then automate the rollout: + +- [Deploy with CI/CD](cicd): wire up GitHub Actions so pushes to `main` deploy to _Staging_ and releases deploy to _Production_. From da150ae0f00f9f40a494605e8bbd4d6b83bc178f Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 21 May 2026 14:23:05 +0200 Subject: [PATCH 02/41] Update team-onboarding.md --- guides/deploy/team-onboarding.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 204b68247d..b43ca23529 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -53,7 +53,18 @@ cds init cds add terraform ``` -You'll be prompted for `globalAccountId`, `region`, and `idp_origin_key`. Three files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`. +You'll be prompted for: + +| Prompt | Used for | +|-------------------------|---------------------------------------------------------| +| `globalAccountId` | Subdomain of your global account | +| `region` | Region label for all subaccounts | +| `idp_origin_key` | IAS origin key (defaults to `sap.custom`) | +| BTP username + password | BTP Terraform provider auth | +| CF username + password | Cloud Foundry Terraform provider auth | +| HANA SYSTEM password | Initial HANA Cloud SYSTEM user password | + +Four files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`, and a `terraform.tfvars` (mode `0600`) holding the values you just entered. The whole `.terraform/` directory is already gitignored. The result: @@ -92,15 +103,7 @@ IAS trust is configured per subaccount, and admins listed in `sandbox_admin_emai ### Apply -Authenticate via env vars and provision: - ```sh - export BTP_USERNAME='you@example.com' - export BTP_PASSWORD='********' - export CF_USER='you@example.com' - export CF_PASSWORD='********' - export TF_VAR_hana_system_password='********' - cd .terraform terraform init terraform plan From 6ee56e8bba99d1dd07d80192a69c2b09be82289b Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 22:45:14 +0200 Subject: [PATCH 03/41] feat(deploy): add Terraform guide for cds add terraform --- guides/deploy/_menu.md | 1 + guides/deploy/terraform.md | 83 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 guides/deploy/terraform.md diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index a3401f792d..7fd755a02b 100644 --- a/guides/deploy/_menu.md +++ b/guides/deploy/_menu.md @@ -2,6 +2,7 @@ # [Team Onboarding](team-onboarding) # [Deploy to Cloud Foundry](to-cf) # [Deploy to Kyma/K8s](to-kyma) +# [Deploy with Terraform](terraform) # [Deploy with CI/CD](cicd) # [Multi-tenant SaaS Applications](../multitenancy/) # [MTX Services Reference](../multitenancy/mtxs) diff --git a/guides/deploy/terraform.md b/guides/deploy/terraform.md new file mode 100644 index 0000000000..e000ad6999 --- /dev/null +++ b/guides/deploy/terraform.md @@ -0,0 +1,83 @@ +--- +description: > + Use Terraform to provision SAP BTP subaccounts, entitlements, HANA Cloud instances, and CF environments for your CAP application. +--- + +# Deploy with Terraform + +[Terraform](https://www.terraform.io/) lets you declare your BTP infrastructure as code and provision it reproducibly. `cds add terraform` generates a ready-to-run Terraform configuration that creates three subaccounts (Sandbox, Staging, Production) with all the services a typical CAP app needs. + +[[toc]] + +## Prerequisites + +- [Terraform CLI](https://developer.hashicorp.com/terraform/install) installed +- An SAP BTP global account with entitlements for: HANA Cloud, XSUAA, Destination, SaaS Registry, Alert Notification, Application Logging +- BTP and CF credentials (user + password) + +## Setup + +Run in your CAP project root: + +```sh +cds add terraform +``` + +You will be prompted for: + +| Prompt | Example | +|--------|---------| +| `globalAccountId` | `my-team` | +| `region` | `eu12` | +| `idp_origin_key` | `sap.custom` (press Enter for default) | +| `BTP username` | `user@example.com` | +| `CF username` | `user@example.com` | +| `admin emails` | `user@example.com, colleague@example.com` | +| `BTP password` | *(hidden)* | +| `CF password` | *(hidden)* | +| `HANA SYSTEM password` | *(hidden)* | + +The **admin emails** (comma-separated) are assigned the *Subaccount Administrator* role collection in all three subaccounts. Leave blank to skip role assignments. + +This writes the following files: + +``` +.terraform/ + main.tf # subaccounts, entitlements, HANA, CF, role assignments + provider.tf # SAP BTP + Cloud Foundry provider config + variables.tf # variable declarations + terraform.tfvars # your credentials — DO NOT commit this file +``` + +::: warning Keep `terraform.tfvars` out of git +It is written with mode `0600`. Add `.terraform/terraform.tfvars` to your `.gitignore`. +::: + +## Run + +```sh +cd .terraform +terraform init +terraform plan # preview what will be created +terraform apply # provision the infrastructure +``` + +## What Gets Provisioned + +For each environment (Sandbox, Staging, Production): + +- A BTP **subaccount** in the given region +- **Entitlements**: XSUAA, Destination, HANA Cloud (hana), HANA HDI (hdi-shared), SaaS Registry, Alert Notification, Application Logging +- A **Cloud Foundry environment** instance and space +- A **HANA Cloud** service instance (default: 30 GB memory) +- An **IAS trust** configuration (if `idp_origin_key` is set) +- **Subaccount Administrator** role assignments for the given admin emails + +## Customization + +After running `cds add terraform`, edit the generated files directly: + +- Change `hana_memory_gb` in `variables.tf` to resize HANA instances +- Add more entitlements or services to `main.tf` +- Adjust `cf_landscape_label` if your region uses a non-default label (e.g. `cf-us10-001`) +- Set per-environment `*_subdomain` variables for custom subaccount subdomains From 567861e4f6d507356583c73db5697d0aace90796 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 22:49:00 +0200 Subject: [PATCH 04/41] fix(deploy): reframe terraform page as BTP account setup, not deployment guide --- guides/deploy/_menu.md | 2 +- guides/deploy/terraform.md | 48 ++++++++++++++++++++------------------ 2 files changed, 26 insertions(+), 24 deletions(-) diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index 7fd755a02b..0bed0f0770 100644 --- a/guides/deploy/_menu.md +++ b/guides/deploy/_menu.md @@ -1,8 +1,8 @@ # [Team Onboarding](team-onboarding) +# [BTP Account Setup with Terraform](terraform) # [Deploy to Cloud Foundry](to-cf) # [Deploy to Kyma/K8s](to-kyma) -# [Deploy with Terraform](terraform) # [Deploy with CI/CD](cicd) # [Multi-tenant SaaS Applications](../multitenancy/) # [MTX Services Reference](../multitenancy/mtxs) diff --git a/guides/deploy/terraform.md b/guides/deploy/terraform.md index e000ad6999..d8e97150a7 100644 --- a/guides/deploy/terraform.md +++ b/guides/deploy/terraform.md @@ -1,21 +1,21 @@ --- description: > - Use Terraform to provision SAP BTP subaccounts, entitlements, HANA Cloud instances, and CF environments for your CAP application. + Use Terraform to provision the SAP BTP subaccounts, entitlements, HANA Cloud instances, and Cloud Foundry environments your CAP project needs. --- -# Deploy with Terraform +# BTP Account Setup with Terraform -[Terraform](https://www.terraform.io/) lets you declare your BTP infrastructure as code and provision it reproducibly. `cds add terraform` generates a ready-to-run Terraform configuration that creates three subaccounts (Sandbox, Staging, Production) with all the services a typical CAP app needs. +Before you deploy a CAP application to Cloud Foundry or Kyma, you need SAP BTP subaccounts with the right entitlements and services in place. `cds add terraform` generates a ready-to-run Terraform configuration that does exactly that — it provisions three environments (Sandbox, Staging, Production) as code so the setup is repeatable and version-controlled. [[toc]] ## Prerequisites - [Terraform CLI](https://developer.hashicorp.com/terraform/install) installed -- An SAP BTP global account with entitlements for: HANA Cloud, XSUAA, Destination, SaaS Registry, Alert Notification, Application Logging -- BTP and CF credentials (user + password) +- An SAP BTP global account with quota for: HANA Cloud, XSUAA, Destination, SaaS Registry, Alert Notification, Application Logging +- BTP and Cloud Foundry credentials (user + password) -## Setup +## Generate the Configuration Run in your CAP project root: @@ -37,15 +37,15 @@ You will be prompted for: | `CF password` | *(hidden)* | | `HANA SYSTEM password` | *(hidden)* | -The **admin emails** (comma-separated) are assigned the *Subaccount Administrator* role collection in all three subaccounts. Leave blank to skip role assignments. +The **admin emails** (comma-separated) receive the *Subaccount Administrator* role collection in all three subaccounts. Leave blank to skip role assignments. -This writes the following files: +The command writes: ``` .terraform/ - main.tf # subaccounts, entitlements, HANA, CF, role assignments + main.tf # subaccounts, entitlements, HANA Cloud, CF spaces, role assignments provider.tf # SAP BTP + Cloud Foundry provider config - variables.tf # variable declarations + variables.tf # variable declarations with defaults terraform.tfvars # your credentials — DO NOT commit this file ``` @@ -53,31 +53,33 @@ This writes the following files: It is written with mode `0600`. Add `.terraform/terraform.tfvars` to your `.gitignore`. ::: -## Run +## Provision ```sh cd .terraform terraform init -terraform plan # preview what will be created -terraform apply # provision the infrastructure +terraform plan # preview what will be created +terraform apply # provision ``` -## What Gets Provisioned +## What Gets Created -For each environment (Sandbox, Staging, Production): +For each of the three environments (Sandbox, Staging, Production): -- A BTP **subaccount** in the given region -- **Entitlements**: XSUAA, Destination, HANA Cloud (hana), HANA HDI (hdi-shared), SaaS Registry, Alert Notification, Application Logging +- A BTP **subaccount** in the configured region +- **Entitlements**: XSUAA, Destination, HANA Cloud, HANA HDI (hdi-shared), SaaS Registry, Alert Notification, Application Logging - A **Cloud Foundry environment** instance and space -- A **HANA Cloud** service instance (default: 30 GB memory) +- A **HANA Cloud** service instance (default: 30 GB) - An **IAS trust** configuration (if `idp_origin_key` is set) - **Subaccount Administrator** role assignments for the given admin emails +Once provisioned, continue with [Deploy to Cloud Foundry](to-cf) or [Deploy to Kyma/K8s](to-kyma) to deploy your application. + ## Customization -After running `cds add terraform`, edit the generated files directly: +Edit the generated files to fit your landscape: -- Change `hana_memory_gb` in `variables.tf` to resize HANA instances -- Add more entitlements or services to `main.tf` -- Adjust `cf_landscape_label` if your region uses a non-default label (e.g. `cf-us10-001`) -- Set per-environment `*_subdomain` variables for custom subaccount subdomains +- `hana_memory_gb` in `variables.tf` — resize HANA instances +- `cf_landscape_label` — change if your region uses a non-default CF landscape (e.g. `cf-us10-001`) +- `*_subdomain` variables — set custom subaccount subdomains +- `main.tf` — add further entitlements or service instances From 28f4824d29fd39d73d2bc3c658613375e50c27d9 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 22:51:01 +0200 Subject: [PATCH 05/41] fix(deploy): fold terraform into team onboarding, drop separate page --- guides/deploy/_menu.md | 1 - guides/deploy/team-onboarding.md | 11 +---- guides/deploy/terraform.md | 85 -------------------------------- 3 files changed, 2 insertions(+), 95 deletions(-) delete mode 100644 guides/deploy/terraform.md diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index 0bed0f0770..a3401f792d 100644 --- a/guides/deploy/_menu.md +++ b/guides/deploy/_menu.md @@ -1,6 +1,5 @@ # [Team Onboarding](team-onboarding) -# [BTP Account Setup with Terraform](terraform) # [Deploy to Cloud Foundry](to-cf) # [Deploy to Kyma/K8s](to-kyma) # [Deploy with CI/CD](cicd) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index b43ca23529..2fc4e2153e 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -62,6 +62,7 @@ You'll be prompted for: | `idp_origin_key` | IAS origin key (defaults to `sap.custom`) | | BTP username + password | BTP Terraform provider auth | | CF username + password | Cloud Foundry Terraform provider auth | +| admin emails | Comma-separated; assigned the admin role collection in all three subaccounts | | HANA SYSTEM password | Initial HANA Cloud SYSTEM user password | Four files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`, and a `terraform.tfvars` (mode `0600`) holding the values you just entered. The whole `.terraform/` directory is already gitignored. @@ -97,7 +98,7 @@ The split matches the CI/CD flow created by `cds add github-actions`: | `alert-notification` | `standard` | Operational alerts | | `application-logs` | `lite` | Log aggregation | -IAS trust is configured per subaccount, and admins listed in `sandbox_admin_emails` / `staging_admin_emails` / `production_admin_emails` are assigned the admin role collection. +IAS trust is configured per subaccount, and the admin emails entered during `cds add terraform` are assigned the admin role collection in all three subaccounts. ::: @@ -114,14 +115,6 @@ HANA Cloud provisioning takes 20–30 minutes per instance, so expect this `terr ::: details Customizing variables -Create a `terraform.tfvars` next to `main.tf` to assign admins: - -```hcl -sandbox_admin_emails = ["alice@example.com"] -staging_admin_emails = ["alice@example.com"] -production_admin_emails = ["alice@example.com"] -``` - Other overrides (region, subdomains, role collection name, HANA memory, IP allowlist) are documented in `variables.tf`. ::: diff --git a/guides/deploy/terraform.md b/guides/deploy/terraform.md deleted file mode 100644 index d8e97150a7..0000000000 --- a/guides/deploy/terraform.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -description: > - Use Terraform to provision the SAP BTP subaccounts, entitlements, HANA Cloud instances, and Cloud Foundry environments your CAP project needs. ---- - -# BTP Account Setup with Terraform - -Before you deploy a CAP application to Cloud Foundry or Kyma, you need SAP BTP subaccounts with the right entitlements and services in place. `cds add terraform` generates a ready-to-run Terraform configuration that does exactly that — it provisions three environments (Sandbox, Staging, Production) as code so the setup is repeatable and version-controlled. - -[[toc]] - -## Prerequisites - -- [Terraform CLI](https://developer.hashicorp.com/terraform/install) installed -- An SAP BTP global account with quota for: HANA Cloud, XSUAA, Destination, SaaS Registry, Alert Notification, Application Logging -- BTP and Cloud Foundry credentials (user + password) - -## Generate the Configuration - -Run in your CAP project root: - -```sh -cds add terraform -``` - -You will be prompted for: - -| Prompt | Example | -|--------|---------| -| `globalAccountId` | `my-team` | -| `region` | `eu12` | -| `idp_origin_key` | `sap.custom` (press Enter for default) | -| `BTP username` | `user@example.com` | -| `CF username` | `user@example.com` | -| `admin emails` | `user@example.com, colleague@example.com` | -| `BTP password` | *(hidden)* | -| `CF password` | *(hidden)* | -| `HANA SYSTEM password` | *(hidden)* | - -The **admin emails** (comma-separated) receive the *Subaccount Administrator* role collection in all three subaccounts. Leave blank to skip role assignments. - -The command writes: - -``` -.terraform/ - main.tf # subaccounts, entitlements, HANA Cloud, CF spaces, role assignments - provider.tf # SAP BTP + Cloud Foundry provider config - variables.tf # variable declarations with defaults - terraform.tfvars # your credentials — DO NOT commit this file -``` - -::: warning Keep `terraform.tfvars` out of git -It is written with mode `0600`. Add `.terraform/terraform.tfvars` to your `.gitignore`. -::: - -## Provision - -```sh -cd .terraform -terraform init -terraform plan # preview what will be created -terraform apply # provision -``` - -## What Gets Created - -For each of the three environments (Sandbox, Staging, Production): - -- A BTP **subaccount** in the configured region -- **Entitlements**: XSUAA, Destination, HANA Cloud, HANA HDI (hdi-shared), SaaS Registry, Alert Notification, Application Logging -- A **Cloud Foundry environment** instance and space -- A **HANA Cloud** service instance (default: 30 GB) -- An **IAS trust** configuration (if `idp_origin_key` is set) -- **Subaccount Administrator** role assignments for the given admin emails - -Once provisioned, continue with [Deploy to Cloud Foundry](to-cf) or [Deploy to Kyma/K8s](to-kyma) to deploy your application. - -## Customization - -Edit the generated files to fit your landscape: - -- `hana_memory_gb` in `variables.tf` — resize HANA instances -- `cf_landscape_label` — change if your region uses a non-default CF landscape (e.g. `cf-us10-001`) -- `*_subdomain` variables — set custom subaccount subdomains -- `main.tf` — add further entitlements or service instances From 263f92a41e8ecdcbb9d3628a9a256bf14ebe52f6 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 22:53:47 +0200 Subject: [PATCH 06/41] fix(deploy): no cds init needed, just npm init -y --- guides/deploy/team-onboarding.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 2fc4e2153e..10b2543301 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -47,9 +47,8 @@ Make sure the basic CAP tools are installed. In addition, you'll need [Terraform Use the bundled Terraform template to provision a consistent _Sandbox + Staging + Production_ landscape in one shot: ```sh -mkdir -cd -cds init +mkdir infra && cd infra +npm init -y cds add terraform ``` From 7e838ee1fabf5cb706a19f85ac738fee91b933a4 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 22:54:08 +0200 Subject: [PATCH 07/41] fix(deploy): use cds init for terraform setup --- guides/deploy/team-onboarding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 10b2543301..e81de5c48d 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -47,8 +47,8 @@ Make sure the basic CAP tools are installed. In addition, you'll need [Terraform Use the bundled Terraform template to provision a consistent _Sandbox + Staging + Production_ landscape in one shot: ```sh -mkdir infra && cd infra -npm init -y +mkdir bookshop && cd bookshop +cds init cds add terraform ``` From b31c311b56087d03fdea8dec61cce56b98901f9b Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 22:54:25 +0200 Subject: [PATCH 08/41] fix(deploy): cds init bookshop && cd bookshop && cds add terraform --- guides/deploy/team-onboarding.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index e81de5c48d..249ee34014 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -47,8 +47,7 @@ Make sure the basic CAP tools are installed. In addition, you'll need [Terraform Use the bundled Terraform template to provision a consistent _Sandbox + Staging + Production_ landscape in one shot: ```sh -mkdir bookshop && cd bookshop -cds init +cds init bookshop && cd bookshop cds add terraform ``` From 18e0666ace63b286526364c44874682be41db2d4 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 23:07:35 +0200 Subject: [PATCH 09/41] fix(deploy): no cds init needed for terraform setup --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 249ee34014..860104cbc6 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -47,7 +47,7 @@ Make sure the basic CAP tools are installed. In addition, you'll need [Terraform Use the bundled Terraform template to provision a consistent _Sandbox + Staging + Production_ landscape in one shot: ```sh -cds init bookshop && cd bookshop +mkdir bookshop && cd bookshop cds add terraform ``` From ea1902324e3b68b3848e0f916441a4412082edc8 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 23:15:07 +0200 Subject: [PATCH 10/41] fix(deploy): no password prompts, set via env before terraform apply --- guides/deploy/team-onboarding.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 860104cbc6..09c12609b7 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -58,12 +58,11 @@ You'll be prompted for: | `globalAccountId` | Subdomain of your global account | | `region` | Region label for all subaccounts | | `idp_origin_key` | IAS origin key (defaults to `sap.custom`) | -| BTP username + password | BTP Terraform provider auth | -| CF username + password | Cloud Foundry Terraform provider auth | +| BTP username | BTP Terraform provider auth | +| CF username | Cloud Foundry Terraform provider auth | | admin emails | Comma-separated; assigned the admin role collection in all three subaccounts | -| HANA SYSTEM password | Initial HANA Cloud SYSTEM user password | -Four files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`, and a `terraform.tfvars` (mode `0600`) holding the values you just entered. The whole `.terraform/` directory is already gitignored. +Four files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`, and a `terraform.tfvars` with the non-secret config. Passwords are never written to disk — set them as environment variables before applying: The result: @@ -103,6 +102,9 @@ IAS trust is configured per subaccount, and the admin emails entered during `cds ### Apply ```sh +export BTP_PASSWORD=... +export CF_PASSWORD=... +export TF_VAR_hana_system_password=... cd .terraform terraform init terraform plan From 7e025603755b92d50c597d79cfe26dd2439b528b Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 23:18:12 +0200 Subject: [PATCH 11/41] fix(deploy): blank line between export and cd in apply snippet --- guides/deploy/team-onboarding.md | 1 + 1 file changed, 1 insertion(+) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 09c12609b7..b5a405fbf6 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -105,6 +105,7 @@ IAS trust is configured per subaccount, and the admin emails entered during `cds export BTP_PASSWORD=... export CF_PASSWORD=... export TF_VAR_hana_system_password=... + cd .terraform terraform init terraform plan From 93b1887f8652b6b6b06fd7ff835f45cca808f7d0 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 5 Aug 2026 23:18:38 +0200 Subject: [PATCH 12/41] fix(deploy): leading space on export lines to suppress shell history --- guides/deploy/team-onboarding.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index b5a405fbf6..1b2215d4f8 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -102,9 +102,9 @@ IAS trust is configured per subaccount, and the admin emails entered during `cds ### Apply ```sh -export BTP_PASSWORD=... -export CF_PASSWORD=... -export TF_VAR_hana_system_password=... + export BTP_PASSWORD=... + export CF_PASSWORD=... + export TF_VAR_hana_system_password=... cd .terraform terraform init From f458460111a2b72b7a7ef070046040f976cbc911 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 6 Aug 2026 00:43:11 +0200 Subject: [PATCH 13/41] fix(deploy): terraform init runs automatically, simplify apply section --- guides/deploy/team-onboarding.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 1b2215d4f8..1c28907e18 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -102,12 +102,7 @@ IAS trust is configured per subaccount, and the admin emails entered during `cds ### Apply ```sh - export BTP_PASSWORD=... - export CF_PASSWORD=... - export TF_VAR_hana_system_password=... - cd .terraform -terraform init terraform plan terraform apply ``` From 600997b5029d4f0b3140ffe9dcdf2982dd80d7a8 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 6 Aug 2026 00:44:53 +0200 Subject: [PATCH 14/41] fix(deploy): restore terraform init in apply section --- guides/deploy/team-onboarding.md | 1 + 1 file changed, 1 insertion(+) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 1c28907e18..54dc725572 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -103,6 +103,7 @@ IAS trust is configured per subaccount, and the admin emails entered during `cds ```sh cd .terraform +terraform init terraform plan terraform apply ``` From 93297a6a8cf0fe22f43ced80655f7b5c2f79ca91 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 6 Aug 2026 00:57:29 +0200 Subject: [PATCH 15/41] fix(deploy): single email prompt for btp/cf user and admins --- guides/deploy/team-onboarding.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 54dc725572..69fda9d16a 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -58,9 +58,7 @@ You'll be prompted for: | `globalAccountId` | Subdomain of your global account | | `region` | Region label for all subaccounts | | `idp_origin_key` | IAS origin key (defaults to `sap.custom`) | -| BTP username | BTP Terraform provider auth | -| CF username | Cloud Foundry Terraform provider auth | -| admin emails | Comma-separated; assigned the admin role collection in all three subaccounts | +| email(s) | BTP + CF username (first); admin role in all subaccounts (all) | Four files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`, and a `terraform.tfvars` with the non-secret config. Passwords are never written to disk — set them as environment variables before applying: From f4d6a0ebd933d6bd1ef9ac483f4bde4118f85f8c Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 6 Aug 2026 01:01:28 +0200 Subject: [PATCH 16/41] fix(deploy): idp_origin_key empty by default, clarify when to set it --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 69fda9d16a..3190fad453 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -57,7 +57,7 @@ You'll be prompted for: |-------------------------|---------------------------------------------------------| | `globalAccountId` | Subdomain of your global account | | `region` | Region label for all subaccounts | -| `idp_origin_key` | IAS origin key (defaults to `sap.custom`) | +| `idp_origin_key` | IAS origin key — leave empty when using SAP default IdP | | email(s) | BTP + CF username (first); admin role in all subaccounts (all) | Four files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`, and a `terraform.tfvars` with the non-secret config. Passwords are never written to disk — set them as environment variables before applying: From 7227d12a5c4edf79f2e6ab5d0735bd8e78264fb4 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Tue, 27 Oct 2026 18:18:46 +0100 Subject: [PATCH 17/41] Document Mac setup through Terraform provisioning and Bookshop deployment --- get-started/index.md | 27 +++- guides/deploy/team-onboarding.md | 233 +++++++++++++++++++++---------- guides/deploy/to-cf.md | 2 +- 3 files changed, 186 insertions(+), 76 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index b4c15c3cba..c5acd73c51 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -36,7 +36,8 @@ bash -c "$( curl https://raw.githubusercontent.com/homebrew/install/HEAD/install ::: code-group ```shell [macOS/Linux] -brew install node # Node.js LTS +brew install node@24 # Node.js LTS supported by CAP +brew link --force node@24 npm i -g @sap/cds-dk # install CAP's cds-dk globally ``` ```PowerShell [Windows] @@ -57,6 +58,30 @@ sqlite3 -version ``` ::: +### Terraform and BTP CLI {.optional #terraform-and-btp-cli} + +For [team landscape provisioning](../guides/deploy/team-onboarding), install [Terraform](https://developer.hashicorp.com/terraform/install) and the [SAP BTP CLI](https://tools.hana.ondemand.com/#cloud-btpcli). + +On macOS, install Terraform with Homebrew: + +~~~sh +brew tap hashicorp/tap +brew install hashicorp/tap/terraform +~~~ + +Download the BTP CLI archive matching your Mac's processor (Apple silicon or Intel), extract it, and put the `btp` executable in a directory on your PATH. For example, if you extracted it into `~/Downloads/btp-cli`: + +~~~sh +mkdir -p ~/.local/bin +install -m 755 ~/Downloads/btp-cli/btp ~/.local/bin/btp +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile +exec zsh -l +btp --info +terraform version +~~~ + +Adjust the source path if you extracted the archive elsewhere. `btp --info` works before login and shows the CLI version. Installation of [CF CLI and its plugins](../guides/deploy/to-cf#cf-cli) and [MTA Build Tool](../guides/deploy/to-cf#mbt) is covered by the deployment guide. + ### Java and Maven {.optional} ::: code-group diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 3190fad453..8d3eb72841 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -1,7 +1,7 @@ --- synopsis: > - Step-by-step guide for onboarding a new team to CAP on SAP BTP, from creating a global account, through provisioning subaccounts via Terraform, to deploying a CAP application with a UI via a production-grade CI/CD pipeline. -status: released + Set up a Mac for CAP development, provision Sandbox, Staging, and Production on SAP BTP, and deploy a Bookshop application to Cloud Foundry from the command line. +status: draft --- # Team Onboarding @@ -10,117 +10,202 @@ status: released [[toc]] -## Overview +## Before You Start -You'll end up with three subaccounts (_Sandbox_, _Staging_, _Production_) provisioned via Terraform, and a release flow where pushes to `main` auto-deploy to _Staging_ and tagged GitHub releases roll out to _Production_. +This guide uses Node.js, Cloud Foundry, SAP HANA Cloud, XSUAA, and a Bookshop Fiori UI served through an App Router and SAP BTP Portal. Terraform owns the landscape; `cds up` owns the application and its bound services. Once a global account is available, the setup below needs no BTP cockpit interaction. SSO and application login still use your browser. -The topology mirrors what `cds add github-actions` produces, so the Terraform infrastructure and CI/CD workflows fit together without further glue. +Bootstrap the landscape once per team. If it already exists, obtain its Terraform outputs from the owner, complete local setup and login, then skip to application deployment. Use a unique application name for your daily work in a shared Sandbox. -## 1. Create the Global Account +A global account and its commercial entitlements must already exist. Request them from your BTP administrator or [SAP for Me](https://me.sap.com). Your provisioning user needs **Global Account Administrator** permissions to create subaccounts and assign entitlements. Include that user's email among the team administrators below. -Global account creation is a one-time, manual step. Request one via your BTP admin or [SAP for Me](https://me.sap.com). +The three stages have separate subaccounts, CF orgs, spaces, and databases. **Sandbox** is for experiments, **Staging** for integration checks, and **Production** for releases. The production classification alone does not configure database high availability, backups, or application scaling; configure those for your workload before serving customers. -You also need an admin user with permissions to create subaccounts. +## 1. Set Up Your Mac -Once the global account exists, note its **subdomain** (e.g. `my-team`) and pick a **region** (`eu12`, `us10`, …). The same region is used for all three subaccounts. +Follow [Initial Setup](../../get-started/#initial-setup) for Homebrew, Node.js, `cds-dk`, Git, and optionally VS Code. Finish Homebrew's printed PATH setup instructions and open a new terminal. -[Learn more about SAP BTP global accounts.](https://help.sap.com/docs/btp/sap-business-technology-platform/global-accounts){.learn-more} +Install [Terraform and the BTP CLI](../../get-started/#terraform-and-btp-cli), the [MTA Build Tool](to-cf#mbt), and the [CF CLI and its MTA and HTML5 plugins](to-cf#cf-cli). Verify: -### Set Up Identity +~~~sh +node --version +cds version +terraform version +btp --info +cf version +mbt --version +cf plugins +cds add --help +~~~ -Authentication for your subaccounts and apps goes through **SAP Cloud Identity Services (IAS)**. Set this up once at the global-account level so every subaccount inherits the same trust: +Use Terraform 1.2 or newer and CF CLI 8 or newer. `cf plugins` must list `multiapps` and `html5-plugin`. The Terraform facet is currently under development: your `cds-dk` build must list `terraform` in `cds add --help`. -1. Provision an IAS tenant for your team if you don't already have one. Request via your BTP admin or [SAP for Me](https://me.sap.com). -2. In the BTP cockpit, open your global account → **Security** → **Trust Configuration** → **Establish Trust** and select the IAS tenant. This makes IAS the identity provider for the global account. -3. Note the IAS **origin key** (e.g. `sap.custom`). Terraform uses it to wire IAS trust into each subaccount and to assign admin role collections. + -[Learn more about IAS trust configuration.](https://help.sap.com/docs/btp/sap-business-technology-platform/establish-trust-and-federation-with-ui){.learn-more} +## 2. Log In and Generate the Landscape -## 2. Install Local Tooling +Obtain the **global-account subdomain** from your administrator. It can be a UUID; it is not the display name or a subaccount ID. Choose a region offering all required services, for example `eu12`: -Make sure the basic CAP tools are installed. In addition, you'll need [Terraform](https://developer.hashicorp.com/terraform/install). +~~~sh +btp login --sso --subdomain +btp --info +btp --format json list accounts/subaccount +btp --format json list accounts/entitlement +cf login --sso -a https://api.cf.eu12-001.hana.ondemand.com +mkdir launchpad +cd launchpad +cds add terraform +~~~ -[Learn more in Get Started.](../../get-started/){.learn-more} +Replace angle-bracket placeholders before running commands. Region and CF foundation are distinct: the default for region `eu12` is landscape `cf-eu12-001` and its API is `https://api.cf.eu12-001.hana.ondemand.com`. For another foundation, set `cf_landscape_label` in your variables and log in to its matching API. Use the same provisioning identity for both logins. CF does not need a target org or space yet. Check that `btp --info` shows the intended global account and server; a cockpit session alone does not authenticate Terraform. -## 3. Set Up the Landscape with Terraform +| Prompt | Answer | +| --- | --- | +| Global account subdomain | The subdomain used for BTP login | +| Region | For example `eu12`; must match the CF API | +| `idp_origin_key` | Empty for SAP's default IdP; otherwise the BTP administrative origin supplied by your administrator | +| Email(s) | Comma-separated users receiving subaccount administrator and CF deployment access; put the logged-in CF provisioning user first | -Use the bundled Terraform template to provision a consistent _Sandbox + Staging + Production_ landscape in one shot: +Authentication uses CLI sessions; the email prompt controls roles. The first email is recorded as `cf_user`, the org creator whose organization membership CF creates automatically. Keep that value unchanged when another administrator later applies the configuration. The command creates `terraform/main.tf`, `provider.tf`, `variables.tf`, `outputs.tf`, local `terraform.tfvars`, and a `.gitignore`. An older preview may have generated its configuration in `.terraform/`: continue using that directory and its state instead of generating another landscape. Repeating the command preserves existing configuration. `--force` regenerates templates while preserving local variables; review changes before planning against a provisioned landscape. -```sh -mkdir bookshop && cd bookshop -cds add terraform -``` +### Choose Names and Identity Settings -You'll be prompted for: +Use a short, unique landscape name. Here `launchpad/` contains Terraform and a nested Bookshop app. Edit `terraform/terraform.tfvars` before the first apply to fit your team's naming: -| Prompt | Used for | -|-------------------------|---------------------------------------------------------| -| `globalAccountId` | Subdomain of your global account | -| `region` | Region label for all subaccounts | -| `idp_origin_key` | IAS origin key — leave empty when using SAP default IdP | -| email(s) | BTP + CF username (first); admin role in all subaccounts (all) | +~~~hcl +landscape = "cap-launchpad" +landscape_name = "CAP Launchpad" +sandbox_subdomain = "cap-launchpad-sandbox" +staging_subdomain = "cap-launchpad-staging" +production_subdomain = "cap-launchpad-production" +~~~ -Four files are written to `.terraform/`: `main.tf`, `provider.tf`, `variables.tf`, and a `terraform.tfvars` with the non-secret config. Passwords are never written to disk — set them as environment variables before applying: +`landscape` controls CF org and HANA names; `landscape_name` controls subaccount display names. Subdomains are globally unique. Check the existing inventory and reserve names with your team. Terraform creates new accounts; do not import an existing team account into this landscape. -The result: +| Stage | Subaccount | CF org | Space | +| --- | --- | --- | --- | +| Sandbox | CAP Launchpad Sandbox | `cap-launchpad-sandbox` | `sandbox` | +| Staging | CAP Launchpad Staging | `cap-launchpad-staging` | `staging` | +| Production | CAP Launchpad Production | `cap-launchpad-production` | `production` | -```zsh -Global Account (‹my-team›) -├── Subaccount: Sandbox -├── Subaccount: Staging -└── Subaccount: Production -``` +Terraform reuses the BTP CLI session with `USE_BTPCLI_SESSION=true` and reads the CF CLI login through its empty CF provider block. Log in to both CLIs before provisioning. Stale `CF_*` credential environment variables can override CF's CLI fallback; clear them or verify their target and user. -Each subaccount gets the same baseline entitlements, a Cloud Foundry environment instance, a default CF space, and a HANA Cloud instance. +The default `cli_server_url` is `https://cli.btp.cloud.sap`. If `btp --info` shows another endpoint, put that exact URL in `terraform.tfvars`. For a custom CLI config location, export `BTPCLI_CONFIG_PATH` with the file path used by `btp --config`. -::: tip Why three subaccounts? -The split matches the CI/CD flow created by `cds add github-actions`: +CF role assignments default to origin `sap.ids`. For a custom CF identity provider, set `cf_origin` to its UAA origin. This is independent of `idp_origin_key` for BTP administrative roles. Optional application IAS trust uses `ias_tenant`, an IAS tenant hostname such as `mytenant.accounts.ondemand.com`. An origin key such as `sap.custom` is not a hostname. Trust is established per new subaccount; global-account application trust is not inherited automatically. -- **Sandbox** for individual developers to experiment. -- **Staging** auto-deployed on every push to `main`. -- **Production** deployed only when a GitHub release is published. -::: +### Check Capacity -::: details Baseline entitlements per subaccount +Verify that the global account can assign the following **to each of the three stages**: -| Service | Plan | Purpose | -|----------------------|---------------|----------------------------------| -| `xsuaa` | `application` | Authentication | -| `destination` | `lite` | Outbound destinations | -| `hana-cloud` | `hana` | Managed HANA | -| `hana` | `hdi-shared` | HDI containers | -| `saas-registry` | `application` | Multitenant scenarios | -| `alert-notification` | `standard` | Operational alerts | -| `application-logs` | `lite` | Log aggregation | +| Service | Plan | Purpose / capacity per stage | +| --- | --- | --- | +| `APPLICATION_RUNTIME` | `MEMORY` | 4 GB CF app memory; configurable with `cf_memory_gb` | +| `xsuaa` | `application` | App authentication | +| `destination` | `lite` | Destinations | +| `hana-cloud` | `hana` | One HANA Cloud database, default 30 GB memory | +| `hana` | `hdi-shared` | App's HDI container | +| `html5-apps-repo` | `app-host`, `app-runtime` | Fiori UI storage and serving | +| `portal` | `standard` | Bookshop launchpad | -IAS trust is configured per subaccount, and the admin emails entered during `cds add terraform` are assigned the admin role collection in all three subaccounts. +The baseline needs 12 GB unassigned CF memory and capacity for three HANA databases. Entitlements authorize consumption; service use can incur charges. Terraform does not reclaim quotas from existing accounts. Obtain additional capacity before applying if necessary. -::: +## 3. Provision and Verify -### Apply +In the same terminal, set a HANA SYSTEM password without putting it in shell history: -```sh -cd .terraform +~~~zsh +read -s 'TF_VAR_hana_system_password?HANA SYSTEM password: ' +printf '\n' +export TF_VAR_hana_system_password +export USE_BTPCLI_SESSION=true +cd terraform terraform init +terraform fmt +terraform validate +terraform plan -out=landscape.tfplan +terraform apply landscape.tfplan +terraform output terraform plan -terraform apply -``` +cd .. +~~~ + +Use a password satisfying [SAP HANA Cloud password requirements](https://help.sap.com/docs/hana-cloud). Review the saved plan before applying: for a fresh landscape it must show only **adds**, **0 changes**, **0 destroys**, and exactly your three new subaccounts. Subaccounts have `prevent_destroy` protection, but every plan still needs review. Do not run `terraform destroy` during onboarding. + +Each stage receives entitlements, CF runtime capacity, an org and space, administrator and Space Developer roles, and a HANA Cloud instance in that space. Space-local database provisioning supplies the app's HDI database without a cockpit mapping step. Provisioning can take 20–30 minutes. Leave the operation running until it finishes. The subsequent plan should report no changes. + +Normal Terraform output hides sensitive values, but state and saved plans can contain passwords. Restrict access and use an encrypted, access-controlled remote state backend before sharing the landscape. Keep **one state per landscape**, backed up; independent states for the same accounts can cause duplicate provisioning. + +### Recover a Failed Apply + +Keep the same directory and state. Fix the reported cause, run `terraform plan -out=landscape.tfplan` again, review it, and apply. Never delete state or change names to retry a partially provisioned landscape. + +| Error | Action | +| --- | --- | +| BTP HTTP 401 | Re-run BTP SSO and match `cli_server_url` to `btp --info` | +| Missing CF credentials | Log in to the region's CF API; clear stale credential overrides | +| HTTP 403 | Check provisioning permissions and that its email is in the admin lists | +| Insufficient entitlement | Obtain capacity; preserve existing assignments | +| Subdomain already exists | Choose unique names before creation; preserve names already recorded in state | +| HANA still provisioning | Wait for the active operation; inspect `cf service ` before retrying | +| HDI cannot find a database | Verify HANA completed provisioning in this stage's space | + +## 4. Create and Deploy Bookshop + +From `launchpad/`: + +~~~sh +cds init bookshop --nodejs --add sample +cd bookshop +cds add hana,xsuaa,mta,portal +npm install +~~~ + +These facets follow [Prepare for Production](to-cf#prepare-for-production), including the [Portal UI option](to-cf#add-ui). Portal adds App Router and HTML5 repository support. Refer to [Build and Deploy](to-cf#build-and-deploy) for the deployment procedure, build customization, and troubleshooting. + +Use the org and space names from `terraform output`. This first run tests the same app in all three new stages: + +~~~sh +for stage in sandbox staging production; do + cf target -o "cap-launchpad-$stage" -s "$stage" + cf target + cds up + cf apps + cf services + cf mta bookshop +done +~~~ + +Change `cap-launchpad` if you chose another prefix. Verify the target before every deployment. For daily work, deploy manually to Sandbox and use a release process for Staging and Production. + +### Assign App Roles and Test + +Infrastructure roles do not grant Bookshop's `admin` role. After deployment, assign the generated role collection for each stage using its output ID, org, space, and your login email: + +~~~sh +btp assign security/role-collection \ + "admin (bookshop -)" \ + --to-user --subaccount +~~~ + +For a custom application IdP, also pass `--of-idp `. App roles belong to the application deployment, not the Terraform infrastructure. -HANA Cloud provisioning takes 20–30 minutes per instance, so expect this `terraform apply` to run for a while. +For **each stage**, open the `bookshop` App Router route shown by `cf apps`. Sign in, open **Browse Books**, and verify seeded books and prices. Open **Manage Books** after granting the role. Test a write in Sandbox and confirm persistence after reloading. The development index and Fiori preview are disabled in production; use the deployed Portal UI. -::: details Customizing variables +All long-running apps must have their requested instances running. `cf services` must show successful creation of HANA, HDI, XSUAA, HTML5, and Portal services. On failure, inspect `cf mta-ops` and `cf logs bookshop-srv --recent`, then use [CF troubleshooting](../../get-started/get-help#mta). A successful deployment operation alone does not prove the UI works. -Other overrides (region, subdomains, role collection name, HANA memory, IP allowlist) are documented in `variables.tf`. +## 5. Set Up CI/CD and Team Ownership -::: +Set the app repository's Git remote before `cds add github-actions`, so release workflows use the correct repository. Follow [Deploy using CI/CD Pipelines](cicd#github-actions). -## 4. Bootstrap, Deploy, and Wire Up CI/CD +Configure GitHub environments **Staging** and **Production** with `CF_API`, `CF_ORG`, `CF_SPACE`, `CF_USERNAME`, and secret `CF_PASSWORD` for their respective Terraform outputs. Use a technical deployment user with supported noninteractive login and CF deployment rights scoped to these new targets. Local CLI SSO sessions are not CI credentials. Grant CF-only deployment rights without making the technical user a BTP administrator: -Pick **one** deployment guide depending on your runtime choice: +~~~sh +cf set-org-role OrgUser +cf set-space-role SpaceDeveloper +~~~ -- [Deploy to Cloud Foundry](to-cf): an opinionated, app-centric runtime where the platform manages buildpacks, routing, and bound services. Best when you want to focus on code over infrastructure. -- [Deploy to Kyma/K8s](to-kyma): a managed Kubernetes runtime where you own the container images, manifests, and networking. Best when you need fine-grained control or are already invested in the K8s ecosystem. +For a custom CF IdP, append `--origin ` to both commands. If this user should receive the template's administrator access, add its email to the appropriate stage's list and apply the reviewed plan. -Then automate the rollout: +The generated workflows deploy `main` pushes to Staging and published releases to Production. Configure Production's required reviewers and branch rules before releasing. Infrastructure provisioning remains separate from app CI/CD. -- [Deploy with CI/CD](cicd): wire up GitHub Actions so pushes to `main` deploy to _Staging_ and releases deploy to _Production_. +Commit app source, `mta.yaml`, lockfiles, and workflows. Commit Terraform configuration and `.terraform.lock.hcl`; keep state, local `*.tfvars`, and saved plans in protected storage. Record who owns provisioning and state access so the next developer can reuse the landscape. diff --git a/guides/deploy/to-cf.md b/guides/deploy/to-cf.md index b83cb60553..e4a5d9a83a 100644 --- a/guides/deploy/to-cf.md +++ b/guides/deploy/to-cf.md @@ -323,7 +323,7 @@ Visit the "Applications" section in your [SAP BTP cockpit](https://help.sap.com/ ![The screenshot shows the SAP BTP cockpit, when a user navigates to their dev space in the trial account and views all deployed applications.](./assets/apps-cockpit.png) ::: tip Next up: Assign the _admin_ role -To access the admin APIs, assign the _admin_ role required by the `AdminService`. By default, CAP creates a **role collection** named _admin‑\‑\_. [Assign it to your user](https://help.sap.com/docs/btp/sap-business-technology-platform/assign-user-groups-to-role-collections) to get access. +To access the admin APIs, assign the _admin_ role required by the `AdminService`. By default, CAP creates a **role collection** named _admin (\ \-\)_. [Assign it to your user](https://help.sap.com/docs/btp/sap-business-technology-platform/assign-user-groups-to-role-collections) to get access. ::: ### Use MTA Extensions with `cds up` From ee547e32448980e66958a68024d89f52da8dd888 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Tue, 27 Oct 2026 18:26:50 +0100 Subject: [PATCH 18/41] Keep Terraform tooling installation in Team Onboarding only --- get-started/index.md | 27 +-------------------------- guides/deploy/team-onboarding.md | 20 +++++++++++++++++++- 2 files changed, 20 insertions(+), 27 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index c5acd73c51..b4c15c3cba 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -36,8 +36,7 @@ bash -c "$( curl https://raw.githubusercontent.com/homebrew/install/HEAD/install ::: code-group ```shell [macOS/Linux] -brew install node@24 # Node.js LTS supported by CAP -brew link --force node@24 +brew install node # Node.js LTS npm i -g @sap/cds-dk # install CAP's cds-dk globally ``` ```PowerShell [Windows] @@ -58,30 +57,6 @@ sqlite3 -version ``` ::: -### Terraform and BTP CLI {.optional #terraform-and-btp-cli} - -For [team landscape provisioning](../guides/deploy/team-onboarding), install [Terraform](https://developer.hashicorp.com/terraform/install) and the [SAP BTP CLI](https://tools.hana.ondemand.com/#cloud-btpcli). - -On macOS, install Terraform with Homebrew: - -~~~sh -brew tap hashicorp/tap -brew install hashicorp/tap/terraform -~~~ - -Download the BTP CLI archive matching your Mac's processor (Apple silicon or Intel), extract it, and put the `btp` executable in a directory on your PATH. For example, if you extracted it into `~/Downloads/btp-cli`: - -~~~sh -mkdir -p ~/.local/bin -install -m 755 ~/Downloads/btp-cli/btp ~/.local/bin/btp -echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile -exec zsh -l -btp --info -terraform version -~~~ - -Adjust the source path if you extracted the archive elsewhere. `btp --info` works before login and shows the CLI version. Installation of [CF CLI and its plugins](../guides/deploy/to-cf#cf-cli) and [MTA Build Tool](../guides/deploy/to-cf#mbt) is covered by the deployment guide. - ### Java and Maven {.optional} ::: code-group diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 8d3eb72841..532bfa4150 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -24,7 +24,25 @@ The three stages have separate subaccounts, CF orgs, spaces, and databases. **Sa Follow [Initial Setup](../../get-started/#initial-setup) for Homebrew, Node.js, `cds-dk`, Git, and optionally VS Code. Finish Homebrew's printed PATH setup instructions and open a new terminal. -Install [Terraform and the BTP CLI](../../get-started/#terraform-and-btp-cli), the [MTA Build Tool](to-cf#mbt), and the [CF CLI and its MTA and HTML5 plugins](to-cf#cf-cli). Verify: +Install the [MTA Build Tool](to-cf#mbt) and the [CF CLI and its MTA and HTML5 plugins](to-cf#cf-cli). + +For landscape provisioning, install [Terraform](https://developer.hashicorp.com/terraform/install) with Homebrew: + +~~~sh +brew tap hashicorp/tap +brew install hashicorp/tap/terraform +~~~ + +Download the [SAP BTP CLI](https://tools.hana.ondemand.com/#cloud-btpcli) archive matching your Mac's processor (Apple silicon or Intel), extract it, and put the `btp` executable on your PATH. For example, if you extracted it into `~/Downloads/btp-cli`: + +~~~sh +mkdir -p ~/.local/bin +install -m 755 ~/Downloads/btp-cli/btp ~/.local/bin/btp +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile +exec zsh -l +~~~ + +Adjust the source path if you extracted the archive elsewhere. `btp --info` works before login and shows the CLI version. Verify all tools: ~~~sh node --version From 32d3144bc7d45795d87e554b0b335cd086588a0b Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Tue, 27 Oct 2026 19:31:19 +0100 Subject: [PATCH 19/41] Document CRM team onboarding with IAS and shared app stages --- guides/deploy/team-onboarding.md | 88 ++++++++++++++++++++------------ 1 file changed, 56 insertions(+), 32 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 532bfa4150..171bc7aa07 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -12,12 +12,22 @@ status: draft ## Before You Start -This guide uses Node.js, Cloud Foundry, SAP HANA Cloud, XSUAA, and a Bookshop Fiori UI served through an App Router and SAP BTP Portal. Terraform owns the landscape; `cds up` owns the application and its bound services. Once a global account is available, the setup below needs no BTP cockpit interaction. SSO and application login still use your browser. +The CRM team maintains several CAP applications, such as Contacts, Sales Orders, and Bookshop. They share a team landscape with separate Sandbox, Staging, and Production subaccounts. This guide deploys Bookshop as the worked example using Node.js, Cloud Foundry, SAP HANA Cloud, IAS authentication, AMS authorization, and a Fiori UI served through an App Router and SAP BTP Portal. Terraform owns the landscape; `cds up` owns the application and its bound services. Once a global account is available, the setup below needs no BTP cockpit interaction. SSO and application login still use your browser. -Bootstrap the landscape once per team. If it already exists, obtain its Terraform outputs from the owner, complete local setup and login, then skip to application deployment. Use a unique application name for your daily work in a shared Sandbox. +Bootstrap the landscape once per team. If it already exists, obtain its Terraform outputs from the owner, complete local setup and login, then skip to application deployment. Each application has its own repository, MTA ID, IAS application, AMS policies, and release pipeline. Use a unique application name for each app in a shared stage; another app does not require another Terraform state or another set of subaccounts. + +| CRM application | Responsibility | Repository / MTA ID | +| --- | --- | --- | +| Contacts | Customer and contact records | `crm-contacts` | +| Sales Orders | Order processing | `crm-orders` | +| Bookshop | Worked example for this onboarding | `bookshop` | + +The CRM platform repository owns Terraform for all three stages. The application repositories own their CDS models, UI, MTA descriptors, service instances, and pipelines. All three apps can run in the same stage space; each app deploys its own services and HDI container. A global account and its commercial entitlements must already exist. Request them from your BTP administrator or [SAP for Me](https://me.sap.com). Your provisioning user needs **Global Account Administrator** permissions to create subaccounts and assign entitlements. Include that user's email among the team administrators below. +An IAS tenant available to that provisioning user must also exist. The CRM team needs IAS identities for app login and policy-administration rights to assign AMS permissions after deployment. List available tenants from the CLI below and obtain application-policy access from your identity administrator. + The three stages have separate subaccounts, CF orgs, spaces, and databases. **Sandbox** is for experiments, **Staging** for integration checks, and **Production** for releases. The production classification alone does not configure database high availability, backups, or application scaling; configure those for your workload before serving customers. ## 1. Set Up Your Mac @@ -68,9 +78,10 @@ btp login --sso --subdomain btp --info btp --format json list accounts/subaccount btp --format json list accounts/entitlement +btp --format json list security/available-idp cf login --sso -a https://api.cf.eu12-001.hana.ondemand.com -mkdir launchpad -cd launchpad +mkdir crm +cd crm cds add terraform ~~~ @@ -82,34 +93,35 @@ Replace angle-bracket placeholders before running commands. Region and CF founda | Region | For example `eu12`; must match the CF API | | `idp_origin_key` | Empty for SAP's default IdP; otherwise the BTP administrative origin supplied by your administrator | | Email(s) | Comma-separated users receiving subaccount administrator and CF deployment access; put the logged-in CF provisioning user first | +| IAS tenant hostname | An available tenant hostname from `btp list security/available-idp`, without `https://` or a trailing slash | Authentication uses CLI sessions; the email prompt controls roles. The first email is recorded as `cf_user`, the org creator whose organization membership CF creates automatically. Keep that value unchanged when another administrator later applies the configuration. The command creates `terraform/main.tf`, `provider.tf`, `variables.tf`, `outputs.tf`, local `terraform.tfvars`, and a `.gitignore`. An older preview may have generated its configuration in `.terraform/`: continue using that directory and its state instead of generating another landscape. Repeating the command preserves existing configuration. `--force` regenerates templates while preserving local variables; review changes before planning against a provisioned landscape. ### Choose Names and Identity Settings -Use a short, unique landscape name. Here `launchpad/` contains Terraform and a nested Bookshop app. Edit `terraform/terraform.tfvars` before the first apply to fit your team's naming: +Use a short, unique landscape name. Here `crm/` contains Terraform and a nested Bookshop app. Edit `terraform/terraform.tfvars` before the first apply to fit your team's naming: ~~~hcl -landscape = "cap-launchpad" -landscape_name = "CAP Launchpad" -sandbox_subdomain = "cap-launchpad-sandbox" -staging_subdomain = "cap-launchpad-staging" -production_subdomain = "cap-launchpad-production" +landscape = "crm" +landscape_name = "CRM" +sandbox_subdomain = "crm-sandbox" +staging_subdomain = "crm-staging" +production_subdomain = "crm-production" ~~~ `landscape` controls CF org and HANA names; `landscape_name` controls subaccount display names. Subdomains are globally unique. Check the existing inventory and reserve names with your team. Terraform creates new accounts; do not import an existing team account into this landscape. | Stage | Subaccount | CF org | Space | | --- | --- | --- | --- | -| Sandbox | CAP Launchpad Sandbox | `cap-launchpad-sandbox` | `sandbox` | -| Staging | CAP Launchpad Staging | `cap-launchpad-staging` | `staging` | -| Production | CAP Launchpad Production | `cap-launchpad-production` | `production` | +| Sandbox | CRM Sandbox | `crm-sandbox` | `sandbox` | +| Staging | CRM Staging | `crm-staging` | `staging` | +| Production | CRM Production | `crm-production` | `production` | Terraform reuses the BTP CLI session with `USE_BTPCLI_SESSION=true` and reads the CF CLI login through its empty CF provider block. Log in to both CLIs before provisioning. Stale `CF_*` credential environment variables can override CF's CLI fallback; clear them or verify their target and user. The default `cli_server_url` is `https://cli.btp.cloud.sap`. If `btp --info` shows another endpoint, put that exact URL in `terraform.tfvars`. For a custom CLI config location, export `BTPCLI_CONFIG_PATH` with the file path used by `btp --config`. -CF role assignments default to origin `sap.ids`. For a custom CF identity provider, set `cf_origin` to its UAA origin. This is independent of `idp_origin_key` for BTP administrative roles. Optional application IAS trust uses `ias_tenant`, an IAS tenant hostname such as `mytenant.accounts.ondemand.com`. An origin key such as `sap.custom` is not a hostname. Trust is established per new subaccount; global-account application trust is not inherited automatically. +CF role assignments default to origin `sap.ids`. For a custom CF identity provider, set `cf_origin` to its UAA origin. This is independent of `idp_origin_key` for BTP administrative roles. The separate `ias_tenant` setting selects the IAS tenant for application login. Terraform establishes its application trust in each new subaccount; global-account platform trust does not provide this application trust. The tenant must be available to your provisioning user. An origin key such as `sap.custom` is not a tenant hostname. ### Check Capacity @@ -118,14 +130,14 @@ Verify that the global account can assign the following **to each of the three s | Service | Plan | Purpose / capacity per stage | | --- | --- | --- | | `APPLICATION_RUNTIME` | `MEMORY` | 4 GB CF app memory; configurable with `cf_memory_gb` | -| `xsuaa` | `application` | App authentication | +| `identity` | `application` | IAS app authentication and AMS authorization | | `destination` | `lite` | Destinations | | `hana-cloud` | `hana` | One HANA Cloud database, default 30 GB memory | | `hana` | `hdi-shared` | App's HDI container | | `html5-apps-repo` | `app-host`, `app-runtime` | Fiori UI storage and serving | | `portal` | `standard` | Bookshop launchpad | -The baseline needs 12 GB unassigned CF memory and capacity for three HANA databases. Entitlements authorize consumption; service use can incur charges. Terraform does not reclaim quotas from existing accounts. Obtain additional capacity before applying if necessary. +The initial Bookshop deployment needs 12 GB unassigned CF memory and capacity for three HANA databases. Additional CRM applications consume more CF memory and may need `cf_memory_gb` increased after a reviewed capacity change. Each app gets its own HDI container; apps in a stage can use the HANA database in that stage. Entitlements authorize consumption; service use can incur charges. Terraform does not reclaim quotas from existing accounts. Obtain additional capacity before applying if necessary. ## 3. Provision and Verify @@ -151,6 +163,8 @@ Use a password satisfying [SAP HANA Cloud password requirements](https://help.sa Each stage receives entitlements, CF runtime capacity, an org and space, administrator and Space Developer roles, and a HANA Cloud instance in that space. Space-local database provisioning supplies the app's HDI database without a cockpit mapping step. Provisioning can take 20–30 minutes. Leave the operation running until it finishes. The subsequent plan should report no changes. +Terraform also establishes IAS application trust for each stage. The app deployment creates an IAS application and deploys AMS policies for that app; these are separate from the BTP and CF infrastructure roles. + Normal Terraform output hides sensitive values, but state and saved plans can contain passwords. Restrict access and use an encrypted, access-controlled remote state backend before sharing the landscape. Keep **one state per landscape**, backed up; independent states for the same accounts can cause duplicate provisioning. ### Recover a Failed Apply @@ -160,6 +174,7 @@ Keep the same directory and state. Fix the reported cause, run `terraform plan - | Error | Action | | --- | --- | | BTP HTTP 401 | Re-run BTP SSO and match `cli_server_url` to `btp --info` | +| BTP HTTP 5xx during entitlement assignment | Preserve state, verify the account and assigned quotas with the CLI, and retry a reviewed plan; report persistent server errors to BTP support | | Missing CF credentials | Log in to the region's CF API; clear stale credential overrides | | HTTP 403 | Check provisioning permissions and that its email is in the admin lists | | Insufficient entitlement | Obtain capacity; preserve existing assignments | @@ -169,22 +184,37 @@ Keep the same directory and state. Fix the reported cause, run `terraform plan - ## 4. Create and Deploy Bookshop -From `launchpad/`: +From `crm/`: ~~~sh cds init bookshop --nodejs --add sample cd bookshop -cds add hana,xsuaa,mta,portal +cds add hana,ias,ams,mta,portal npm install ~~~ These facets follow [Prepare for Production](to-cf#prepare-for-production), including the [Portal UI option](to-cf#add-ui). Portal adds App Router and HTML5 repository support. Refer to [Build and Deploy](to-cf#build-and-deploy) for the deployment procedure, build customization, and troubleshooting. +Give each CRM app a distinct route prefix. In `mta.yaml`, add `host` to the existing parameters of the `bookshop` App Router module: + +~~~yaml +modules: + - name: bookshop + parameters: + host: crm-${space} +~~~ + +For Contacts use `crm-contacts-${space}`; for Sales Orders use `crm-orders-${space}`. `${space}` is resolved from the targeted CF stage. Keep the other generated module parameters and bindings. + +In the existing `bookshop-ias` resource, set `parameters.config.display-name` to `CRM Bookshop (${space})`. This makes the three IAS applications easy to distinguish when assigning AMS policies. Give the other apps their own corresponding display names. + +For the other CRM apps, use their repository names when running `cds init`, for example `cds init crm-contacts --nodejs` or `cds init crm-orders --nodejs`. Develop their models and UI following [Domain Modeling](../../guides/domain-modeling), then add the same production facets. Their unique package names become distinct MTA IDs, so deploying one app does not replace another. + Use the org and space names from `terraform output`. This first run tests the same app in all three new stages: ~~~sh for stage in sandbox staging production; do - cf target -o "cap-launchpad-$stage" -s "$stage" + cf target -o "crm-$stage" -s "$stage" cf target cds up cf apps @@ -193,27 +223,19 @@ for stage in sandbox staging production; do done ~~~ -Change `cap-launchpad` if you chose another prefix. Verify the target before every deployment. For daily work, deploy manually to Sandbox and use a release process for Staging and Production. +Change `crm` if you chose another prefix. Verify the target before every deployment. For daily work, deploy manually to Sandbox and use a release process for Staging and Production. ### Assign App Roles and Test -Infrastructure roles do not grant Bookshop's `admin` role. After deployment, assign the generated role collection for each stage using its output ID, org, space, and your login email: - -~~~sh -btp assign security/role-collection \ - "admin (bookshop -)" \ - --to-user --subaccount -~~~ +Infrastructure roles do not grant Bookshop application permissions. `cds add ams` generates and deploys authorization policies alongside the app. Assign the generated `cap.admin` policy to your IAS user for the IAS application in each stage, following [AMS policy assignment](../security/cap-users#ams-deployment). This uses the IAS tenant Administrative Console and requires policy-administration rights. Reuse existing CRM team identities across applications. -For a custom application IdP, also pass `--of-idp `. App roles belong to the application deployment, not the Terraform infrastructure. +For **each stage**, open the `bookshop` App Router route shown by `cf apps`. Sign in, open **Browse Books**, and verify seeded books and prices. Open **Manage Books** after assigning the policy. In Sandbox, record a book's stock, change it by one, save, and reload to confirm persistence; then restore the original value and reload again. The development index and Fiori preview are disabled in production; use the deployed Portal UI. -For **each stage**, open the `bookshop` App Router route shown by `cf apps`. Sign in, open **Browse Books**, and verify seeded books and prices. Open **Manage Books** after granting the role. Test a write in Sandbox and confirm persistence after reloading. The development index and Fiori preview are disabled in production; use the deployed Portal UI. - -All long-running apps must have their requested instances running. `cf services` must show successful creation of HANA, HDI, XSUAA, HTML5, and Portal services. On failure, inspect `cf mta-ops` and `cf logs bookshop-srv --recent`, then use [CF troubleshooting](../../get-started/get-help#mta). A successful deployment operation alone does not prove the UI works. +All long-running apps must have their requested instances running. `cf services` must show successful creation of HANA, HDI, IAS, HTML5, and Portal services. On failure, inspect `cf mta-ops` and `cf logs bookshop-srv --recent`, then use [CF troubleshooting](../../get-started/get-help#mta). A successful deployment operation alone does not prove the UI works. ## 5. Set Up CI/CD and Team Ownership -Set the app repository's Git remote before `cds add github-actions`, so release workflows use the correct repository. Follow [Deploy using CI/CD Pipelines](cicd#github-actions). +For each CRM app, set its own repository's Git remote before `cds add github-actions`, so release workflows use the correct repository. Follow [Deploy using CI/CD Pipelines](cicd#github-actions). Configure GitHub environments **Staging** and **Production** with `CF_API`, `CF_ORG`, `CF_SPACE`, `CF_USERNAME`, and secret `CF_PASSWORD` for their respective Terraform outputs. Use a technical deployment user with supported noninteractive login and CF deployment rights scoped to these new targets. Local CLI SSO sessions are not CI credentials. Grant CF-only deployment rights without making the technical user a BTP administrator: @@ -226,4 +248,6 @@ For a custom CF IdP, append `--origin ` to both commands. If this use The generated workflows deploy `main` pushes to Staging and published releases to Production. Configure Production's required reviewers and branch rules before releasing. Infrastructure provisioning remains separate from app CI/CD. +Keep Contacts, Sales Orders, and Bookshop in separate repositories with distinct MTA IDs and app-specific routes. Their pipelines target the same team stage orgs and spaces, while keeping service instances and credentials app-specific. + Commit app source, `mta.yaml`, lockfiles, and workflows. Commit Terraform configuration and `.terraform.lock.hcl`; keep state, local `*.tfvars`, and saved plans in protected storage. Record who owns provisioning and state access so the next developer can reuse the landscape. From a640067239415e827a5af28bab5f5476f8e6bfc7 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Tue, 27 Oct 2026 19:32:51 +0100 Subject: [PATCH 20/41] Fix onboarding Domain Modeling guide link --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 171bc7aa07..6b26c354f2 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -208,7 +208,7 @@ For Contacts use `crm-contacts-${space}`; for Sales Orders use `crm-orders-${spa In the existing `bookshop-ias` resource, set `parameters.config.display-name` to `CRM Bookshop (${space})`. This makes the three IAS applications easy to distinguish when assigning AMS policies. Give the other apps their own corresponding display names. -For the other CRM apps, use their repository names when running `cds init`, for example `cds init crm-contacts --nodejs` or `cds init crm-orders --nodejs`. Develop their models and UI following [Domain Modeling](../../guides/domain-modeling), then add the same production facets. Their unique package names become distinct MTA IDs, so deploying one app does not replace another. +For the other CRM apps, use their repository names when running `cds init`, for example `cds init crm-contacts --nodejs` or `cds init crm-orders --nodejs`. Develop their models and UI following [Domain Modeling](../domain/), then add the same production facets. Their unique package names become distinct MTA IDs, so deploying one app does not replace another. Use the org and space names from `terraform output`. This first run tests the same app in all three new stages: From 8d404fb7dd1ec772c886c776f64f86b9a3e25b1d Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 01:17:24 +0100 Subject: [PATCH 21/41] Choose CF or Kyma before provisioning the team landscape --- guides/deploy/team-onboarding.md | 112 ++++++++++++++++++++++++------- 1 file changed, 86 insertions(+), 26 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 13fa6f2f08..b5338d6d14 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -22,21 +22,35 @@ Assume your team is developing a complex CRM solution with multiple apps and ser Each app has its own repository and release pipeline. We'll set up the shared landscape with Terraform so you can deploy your apps with a simple `cds up`. -## 1. Install Deployment Tools +## 1. Choose Your Deployment Runtime -We assume you've installed the basic tooling from [Getting Started](../../get-started/#initial-setup). Add the deployment tools below: +Choose the runtime that fits your team before provisioning the landscape: + +### Cloud Foundry + +Cloud Foundry is an opinionated runtime where the platform manages buildpacks, routing, and bound services. It fits teams that want to focus on application code. + +[Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} + +### Kyma/K8s + +Kyma/K8s is a managed Kubernetes runtime where you own the container images, manifests, and networking. Choose it when you need more control or already work with Kubernetes. + +[Learn more in Deploy to Kyma/K8s.](to-kyma){.learn-more} + +## 2. Install Deployment Tools + +We assume you've installed the basic tooling from [Getting Started](../../get-started/#initial-setup). Install Terraform and the BTP CLI, then the tools for your chosen runtime: ::: code-group ~~~sh [macOS] brew tap hashicorp/tap brew install hashicorp/tap/terraform brew install --cask btp -brew install cloudfoundry/tap/cf-cli@8 ~~~ ~~~sh [Linux] brew tap hashicorp/tap brew install hashicorp/tap/terraform -brew install cloudfoundry/tap/cf-cli@8 btp_arch=$(uname -m) btp_arch=${btp_arch/x86_64/amd64} btp_arch=${btp_arch/aarch64/arm64} @@ -47,13 +61,23 @@ sudo install -m 755 "linux-$btp_arch/btp" /usr/local/bin/btp ~~~powershell [Windows] winget install --silent Hashicorp.Terraform winget install --silent SAP.btp -winget install --silent CloudFoundry.CLI.v8 -winget install --silent ezwinports.make ~~~ ::: > On Windows, open a new terminal after installation. For WSL, follow the Linux steps. +::: details Cloud Foundry tools + +::: code-group +~~~sh [macOS/Linux] +brew install cloudfoundry/tap/cf-cli@8 +~~~ +~~~powershell [Windows] +winget install --silent CloudFoundry.CLI.v8 +winget install --silent ezwinports.make +~~~ +::: + In your terminal: ~~~sh @@ -62,25 +86,56 @@ cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org cf install-plugin -f multiapps cf install-plugin -f html5-plugin ~~~ +::: + +::: details Kyma/K8s tools + +::: code-group +~~~sh [macOS/Linux] +brew install kubernetes-cli helm buildpacks/tap/pack +brew install int128/kubelogin/kubelogin +~~~ +~~~powershell [Windows] +winget install --silent Kubernetes.kubectl +winget install --silent Helm.Helm +winget install --silent int128.kubelogin +Invoke-WebRequest https://github.com/buildpacks/pack/releases/download/v0.40.10/pack-v0.40.10-windows.zip -OutFile pack.zip +Expand-Archive pack.zip -DestinationPath "$env:LOCALAPPDATA\Microsoft\WinGet\Links" -Force +~~~ +::: + +For app deployment, you also need [Docker](https://docs.docker.com/get-docker/) and a [container registry](to-kyma#get-access-to-a-container-registry). +::: -## 2. Prepare Your Global Account +## 3. Prepare Your Global Account [Request a global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account) and an IAS tenant from your BTP admin. You need **Global Account Administrator** access and permission to assign IAS authorization policies. Note your global-account subdomain and IAS hostname. This example uses `eu10`. -## 3. Provision the Team Landscape +## 4. Provision the Team Landscape -Log in with the same user in both CLIs: +Log in and create a directory for your team: ~~~sh btp login --sso -cf login --sso -a https://api.cf.eu10.hana.ondemand.com mkdir crm cd crm -cds add terraform ~~~ +Choose the matching variant: + +::: code-group +~~~sh [Cloud Foundry] +cf login --sso -a https://api.cf.eu10.hana.ondemand.com +cds add terraform --cf +~~~ +~~~sh [Kyma/K8s] +cds add terraform --k8s +~~~ +::: + + You will be prompted for some inputs: | Prompt | Enter | @@ -93,7 +148,7 @@ You will be prompted for some inputs: The command creates the Terraform configuration in `crm/` for these stages: -| Subaccount | CF org | Space | +| Subaccount | CF org / Kyma cluster | Space / Namespace | | --- | --- | --- | | CRM Sandbox | `crm-sandbox` | `team` | | CRM Staging | `crm-staging` | `ci` | @@ -120,29 +175,34 @@ terraform plan terraform apply ~~~ -Terraform creates the subaccounts, entitlements, CF orgs and spaces, admin access, IAS trust, and a HANA database per stage. +Terraform creates the subaccounts, runtime, admin access, IAS trust, and a HANA database per stage. For Kyma, it also prepares the namespaces, service operator, and HANA mappings. -::: tip Allow time for HANA -Provisioning takes about 20–30 minutes. +::: tip Allow time for provisioning +HANA takes about 20–30 minutes. Kyma clusters can take longer. Complete browser sign-in when prompted. ::: -## 4. Choose Your Deployment Runtime +## 5. Deploy to Sandbox -Start in Sandbox and follow the guide for the runtime that fits your team: - -### Cloud Foundry +Select Sandbox, then follow the deployment guide for your runtime: -Cloud Foundry is an opinionated runtime where the platform manages buildpacks, routing, and bound services. It fits teams that want to focus on application code. +::: code-group +~~~sh [Cloud Foundry] +cf target -o crm-sandbox -s team +~~~ +~~~sh [Kyma macOS/Linux] +export KUBECONFIG="$PWD/crm-sandbox.kubeconfig" +kubectl config set-context --current --namespace=team +~~~ +~~~powershell [Kyma Windows] +$env:KUBECONFIG = "$PWD/crm-sandbox.kubeconfig" +kubectl config set-context --current --namespace=team +~~~ +::: [Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} - -### Kyma/K8s - -Kyma/K8s is a managed Kubernetes runtime where you own the container images, manifests, and networking. Choose it when you need more control or already work with Kubernetes. - [Learn more in Deploy to Kyma/K8s.](to-kyma){.learn-more} -## 5. Set Up CI/CD +## 6. Set Up CI/CD Once your app runs in Sandbox, set up CI/CD to roll out changes to Staging and Production. From b501b770a9b910249fdb023294b3620943a83f46 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 10:26:43 +0100 Subject: [PATCH 22/41] Fix onboarding layout and shorten guide headings --- guides/deploy/_menu.md | 2 +- guides/deploy/team-onboarding.md | 34 +++++++++++++++++--------------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index 703ab900dc..5ca8e02c4e 100644 --- a/guides/deploy/_menu.md +++ b/guides/deploy/_menu.md @@ -1,7 +1,7 @@ # [Team Onboarding](team-onboarding) # [Deploy to Cloud Foundry](to-cf) -# [Deploy to Kyma/K8s](to-kyma) +# [Deploy to Kyma](to-kyma) # [Deploy with CI/CD](cicd) # [Deploy with Confidence](../../../guides/deploy/dwc) # [Microservice Architectures](microservices) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index b5338d6d14..e186b26275 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -14,7 +14,8 @@ status: released Assume your team is developing a complex CRM solution with multiple apps and services. -::: tip Three stages +::: tip A subaccount for each stage + - **Sandbox** for development and experiments. - **Staging** for integration checks. - **Production** for releases to users. @@ -22,7 +23,7 @@ Assume your team is developing a complex CRM solution with multiple apps and ser Each app has its own repository and release pipeline. We'll set up the shared landscape with Terraform so you can deploy your apps with a simple `cds up`. -## 1. Choose Your Deployment Runtime +## 1. Choose Runtime Choose the runtime that fits your team before provisioning the landscape: @@ -32,13 +33,13 @@ Cloud Foundry is an opinionated runtime where the platform manages buildpacks, r [Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} -### Kyma/K8s +### Kyma -Kyma/K8s is a managed Kubernetes runtime where you own the container images, manifests, and networking. Choose it when you need more control or already work with Kubernetes. +Kyma is a managed Kubernetes runtime where you own the container images, manifests, and networking. Choose it when you need more control or already work with Kubernetes. -[Learn more in Deploy to Kyma/K8s.](to-kyma){.learn-more} +[Learn more in Deploy to Kyma.](to-kyma){.learn-more} -## 2. Install Deployment Tools +## 2. Install Tools We assume you've installed the basic tooling from [Getting Started](../../get-started/#initial-setup). Install Terraform and the BTP CLI, then the tools for your chosen runtime: @@ -66,7 +67,7 @@ winget install --silent SAP.btp > On Windows, open a new terminal after installation. For WSL, follow the Linux steps. -::: details Cloud Foundry tools +### Cloud Foundry Tools ::: code-group ~~~sh [macOS/Linux] @@ -86,9 +87,8 @@ cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org cf install-plugin -f multiapps cf install-plugin -f html5-plugin ~~~ -::: -::: details Kyma/K8s tools +### Kyma Tools ::: code-group ~~~sh [macOS/Linux] @@ -105,15 +105,14 @@ Expand-Archive pack.zip -DestinationPath "$env:LOCALAPPDATA\Microsoft\WinGet\Lin ::: For app deployment, you also need [Docker](https://docs.docker.com/get-docker/) and a [container registry](to-kyma#get-access-to-a-container-registry). -::: -## 3. Prepare Your Global Account +## 3. Global Account [Request a global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account) and an IAS tenant from your BTP admin. You need **Global Account Administrator** access and permission to assign IAS authorization policies. Note your global-account subdomain and IAS hostname. This example uses `eu10`. -## 4. Provision the Team Landscape +## 4. Provision Landscape Log in and create a directory for your team: @@ -130,12 +129,11 @@ Choose the matching variant: cf login --sso -a https://api.cf.eu10.hana.ondemand.com cds add terraform --cf ~~~ -~~~sh [Kyma/K8s] +~~~sh [Kyma] cds add terraform --k8s ~~~ ::: - You will be prompted for some inputs: | Prompt | Enter | @@ -146,6 +144,8 @@ You will be prompted for some inputs: | Email(s) | Team admin emails, with your login email first | | IAS tenant hostname | Your team's IAS hostname for application trust, without `https://` | +
+ The command creates the Terraform configuration in `crm/` for these stages: | Subaccount | CF org / Kyma cluster | Space / Namespace | @@ -183,7 +183,7 @@ HANA takes about 20–30 minutes. Kyma clusters can take longer. Complete browse ## 5. Deploy to Sandbox -Select Sandbox, then follow the deployment guide for your runtime: +Select Sandbox from `crm/` to deploy your first app: ::: code-group ~~~sh [Cloud Foundry] @@ -199,8 +199,10 @@ kubectl config set-context --current --namespace=team ~~~ ::: +Keep the app in its own repository, adding HANA, IAS, and an App Router with `cds add`. The runtime guides show how to prepare the deployment configuration and deploy with `cds up`. + [Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} -[Learn more in Deploy to Kyma/K8s.](to-kyma){.learn-more} +[Learn more in Deploy to Kyma.](to-kyma){.learn-more} ## 6. Set Up CI/CD From 1dbd324348ce9931b542c4cbb5490f7b2b913697 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 10:28:32 +0100 Subject: [PATCH 23/41] Emphasize the Sandbox deployment guide links --- guides/deploy/team-onboarding.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index e186b26275..0f541bf321 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -199,10 +199,8 @@ kubectl config set-context --current --namespace=team ~~~ ::: -Keep the app in its own repository, adding HANA, IAS, and an App Router with `cds add`. The runtime guides show how to prepare the deployment configuration and deploy with `cds up`. - -[Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} -[Learn more in Deploy to Kyma.](to-kyma){.learn-more} +- [**Deploy to Cloud Foundry**](to-cf) +- [**Deploy to Kyma**](to-kyma) ## 6. Set Up CI/CD From 697fe80d5c25429e10b3505c263ec7d6431147ad Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 10:41:25 +0100 Subject: [PATCH 24/41] Clarify operator setup and link to deployment guides --- guides/deploy/team-onboarding.md | 27 +++------------------------ 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 0f541bf321..8d4ccbe5d5 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -14,14 +14,14 @@ status: released Assume your team is developing a complex CRM solution with multiple apps and services. -::: tip A subaccount for each stage +::: info A subaccount for each stage - **Sandbox** for development and experiments. - **Staging** for integration checks. - **Production** for releases to users. ::: -Each app has its own repository and release pipeline. We'll set up the shared landscape with Terraform so you can deploy your apps with a simple `cds up`. +Each app has its own repository and release pipeline. Typically, one operator sets up the shared landscape with Terraform so the whole team can deploy apps with `cds up` without repeating the setup. ## 1. Choose Runtime @@ -31,14 +31,10 @@ Choose the runtime that fits your team before provisioning the landscape: Cloud Foundry is an opinionated runtime where the platform manages buildpacks, routing, and bound services. It fits teams that want to focus on application code. -[Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} - ### Kyma Kyma is a managed Kubernetes runtime where you own the container images, manifests, and networking. Choose it when you need more control or already work with Kubernetes. -[Learn more in Deploy to Kyma.](to-kyma){.learn-more} - ## 2. Install Tools We assume you've installed the basic tooling from [Getting Started](../../get-started/#initial-setup). Install Terraform and the BTP CLI, then the tools for your chosen runtime: @@ -183,24 +179,7 @@ HANA takes about 20–30 minutes. Kyma clusters can take longer. Complete browse ## 5. Deploy to Sandbox -Select Sandbox from `crm/` to deploy your first app: - -::: code-group -~~~sh [Cloud Foundry] -cf target -o crm-sandbox -s team -~~~ -~~~sh [Kyma macOS/Linux] -export KUBECONFIG="$PWD/crm-sandbox.kubeconfig" -kubectl config set-context --current --namespace=team -~~~ -~~~powershell [Kyma Windows] -$env:KUBECONFIG = "$PWD/crm-sandbox.kubeconfig" -kubectl config set-context --current --namespace=team -~~~ -::: - -- [**Deploy to Cloud Foundry**](to-cf) -- [**Deploy to Kyma**](to-kyma) +Follow [Deploy to Cloud Foundry](to-cf) or [Deploy to Kyma](to-kyma) to prepare your app for production and deploy it to Sandbox with `cds up`. ## 6. Set Up CI/CD From adab11fe8dfab2f7f5c7ddcc48c1c26f72a2c85d Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 10:55:39 +0100 Subject: [PATCH 25/41] Link IAS tenant requests and highlight shared setup --- guides/deploy/team-onboarding.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 8d4ccbe5d5..19c754d6ac 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -21,7 +21,12 @@ Assume your team is developing a complex CRM solution with multiple apps and ser - **Production** for releases to users. ::: -Each app has its own repository and release pipeline. Typically, one operator sets up the shared landscape with Terraform so the whole team can deploy apps with `cds up` without repeating the setup. +Each app has its own repository and release pipeline. + +::: tip Shared Setup + +Typically, one operator sets up the shared landscape with Terraform so the whole team can deploy apps with `cds up` without repeating the setup. +::: ## 1. Choose Runtime @@ -104,7 +109,9 @@ For app deployment, you also need [Docker](https://docs.docker.com/get-docker/) ## 3. Global Account -[Request a global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account) and an IAS tenant from your BTP admin. You need **Global Account Administrator** access and permission to assign IAS authorization policies. +[Request a global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account) and [an IAS tenant](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/get-your-tenant) from your BTP admin. You need **Global Account Administrator** access and permission to assign IAS authorization policies. + + Note your global-account subdomain and IAS hostname. This example uses `eu10`. From 1073ed16d4f61edb5aec9b6cf96a54307c788c5e Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:05:02 +0100 Subject: [PATCH 26/41] Remove region example from the account note --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 19c754d6ac..cfe5618598 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -113,7 +113,7 @@ For app deployment, you also need [Docker](https://docs.docker.com/get-docker/) -Note your global-account subdomain and IAS hostname. This example uses `eu10`. +Note your global-account subdomain and IAS hostname. ## 4. Provision Landscape From ac1e69d8972def365f24649eabdd49d9adf199d9 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:26:16 +0100 Subject: [PATCH 27/41] Polish team onboarding structure and wording --- guides/deploy/team-onboarding.md | 47 +++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index cfe5618598..da376e9020 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -25,10 +25,10 @@ Each app has its own repository and release pipeline. ::: tip Shared Setup -Typically, one operator sets up the shared landscape with Terraform so the whole team can deploy apps with `cds up` without repeating the setup. +Typically, one operator sets up the shared landscape so the whole team can deploy apps with `cds up` without repeating the setup. ::: -## 1. Choose Runtime +## 1. Choose a Runtime Choose the runtime that fits your team before provisioning the landscape: @@ -40,7 +40,7 @@ Cloud Foundry is an opinionated runtime where the platform manages buildpacks, r Kyma is a managed Kubernetes runtime where you own the container images, manifests, and networking. Choose it when you need more control or already work with Kubernetes. -## 2. Install Tools +## 2. Install the Tools We assume you've installed the basic tooling from [Getting Started](../../get-started/#initial-setup). Install Terraform and the BTP CLI, then the tools for your chosen runtime: @@ -63,11 +63,12 @@ sudo install -m 755 "linux-$btp_arch/btp" /usr/local/bin/btp ~~~powershell [Windows] winget install --silent Hashicorp.Terraform winget install --silent SAP.btp + +# Open a new terminal after installation. +# For WSL, follow the Linux steps. ~~~ ::: -> On Windows, open a new terminal after installation. For WSL, follow the Linux steps. - ### Cloud Foundry Tools ::: code-group @@ -107,17 +108,17 @@ Expand-Archive pack.zip -DestinationPath "$env:LOCALAPPDATA\Microsoft\WinGet\Lin For app deployment, you also need [Docker](https://docs.docker.com/get-docker/) and a [container registry](to-kyma#get-access-to-a-container-registry). -## 3. Global Account +## 3. Get a Global Account [Request a global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account) and [an IAS tenant](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/get-your-tenant) from your BTP admin. You need **Global Account Administrator** access and permission to assign IAS authorization policies. -Note your global-account subdomain and IAS hostname. +Note your global account subdomain and IAS hostname. -## 4. Provision Landscape +## 4. Provision the Landscape -Log in and create a directory for your team: +Log in to BTP and create a directory for your team: ~~~sh btp login --sso @@ -141,7 +142,7 @@ You will be prompted for some inputs: | Prompt | Enter | | --- | --- | -| Global account subdomain | Your global-account subdomain | +| Global account subdomain | Your global account subdomain | | Region | Your region, for example `eu10` | | `idp_origin_key` | Leave empty for SAP's default identity provider; otherwise use your administrative identity provider's origin key | | Email(s) | Team admin emails, with your login email first | @@ -170,7 +171,7 @@ $env:USE_BTPCLI_SESSION = 'true' ~~~ ::: -Terraform prompts for the HANA SYSTEM password: +Initialize the configuration, review the plan, then apply it: ~~~sh terraform init @@ -178,22 +179,36 @@ terraform plan terraform apply ~~~ -Terraform creates the subaccounts, runtime, admin access, IAS trust, and a HANA database per stage. For Kyma, it also prepares the namespaces, service operator, and HANA mappings. +> You'll be prompted for the HANA SYSTEM password. + +Applying the configuration creates the subaccounts, runtime, admin access, IAS trust, and a HANA database per stage. For Kyma, it also prepares the namespaces, service operator, and HANA mappings. ::: tip Allow time for provisioning -HANA takes about 20–30 minutes. Kyma clusters can take longer. Complete browser sign-in when prompted. +Provisioning HANA usually takes around 20–30 minutes, and you may be asked to sign in through your browser. ::: ## 5. Deploy to Sandbox -Follow [Deploy to Cloud Foundry](to-cf) or [Deploy to Kyma](to-kyma) to prepare your app for production and deploy it to Sandbox with `cds up`. +Deploy your first app to *Sandbox* using the guide for your runtime: + +### Cloud Foundry + +Prepare and deploy your app with `cds up`. + +[Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} + +### Kyma + +Build container images and deploy your app using CAP's Helm charts. + +[Learn more in Deploy to Kyma.](to-kyma){.learn-more} ## 6. Set Up CI/CD -Once your app runs in Sandbox, set up CI/CD to roll out changes to Staging and Production. +Once your app runs in *Sandbox*, set up CI/CD to roll out changes to *Staging* and *Production*. ::: tip Release flow -Pushes to `main` deploy to Staging. Published GitHub releases deploy to Production. +Pushes to `main` deploy to *Staging*. Published GitHub releases deploy to *Production*. ::: [Learn more in Deploy with CI/CD.](cicd){.learn-more} From 350fb7e2e439060e4e3d77d88d8650862ae14447 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:27:30 +0100 Subject: [PATCH 28/41] Connect the CRM example to the shared stages --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index da376e9020..6ed3b1e8a4 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -12,7 +12,7 @@ status: released ## Overview -Assume your team is developing a complex CRM solution with multiple apps and services. +Assume your team is developing a complex CRM solution with multiple apps and services that share three subaccounts, one for each stage: ::: info A subaccount for each stage From c86335e7240f4cbee97fe73e0b9826b1f6c8bb38 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:31:34 +0100 Subject: [PATCH 29/41] Show explicit deployment targets in team onboarding --- guides/deploy/team-onboarding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 6ed3b1e8a4..79ebf0eb17 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -193,13 +193,13 @@ Deploy your first app to *Sandbox* using the guide for your runtime: ### Cloud Foundry -Prepare and deploy your app with `cds up`. +Prepare and deploy your app with `cds up --to cf`. [Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} ### Kyma -Build container images and deploy your app using CAP's Helm charts. +Prepare and deploy your app with `cds up --to k8s`. [Learn more in Deploy to Kyma.](to-kyma){.learn-more} From f2662673b99f40b82fa3d12cb51ebb506eb900d4 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:32:14 +0100 Subject: [PATCH 30/41] Clarify browser sign-in for Kyma cluster access --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 79ebf0eb17..f91c2a2abf 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -184,7 +184,7 @@ terraform apply Applying the configuration creates the subaccounts, runtime, admin access, IAS trust, and a HANA database per stage. For Kyma, it also prepares the namespaces, service operator, and HANA mappings. ::: tip Allow time for provisioning -Provisioning HANA usually takes around 20–30 minutes, and you may be asked to sign in through your browser. +Provisioning HANA usually takes around 20–30 minutes. When setting up Kyma, you may be asked to sign in through your browser for cluster access. ::: ## 5. Deploy to Sandbox From 94cf5c3a62010a2689c194ade37dd5aa2e574baf Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:33:19 +0100 Subject: [PATCH 31/41] Link to BTP regions from onboarding inputs --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index f91c2a2abf..e382af5d12 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -143,7 +143,7 @@ You will be prompted for some inputs: | Prompt | Enter | | --- | --- | | Global account subdomain | Your global account subdomain | -| Region | Your region, for example `eu10` | +| Region | Your region, for example `eu10`. [Learn more about regions.](https://help.sap.com/docs/btp/sap-business-technology-platform/regions){.learn-more} | | `idp_origin_key` | Leave empty for SAP's default identity provider; otherwise use your administrative identity provider's origin key | | Email(s) | Team admin emails, with your login email first | | IAS tenant hostname | Your team's IAS hostname for application trust, without `https://` | From a566fbf58256363533aa30fab48b0b8102eeec10 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:33:51 +0100 Subject: [PATCH 32/41] Clarify optional team admin emails and separators --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index e382af5d12..8ddd123d2c 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -145,7 +145,7 @@ You will be prompted for some inputs: | Global account subdomain | Your global account subdomain | | Region | Your region, for example `eu10`. [Learn more about regions.](https://help.sap.com/docs/btp/sap-business-technology-platform/regions){.learn-more} | | `idp_origin_key` | Leave empty for SAP's default identity provider; otherwise use your administrative identity provider's origin key | -| Email(s) | Team admin emails, with your login email first | +| Email(s) | One or more team admin emails separated by commas, with your login email first | | IAS tenant hostname | Your team's IAS hostname for application trust, without `https://` |
From 349cf507b57febc9c5d20f71f211f03dffad3198 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:39:43 +0100 Subject: [PATCH 33/41] Improve the transition into the team stages --- guides/deploy/team-onboarding.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 8ddd123d2c..0d8d5e4236 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -12,7 +12,8 @@ status: released ## Overview -Assume your team is developing a complex CRM solution with multiple apps and services that share three subaccounts, one for each stage: +Assume your team is developing a complex CRM solution with multiple apps and services. +The team needs a shared landscape that keeps development separate from releases. ::: info A subaccount for each stage From 1c54a818cd1563593d1d690f3dffe42e25147672 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 11:41:53 +0100 Subject: [PATCH 34/41] Refine the BTP regions link text and spacing --- guides/deploy/team-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 0d8d5e4236..244036b9f1 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -144,7 +144,7 @@ You will be prompted for some inputs: | Prompt | Enter | | --- | --- | | Global account subdomain | Your global account subdomain | -| Region | Your region, for example `eu10`. [Learn more about regions.](https://help.sap.com/docs/btp/sap-business-technology-platform/regions){.learn-more} | +| Region | Your region, for example `eu10`. [Learn more about regions in BTP.](https://help.sap.com/docs/btp/sap-business-technology-platform/regions){.learn-more style="margin-top:5px"} | | `idp_origin_key` | Leave empty for SAP's default identity provider; otherwise use your administrative identity provider's origin key | | Email(s) | One or more team admin emails separated by commas, with your login email first | | IAS tenant hostname | Your team's IAS hostname for application trust, without `https://` | From 10edcfccadabcc417519eda27adea58b994ad03d Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 15:28:31 +0100 Subject: [PATCH 35/41] Select the CF deployment org and space explicitly --- guides/deploy/to-cf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/to-cf.md b/guides/deploy/to-cf.md index 9113f0847d..2b0a662ba3 100644 --- a/guides/deploy/to-cf.md +++ b/guides/deploy/to-cf.md @@ -237,7 +237,7 @@ The previous steps are required _only once_ in a project's lifetime. With that d Make sure you are logged in to Cloud Foundry and target the space you want to deploy to: ```sh cf login --sso # to log on with SAP Universal ID -cf target +cf target -o -s ``` [Learn more about `cf login`](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/7a37d66c2e7d401db4980db0cd74aa6b.html){.learn-more} From 6c7af2b4ad375d0a55b4cde60df37070be278e9e Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 15:35:20 +0100 Subject: [PATCH 36/41] Use CRM as the team directory and anchor the SAP workflow note --- guides/deploy/cicd.md | 2 ++ guides/deploy/team-onboarding.md | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/guides/deploy/cicd.md b/guides/deploy/cicd.md index 746d5ac3c4..1a324a9b98 100644 --- a/guides/deploy/cicd.md +++ b/guides/deploy/cicd.md @@ -22,6 +22,8 @@ cds add github-actions ``` > You can also use `cds add gha` as a shortcut. + + ### Deploy to Staging The created workflows do a _Staging_ deployment for pushes on the `main` branch, usually after merging pull requests. diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 244036b9f1..34134583bb 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -123,8 +123,8 @@ Log in to BTP and create a directory for your team: ~~~sh btp login --sso -mkdir crm -cd crm +mkdir CRM +cd CRM ~~~ Choose the matching variant: @@ -151,7 +151,7 @@ You will be prompted for some inputs:
-The command creates the Terraform configuration in `crm/` for these stages: +The command creates the Terraform configuration in `CRM/` for these stages: | Subaccount | CF org / Kyma cluster | Space / Namespace | | --- | --- | --- | From 12ecd51f7018f6bdef72864dc2b31d10d0d9796f Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 15:54:33 +0100 Subject: [PATCH 37/41] Describe Terraform-managed CF CI access --- guides/deploy/team-onboarding.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index 34134583bb..d324f86134 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -148,6 +148,7 @@ You will be prompted for some inputs: | `idp_origin_key` | Leave empty for SAP's default identity provider; otherwise use your administrative identity provider's origin key | | Email(s) | One or more team admin emails separated by commas, with your login email first | | IAS tenant hostname | Your team's IAS hostname for application trust, without `https://` | +| CF CI user | Your workflows' `CF_USERNAME`, or leave empty to set `cf_ci_user` in `terraform.tfvars` later |
@@ -208,6 +209,8 @@ Prepare and deploy your app with `cds up --to k8s`. Once your app runs in *Sandbox*, set up CI/CD to roll out changes to *Staging* and *Production*. +For CF, Terraform grants your CI user deployment access in all three spaces. Set `cf_ci_origin` in `terraform.tfvars` if it uses a different identity provider from the team. + ::: tip Release flow Pushes to `main` deploy to *Staging*. Published GitHub releases deploy to *Production*. ::: From d2816b3ad86582ec0d2a3365610d2dcb0b6263c4 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 15:55:23 +0100 Subject: [PATCH 38/41] Restore Kyma/K8S deployment menu label --- guides/deploy/_menu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index 5ca8e02c4e..08129928db 100644 --- a/guides/deploy/_menu.md +++ b/guides/deploy/_menu.md @@ -1,7 +1,7 @@ # [Team Onboarding](team-onboarding) # [Deploy to Cloud Foundry](to-cf) -# [Deploy to Kyma](to-kyma) +# [Deploy to Kyma/K8S](to-kyma) # [Deploy with CI/CD](cicd) # [Deploy with Confidence](../../../guides/deploy/dwc) # [Microservice Architectures](microservices) From 84d58a57b5c7521e51a0f7c096feb5d8c15af8d6 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 16:01:45 +0100 Subject: [PATCH 39/41] Revert "Describe Terraform-managed CF CI access" This reverts commit 12ecd51f7018f6bdef72864dc2b31d10d0d9796f. --- guides/deploy/team-onboarding.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/guides/deploy/team-onboarding.md b/guides/deploy/team-onboarding.md index d324f86134..34134583bb 100644 --- a/guides/deploy/team-onboarding.md +++ b/guides/deploy/team-onboarding.md @@ -148,7 +148,6 @@ You will be prompted for some inputs: | `idp_origin_key` | Leave empty for SAP's default identity provider; otherwise use your administrative identity provider's origin key | | Email(s) | One or more team admin emails separated by commas, with your login email first | | IAS tenant hostname | Your team's IAS hostname for application trust, without `https://` | -| CF CI user | Your workflows' `CF_USERNAME`, or leave empty to set `cf_ci_user` in `terraform.tfvars` later |
@@ -209,8 +208,6 @@ Prepare and deploy your app with `cds up --to k8s`. Once your app runs in *Sandbox*, set up CI/CD to roll out changes to *Staging* and *Production*. -For CF, Terraform grants your CI user deployment access in all three spaces. Set `cf_ci_origin` in `terraform.tfvars` if it uses a different identity provider from the team. - ::: tip Release flow Pushes to `main` deploy to *Staging*. Published GitHub releases deploy to *Production*. ::: From aa9779816b8ab82155deeb8ce427629e2f5586fd Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 16:02:36 +0100 Subject: [PATCH 40/41] Update _menu.md --- guides/deploy/_menu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index 08129928db..703ab900dc 100644 --- a/guides/deploy/_menu.md +++ b/guides/deploy/_menu.md @@ -1,7 +1,7 @@ # [Team Onboarding](team-onboarding) # [Deploy to Cloud Foundry](to-cf) -# [Deploy to Kyma/K8S](to-kyma) +# [Deploy to Kyma/K8s](to-kyma) # [Deploy with CI/CD](cicd) # [Deploy with Confidence](../../../guides/deploy/dwc) # [Microservice Architectures](microservices) From 565552aea6ddc34dc207ffb82a6d7286ba183dd5 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Wed, 28 Oct 2026 16:37:09 +0100 Subject: [PATCH 41/41] Remove duplicate App Router setup and guide test generation --- guides/deploy/cicd.md | 2 ++ guides/deploy/to-cf.md | 19 +++++-------------- 2 files changed, 7 insertions(+), 14 deletions(-) diff --git a/guides/deploy/cicd.md b/guides/deploy/cicd.md index 1a324a9b98..053cd8a68f 100644 --- a/guides/deploy/cicd.md +++ b/guides/deploy/cicd.md @@ -24,6 +24,8 @@ cds add github-actions +> If your Node.js project has no tests yet, run `cds add test` to generate service tests. + ### Deploy to Staging The created workflows do a _Staging_ deployment for pushes on the `main` branch, usually after merging pull requests. diff --git a/guides/deploy/to-cf.md b/guides/deploy/to-cf.md index 2b0a662ba3..960e04a24b 100644 --- a/guides/deploy/to-cf.md +++ b/guides/deploy/to-cf.md @@ -170,7 +170,7 @@ cds add mta #### Option A: App Router -To serve your UI through an App Router: +Add an App Router to your project: ```sh cds add approuter @@ -181,6 +181,10 @@ The App Router acts as a single point-of-entry gateway to route requests to. In particular, it ensures user login and authentication in combination with XSUAA or IAS. ::: +For the UI from `cds add sample`, the build includes its static files and uses `/fiori-apps.html` as the welcome page. + +[Learn more about the SAP BTP Application Router.](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/01c5f9ba7d6847aaaf069d153b981b51.html?locale=en-US){.learn-more} + #### Option B: SAP BTP Application Frontend For **single-tenant** applications, you can use the new [SAP BTP Application Frontend](https://help.sap.com/docs/application-frontend-service) service: @@ -200,19 +204,6 @@ cds add workzone This approach uses the **managed App Router** provided by SAP Fiori Launchpad — you don't need to deploy your own. Instead, destinations are configured. -
- -You can also customize the App Router setup: - -```sh -cds add approuter -``` -[Learn more about the SAP BTP Application Router.](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/01c5f9ba7d6847aaaf069d153b981b51.html?locale=en-US){.learn-more} -
-However, in this case, you need to create symlinks from your _app_ folders to make them visible to the deployed App Router. -The [samples _modulith_](https://github.com/capire/samples) project uses this setup for serving a static _index.html_ consuming Vue.js via CDN. - -[Find the symlink directory in the App Router's _resources_ folder](https://github.com/capire/samples/tree/main/.deploy/app-router/resources){.learn-more} ::: ### 6. Optional: Multitenancy { #add-multitenancy }