diff --git a/guides/deploy/_menu.md b/guides/deploy/_menu.md index b6d5235f6..703ab900d 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/cicd.md b/guides/deploy/cicd.md index 746d5ac3c..053cd8a68 100644 --- a/guides/deploy/cicd.md +++ b/guides/deploy/cicd.md @@ -22,6 +22,10 @@ cds add github-actions ``` > You can also use `cds add gha` as a shortcut. + + +> 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/team-onboarding.md b/guides/deploy/team-onboarding.md new file mode 100644 index 000000000..34134583b --- /dev/null +++ b/guides/deploy/team-onboarding.md @@ -0,0 +1,215 @@ +--- +description: > + Prepare a team landscape on SAP BTP for app deployment and CI/CD. +status: released +--- + +# Team Onboarding + +{{ $frontmatter.description }} + +[[toc]] + +## Overview + +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 + +- **Sandbox** for development and experiments. +- **Staging** for integration checks. +- **Production** for releases to users. +::: + +Each app has its own repository and release pipeline. + +::: tip Shared 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 a Runtime + +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. + +### 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. + +## 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: + +::: code-group +~~~sh [macOS] +brew tap hashicorp/tap +brew install hashicorp/tap/terraform +brew install --cask btp +~~~ +~~~sh [Linux] +brew tap hashicorp/tap +brew install hashicorp/tap/terraform +btp_arch=$(uname -m) +btp_arch=${btp_arch/x86_64/amd64} +btp_arch=${btp_arch/aarch64/arm64} +curl -L "https://tools.hana.ondemand.com/additional/btp-cli-linux-$btp_arch-2.116.3.tar.gz" -o btp.tar.gz +tar -xzf btp.tar.gz +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. +~~~ +::: + +### 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 +npm install -g mbt +cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org +cf install-plugin -f multiapps +cf install-plugin -f html5-plugin +~~~ + +### Kyma 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). + +## 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. + +## 4. Provision the Landscape + +Log in to BTP and create a directory for your team: + +~~~sh +btp login --sso +mkdir CRM +cd CRM +~~~ + +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] +cds add terraform --k8s +~~~ +::: + +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 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://` | + +
+ +The command creates the Terraform configuration in `CRM/` for these stages: + +| Subaccount | CF org / Kyma cluster | Space / Namespace | +| --- | --- | --- | +| CRM Sandbox | `crm-sandbox` | `team` | +| CRM Staging | `crm-staging` | `ci` | +| CRM Production | `crm-production` | `ci` | + +### Apply + +Use your BTP CLI login: + +::: code-group +~~~sh [macOS/Linux] +export USE_BTPCLI_SESSION=true +~~~ +~~~powershell [Windows] +$env:USE_BTPCLI_SESSION = 'true' +~~~ +::: + +Initialize the configuration, review the plan, then apply it: + +~~~sh +terraform init +terraform plan +terraform apply +~~~ + +> 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 +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 + +Deploy your first app to *Sandbox* using the guide for your runtime: + +### Cloud Foundry + +Prepare and deploy your app with `cds up --to cf`. + +[Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more} + +### Kyma + +Prepare and deploy your app with `cds up --to k8s`. + +[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*. + +::: tip Release flow +Pushes to `main` deploy to *Staging*. Published GitHub releases deploy to *Production*. +::: + +[Learn more in Deploy with CI/CD.](cicd){.learn-more} diff --git a/guides/deploy/to-cf.md b/guides/deploy/to-cf.md index 02bf311af..960e04a24 100644 --- a/guides/deploy/to-cf.md +++ b/guides/deploy/to-cf.md @@ -117,16 +117,24 @@ cds add hana ### 2. Authorization/Authentication -Configure your app for XSUAA-based authentication: +Choose IAS with AMS authorization, or XSUAA: -```sh +::: code-group +```sh [IAS] +cds add ias +cds add ams +``` +```sh [XSUAA] cds add xsuaa ``` +::: -::: tip This will also generate an `xs-security.json` file -The roles/scopes are derived from authorization-related annotations in your CDS models. Ensure to rerun `cds compile --to xsuaa`, as documented in the [_Security_ guide](../security/cap-users#xsuaa-roles) whenever there are changes to these annotations. +::: tip XSUAA roles +`cds add xsuaa` generates an `xs-security.json` file from authorization annotations in your CDS models. Rerun `cds compile --to xsuaa` when these annotations change. ::: +[Learn more about IAS authentication.](../security/authentication#ias-auth){.learn-more} +[Learn more about AMS authorization.](../security/cap-users#roles-assignment-ams){.learn-more} [Learn more about SAP Authorization and Trust Management/XSUAA.](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all){.learn-more} ### 3. Remote Service Consumption {#remote-services} @@ -160,19 +168,23 @@ cds add mta ### 5. User Interfaces {#add-ui} -#### Option A: SAP Cloud Portal +#### Option A: App Router -If you intend to deploy **multitenant** applications with a UI, set up the [HTML5 Application Repository](https://discovery-center.cloud.sap/serviceCatalog/html5-application-repository-service) in combination with the [SAP Cloud Portal service](https://discovery-center.cloud.sap/serviceCatalog/cloud-portal-service): +Add an App Router to your project: ```sh -cds add portal +cds add approuter ``` -::: tip `cds add portal` adds an _App Router_ configuration to your project +::: tip `cds add approuter` adds an _App Router_ configuration to your project 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: @@ -192,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 might also use a custom App Router setup without SAP BTP Cloud Portal service: - -```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 } @@ -229,7 +228,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} @@ -311,7 +310,9 @@ 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. +With IAS and AMS, assign the `cap.admin` policy to your user in the [IAS Administration Console](../security/cap-users#ams-deployment). + +With XSUAA, 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 access the admin APIs. ::: ### Use MTA Extensions with `cds up`