Skip to content

Commit

Permalink
Initial doc edits on MAIN document
Browse files Browse the repository at this point in the history 
Edited the MAIN doc content according to documentation style guide.
Titles in sentence style, gerund form where possible. Fixed wording
and punctuation. Fixed typos.
  • Loading branch information
@chabowski
chabowski committed Jul 4, 2024
1 parent 885cf95 commit 99ddcf5
Showing 1 changed file with 57 additions and 54 deletions.
111 changes: 57 additions & 54 deletions adoc/SAP-EIC-Main.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -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:

Expand All @@ -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]

Expand Down Expand Up @@ -89,46 +90,49 @@ 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 <yourUser> -p <your-token>
----


[#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=<yourUser> --docker-password=<yourPassword>
----

==== 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:

Expand All @@ -138,20 +142,20 @@ image::EIC-Secrets-Menu.png[title=Secrets Menu,scaledwidth=99%]
<?pdfpagebreak?>
++++

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%]

++++
<?pdfpagebreak?>
++++

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%]

Expand All @@ -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]
++++
Expand All @@ -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[]
Expand All @@ -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[]
Expand All @@ -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.

++++
Expand All @@ -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:<ca-passphrase> -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:<csr-passphrase> -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 *<servicename>* and *<namespace>* 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 *<servicename>* and *<namespace>* with the name of your Kubernetes service and the namespace in which it is placed:

----
authorityKeyIdentifier=keyid,issuer
Expand All @@ -247,35 +250,35 @@ DNS.1 = <servicename>.<namespace>.svc.cluster.local
DNS.2 = <AltService>.<AltNamespace>.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:<ca-passphrase>
----

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:<csr-passphrase> -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 <namespace> create secret generic <certName> --from-file=./root.pem --from-file=./server.pem --from-file=./server.key
Expand Down

0 comments on commit 99ddcf5

Please sign in to comment.