diff --git a/tutorials/cap-operator-01-prepare/cap-operator-01-prepare.md b/tutorials/cap-operator-01-prepare/cap-operator-01-prepare.md new file mode 100644 index 000000000..2fd0709a8 --- /dev/null +++ b/tutorials/cap-operator-01-prepare/cap-operator-01-prepare.md @@ -0,0 +1,182 @@ +--- +title: Prepare for Deployment +description: Learn how to set up the SAP BTP, Kyma runtime for deploying the application. +parser: v2 +auto_validation: true +time: 30 +tags: [ tutorial>beginner, software-product>sap-cap-operator--kubernetes-environment, topic>cloud-operations, software-product-function>sap-cloud-application-programming-model, programming-tool>node-js, software-product>sap-business-technology-platform, software-product>sap-btp--kyma-runtime] +primary_tag: software-product>sap-cap-operator--kubernetes-environment +author_name: Anirudh Prasad +author_profile: https://github.com/anirudhprasad-sap +--- + +## You will learn + +- How to configure entitlements. +- How to enable the SAP BTP Kyma runtime in your subaccount in SAP BTP. +- How to create an SAP HANA Cloud service instance in the SAP BTP cockpit. +- How to enable the CAP Operator community module in your Kyma cluster. + +## Prerequisites + +- You have an [enterprise global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account#loiod61c2819034b48e68145c45c36acba6e) in SAP BTP. To use services for free, you can sign up for an SAP BTPEA (SAP BTP Enterprise Agreement) or a Pay-As-You-Go for SAP BTP global account and use the free tier services only. See [Using Free Service Plans](https://help.sap.com/docs/btp/sap-business-technology-platform/using-free-service-plans?version=Cloud). +- You have a platform user. See [User and Member Management](https://help.sap.com/docs/btp/sap-business-technology-platform/user-and-member-management). +- You're an administrator of the global account in SAP BTP. +- You have a subaccount in SAP BTP to deploy the services and applications. + +> This tutorial follows the guidance provided in the [SAP BTP Developer's Guide](https://help.sap.com/docs/btp/btp-developers-guide/what-is-btp-developers-guide). + +### Configure the entitlements + +To deploy the Incident Management sample application, you need the following entitlements: + +| Service | Plan | Quota required | +| ------------- | :-----------: | ----: | +| Kyma runtime | free (Environment) | 1 | +| SAP HANA Cloud | hana-free | 1 | +| SAP HANA Cloud | tools (Application) | 1 | +| SAP HANA Schemas & HDI Containers | hdi-shared | 1 | +| HTML5 Application Repository Service | app-host | 1 | +| HTML5 Application Repository Service | app-runtime | 1 | +| Destination Service | lite | 1 | +| SaaS Provisioning Service | application | 1 | +| Service Manager | container | 1 | +| Authorization and Trust Management Service | broker | 1 | + +> You can find more information about entitlements in [Configure Entitlements and Quotas](https://help.sap.com/docs/btp/sap-business-technology-platform/configure-entitlements-and-quotas-for-subaccounts). + +### Enable SAP BTP, Kyma runtime + +Let's enable your subaccount to use the SAP BTP, Kyma runtime. + +1. Navigate to your subaccount and choose **Enable Kyma** under the **Kyma Environment** tab. + + ![Enable Kyma](./img/enable-kyma.png) + +2. In the **Enable Kyma** popup, change the values for **Instance Name** and **Cluster Name** as needed and choose **Create**. + + ![Enable Kyma popup](./img/enable-kyma-popup.png) + + > Make sure that the instance name is CLI-friendly. CLI-friendly names make it easier to manage your instances with the SAP BTP command-line interface as well. + > + > A CLI-friendly name is a short string (up to 32 characters) that contains only alphanumeric characters (A-Z, a-z, 0-9), periods, underscores, and hyphens. It can't contain white spaces. + > + > When enabling the runtime, you notice that the instance name is generated automatically for you. You can use that name or replace it with the name of your choice. + + +### Subscribe to SAP HANA Cloud Administration Tools + +1. Navigate to your subaccount and choose **Services** → **Service Marketplace** on the left. + +2. Type **SAP HANA Cloud** in the search box and choose **Create**. + + ![Create an SAP HANA Cloud tools instance](./img/create-hana-tools.png) + +3. In the **New Instance or Subscription** popup, select **tools** from the dropdown in the **Plan** field and choose **Create**. + + ![SAP HANA Cloud tools instance creation popup](./img/create-hana-tools-popup.png) + +4. Choose **View Subscription** and wait until the status changes to **Subscribed**. + + ![View subscription](./img/view-subscription.png) + + ![Status subscribed](./img/hanatools-status-subscribed.png) + +5. In your SAP BTP subaccount, choose **Security** → **Role Collections** in the left-hand pane. + +6. Choose role collection **SAP HANA Cloud Administrator**. + +7. Choose **Edit**. + + ![Edit role](./img/hana-edit-role.png) + +8. In the **Users** section, enter your user and select the icon to add the user. + + ![Add user](./img/hana-add-user.png) + + > Keep the `Default Identity Provider` setting unless you have a custom identity provider configured. + +9. Choose **Save**. + + You've assigned the **SAP HANA Cloud Administrator** role collection to your user. + +> Log out and log back in to make sure your new role collection is considered. + +### Create an SAP HANA Cloud service instance + +SAP HANA Cloud is used as a persistence layer. + +Follow these steps to create an SAP HANA Cloud service instance in the SAP BTP cockpit: + +1. In your SAP BTP subaccount, navigate to **Services** → **Instances and Subscriptions** in the left-hand pane. + +2. Choose **SAP HANA Cloud**. You're redirected to SAP HANA Cloud multi-environment administration tools. Sign in with your SAP BTP cockpit username/email if necessary. + + ![SAP HANA Cloud Go to application](./img/hana-goto-app.png) + +3. In SAP HANA Cloud Central, choose **Create Instance**. + + ![SAP HANA Cloud create instance](./img/hana-create-instance.png) + +4. Choose *Confiure manually* as **Instance Configuration** and *SAP HANA Database* as **Instance Type**. Then, choose **Next Step**. + + ![Create SAP HANA DB Step 1](./img/create-hana-db1.png) + +5. In the **Instance Name** field, enter *application-hana-instance*. + +6. In the **Administrator Password** and **Confirm Administrator Password** fields, enter a password for DBADMIN. Choose **Next Step**. + + ![Create SAP HANA DB Step 2](./img/create-hana-db2.png) + +7. At **SAP HANA Database: Size and Availability**, choose **Next Step**. + +8. In **SAP HANA Database: Connections**, select the **All IP addresses** radio button, and choose **Next Step**. + + ![Create SAP HANA DB Step 3](./img/create-hana-db3.png) + +9. At **SAP HANA Database: Advanced Settings**, choose **Next Step**. + +10. At **Data Lake: General**, choose **Review and Create**. + +11. Choose **Create Instance**. + +The creation of the database instance can take some minutes to complete. + +> Your SAP HANA Cloud service instance automatically stops overnight, according to the time zone of the region where the server is located. This means you need to restart your instance every day before you start working with it. + +### Map your SAP HANA Cloud service instance to your Kyma cluster + +1. Go to SAP HANA Cloud Central. If you've closed it, open it again by following these steps: + + - In your SAP BTP subaccount, navigate to **Services** → **Instances and Subscriptions**. + - Choose **SAP HANA Cloud**. You're redirected to SAP HANA Cloud multi-environment administration tools. Sign in with your SAP BTP cockpit username/email if necessary. + +2. For the **application-hana-instance** instance, choose **Manage Configuration**. + + ![Manage instance configuration](./img/hana-config.png) + +3. Select the **Instance Mapping** tab and choose **Add Mapping**. + + ![Add instance mapping](./img/hana-add-mapping.png) + +4. Select **Kyma** from the dropdown under **Environment Type**. + +5. Under **Environment Instance ID**, paste the GUID of your Kyma cluster. Here's how to find it: + + - Open your Kyma dashboard. + - Choose **Namespaces** on the left and choose **kyma-system**. + - Navigate to **Configuration** → **Config Maps** and choose **sap-btp-operator-config**. + - You can see the GUID of your Kyma cluster in the **CLUSTER_ID** section. + + ![Add environment instance ID](./img/hana-kyma-cluster-id.png) + + > If no namespace is provided, the instance is mapped to all namespaces in the cluster. + +6. Choose **Review and Save**. In the popup, choose **Save Changes**. + + ![Save changes](./img/hana-save-mapping.png) + + You've mapped your SAP HANA Cloud service instance to your Kyma cluster. + + > For more information, see [Map an SAP HANA Database to another Environment Context](https://help.sap.com/docs/HANA_CLOUD/9ae9104a46f74a6583ce5182e7fb20cb/1683421d02474567a54a81615e8e2c48.html) to add a new Cloud foundry or Kyma mapping. + diff --git a/tutorials/cap-operator-01-prepare/img/create-hana-db1.png b/tutorials/cap-operator-01-prepare/img/create-hana-db1.png new file mode 100644 index 000000000..7fbd30d62 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/create-hana-db1.png differ diff --git a/tutorials/cap-operator-01-prepare/img/create-hana-db2.png b/tutorials/cap-operator-01-prepare/img/create-hana-db2.png new file mode 100644 index 000000000..210f5d115 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/create-hana-db2.png differ diff --git a/tutorials/cap-operator-01-prepare/img/create-hana-db3.png b/tutorials/cap-operator-01-prepare/img/create-hana-db3.png new file mode 100644 index 000000000..cbe330331 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/create-hana-db3.png differ diff --git a/tutorials/cap-operator-01-prepare/img/create-hana-tools-popup.png b/tutorials/cap-operator-01-prepare/img/create-hana-tools-popup.png new file mode 100644 index 000000000..d82dacc94 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/create-hana-tools-popup.png differ diff --git a/tutorials/cap-operator-01-prepare/img/create-hana-tools.png b/tutorials/cap-operator-01-prepare/img/create-hana-tools.png new file mode 100644 index 000000000..3dfd3fc0c Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/create-hana-tools.png differ diff --git a/tutorials/cap-operator-01-prepare/img/enable-kyma-popup.png b/tutorials/cap-operator-01-prepare/img/enable-kyma-popup.png new file mode 100644 index 000000000..8430d0fd6 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/enable-kyma-popup.png differ diff --git a/tutorials/cap-operator-01-prepare/img/enable-kyma.png b/tutorials/cap-operator-01-prepare/img/enable-kyma.png new file mode 100644 index 000000000..9887e946f Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/enable-kyma.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-add-mapping.png b/tutorials/cap-operator-01-prepare/img/hana-add-mapping.png new file mode 100644 index 000000000..994d635c0 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-add-mapping.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-add-user.png b/tutorials/cap-operator-01-prepare/img/hana-add-user.png new file mode 100644 index 000000000..1370299eb Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-add-user.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-config.png b/tutorials/cap-operator-01-prepare/img/hana-config.png new file mode 100644 index 000000000..0c503439e Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-config.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-create-instance.png b/tutorials/cap-operator-01-prepare/img/hana-create-instance.png new file mode 100644 index 000000000..8bd38404f Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-create-instance.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-edit-role.png b/tutorials/cap-operator-01-prepare/img/hana-edit-role.png new file mode 100644 index 000000000..8de9d20d2 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-edit-role.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-goto-app.png b/tutorials/cap-operator-01-prepare/img/hana-goto-app.png new file mode 100644 index 000000000..012a31ce2 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-goto-app.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-kyma-cluster-id.png b/tutorials/cap-operator-01-prepare/img/hana-kyma-cluster-id.png new file mode 100644 index 000000000..57403aac5 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-kyma-cluster-id.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hana-save-mapping.png b/tutorials/cap-operator-01-prepare/img/hana-save-mapping.png new file mode 100644 index 000000000..abec19953 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hana-save-mapping.png differ diff --git a/tutorials/cap-operator-01-prepare/img/hanatools-status-subscribed.png b/tutorials/cap-operator-01-prepare/img/hanatools-status-subscribed.png new file mode 100644 index 000000000..a1faa2b81 Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/hanatools-status-subscribed.png differ diff --git a/tutorials/cap-operator-01-prepare/img/view-subscription.png b/tutorials/cap-operator-01-prepare/img/view-subscription.png new file mode 100644 index 000000000..fffbb70ef Binary files /dev/null and b/tutorials/cap-operator-01-prepare/img/view-subscription.png differ diff --git a/tutorials/cap-operator-02-tools/cap-operator-02-tools.md b/tutorials/cap-operator-02-tools/cap-operator-02-tools.md new file mode 100644 index 000000000..948c57ada --- /dev/null +++ b/tutorials/cap-operator-02-tools/cap-operator-02-tools.md @@ -0,0 +1,213 @@ +--- +title: Install Tools for Deployment +description: Learn how to install the necessary tools for deploying the application +parser: v2 +auto_validation: true +time: 30 +tags: [ tutorial>beginner, software-product>sap-cap-operator--kubernetes-environment, topic>cloud-operations, software-product-function>sap-cloud-application-programming-model, programming-tool>node-js, software-product>sap-business-technology-platform, software-product>sap-btp--kyma-runtime] +primary_tag: software-product>sap-cap-operator--kubernetes-environment +author_name: Anirudh Prasad +author_profile: https://github.com/anirudhprasad-sap +--- + +## You will learn + +- How to install the tools required for deploying CAP applications in the SAP BTP, Kyma runtime. + - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) + - [kubelogin](https://github.com/int128/kubelogin) + - [helm](https://helm.sh/docs/intro/install/) + - [pack](https://buildpacks.io/docs/tools/pack/#install) + - A container management app such as [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [Rancher Desktop](https://rancherdesktop.io/). + +## Prerequisites + +- You've configured the respective entitlements, enabled the Kyma runtime in your subaccount, and created an SAP HANA Cloud service instance in the SAP BTP cockpit. Follow the steps in the [Prepare for Deployment](cap-operator-01-prepare) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. +- You have an [enterprise global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account#loiod61c2819034b48e68145c45c36acba6e) in SAP BTP. To use services for free, you can sign up for an SAP BTPEA (SAP BTP Enterprise Agreement) or a Pay-As-You-Go for SAP BTP global account and use the free tier services only. See [Using Free Service Plans](https://help.sap.com/docs/btp/sap-business-technology-platform/using-free-service-plans?version=Cloud). +- You have a platform user. See [User and Member Management](https://help.sap.com/docs/btp/sap-business-technology-platform/user-and-member-management). +- You're an administrator of the global account in SAP BTP. +- You have a subaccount in SAP BTP to deploy the services and applications. +- For Windows, you need Chocolatey. Chocolatey is a package manager that speeds up and eases installation of the tools in this tutorial. See how to install Chocolatey in [Setup/Install](https://docs.chocolatey.org/en-us/choco/setup). +- You've prepared a container registry and you've logged in to the container registry through your CLI. A container registry is a repo where you can push your Docker images. You can use any container registry offering as long as it can be reached from the public internet. In case if you don't have access to a container registry, you can make use of the [Docker Registry Community Module](https://kyma-project.io/external-content/docker-registry/docs/user/README.html) from Kyma. + +### Install kubectl + +[OPTION BEGIN [macOS]] +1. To install kubectl, run the following command: +```Shell/Bash +brew install kubectl +``` +2. Check if the installation is successful: +```Shell/Bash +kubectl version --client +``` +You see a version number. +[OPTION END] + +[OPTION BEGIN [Windows]] +You can install kubectl using Chocolatey. + +1. To install kubectl, run the following command: +```Shell/Bash +choco install kubernetes-cli +``` +2. Check if the installation is successful: +```Shell/Bash +kubectl version --client +``` +You see something like: +`Client Version: version.Info{Major:"1", Minor:"19", GitVersion:"v1.19.3", GitCommit:"1e11e4a2108024935ecfcb2912226cedeafd99df", GitTreeState:"clean", BuildDate:"2020-10-14T12:50:19Z", GoVersion:"go1.15.2", Compiler:"gc", Platform:"windows/amd64"}` +[OPTION END] + +[OPTION BEGIN [Linux]] +Follow the instructions for your preferred way of installing kubectl at [Install and Set Up kubectl on Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/). +[OPTION END] + +### Install kubelogin + +[OPTION BEGIN [macOS]] +To install kubelogin, run the following command: +```Shell/Bash +brew install int128/kubelogin/kubelogin +``` +See [Setup](https://github.com/int128/kubelogin#setup) in the kubelogin docs for more details. +[OPTION END] + +[OPTION BEGIN [Windows]] +You can install kubelogin using Chocolatey: + +```Shell/Bash +choco install kubelogin +``` + +See [Setup](https://github.com/int128/kubelogin#setup) in the kubelogin docs for more details. +[OPTION END] + +[OPTION BEGIN [Linux]] +To install kubelogin, run the following command: +```Shell/Bash +brew install int128/kubelogin/kubelogin +``` + +See [Setup](https://github.com/int128/kubelogin#setup) in the kubelogin docs for more details. +[OPTION END] + +### Log in to your Kyma cluster + +1. Choose `KubeconfigURL` under the **Kyma Environment** tab in your subaccount. + + ![Kubeconfig URL](./img/kubeconfigURL.png) + + A `kubeconfig.yaml` file is downloaded. + + ![Kubeconfig yaml](./img/kubeconfig_yaml.png) + +2. Copy the `kubeconfig.yaml` file to the `~/.kube/` directory and rename it to `config`. Replace or rename any existing file with the same name. + +There are two additional steps for Windows users only: + +3. Go to `C:\ProgramData\chocolatey\bin`. + +4. Rename `kubelogin.exe` to `kubectl-oidc_login.exe`. + +### Install helm + +[OPTION BEGIN [macOS]] +There's a multitude of options to install Helm. You can see the full list at [Installing Helm](https://helm.sh/docs/intro/install/). We have also listed some options: + +To install Helm, run the following command: +```Shell/Bash +brew install helm +``` +[OPTION END] + +[OPTION BEGIN [Windows]] +There's a multitude of options to install Helm. You can see the full list at [Installing Helm](https://helm.sh/docs/intro/install/). We have also listed some options: + +You can install Helm using Chocolatey. + +1. To install Helm, run the following command: +```Shell/Bash +choco install kubernetes-helm +``` +2. Check if the installation is successful: +```Shell/Bash +helm version +``` +You see something like `version.BuildInfo{Version:"v3.8.0", GitCommit:"d14138609b01886f544b2025f5000351c9eb092e", GitTreeState:"clean", GoVersion:"go1.17.5"}`. +[OPTION END] + + +### Install Paketo (pack) + +[OPTION BEGIN [macOS]] +Pack lets you build container images that are collaboratively maintained, making it easier to maintain and update. + +```Shell/Bash +brew install buildpacks/tap/pack +``` +[OPTION END] + +[OPTION BEGIN [Windows]] +Pack lets you build container images that are collaboratively maintained, making it easier to maintain and update. + +You can install pack using Chocolatey with the following command: +```Shell/Bash +choco install pack +``` +As an alternative, you can install `pack` manually: + +1. Download `pack` for your platform from [GitHub](https://github.com/buildpacks/pack/releases). +2. Extract the `pack` binary. +3. Enter **Edit the System Environment Variables** in the Windows search box (Windows icon in the task bar). The **System Properties** dialog is opened. +4. Choose **Environment Variables...**. +5. Choose your `Path` environment variable under *User Variables for ``* and choose **Edit**. +6. Choose **Browse** and navigate to the folder where you extracted the `pack` binary. +7. Choose **OK** to add `pack` to your `Path` environment variable. +[OPTION END] + +[OPTION BEGIN [Linux]] +Pack lets you build container images that are collaboratively maintained, making it easier to maintain and update. + +Follow the instructions to install the [pack CLI](https://buildpacks.io/docs/tools/pack/#install). +[OPTION END] + +### Install a container management app + +[OPTION BEGIN [Docker Desktop]] + +Kyma runs on containers. For this tutorial, you need an application that enables you to manage container images on your desktop (build, push, pull, and run) and a Docker-compatible command-line interface. We provide two examples - Docker Desktop and Rancher Desktop. You can choose one of these or any other app suitable for this purpose. + +* **macOS**: Download the installer from [Install Docker Desktop on Mac](https://docs.docker.com/desktop/mac/install/) and follow the instructions to install and set up Docker Desktop. + +* **Windows**: Download the installer from [Install Docker Desktop on Windows](https://docs.docker.com/desktop/windows/install/) and follow the instructions to install and set up Docker Desktop. + +[OPTION END] +[OPTION BEGIN [Rancher Desktop]] + +Kyma runs on containers. For this tutorial, you need an application that enables you to manage container images on your desktop (build, push, pull, and run) and a Docker-compatible command-line interface. We provide two examples - Docker Desktop and Rancher Desktop. You can choose one of these or any other app suitable for this purpose. + +* **macOS**: + + 1. Go to the [releases](https://github.com/rancher-sandbox/rancher-desktop/releases) page. + 2. Download the Rancher Desktop installer for macOS. + + > The macOS installer is called `Rancher.Desktop-.dmg`. Here's an example with the current latest version: `Rancher.Desktop-1.2.1.x86_64.dmg`. + + 3. Run the installer. When the installation is complete, drag the Rancher Desktop icon to the **Applications** folder. + + > You can find details about installation requirements and steps to install or uninstall in [macOS](https://docs.rancherdesktop.io/getting-started/installation#macos). + +* **Windows**: + + 1. Go to the [releases](https://github.com/rancher-sandbox/rancher-desktop/releases) page. + 2. Download the Rancher Desktop installer for Windows. + + > The Windows installer is called `Rancher.Desktop.Setup..exe`. Here's an example with the current latest version: `Rancher.Desktop.Setup.1.2.1.exe`. + + 3. Run the installer. When the installation is complete, choose **Finish**. + + > You can find details about installation requirements and steps to install or uninstall in [Windows](https://docs.rancherdesktop.io/getting-started/installation#windows). + +* **Linux**: There are several ways to install Rancher Desktop on Linux. You can find details about installation requirements and steps to install or uninstall in [Linux](https://docs.rancherdesktop.io/getting-started/installation#linux). + +[OPTION END] diff --git a/tutorials/cap-operator-02-tools/img/kubeconfigURL.png b/tutorials/cap-operator-02-tools/img/kubeconfigURL.png new file mode 100644 index 000000000..744207e3d Binary files /dev/null and b/tutorials/cap-operator-02-tools/img/kubeconfigURL.png differ diff --git a/tutorials/cap-operator-02-tools/img/kubeconfig_yaml.png b/tutorials/cap-operator-02-tools/img/kubeconfig_yaml.png new file mode 100644 index 000000000..ab1cd3775 Binary files /dev/null and b/tutorials/cap-operator-02-tools/img/kubeconfig_yaml.png differ diff --git a/tutorials/cap-operator-03-add-cap-operator/cap-operator-03-add-cap-operator.md b/tutorials/cap-operator-03-add-cap-operator/cap-operator-03-add-cap-operator.md new file mode 100644 index 000000000..f67291b5d --- /dev/null +++ b/tutorials/cap-operator-03-add-cap-operator/cap-operator-03-add-cap-operator.md @@ -0,0 +1,47 @@ +--- +title: Enable CAP Operator Community Module in Kyma Cluster +description: Learn how to enable the CAP Operator community module in your Kyma cluster. +parser: v2 +auto_validation: true +time: 10 +tags: [ tutorial>beginner, software-product>sap-cap-operator--kubernetes-environment, topic>cloud-operations, software-product-function>sap-cloud-application-programming-model, programming-tool>node-js, software-product>sap-business-technology-platform, software-product>sap-btp--kyma-runtime] +primary_tag: software-product>sap-cap-operator--kubernetes-environment +author_name: Anirudh Prasad +author_profile: https://github.com/anirudhprasad-sap +--- + +## You will learn + +- How to enable the CAP Operator community module in your Kyma cluster. + +## Prerequisites + +- You've enabled the Kyma runtime in your subaccount. Follow the steps in the [Prepare for Deployment](cap-operator-01-prepare) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. +- You have an [enterprise global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account#loiod61c2819034b48e68145c45c36acba6e) in SAP BTP. To use services for free, you can sign up for an SAP BTPEA (SAP BTP Enterprise Agreement) or a Pay-As-You-Go for SAP BTP global account and use the free tier services only. See [Using Free Service Plans](https://help.sap.com/docs/btp/sap-business-technology-platform/using-free-service-plans?version=Cloud). +- You have a platform user. See [User and Member Management](https://help.sap.com/docs/btp/sap-business-technology-platform/user-and-member-management). +- You're an administrator of the global account in SAP BTP. +- You have a subaccount in SAP BTP to deploy the services and applications. + +### Enable CAP Operator community module + +1. Open your Kyma dashboard. + +2. Navigate to **Configuration** → **Modules** and choose **Add** within the **Community Modules** list. + + ![Add Community Module](./img/community-module-1.png) + +3. Choose **Add** in the **Source YAMLs** section to load the list of community modules. + + ![Load Community Modules](./img/community-module-2.png) + +4. In the popup, you can see the list of available community modules. Choose **Add**. + + ![Select CAP Operator Module](./img/community-module-3.png) + +5. Select the **CAP Operator** module and choose **Add**. + + ![Add CAP Operator Module](./img/community-module-4.png) + +6. Wait until the automatic installation is complete and the **Module State** changes to **Ready**. + + ![CAP Operator Installed](./img/community-module-5.png) diff --git a/tutorials/cap-operator-03-add-cap-operator/img/community-module-1.png b/tutorials/cap-operator-03-add-cap-operator/img/community-module-1.png new file mode 100644 index 000000000..49cf5e5a4 Binary files /dev/null and b/tutorials/cap-operator-03-add-cap-operator/img/community-module-1.png differ diff --git a/tutorials/cap-operator-03-add-cap-operator/img/community-module-2.png b/tutorials/cap-operator-03-add-cap-operator/img/community-module-2.png new file mode 100644 index 000000000..e1ea71d4e Binary files /dev/null and b/tutorials/cap-operator-03-add-cap-operator/img/community-module-2.png differ diff --git a/tutorials/cap-operator-03-add-cap-operator/img/community-module-3.png b/tutorials/cap-operator-03-add-cap-operator/img/community-module-3.png new file mode 100644 index 000000000..0450daeba Binary files /dev/null and b/tutorials/cap-operator-03-add-cap-operator/img/community-module-3.png differ diff --git a/tutorials/cap-operator-03-add-cap-operator/img/community-module-4.png b/tutorials/cap-operator-03-add-cap-operator/img/community-module-4.png new file mode 100644 index 000000000..98ff3fc65 Binary files /dev/null and b/tutorials/cap-operator-03-add-cap-operator/img/community-module-4.png differ diff --git a/tutorials/cap-operator-03-add-cap-operator/img/community-module-5.png b/tutorials/cap-operator-03-add-cap-operator/img/community-module-5.png new file mode 100644 index 000000000..16589e651 Binary files /dev/null and b/tutorials/cap-operator-03-add-cap-operator/img/community-module-5.png differ diff --git a/tutorials/cap-operator-04-prepare-app/cap-operator-04-prepare-app.md b/tutorials/cap-operator-04-prepare-app/cap-operator-04-prepare-app.md new file mode 100644 index 000000000..a385ca31f --- /dev/null +++ b/tutorials/cap-operator-04-prepare-app/cap-operator-04-prepare-app.md @@ -0,0 +1,143 @@ +--- +title: Prepare Multi-Tenant Applications for Deployment with CAP Operator +description: This tutorial shows you how to prepare your multi-tenant application for deployment in SAP BTP, Kyma runtime using the CAP Operator. +parser: v2 +auto_validation: true +time: 20 +tags: [ tutorial>beginner, software-product>sap-cap-operator--kubernetes-environment, topic>cloud-operations, software-product-function>sap-cloud-application-programming-model, programming-tool>node-js, software-product>sap-business-technology-platform, software-product>sap-btp--kyma-runtime] +primary_tag: software-product>sap-cap-operator--kubernetes-environment +author_name: Anirudh Prasad +author_profile: https://github.com/anirudhprasad-sap +--- + +## You will learn + +- How to build container images for your multi-tenant application and push them to a container registry. + +## Prerequisites + +- You've configured the respective entitlements, enabled the Kyma runtime in your SAP BTP subaccount, and created an SAP HANA Cloud service instance in the SAP BTP cockpit. Follow the steps in the [Prepare for Deployment](cap-operator-01-prepare) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. +- You've installed all the required tools. Follow the steps in the [Install Tools for Deployment](cap-operator-02-tools) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. + +### Download and set up the project locally + +Clone the application from the [Incident Management Application GitHub Repository](https://github.com/cap-js/incidents-app/tree/cap-operator-tutorials). For e.g. using: +```bash +git clone https://github.com/cap-js/incidents-app.git -b cap-operator-tutorials +``` + +This is a multi-tenant SAP Cloud Application Programming Model (CAP) application. It utilizes the [application router](https://www.npmjs.com/package/@sap/approuter) for routing, SAP Authorization and Trust Management service (XSUAA), and SAP HANA Cloud as the database. The front end is built with SAP Fiori and deployed to the HTML5 Application Repository. + +Open a command-line window in the folder where your application holds **incidents-app** and run the following command to open the project in Visual Studio (VS) Code: + +```bash +code . +``` + +### Build images + +> Make sure you're logged in to your container registry. In case if you don't have access to a container registry, you can make use of the [Docker Registry Community Module](https://kyma-project.io/external-content/docker-registry/docs/user/README.html) from Kyma. + +> If you're using a device with a non-x86 processor (for example, MacBook M1/M2), you need to instruct Docker to use x86 images by setting the **DOCKER_DEFAULT_PLATFORM** environment variable using the command `export DOCKER_DEFAULT_PLATFORM=linux/amd64`. Check the [environment variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) for more information. + +> Make sure to replace `` with the link to your container registry and keep in mind that `` is a string. + +> Looking for your Docker server URL? + +> The Docker server URL is the same as the path used for Docker login, so you can quickly check it by running the following command in your terminal: + +> ```json +> cat ~/.docker/config.json +> ``` + +> In case you're using Docker Hub as your container registry, replace the placeholder `` with your Docker Hub user ID. + +#### Build the CAP Node.js and the MTXS sidecar image + +1. In VS Code, choose **Terminal** → **New Terminal** and run the following command: + + ```bash + npm install + ``` + + This command installs the required dependencies and updates the **package-lock.json** file of your project. + +2. Create the productive CAP build for your application: + + ```bash + npx cds build --production + ``` + + The CAP build writes to the **gen/srv** folder. + +3. Build the CAP Node.js image: + + ```bash + pack build /incident-management-srv: \ + --path gen/srv \ + --builder paketobuildpacks/builder-jammy-base \ + --publish + ``` + + > The pack CLI builds the image that contains the build result in the **gen/srv** folder and the required npm packages by using the [Cloud Native Buildpack for Node.js](https://github.com/paketo-buildpacks/nodejs) provided by Paketo. + +4. Build the MTXS sidecar image: + + ```bash + pack build /incident-management-mtxs-sidecar: \ + --path gen/mtx/sidecar \ + --builder paketobuildpacks/builder-jammy-base \ + --publish + ``` + + > **IMPORTANT:** The **project.toml** file in the **gen/mtx/sidecar** folder is copied automatically from the **mtxs/sidecar** folder during the build. This file exposes the node process inside the container so that CAP Operator can trigger tenant operations using the MTXS CLIs. + +#### Build the application router image + +1. In the VS Code terminal, navigate to the **app/router** folder and run the following command: + + ```bash + npm install + ``` + +2. In the VS Code terminal, navigate back to the root folder of your project: + + ```bash + cd ../.. + ``` + +3. Build the application router image: + + ```bash + pack build /incident-management-approuter: \ + --path app/router \ + --buildpack paketo-buildpacks/nodejs \ + --builder paketobuildpacks/builder-jammy-base \ + --env BP_NODE_RUN_SCRIPTS="" \ + --publish + ``` + +#### Build the HTML5 deployer image + +1. In the VS Code terminal, navigate to the **ui-resources** folder and run the following command: + + ```bash + npm install && npm run package + ``` + + This command builds and copies the archive **nsincidents.zip** inside the **ui-resources/resources** folder. + +2. In the VS Code terminal, navigate back to the root folder of your project: + + ```bash + cd .. + ``` + +3. Build the UI deployer image: + + ```bash + pack build /incident-management-html5-deployer: \ + --path ui-resources \ + --builder paketobuildpacks/builder-jammy-base \ + --publish + ``` diff --git a/tutorials/cap-operator-05-deploy-app/cap-operator-05-deploy-app.md b/tutorials/cap-operator-05-deploy-app/cap-operator-05-deploy-app.md new file mode 100644 index 000000000..60f94d9d6 --- /dev/null +++ b/tutorials/cap-operator-05-deploy-app/cap-operator-05-deploy-app.md @@ -0,0 +1,178 @@ +--- +title: Deploy Multi-Tenant Applications using CAP Operator +description: This tutorial shows you how to deploy your multi-tenant application in SAP BTP, Kyma runtime using the CAP Operator. +parser: v2 +auto_validation: true +time: 20 +tags: [ tutorial>beginner, software-product>sap-cap-operator--kubernetes-environment, topic>cloud-operations, software-product-function>sap-cloud-application-programming-model, programming-tool>node-js, software-product>sap-business-technology-platform, software-product>sap-btp--kyma-runtime] +primary_tag: software-product>sap-cap-operator--kubernetes-environment +author_name: Anirudh Prasad +author_profile: https://github.com/anirudhprasad-sap +--- + +## You will learn + +- How to deploy your multi-tenant application in SAP BTP, Kyma runtime using the CAP Operator. + +## Prerequisites + +- You've configured the respective entitlements, enabled the Kyma runtime in your SAP BTP subaccount, and created an SAP HANA Cloud service instance in the SAP BTP cockpit. Follow the steps in the [Prepare for Deployment](cap-operator-01-prepare) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. +- You've installed all the required tools. Follow the steps in the [Install Tools for Deployment](cap-operator-02-tools) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. +- You've enabled the CAP Operator community module in your Kyma cluster. Follow the steps in the [Enable CAP Operator Community Module](cap-operator-03-add-cap-operator) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. +- You've prepared your multi-tenant application for deployment. Follow the steps in the [Prepare Multi-Tenant Applications for Deployment with CAP Operator](cap-operator-04-prepare-app) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. + +### Add CAP Operator Helm chart + +CAP Operator provides a plugin to generate a Helm chart for your CAP application. + +1. Add the [CAP Operator plugin](https://www.npmjs.com/package/@cap-js/cap-operator-plugin/) to your project by running the following command in your project root folder: + + ```bash + npm add @cap-js/cap-operator-plugin -D + ``` + +2. Run the following command to generate a Helm chart for your CAP application: + + ```bash + npx cds add cap-operator --with-templates + ``` + + As a result, you see a newly created **chart** folder in your project. The **chart** folder holds the Helm configuration, including the **values.yaml** file where you add your container images. + +3. Add your container image settings to your **chart/values.yaml** file: + + ```yaml[7,13,19,25] + ... + workloads: + appRouter: + ... + deploymentDefinition: + type: Router + image: /incident-management-approuter: + ... + server: + ... + deploymentDefinition: + type: CAP + image: /incident-management-srv: + ... + contentDeploy: + ... + jobDefinition: + type: Content + image: /incident-management-html5-deployer: + ... + tenantJob: + ... + jobDefinition: + type: TenantOperation + image: /incident-management-mtxs-sidecar: + ... + ... + ``` + +4. Add the `EXIT_PROCESS_AFTER_UPLOAD` environment variable to the content deploy job in your **chart/values.yaml** file to ensure that the HTML5 deployer exits after the upload is complete: + + ```yaml[8,9] + ... + contentDeploy: + ... + jobDefinition: + type: Content + image: /incident-management-html5-deployer: + env: + - name: EXIT_PROCESS_AFTER_UPLOAD + value: "true" + ... + ``` + +### Deploy CAP Operator Helm chart + +1. Run the following command to create a dedicated space for your application and enable the Istio service mesh to handle communication: + + ```bash + kubectl create namespace incident-management + kubectl label namespace incident-management istio-injection=enabled + ``` + +2. If you are using a private container registry, create a secret in the **incident-management** namespace so the cluster can pull your images. If your images are public, you can skip this step. + + ```bash + kubectl -n incident-management create secret generic regcred --from-file=.dockerconfigjson=$HOME/.docker/config.json --type=kubernetes.io/dockerconfigjson + ``` + +3. Run the following command to get the cluster shoot domain: + + ```bash + kubectl get gateway -n kyma-system kyma-gateway -o jsonpath='{.spec.servers[0].hosts[0]}' | sed 's/^\*\.//' + ``` + + The result looks like this: + ```bash + .kyma.ondemand.com + ``` + + > `` is a placeholder for a string of characters that’s unique for your cluster. + +4. Create a new file named **trial-env.yaml** in the project root folder with the following content and replace the placeholder values with your specific information: + + ```yaml + appName: + capOperatorSubdomain: cap-op + clusterDomain: # Value obtained in the previous step + globalAccountId: + providerSubaccountId: + providerSubdomain: + tenantId: + imagePullSecret: regcred # Only include if you performed Step 2 + ``` + + > **`appName`**: Choose a name that is unique within your subaccount region. This prevents naming collisions with other deployments. + + > **`capOperatorSubdomain`**: In Kyma clusters, CAP Operator subdomain default value is `cap-op`. + + > **`clusterDomain`**: Use the domain string you retrieved in the previous step. + + > **`globalAccountId`**: You can find this in the URL of your browser when you are viewing your subaccount in the SAP BTP Cockpit. + + > ![Save changes](./img/global-account-id.png) + + > **`providerSubaccountId`**, **`providerSubdomain`** and **`providerTenantId`**: In the SAP BTP cockpit, go to your subaccount **Overview** and check the **General** section. You can find all three values there. + + > ![Save changes](./img/provider-subdomain-tenant-id.png) + + > **`imagePullSecret`**: Only include this line if you are using a private registry. If you followed Step 2, set this to `regcred`. + +4. To prepare your deployment, run the following command in your project root to generate the **runtime-values.yaml** file inside your **chart** folder: + + ```bash + npx cap-op-plugin generate-runtime-values --with-input-yaml trial-env.yaml + ``` + + > This command maps your environment settings to the application's configuration. It creates a **runtime-values.yaml** file that Helm uses during deployment to override the default settings in the **values.yaml** file with your specific cluster and account details. + +5. Make sure that your SAP HANA Cloud instance is running. Free tier HANA instances are stopped overnight. + + > Your SAP HANA Cloud service instance automatically stops overnight, according to the time zone of the region where the server is located. This means you need to restart your instance every day before you start working with it. You can restart your instance using the SAP BTP cockpit. + +6. Deploy using the Helm command: + + ```bash + helm upgrade --install incident-management --namespace incident-management ./chart \ + --set-file serviceInstances.xsuaa.jsonParameters=xs-security.json -f ./chart/runtime-values.yaml + ``` + + This command installs the Helm chart from the chart folder with the release name **incident-management** in the **incident-management** namespace. + + > With the **helm upgrade --install** command, you can install a new chart as well as upgrade an existing chart. + +7. To check the status of your deployment: + + 1. Open your Kyma dashboard. + 2. Choose **Namespaces** on the left and choose **incident-management**. + 3. Navigate to **CAP Operator** → **CAP Application**. + 4. You can see the status of your deployed application here. When the status is **Consistent**, your application is successfully deployed. + + ![Save changes](./img/kyma-dashboard-cap-application-status.png) + + > In the example deployment, the unique **appName** is **incident-tutorial**. diff --git a/tutorials/cap-operator-05-deploy-app/img/global-account-id.png b/tutorials/cap-operator-05-deploy-app/img/global-account-id.png new file mode 100644 index 000000000..4069768c2 Binary files /dev/null and b/tutorials/cap-operator-05-deploy-app/img/global-account-id.png differ diff --git a/tutorials/cap-operator-05-deploy-app/img/hana-instance-id.png b/tutorials/cap-operator-05-deploy-app/img/hana-instance-id.png new file mode 100644 index 000000000..63598b010 Binary files /dev/null and b/tutorials/cap-operator-05-deploy-app/img/hana-instance-id.png differ diff --git a/tutorials/cap-operator-05-deploy-app/img/kyma-dashboard-cap-application-status.png b/tutorials/cap-operator-05-deploy-app/img/kyma-dashboard-cap-application-status.png new file mode 100644 index 000000000..02ab42d4f Binary files /dev/null and b/tutorials/cap-operator-05-deploy-app/img/kyma-dashboard-cap-application-status.png differ diff --git a/tutorials/cap-operator-05-deploy-app/img/provider-subdomain-tenant-id.png b/tutorials/cap-operator-05-deploy-app/img/provider-subdomain-tenant-id.png new file mode 100644 index 000000000..84cf59b32 Binary files /dev/null and b/tutorials/cap-operator-05-deploy-app/img/provider-subdomain-tenant-id.png differ diff --git a/tutorials/cap-operator-06-subscribe/cap-operator-06-subscribe.md b/tutorials/cap-operator-06-subscribe/cap-operator-06-subscribe.md new file mode 100644 index 000000000..87ebfd7ea --- /dev/null +++ b/tutorials/cap-operator-06-subscribe/cap-operator-06-subscribe.md @@ -0,0 +1,48 @@ +--- +title: Subscribe to the Multi-Tenant Application from Consumer Subaccount +description: This tutorial shows you how to subscribe to a multi-tenant application from a consumer subaccount. +parser: v2 +auto_validation: true +time: 10 +tags: [ tutorial>beginner, software-product>sap-cap-operator--kubernetes-environment, topic>cloud-operations, software-product-function>sap-cloud-application-programming-model, programming-tool>node-js, software-product>sap-business-technology-platform, software-product>sap-btp--kyma-runtime] +primary_tag: software-product>sap-cap-operator--kubernetes-environment +author_name: Anirudh Prasad +author_profile: https://github.com/anirudhprasad-sap +--- + +## You will learn + +- How to subscribe to a multi-tenant application from a consumer subaccount using the CAP Operator. + +## Prerequisites + +- You've deployed the application. Follow the steps in the [Deploy your Application using CAP Operator](cap-operator-05-deploy-app) tutorial that is part of the [Application Lifecycle Management using CAP Operator]() tutorial group. +- You're an administrator of the global account in SAP BTP. + +### Create new subaccount + +Create a new subaccount in the same global account where you have deployed the multi-tenant CAP application in the previous tutorial, for example, `Customer`. You can find the steps to create a new subaccount in the [Create Subaccounts](https://help.sap.com/docs/btp/sap-business-technology-platform/create-subaccount) documentation. + +### Subscribe to the multi-tenant application + +1. Navigate to your subaccount and choose **Services** → **Service Marketplace** on the left. + +2. Type your application name in the search box and choose **Create**. + + ![application-search](./img/application-search.png) + + > When you enter your application name, ensure it matches the one you used in the previous tutorial. For instance, if you used **incident-tutorial** earlier, use that same name here. + +3. In the **New Instance or Subscription** popup, choose **Create**. + + ![subscribe-application](./img/subscribe-application.png) + + > This subscribes your subaccount to the multi-tenant application deployed in the provider subaccount. + +4. In the **Creation in Progress** popup, choose **View Subscription**. + +5. Wait until the subscription status changes to **Subscribed** and choose **Go to Application**. + + ![subscription-succeeded](./img/subscription-succeeded.png) + + > You've successfully subscribed to the multi-tenant application from your consumer subaccount. diff --git a/tutorials/cap-operator-06-subscribe/img/application-search.png b/tutorials/cap-operator-06-subscribe/img/application-search.png new file mode 100644 index 000000000..8f2efde2a Binary files /dev/null and b/tutorials/cap-operator-06-subscribe/img/application-search.png differ diff --git a/tutorials/cap-operator-06-subscribe/img/subscribe-application.png b/tutorials/cap-operator-06-subscribe/img/subscribe-application.png new file mode 100644 index 000000000..51b36ae15 Binary files /dev/null and b/tutorials/cap-operator-06-subscribe/img/subscribe-application.png differ diff --git a/tutorials/cap-operator-06-subscribe/img/subscription-succeeded.png b/tutorials/cap-operator-06-subscribe/img/subscription-succeeded.png new file mode 100644 index 000000000..a85a393b1 Binary files /dev/null and b/tutorials/cap-operator-06-subscribe/img/subscription-succeeded.png differ