diff --git a/adoc/SAP-EIC-Main.adoc b/adoc/SAP-EIC-Main.adoc index defb441c..77af1f8c 100644 --- a/adoc/SAP-EIC-Main.adoc +++ b/adoc/SAP-EIC-Main.adoc @@ -29,14 +29,14 @@ This guide describes how to prepare your infrastructure for the installation of It will guide you through the steps of: * Installing {rancher} -* Setup {rke} clusters -* Deploy mandatory components for {eic} +* Setting up {rke} clusters +* Deploying mandatory components for {eic} // * Deploying {eic} into your {rke} -NOTE: This guide does not contain information about sizing your landscapes. Please refer to -https://help.sap.com/docs/integration-suite?locale=en-US and look for the "Edge Integration Cell Sizing Guide". +NOTE: This guide does not contain information about sizing your landscapes. Visit +https://help.sap.com/docs/integration-suite?locale=en-US and search for the "Edge Integration Cell Sizing Guide". -== Preparations +== Preparation * Get subscriptions for: ** {slem} {slem_version} @@ -47,7 +47,7 @@ https://help.sap.com/docs/integration-suite?locale=en-US and look for the "Edge * Create a or get access to a private container registry. -* Get an SAP S-user to access software and documentation by SAP. +* Get an SAP S-user ID to access software and documentation from SAP. * Read the relevant SAP documentation: @@ -59,7 +59,8 @@ https://help.sap.com/docs/integration-suite?locale=en-US and look for the "Edge == Installing {slem} {slem_version} -There are several ways to install {slem} {slem_version}. We will use in our Best Practice Guide the installation method via the graphical installer. Further installation routines can be found in the https://documentation.suse.com/sle-micro/5.4/html/SLE-Micro-all/book-deployment-slemicro.html[Deployment Guide]. +There are several ways to install {slem} {slem_version}. For this best practice guide, we use the installation method via graphical installer. +Further installation routines can be found in the https://documentation.suse.com/sle-micro/5.4/html/SLE-Micro-all/book-deployment-slemicro.html[Deployment Guide for SUSE Linux Enterprise Micro 5.4]. include::SAP-EIC-SLEMicro.adoc[SLEMicro] @@ -89,23 +90,24 @@ include::SAPDI3-Longhorn.adoc[] == Installing {metallb} and databases -In this chapter we'll give an example how to setup {metallb}, {redis} and {pg}. +In the following chapter we present an example for setting up {metallb}, {redis} and {pg}. -NOTE: Please note, that this might differ from the deployment you'll need for your infrastructure and use-cases. +NOTE: Keep in mind that the descriptions and instructions below might differ from the deployment you need for your specific infrastructure and use cases. -=== Login to {rac} +=== Logging in to {rac} -{rancher} instances prior to version 2.9 can not integrate the {rac}. Thus you need to use the console and Helm. -The easiest way to do so is to use the built-in shell in {rancher}. To access it, navigate to your cluster and click on *Kubectl Shell* as shown below: +{rancher} instances prior to version 2.9 cannot integrate the {rac}. Therefore, you need to use the console and Helm. +The easiest way to do so is to use the built-in shell in {rancher}. To access it, navigate to your cluster and click *Kubectl Shell* as shown below: image::EIC-Rancher-Kubectl-Button.png[title=Rancher Shell Access,scaledwidth=99%] -A shell will open as in the given picture: +A shell will open as shown in the image: image::EIC-Rancher-Kubectl-Shell.png[title=Rancher Shell Overview,scaledwidth=99%] -You will need to login to the {rac} which can be done like: +You must log in to {rac}. This can be done as follows: + ---- $ helm registry login dp.apps.rancher.io/charts -u -p ---- @@ -113,14 +115,16 @@ $ helm registry login dp.apps.rancher.io/charts -u -p [#imagePullSecret] === Creating an imagePullSecret -To make the ressources be available to roll out, you'll need to create a imagePullSecret. -In this guide we'll use the name application-collection for it. -==== Creating a imagePullSecret using kubectl +To make the resources available for deployment, you need to create an imagePullSecret. +In this guide we use the name _application-collection_ for it. + +==== Creating an imagePullSecret using kubectl -Using kubectl to create the imagePullSecret is quite easy. -Get your username and your access token for the {rac}. +Using `kubectl` to create the imagePullSecret is quite easy. +Get your user name and your access token for the {rac}. Then run: + ---- $ kubectl create secret docker-registry application-collection --docker-server=dp.apps.rancher.io --docker-username= --docker-password= ---- @@ -128,7 +132,7 @@ $ kubectl create secret docker-registry application-collection --docker-server=d ==== Creating an imagePullSecret using {rancher} You can also create an imagePullSecret using {rancher}. -Therefore open {rancher} and enter your cluster. +Therefore, open {rancher} and enter your cluster. Navigate to *Storage* -> *Secrets* as shown below: @@ -138,11 +142,11 @@ image::EIC-Secrets-Menu.png[title=Secrets Menu,scaledwidth=99%] ++++ -Select the *Create* button in the upper right corner. +Click the *Create* button in the top right corner. image::EIC-Secrets-Overview.png[title=Secrets Overview,scaledwidth=99%] -A selection screen will be shown asking you to choose the Secret type. Select *Registry* as shown here: +A window will appear asking you to select the Secret type. Select *Registry* as shown here: image::EIC-Secrets-Types.png[title=Secrets Type Selection,scaledwidth=99%] @@ -150,8 +154,8 @@ image::EIC-Secrets-Types.png[title=Secrets Type Selection,scaledwidth=99%] ++++ -Enter a name like application-collection for the Secret. For the text field *Registry Domain Name*, enter dp.apps.rancher.io . -Enter your username and password and hit the *Create* button on the bottom right side. +Enter a name such as _application-collection_ for the Secret. In the text box *Registry Domain Name*, enter _dp.apps.rancher.io_. +Enter your user name and password and click the *Create* button at the bottom right. image::EIC-Secret-Create.png[title=Secrets Creation Step,scaledwidth=99%] @@ -161,7 +165,7 @@ image::EIC-Secret-Create.png[title=Secrets Creation Step,scaledwidth=99%] === Installing {metallb} -This chapter is to guide you through the installation and configuration of {metallb} on your Kubernetes cluster used for the {eic}. +This chapter is intended to walk you through installing and configuring {metallb} on your Kubernetes cluster used for {eic}. include::SAP-EIC-Metallb.adoc[Metallb] ++++ @@ -172,13 +176,12 @@ include::SAP-EIC-Metallb.adoc[Metallb] // https://help.sap.com/docs/integration-suite/sap-integration-suite/prepare-your-kubernetes-cluster#redis-data-store-requirements -Before deploying {redis}, make sure that the requirements described in -https://me.sap.com/notes/3247839 -are met. +Before deploying {redis}, esure that the requirements described at +https://me.sap.com/notes/3247839 are met. -Furthermore make sure to get an understanding of what grade of persistence you want to achieve for your {redis} cluster. -To get more information about persistence in {redis}, have a look at -https://redis.io/docs/management/persistence/ . +Also, make sure you understand what grade of persistence you want to achieve for your {redis} cluster. +For more information about persistence in {redis}, see +https://redis.io/docs/management/persistence/. include::SAP-EIC-Redis.adoc[] @@ -191,7 +194,7 @@ include::SAP-EIC-Redis.adoc[] // https://help.sap.com/docs/integration-suite/sap-integration-suite/prepare-your-kubernetes-cluster#postgresql-database-requirements -Before deploying {pg}, make sure that the requirements described in +Before deploying {pg}, ensure that the requirements described at https://me.sap.com/notes/3247839 are met. include::SAP-EIC-PostgreSQL.adoc[] @@ -204,7 +207,7 @@ include::SAP-EIC-PostgreSQL.adoc[] // include::SAP-EIC.adoc[] At this point, you should be able to deploy {eic}. -Please follow the instructions at https://help.sap.com/docs/integration-suite/sap-integration-suite/setting-up-and-managing-edge-integration-cell +Follow the instructions at https://help.sap.com/docs/integration-suite/sap-integration-suite/setting-up-and-managing-edge-integration-cell to install {eic} in your prepared environments. ++++ @@ -214,29 +217,29 @@ to install {eic} in your prepared environments. [#Appendix] == Appendix -=== Using self signed certificates +=== Using self-signed certificates -In this chapter we will explain how to create self signed certificates and how to make them available within Kubernetes. +In this chapter we will explain how to create self-signed certificates and how to make them available within Kubernetes. -==== Create the self signed certificates +==== Creating self-signed certificates -CAUTION: It is discouraged to use self signed certifcates for production environments. +WARNING: We strongly advise against using self-signed certificates in production environments. -As a first step, you need to create a certificate authority (further called CA) with its key and certificate. -In the excerpt below you can find an example how create such with a passpharse of your choice: +The first step is to create a certification authority (hereinafter referred to as CA) with a key and certificate. +The following excerpt provides an example of how to create one with a passphrase of your choice: ---- $ openssl req -x509 -sha256 -days 1825 -newkey rsa:2048 -keyout rootCA.key -out rootCA.crt -passout pass: -subj "/C=DE/ST=BW/L=Nuremberg/O=SUSE" ---- -This gives you the *rootCA.key* and the *rootCA.crt*. -For the server certificate, a certificate signing request (further called CSR) is needed. -The given excerpt show how to create such a CSR: +This will give you the files `rootCA.key` and `rootCA.crt`. +The server certificate requires a certificate signing request (hereinafter referred to as CSR). +The following excerpt shows how to create such a CSR: ---- $ openssl req -newkey rsa:2048 -keyout domain.key -out domain.csr -passout pass: -subj "/C=DE/ST=BW/L=Nuremberg/O=SUSE" ---- -Before you can sing the CSR, you'll need to add the DNS names of your Kuberntes Services to the CSR. -Therefore create a file with the content below and replace the ** and ** with the name of your Kubernetes service and the namespace this is placed in: +Before you can sign the CSR, you need to add the DNS names of your Kuberntes Services to the CSR. +Therefore, create a file with the content below and replace the ** and ** with the name of your Kubernetes service and the namespace in which it is placed: ---- authorityKeyIdentifier=keyid,issuer @@ -247,35 +250,35 @@ DNS.1 = ..svc.cluster.local DNS.2 = ..svc.cluster.local ---- -You can now use the previously created rootCA.key and rootCA.crt with the extension file to sign the CSR. -The example below shows how to do that by passing the extension file (here named *domain.ext*): +You can now use the previously created files _rootCA.key_ and _rootCA.crt_ with the extension file to sign the CSR. +The example below shows how to do that by passing the extension file (here called _domain.ext_): ---- $ openssl x509 -req -CA rootCA.crt -CAkey rootCA.key -in domain.csr -out server.pem -days 365 -CAcreateserial -extfile domain.ext -passin pass: ---- -This creates a file called *server.pem* which is your certificate to be used for your application. +This creates a file called _server.pem_ which is your certificate to be used for your application. -Your *domain.key* is at this point still encrypted, but the application will need an uncrypted server key. -To decrypt, run the given command, which will create the *server.key* +Your _domain.key_ is still encrypted at this point, but the application requires an unencrypted server key. +To decrypt, run the given command which will create the _server.key_. ---- $ openssl rsa -passin pass: -in domain.key -out server.key ---- Some applications (like Redis) require a full certificate chain to operate. -To get a full certificate chain, concat the generated *server.pem* with the *rooCA.crt* like below: +To get a full certificate chain, link the generated file _server.pem_ with the file _rootCA.crt_ as follows: ---- $ cat server.pem rootCA.crt > chained.pem ---- -Afterwards you should have the files called server.pem, server.key and chained.pem which can be used for your applications like Redis or PostgresSQL. +You should then have the files _server.pem_, _server.key_ and _chained.pem_ that can be used for your applications such as Redis or PostgresSQL. -==== Upload certificates to Kubernetes +==== Uploading certificates to Kubernetes -To use certificate files in Kubernetes, you need to store them as so called *secrets*. -An example how to upload your certificates to Kubernetes is shown in the given excerpt: +To use certificate files in Kubernetes, you need to save them as so-called *Secrets*. +For an example of uploading your certificates to Kubernetes, see the following excerpt: ---- $ kubectl -n create secret generic --from-file=./root.pem --from-file=./server.pem --from-file=./server.key