# Installation on Red Hat OpenShift using the OperatorHub
# Overview
The following tutorial shows how to install an Entando application using the Red Hat-certified Entando Operator
and covers a few common enterprise configurations. If you're working with an OpenShift version prior to 4.6 then you may require the alternative manual instructions.
We have two sets of scenarios listed below:
- Scenario 1.1-1.5 for cluster admins who can create projects and operators
- Scenario 2.1 for a user with access to administer a project.
Scenario 1.1 is similar to the Entando quickstart style of deployment which can be applied in many environments, including on local developer laptops. The subsequent scenarios (1.2-1.5) build on that initial setup but can be performed independently if desired. Unless otherwise noted, you have the freedom to keep or modify the default options when installing the Entando Operator
and other resources in the tutorials.
# Prerequisites
- A 4.6 (or higher) OpenShift installation
- For simplicity the tutorial instructions are for a local Code Ready Containers (CRC) instance but this will require significant dedicated resources, e.g. at least 4 vCPU and 10GB RAM. In some environments you may need to start CRC using
crc start -n 8.8.8.8
in order to install operators.
- For simplicity the tutorial instructions are for a local Code Ready Containers (CRC) instance but this will require significant dedicated resources, e.g. at least 4 vCPU and 10GB RAM. In some environments you may need to start CRC using
- (For scenarios 1.x) cluster-admin access to OpenShift for initial installation of the Entando Operator
- (For scenarios 2.x) namepace-level access to a specific OpenShift project for installation of an Entando application using an Entando Operator installed in the cluster
- Familiarity with the OpenShift console and operation
# Scenario 1.1 - Embedded Database
The initial scenario is to deploy the operator and Entando application in a single namespace. We'll start with the smallest application footprint which uses an embedded database.
- Locate the
Entando Operator
in theOperators → OperatorHub
using the Filter feature. - Click
Install
to view theEntando Operator
install options. - Select
A specific namespace on the cluster
for theInstallation mode
. - Choose an empty namespace for
Installed Namespace
. You can create one fromHome → Projects
first, if needed, e.g.entando-one
. - Click
Install
to install the operator into your target namespace. - The install may take a few minutes to complete after which you can click
View Operator
to see the operator in your namespace, or you can go toOperators → Installed Operators
at any point and select it from there. - Now go to
Entando Composite Application
and clickCreate instance
- Change the
Dbms Override
toembedded
. This is the lightest and quickest way to test a full Entando application but you'll need to modify the YAML as well in step 10. - (Optional) If you're working in anything but a single project environment, you'll need to provide an
Ingress Host Name Override
specific to your namespace, e.g.entando-one.<my-base-openshift-url>.
In CRC you can keep the defaultentando.apps-crc.testing
for your first project. - Switch to the YAML view and remove the following section since it isn't needed with an embedded database.
- kind: EntandoDatabaseService
metadata:
name: inline-entando-database-service
spec:
createDeployment: true
- (Optional) Feel free to edit the YAML to customize the names of the components deployed by the EntandoCompositeApp, e.g.
inline-entando-database-service
- Click
Create
. TheEntando Operator
will now proceed to deploy the appropriate resources. - Go to
Entando Composite Application → my-entando-composite-app
to check the status of the deploy or itsEvents
tab to follow its progress.
See the Next Steps below to continue your work with Entando.
# Scenario 1.2 - PostgreSQL
For this scenario we'll prepare a more production-like configuration. Here we'll switch from an embedded on-disk database to a dedicated PostgreSQL database. For this scenario we'll start where step 6 ends in the previous scenario. If you already ran Scenario 1.1 you can either go to that project and remove the Composite App via Installed Operators → Entando Operator → Entando Composite Application
or prepare a new project using steps 1-5 above.
Now let's create a new application, this time using PostgreSQL.
- Go to
Entando Composite Application
and clickCreate instance
- Keep the default
Dbms Override
aspostgresql
. You should not remove the EntandoDatabaseService in this case. - (Optional) Set the
Ingress Host Name Override
as in step 9 above. - Click
Create
. TheEntando Operator
will now proceed to deploy the appropriate resources just as in Scenario 1.1 but with the addition of a PostgreSQL database deployment.
See the Next Steps below to continue your work with Entando.
# Scenario 1.3 - PostgreSQL plus OpenShift SSL
For this scenario we'll build on Scenario 1.2 but enable SSL using OpenShift's internal Certificate Authority. As a starting point, you can either remove the Composite App from the previous scenarios or prepare a new project per steps 1-5 in Scenario 1.1.
- Using your browser, examine and save the SSL certificate for your environment. For example, in Chrome, go to any OpenShift console page, click on
View Site Information
next to the URL (it may be labeledNot secure
) then go toDetails -> Copy to File
and save the certificate as a Base-64 encoded X.509 file, e.g.openshift.cer.
- Go to
Workflows → Secrets → Create
and selectKey/value secret
- Set the
Secret Name
, e.g.entando-ca-cert-secret
- Set the
Key
, e.g.openshift.cer
- Set the
Value
by clickingBrowse...
and loading the file you saved in Step 1. - Click
Create
- Next go to
Workloads → ConfigMaps
and create a ConfigMap namedentando-operator-config
This is the ConfigMap used by the Operator to configure the deployments. You'll need to supply your own project name for the namespace.
kind: ConfigMap
apiVersion: v1
metadata:
name: entando-operator-config
namespace: entando-one
data:
entando.ca.secret.name: entando-ca-cert-secret
entando.use.auto.cert.generation: 'true'
- Click
Create
Now let's create a new application, just like in Scenario 1.2 but with OpenShift SSL in place.
- Go to
Entando Composite Application
and clickCreate instance
- Keep the default
Dbms Override
aspostgresql
. - (Optional) Set the
Ingress Host Name Override
as in Scenario 1 step 9. - You don't need to set the
TLS Secret Name Override
since it will be taken from theentando-operator-config
ConfigMap. - Click
Create
. TheEntando Operator
will now proceed to deploy the appropriate resources.
Once the deployment is complete you can confirm that all routes use https with OpenShift's CA. You will likely still see security warnings in the browser.
See the Next Steps below to continue your work with Entando.
# Scenario 1.4 - PostgreSQL plus self-signed SSL
This scenario is similar to Scenario 1.3 but here we'll use a self-signed certificate rather than using OpenShift's Certificate Authority. As a starting point, you can either remove the Composite App from the previous scenarios or prepare a new project per steps 1-5 in Scenario 1.1.
We'll start by creating a self-signed certificate and then preparing the Secrets and ConfigMap to match. There are various ways to create an X.509 self-signed certificate and you can use your own preferred mechanism.
- Using OpenSSL (opens new window) create a certificate for your application. You'll need to adjust the CN value to match your project.
openssl req -nodes -x509 -newkey rsa:4096 -keyout tls.key -out tls.crt -days 365 -subj "/CN=entando.apps-crc.testing"
You should see output similar to this:
Generating a RSA private key
.....................................................................++++
........................................................................................................................................................................................++++
writing new private key to 'tls.key'
-----
Now we can create a TLS Secret using the generated files.
- Go to
Workloads → Secrets → Create
and selectFrom YAML
. - Enter this
YAML
, update the namespace to match your project, and clickCreate
:
kind: Secret
apiVersion: v1
metadata:
name: entando-tls-secret
namespace: entando-one
data:
tls.key: ''
tls.crt: ''
type: kubernetes.io/tls
- Click on
Actions → Edit Secret
and use theBrowse...
buttons to upload the key and cert files.
Now we'll also create the entando-ca-cert-secret
Secret, similar to what was done in Scenario 1.3 but now using the self-signed certificate.
- Go to
Workflows → Secrets → Create
and selectKey/value secret
- Set the
Secret Name
, e.g.entando-ca-cert-secret
- Set the
Key
, e.g.cert1.crt
- Set the
Value
by clickingBrowse...
and loading the cert file from Step 1, e.g.tls.crt
- Click
Create
- Next go to
Workloads → ConfigMaps
and create a ConfigMap namedentando-operator-config.
This is the ConfigMap used by the Operator to configure the deployments. You'll need to supply your own project name for the namespace.
kind: ConfigMap
apiVersion: v1
metadata:
name: entando-operator-config
namespace: entando-one
data:
entando.ca.secret.name: entando-ca-cert-secret
entando.tls.secret.name: entando-tls-secret
- Click
Create
Now let's create a new application, just like in Scenario 1.3 but with the self-signed SSL certificate.
- Go to
Entando Composite Application
and clickCreate instance
- Keep the default
Dbms Override
aspostgresql
. - (Optional) Set the
Ingress Host Name Override
as in Scenario 1.1 step 9. - You don't need to set the
TLS Secret Name Override
since it will be taken from theentando-operator-config
ConfigMap. - Click
Create
. TheEntando Operator
will now proceed to deploy the appropriate resources.
Once the deployment is complete you can confirm that all routes use https with the self-signed certificate. You will still see security warnings in the browser.
See the Next Steps below to continue your work with Entando.
# Scenario 1.5 - Cluster-scoped operator with wildcard SSL
For this scenario we'll install the Entando Operator so the same operator instance can manage applications across namespaces.
- Locate the
Entando Operator
in theOperators → OperatorHub
using the Filter feature. - Click
Install
to view theEntando Operator
install options. - Select
All namespaces on the cluster
for theInstallation mode
. - Keep the default
openshift-operators
for theInstalled Namespace
. - Click
Install
to install the operator into the cluster.
Now, similar to Scenario 1.4, we'll setup a self-signed certificate but this time as a wildcard certificate and then configure the Secrets and ConfigMap to match. There are various ways to create an X.509 self-signed certificate and you can use your own preferred mechanism.
- Using OpenSSL (opens new window) create a certificate for your application. You'll need to adjust the CN value to match your environment but make sure to include the leading
*.
for the wildcard designation.
openssl req -nodes -x509 -newkey rsa:4096 -keyout tls.key -out tls.crt -days 365 -subj "/CN=*.apps-crc.testing"
You should see output similar to this:
Generating a RSA private key
.....................................................................++++
........................................................................................................................................................................................++++
writing new private key to 'tls.key'
-----
Now we can go to the openshift-operators
project and create a TLS Secret using the generated files.
- Go to
Workloads → Secrets → Create
and selectFrom YAML
. - Enter this
YAML
and clickCreate
:
kind: Secret
apiVersion: v1
metadata:
name: entando-tls-secret
namespace: openshift-operators
data:
tls.key: ''
tls.crt: ''
type: kubernetes.io/tls
- Click on
Actions → Edit Secret
and use theBrowse...
buttons to upload the key and cert files.
Now we'll also create the entando-ca-cert-secret
Secret using the self-signed wildcard certificate.
- Go to
Workflows → Secrets → Create
and selectKey/value secret
- Set the
Secret Name
, e.g.entando-ca-cert-secret
- Set the
Key
, e.g.cert1.crt
- Set the
Value
by clickingBrowse...
and loading the cert file from Step 1, e.g.tls.crt
- Click
Create
- Next go to
Workloads → ConfigMaps
and create a ConfigMap namedentando-operator-config.
This is the ConfigMap used by the Operator to configure the deployments. You'll need to supply the routing suffix for your environment. Don't include a leading*.
since this is just the suffix.
kind: ConfigMap
apiVersion: v1
metadata:
name: entando-operator-config
namespace: openshift-operators
data:
entando.ca.secret.name: entando-ca-cert-secret
entando.tls.secret.name: entando-tls-secret
entando.default.routing.suffix: apps-crc.testing
- Click
Create
- You can now proceed to create one or more Entando applications in their own namespaces, e.g. using the steps for Scenario 1.1 starting from Step 7 or as a different user in Scenario 2.1. You can leave out the
Ingress Host Name Override
since the cluster-scoped operator will provide it for you based on the routing.suffix.
See the Next Steps below to continue your work with Entando.
# Scenario 2.1 - Developer Project
For this scenario we'll use the cluster-installed Entando Operator to install an Entando application by individually creating each of its elements. This is much like what is done in Scenarios 1.1-1.2 but gives you greater control of the overall setup of the application. The prerequisites are that the Operator was installed in the cluster and that you have access to your own project.
First we'll start by creating the database for the application.
- Go to
Installed Operators
, make sure you've selected your own Project, e.g.entando-two
, and and then go toProvided APIs → Entando Database Service
and clickCreate EntandoDatabaseService.
The default settings work fine for this step. They include creating the deployment and using PostgresSQL for the DBMS. If you examine the YAML it looks something like this:
apiVersion: entando.org/v1
kind: EntandoDatabaseService
metadata:
namespace: entando-two
name: my-entando-database-service
spec:
createDeployment: true
dbms: postgresql
databaseName: my_database
- Click
Create.
The operator will now create the deployment and resources needed for the database.
Next let's setup the Keycloak server for identity management.
- Similar to Step 1, go to
Installed Operators -> Select your project (if needed) → Provided APIs → Entando Keycloak Server
and clickCreate EntandoKeycloakServer.
- (Optional) Select a
TLS Secret
to secure the service, e.gentando-tls-secret
per Scenario 1.5. - (Optional) Set the
Ingress Host Name
for your project, e.g.entando-two.<my-base-openshift-url>
- Click
Create
Once the deployment is complete you can check Networking → Routes
to find the URL for the new Keycloak if you didn't specify the Ingress Host Name
, e.g. my-keycloak-entando-two.apps-crc.testing/auth/
. The generated admin credentials can be found under Workloads → Secrets
, e.g. my-keycloak-admin-secret
Next we'll prepare the infrastructure service.
- Go to
Installed Operators -> Select your project (if needed) → Provided APIs → Entando Cluster Infrastructure
and clickCreate EntandoClusterInfrastructure.
- (Optional) Set the
Ingress Host Name
, e.g.entando-two.<my-base-openshift-url>
- (Optional) If you chose to apply a
TLS Secret
in Step 4 then you'll want to do the same here by setting theTLS Secret Name
, e.g.entando-tls-secret.
- Click
Create
Now we'll create the application itself.
- Go to
Installed Operators -> Select your project (if needed) → Provided APIs → CLick on View more (if needed) -> EntandoApp
and clickCreate instance.
- (Optional) Set the
Ingress Host Name
, e.g.entando-two.<my-base-openshift-url>
- (Optional) If you chose to apply a
TLS Secret
in Step 4 then you'll want to do the same here by setting theTLS Secret Name
, e.g.entando-tls-secret.
See the Next Steps below to continue your work with Entando.
# Next Steps
Once you've completed any of the scenarios above, you have several options.
- Check out
Networking → Routes
to see the URLs for the running services. Common starting points include theEntando App Builder
(e.g.http://entando.apps-crc.testing/app-builder/
) orEntando application
itself (e.g.http://entando.apps-crc.testing/entando-de-app/
). - This suggested list of next steps could also be useful.