diff --git a/vuepress/docs/.vuepress/next.js b/vuepress/docs/.vuepress/next.js index 9c7f5f9d24..97b001fee1 100644 --- a/vuepress/docs/.vuepress/next.js +++ b/vuepress/docs/.vuepress/next.js @@ -205,8 +205,8 @@ module.exports = { path: path + 'getting-started/openshift-install.md' }, { - title: 'Red Hat OpenShift using the OperatorHub', - path: path + 'getting-started/openshift-install-by-operator-hub.md' + title: 'Red Hat OpenShift using the Operator', + path: path + 'getting-started/openshift-install-by-operator.md' }, { title: 'Amazon Elastic Kubernetes Service (EKS)', diff --git a/vuepress/docs/next/docs/consume/operator-intro.md b/vuepress/docs/next/docs/consume/operator-intro.md index 69bdfcf91a..64657605a8 100644 --- a/vuepress/docs/next/docs/consume/operator-intro.md +++ b/vuepress/docs/next/docs/consume/operator-intro.md @@ -3,74 +3,36 @@ The Entando Operator processes the custom resources in Kubernetes that represent the different [components of an Entando application](../README.md). The goal of the operator is to provide automation and a set of default configuration options to simplify and accelerate the deployment of an Entando application. -The sections below provide details and assumptions that the operator makes when deploying Entando Custom Resources. If you're using OpenShift these -sections will provide details on how to configure your deployment via the Operator Hub. +The sections below provide details and assumptions that the operator makes when deploying Entando Custom Resources. If you're using OpenShift, these sections will provide details on how to configure your deployment via the Operator Hub. -For details on the individual custom resources and their configuration check out the [custom resources documentation](./custom-resources.md). - -## Installation Scope Options - -The Entando Operator can be installed in one of two modes. Either cluster scoped or namespace scoped. In a cluster scoped deployment the operator will have -visibility across the cluster and will manage all of the Entando applications in the Kubernetes cluster. In a namespace scoped deployment the operator -will only have visibility to the namespace where it is deployed and will manage only the components in that namespace. - -When installing the operator via OpenShift look for the `Installation Mode` option to select the scoping for the operator. - -### When to use Cluster Scoped Deployments -When choosing how to deploy your operator there are no right or wrong answers. Think about the deployment that best fits your goals and team. Here are some items to think about. - -- Cluster scoped deployments are common in production clusters and in environments with strong operational support and controls. -- A cluster scoped deployment can saves resources When you want to optimize resource consumption and share Kubernetes infrastructure. -- When you are planning to centralize and share other infrastructure resources like Keycloak and databases a cluster scoped deployment can fit into the same management processes. - - Sharing infrastructure resources is a recommended approach for medium or large teams and the operator can be treated like other infrastructure services. -- In some cases security requirements will require that the permissions required for the operator are managed separately from the deployed applications. A cluster scoped deployment isolates the operator permissions in a separate namespace. -- Cluster scoped deployments can simplify the deployment of an Entando app by developers or end users because they have fewer resources to manage - -### When to use Namespace Scoped Deployments -When choosing how to deploy your operator there are no right or wrong answers. Think about the deployment that best fits your goals and team. Here are some items to think about. - -- Namespace scoped deployments are common in dev clusters. Or in clusters where application naemspaces come and go frequently -- Namespace scoped deployments are useful in scenarios where you plan to, or could have, many different versions of Entando -- Namespace scoped deployments give your teams complete team autonomy and the ability to create and destroy applications -- When teams are small and self managing from an operational perspective a namespace scoped deployment is a simpler architecture -- If you plan to have a small number of applications deployed in the cluster a namespace scoped deployment can be easier to manage - -[Click here for tutorials and instructions for deploying via operator hub](../../tutorials/getting-started/openshift-install-by-operator-hub.md) +For details on the individual custom resources and their configuration, check out the [custom resources documentation](./custom-resources.md). [See the instructions here on deploying via the Entando Operator](../../tutorials/getting-started/openshift-install-by-operator.md). ## TLS Secret Creation -When configuring and deploying Entando via the operator you will be asked to provide a secret for some of the components in the architecture. A few things to be aware of when creating and configuring a secret: +When configuring and deploying Entando via the operator, you will be asked to provide a secret for some of the components in the architecture. A few things to be aware of when creating and configuring a Secret: -- The secret is assumed to be in the same namespace as the component being created. -- This secret is expected to have a private key, and a certificate for the hostname (or a wildcard cert) that the service -will be exposed on. -- Refer to the 'ingressHostname' property in the custom resource for more information on how the hostname is -determined. -- If a secret isn't provided the Entando Operator will evaluate the value of the `ENTANDO_PATH_TO_TLS_KEYPAIR` which is -expected to contain two files: tls.key and tls.crt. - - If a key pair is found in the folder specified, it will revert to the keypair found. - - If a key pair is not found the Entando Operator will evaluate the value of the `ENTANDO_USE_AUTO_CERT_GENERATION`. - If that property is set to `true` the Entando Operator will assume that the cluster has been configured with a valid CA and leave it to - the Ingress controller to generate its own certificates. +- The Secret is assumed to be in the same namespace as the component being created. +- This Secret is expected to have a private key, and a certificate for the hostname (or a wildcard certificate) that the service will be exposed on. +- Refer to the 'ingressHostname' property in the custom resource for more information on how the hostname is determined. +- If a Secret isn't provided, the Entando Operator will evaluate the value of the `ENTANDO_PATH_TO_TLS_KEYPAIR`, which is expected to contain two files: tls.key and tls.crt. + - If a key pair is found in the folder specified, the operator will use that key pair. + - If a key pair is not found, the Entando Operator will evaluate the value of the `ENTANDO_USE_AUTO_CERT_GENERATION`. If that property is set to `true`, the Entando Operator will assume that the cluster has been configured with a valid Certificate Authority (CA) and leave it to the Ingress controller to generate its own certificates. -[Click here for tutorials on creating secrets and setting up TLS in your Entando Apps.](../../tutorials/getting-started/openshift-install-by-operator-hub.md) +[Click here for instructions on setting up TLS in your Entando Apps](../../tutorials/getting-started/openshift-install-by-operator.md). ## Database Deployment -Some Entando components include the ability to select a database management system (DBMS) when deploying the component. +Some Entando components include the option to select a database management system (DBMS): -- The DBMS field in Entando Custom Resources can be one of mysql, oracle, postgresql or embedded. - - **IMPORTANT!** -- If embedded is selected for a component only 1 replica for the component can be created. - - **IMPORTANT!** -- Oracle instances are not supported for automatic deployment in a container. You must create an Oracle instance or use an existing instance and configure it as an [external database](../../tutorials/devops/external-db.md) for your Entando app +- The value of the DBMS field in Entando Custom Resources can be mysql, oracle, postgresql or embedded. + - **IMPORTANT!** -- If embedded is selected for a component, only one replica for the component can be created. + - **IMPORTANT!** -- Oracle instances are not supported for automatic deployment in a container. You must create your own Oracle instance or reuse an existing instance and then configure the [external database](../../tutorials/devops/external-db.md) for your EntandoApp. -- If an EntandoDatabaseService has been deployed in the component's namespace, and the DBMS specified on this EntandoDatabaseService - is the same as the DBMS specified on this EntandoApp, the Entando Operator will create dedicated +- If an EntandoDatabaseService has been deployed in the component's namespace and the DBMS specified for this EntandoDatabaseService is the same as the DBMS specified for this EntandoApp, then the Entando Operator will create dedicated schemas (in the case of PostgreSQL or Oracle), or databases in the case of MySQL. - If a matching EntandoDatabaseService does not exist in this namespace, the Entando Operator - will automatically deploy the appropriate container to host the DBMS specified. This last option is not - yet supported for Oracle. -- For an EntandoApp three schemas/database will be created: the Entando Port DB, tne Entando Serv DB and a database for - the Entando Component Manager. + will automatically deploy the appropriate container to host the DBMS specified. This last option is not yet supported for Oracle. +- For an EntandoApp, three schemas/databases will be created: the Entando Port DB, tne Entando Serv DB and a database for the Entando Component Manager. - If the Port and Serv schemas/databases are empty, the Entando Operator will use the underlying Entando App to populate these databases with the data backup available in the standard backup path in the WAR deployment. - In scenarios where the EntandoApp needs to connect to an existing database that is fully managed by the customer, it is best to setup the standard database connection variables using the @@ -86,8 +48,5 @@ the documentation for each component's CRD to determine how each Entando resourc When deploying an Entando Custom Resource that uses an Ingress path: - The `ingressHostName` property defines the host path that will be used to access this - service from outside the cluster. The Entando Operator will - create an ingress reflecting this hostname, and expose the resource at its default path. - - **IMPORTANT!** -- If omitted, the Entando Operator will automatically generate a hostname - using the value of the ENTANDO_DEFAULT_ROUTING_SUFFIX environment variable that the Entando Operator was - configured with. It will prefix the name and namespace of the EntandoKeycloakServer to this default routing suffix. + service from outside the cluster. The Entando Operator will create an ingress with this hostname and expose the resource at its default path. + diff --git a/vuepress/docs/next/tutorials/devops/entando-operator.md b/vuepress/docs/next/tutorials/devops/entando-operator.md index ce587c6cec..bf6e362e6a 100644 --- a/vuepress/docs/next/tutorials/devops/entando-operator.md +++ b/vuepress/docs/next/tutorials/devops/entando-operator.md @@ -3,34 +3,34 @@ sidebarDepth: 2 --- # Configure the Entando Operator -This tutorial demonstrates how to provide a ```ConfigMap``` for the Entando Operator to customize its behavior. +This tutorial demonstrates how to provide the Entando Operator with a ConfigMap to customize its behavior. See the template file below for possible settings related to image timeouts, TLS/SSL configuration, and the default image repository. Some specific tutorials (e.g. [Plugin Configuration Profiles](./plugin-configuration.md)) also require updates to the Entando Operator configuration. ## Prerequisites -The Entando Operator makes use of an optional ```ConfigMap``` named ```entando-operator-config```. It must be present in the same namespace. In a quickstart environment, you can check for its presence with this command: +The Entando Operator makes use of an optional ConfigMap named `entando-operator-config`. The ConfigMap must be present in the same namespace as the operator. In a quickstart environment, you can check for its presence with this command: ```sh kubectl get configmap -n entando ``` ## Add a new ConfigMap -If the ```ConfigMap``` doesn't already exist, you can use a template as a starting point. +If the ConfigMap doesn't already exist, you can use a template as a starting point. ```sh curl -sfL "https://raw.githubusercontent.com/entando/entando-releases/v7.0.0/dist/ge-1-1-6/samples/entando-operator-config.yaml" ``` -Edit ```entando-operator-config.yaml``` to adjust existing settings or add new ones. You can then apply it to Kubernetes. +Edit `entando-operator-config.yaml` to adjust existing settings or add new ones. You can then apply it to Kubernetes. ```sh kubectl apply -f entando-operator-config.yaml -n entando ``` -The Entando Operator automatically reloads the settings from the new ```ConfigMap```. You can verify the reload by checking the logs in the operator pod. +The Entando Operator automatically reloads settings from the ConfigMap when the ConfigMap is created. You can verify the reload by checking the logs in the operator pod. ## Update an existing ConfigMap -If the ```ConfigMap``` already exists, you can edit the ```ConfigMap``` to adjust existing settings or add new ones. +You can edit an existing ConfigMap to add or update settings. ```sh kubectl edit configmap/entando-operator-config -n entando ``` -The Entando Operator automatically reloads the settings from the ```ConfigMap```. You can verify the reload by checking the logs in the operator pod. Some settings may only take effect when a deployment is first created, e.g. timeout settings or cpu limits. +The Entando Operator automatically reloads settings from the ConfigMap whenever it is modified. You can verify the reload by checking the logs in the operator pod. Some settings may only take effect when a deployment is first created, e.g. timeout settings or CPU limits. diff --git a/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator-hub.md b/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator-hub.md deleted file mode 100644 index 7ed9f8a6c7..0000000000 --- a/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator-hub.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -sidebarDepth: 2 ---- -# 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](./openshift-install.md). - -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 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. -1. Locate the `Entando Operator` in the `Operators → OperatorHub` using the Filter feature. -2. Click `Install` to view the `Entando Operator` install options. -3. Select `A specific namespace on the cluster` for the `Installation mode`. -4. Choose an empty namespace for `Installed Namespace`. You can create one from `Home → Projects` first, if needed, e.g. `entando-one`. -5. Click `Install` to install the operator into your target namespace. -6. 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 to `Operators → Installed Operators` at any point and select it from there. -7. Now go to `Entando Composite Application` and click `Create instance` -8. Change the `Dbms Override` to `embedded`. 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. -9. (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..` In CRC you can keep the default `entando.apps-crc.testing` for your first project. -10. 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 -``` -11. (Optional) Feel free to edit the YAML to customize the names of the components deployed by the EntandoCompositeApp, e.g. `inline-entando-database-service` -12. Click `Create`. The `Entando Operator` will now proceed to deploy the appropriate resources. -13. Go to `Entando Composite Application → my-entando-composite-app` to check the status of the deploy or its `Events` tab to follow its progress. - -See the [Next Steps](#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. -1. Go to `Entando Composite Application` and click `Create instance` -2. Keep the default `Dbms Override` as `postgresql`. You should not remove the EntandoDatabaseService in this case. -3. (Optional) Set the `Ingress Host Name Override` as in step 9 above. -4. Click `Create`. The `Entando 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](#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. - -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 labeled `Not secure` ) then go to `Details -> Copy to File` and save the certificate as a Base-64 encoded X.509 file, e.g. `openshift.cer.` -2. Go to `Workflows → Secrets → Create` and select `Key/value secret` -3. Set the `Secret Name`, e.g. `entando-ca-cert-secret` -4. Set the `Key`, e.g. `openshift.cer` -5. Set the `Value` by clicking `Browse...` and loading the file you saved in Step 1. -6. Click `Create` -7. Next go to `Workloads → ConfigMaps` and create a ConfigMap named `entando-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' -``` -8. Click `Create` - -Now let's create a new application, just like in Scenario 1.2 but with OpenShift SSL in place. - -9. Go to `Entando Composite Application` and click `Create instance` -10. Keep the default `Dbms Override` as `postgresql`. -11. (Optional) Set the `Ingress Host Name Override` as in Scenario 1 step 9. -12. You don't need to set the `TLS Secret Name Override` since it will be taken from the `entando-operator-config` ConfigMap. -13. Click `Create`. The `Entando 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](#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. - -1. Using [OpenSSL](https://www.openssl.org/) 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. - -2. Go to `Workloads → Secrets → Create` and select `From YAML`. -3. Enter this `YAML`, update the namespace to match your project, and click `Create`: -``` -kind: Secret -apiVersion: v1 -metadata: - name: entando-tls-secret - namespace: entando-one -data: - tls.key: '' - tls.crt: '' -type: kubernetes.io/tls -``` -4. Click on `Actions → Edit Secret` and use the ```Browse...``` 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. - -5. Go to `Workflows → Secrets → Create` and select `Key/value secret` -6. Set the `Secret Name`, e.g. `entando-ca-cert-secret` -7. Set the `Key`, e.g. `cert1.crt` -8. Set the `Value` by clicking `Browse...` and loading the cert file from Step 1, e.g. `tls.crt` -9. Click `Create` -10. Next go to `Workloads → ConfigMaps` and create a ConfigMap named `entando-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 -``` -11. Click `Create` - -Now let's create a new application, just like in Scenario 1.3 but with the self-signed SSL certificate. - -12. Go to `Entando Composite Application` and click `Create instance` -13. Keep the default `Dbms Override` as `postgresql`. -14. (Optional) Set the `Ingress Host Name Override` as in Scenario 1.1 step 9. -15. You don't need to set the `TLS Secret Name Override` since it will be taken from the `entando-operator-config` ConfigMap. -16. Click `Create`. The `Entando 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](#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. -1. Locate the `Entando Operator` in the `Operators → OperatorHub` using the Filter feature. -2. Click `Install` to view the `Entando Operator` install options. -3. Select `All namespaces on the cluster` for the `Installation mode`. -4. Keep the default `openshift-operators` for the `Installed Namespace`. -5. 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. - -6. Using [OpenSSL](https://www.openssl.org/) 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. - -7. Go to `Workloads → Secrets → Create` and select `From YAML`. -8. Enter this `YAML` and click `Create`: -``` -kind: Secret -apiVersion: v1 -metadata: - name: entando-tls-secret - namespace: openshift-operators -data: - tls.key: '' - tls.crt: '' -type: kubernetes.io/tls -``` -9. Click on `Actions → Edit Secret` and use the ```Browse...``` 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. - -10. Go to `Workflows → Secrets → Create` and select `Key/value secret` -11. Set the `Secret Name`, e.g. `entando-ca-cert-secret` -12. Set the `Key`, e.g. `cert1.crt` -13. Set the `Value` by clicking `Browse...` and loading the cert file from Step 1, e.g. `tls.crt` -14. Click `Create` -15. Next go to `Workloads → ConfigMaps` and create a ConfigMap named `entando-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 -``` -16. Click `Create` -17. 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](#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. -1. Go to `Installed Operators`, make sure you've selected your own Project, e.g. `entando-two`, and and then go to `Provided APIs → Entando Database Service` and click `Create 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 -``` -2. 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. - -3. Similar to Step 1, go to `Installed Operators -> Select your project (if needed) → Provided APIs → Entando Keycloak Server` and click `Create EntandoKeycloakServer.` -4. (Optional) Select a `TLS Secret` to secure the service, e.g `entando-tls-secret` per Scenario 1.5. -5. (Optional) Set the `Ingress Host Name` for your project, e.g. `entando-two.` -6. 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. - -7. Go to `Installed Operators -> Select your project (if needed) → Provided APIs → Entando Cluster Infrastructure` and click `Create EntandoClusterInfrastructure.` -8. (Optional) Set the `Ingress Host Name`, e.g. `entando-two.` -9. (Optional) If you chose to apply a `TLS Secret` in Step 4 then you'll want to do the same here by setting the `TLS Secret Name`, e.g. `entando-tls-secret.` -10. Click `Create` - -Now we'll create the application itself. - -11. Go to `Installed Operators -> Select your project (if needed) → Provided APIs → CLick on View more (if needed) -> EntandoApp` and click `Create instance.` -12. (Optional) Set the `Ingress Host Name`, e.g. `entando-two.` -13. (Optional) If you chose to apply a `TLS Secret` in Step 4 then you'll want to do the same here by setting the `TLS Secret Name`, e.g. `entando-tls-secret.` - -See the [Next Steps](#next-steps) below to continue your work with Entando. - -## Appendix A - Troubleshooting and Common Errors - -### Image Pull Error -When installing Entando 6.3.2 into OpenShift 4.6, you may run into an image pull error. This happens because of restricted registries for the docker image. - -To address this issue, a property in the ConfigMap is used to override the default docker registry. Every time there is a docker image name without a registry, it will apply this override property. - -Create a ConfigMap named `entando-operator-config` with the property `entando.docker.registry.override: [registry.hub.docker.com](http://registry.hub.docker.com)` as shown below: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: entando-operator-config - namespace: -data: - entando.docker.registry.override: registry.hub.docker.com -``` - -Replace `` with the proper name for the namespace. Then create the ConfigMap from the command line or from the OpenShift UI. - -**Note: This configuration should be done after deploying the operator and before deploying the CompositeApp.** - - -## 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 the `Entando App Builder` (e.g. `http://entando.apps-crc.testing/app-builder/`) or `Entando application` itself (e.g. `http://entando.apps-crc.testing/entando-de-app/`). -* This suggested [list of next steps](../../docs/getting-started/#next-steps) could also be useful. - - \ No newline at end of file diff --git a/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md b/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md new file mode 100644 index 0000000000..815d890b5f --- /dev/null +++ b/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md @@ -0,0 +1,152 @@ +--- +sidebarDepth: 2 +--- +# Installation on Red Hat OpenShift using the Operator + +## Overview +The following tutorial shows how to install an Entando Application using the Entando Operator and covers a few common enterprise configurations. You may also find the alternative [manual instructions](./openshift-install.md) useful. + +Scenario 1 is similar to the Entando quickstart style of deployment which can be applied in many environments, including on developer laptops. The subsequent scenarios build on that initial setup but can also be performed independently. Unless otherwise noted, you have the freedom to keep or modify the default options when installing the Entando Operator and other resources. + +## Prerequisites +- OpenShift 4.8.x +- Cluster-admin access to OpenShift for initial installation of the Entando Operator +- Familiarity with the OpenShift console and operation + +## Add the Entando Operator to the OperatorHub +A cluster admin can add the 7.0 version of the Entando Operator into the local OperatorHub using the following command. +```shell +oc apply -f https://raw.githubusercontent.com/entando/entando-releases/v7.0.1/dist/ge-1-1-6/samples/openshift-catalog-source.yaml +``` + +## Scenario 1 - Embedded Database +The initial scenario deploys the operator and Entando Application into a single namespace. We start with the smallest application footprint by using an embedded database, although this is not recommended for production use cases. +1. Locate the Entando Operator in the `Operators` → `OperatorHub`. Make sure to select the appropriate version. +2. Click `Install` to view the Entando Operator install options +3. Select `A specific namespace on the cluster` for the `Installation mode` +4. Choose an empty namespace for `Installed Namespace`. You can create one from `Home` → `Projects` first, if needed, e.g. `entando-one`. +5. Click `Install` to install the operator into your target namespace +6. The install may take a few minutes to complete, after which you can click `View Operator` to see the operator in your namespace. You can also go to `Operators` → `Installed Operators` at any time and select it from there. +7. Now go to `EntandoApp` and click `Create EntandoApp` + - Keep the default `my-app` as your application name or select your own + - Select the EntandoApp version: `7.0` +8. Provide an `Ingress Host Name` specific to your namespace, e.g. `my-app.YOUR-BASE-OPENSHIFT-URL`. In CRC you can keep the default `entando.apps-crc.testing` for your first project. +9. Change the `DBMS` value to `embedded`. This is the lightest and quickest way to test a full Entando Application. However, a non-embedded relational database is strongly recommended for production use. +10. Click `Create`. The Entando Operator proceeds to deploy the appropriate resources. +11. Go to `EntandoApp` → `my-app` to check the status of the deploy + +See the [Next Steps](#next-steps) below to continue your work with Entando. + +## Scenario 2 - PostgreSQL +For this scenario we prepare a more production-like configuration. Here we switch from an embedded on-disk database to a dedicated PostgreSQL database. This scenario starts where step 6 ends in the previous scenario. If you already ran Scenario 1, you can either go to that project and remove the EntandoApp and ProvidedCapabilities via `Installed Operators` → `Entando Operator` or prepare a new project using steps 1-5 above. + +Now create a new application, this time using PostgreSQL. +1. Go to `EntandoApp` and click `Create instance` + - Keep the default `my-app` as your application name or select your own + - Select the EntandoApp version: `7.0` +2. Set the `Ingress Host Name` as in Scenario 1 above +3. Keep the default `DBMS` value of `postgresql` +4. Click `Create`. The Entando Operator now deploys the appropriate resources as in Scenario 1 but with the addition of a PostgreSQL database deployment. + +See the [Next Steps](#next-steps) below to continue your work with Entando. + +## Scenario 3 - PostgreSQL plus OpenShift SSL +This scenario sets up PostgreSQL, like Scenario 2, but also enables SSL using OpenShift's internal Certificate Authority (CA). As a starting point, you can either remove the EntandoApp and ProvidedCapabilities using the Entando Operator or you can prepare a new project per steps 1-5 in Scenario 1. + +1. Using your browser, examine and save the SSL certificate for your environment + - In Chrome, go to any OpenShift console page and click on `View Site Information` next to the URL. Note that it may be labeled `Not secure`. + - Go to `Details` -> `Copy to File` and save the certificate as a Base-64 encoded X.509 file, e.g. `openshift.cer`. +2. Go to `Workloads` → `Secrets` → `Create` and select `Key/value secret` +3. Set the `Secret Name`, e.g. `entando-ca-cert-secret` +4. Set the `Key`, e.g. `openshift.cer` +5. Set the `Value` by clicking `Browse...` and loading the file you saved in Step 1 +6. Click `Create` +7. Next, go to `Workloads` → `ConfigMaps` and create or update the ConfigMap named `entando-operator-config`. This is the ConfigMap used by the operator to configure the deployments. You can [download the Entando Operator template](../devops/entando-operator.md#add-a-new-configmap) as a starting point. Set the "data/entando.ca.secret.name" to match the name from step 3. +```yaml +data: + entando.ca.secret.name: entando-ca-cert-secret + entando.use.auto.cert.generation: 'true' +``` +8. Click `Create` + +Now let's create a new application similar to Scenario 2, but with OpenShift SSL in place. + +9. Go to `EntandoApp` and click `Create instance` + - Keep the default `my-app` as your application name or select your own + - Select the EntandoApp version: `7.0` + - Set the `Ingress Host Name` as in Scenario 1 above + - Keep the default `DBMS` value of `postgresql` +10. Click `Create`. The Entando Operator proceeds to deploy the appropriate resources. + +Once the deployment is complete, you can confirm that all routes use HTTPS with OpenShift's CA. You may still see security warnings in the browser. + +See the [Next Steps](#next-steps) below to continue your work with Entando. + +## Scenario 4 - PostgreSQL plus Self-Signed SSL +This scenario is similar to Scenario 3, but here you'll use a self-signed certificate instead of a certificate provided by OpenShift's internal Certificate Authority. As a starting point, you can either remove the EntandoApp and Provided Capabilities from the previous scenarios or prepare a new project per steps 1-5 in Scenario 1. + +Start by creating a self-signed certificate and then prepare the Secrets and ConfigMap to match. There are various ways to create an X.509 self-signed certificate, so you can use your preferred mechanism. + +1. Using [OpenSSL](https://www.openssl.org/), create a certificate for your application. You'll need to adjust the Common Name (CN) value to match the `Ingress Host Name` for your project. +```shell +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: +```shell +Generating a RSA private key +.....................................................................++++ +........................................................................................................................................................................................++++ +writing new private key to 'tls.key' +----- +``` +Now you can create a TLS Secret using the generated files. + +2. Go to `Workloads` → `Secrets` → `Create` and select `From YAML`. Use the following YAML as a starting point and then click `Create`. +```yaml +kind: Secret +apiVersion: v1 +metadata: + name: entando-tls-secret +data: + tls.key: '' + tls.crt: '' +type: kubernetes.io/tls +``` +3. Click on `Actions` → `Edit Secret` and use the `Browse...` buttons to upload the key and cert files. + +Now create the `entando-ca-cert-secret` Secret, similar to what was done in Scenario 3, but this time using the self-signed certificate. + +4. Go to `Workloads` → `Secrets` → `Create` and select `Key/value secret` +5. Set the `Secret Name`, e.g. `entando-ca-cert-secret` +6. Set the `Key`, e.g. `tls.crt` +7. Set the `Value` by clicking `Browse...` and loading the cert file from Step 1, e.g. `tls.crt` +8. Click `Create` +9. Next, go to `Workloads` → `ConfigMaps` and update or create a ConfigMap named `entando-operator-config`. This is the ConfigMap used by the operator to configure the deployments. You can [download the Entando Operator template](../devops/entando-operator.md#add-a-new-configmap) as a starting point. Set the "data/entando.ca.secret.name" and "data/entando.tls.secret.name" to match the names from above. +```yaml +data: + entando.ca.secret.name: entando-ca-cert-secret + entando.tls.secret.name: entando-tls-secret +``` +10. Click `Create` + +Now let's create a new application similar to Scenario 3, but with the self-signed SSL certificate. + +11. Go to `EntandoApp` and click `Create instance` + - Keep the default `my-app` as your application name or select your own + - Select the EntandoApp version: `7.0` + - Set the `Ingress Host Name` as in Scenario 1 above. It should match the CN used to generate the certificate in step 1. + - Keep the default `DBMS` value as `postgresql` +12. Click `Create`. The Entando Operator now proceeds to deploy the appropriate resources. + +Once the deployment is complete, you can confirm that all routes use HTTPS with the self-signed certificate. You may still see security warnings in the browser. + +See the [Next Steps](#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 the Entando App Builder (e.g. `http://entando.apps-crc.testing/app-builder/`) or the Entando Application itself (e.g. `http://entando.apps-crc.testing/entando-de-app/`). +* See the [Entando Operator Configuration](../devops/entando-operator.md) for options related to timeout settings and the default image registry. +* This suggested [list of next steps](../../docs/getting-started/#next-steps) could also be useful. + + + diff --git a/vuepress/docs/next/tutorials/getting-started/openshift-install.md b/vuepress/docs/next/tutorials/getting-started/openshift-install.md index 35e222154c..436a5d2116 100644 --- a/vuepress/docs/next/tutorials/getting-started/openshift-install.md +++ b/vuepress/docs/next/tutorials/getting-started/openshift-install.md @@ -5,7 +5,7 @@ sidebarDepth: 2 # Installation on OpenShift ## Overview -This tutorial shows how to manually install Entando into OpenShift 4.8.x. __Installation via the Entando Operator is highly recommended for OpenShift 4.6+.__ See the [Installation on Red Hat OpenShift using the Operator tutorial](./openshift-install-by-operator-hub.md) for specific instructions. +This tutorial shows how to manually install Entando into OpenShift 4.8.x. __Installation via the Entando Operator is highly recommended for OpenShift 4.6+.__ See the [Installation on Red Hat OpenShift using the Operator tutorial](./openshift-install-by-operator.md) for specific instructions. ## Prerequisites - An OpenShift 4.8.x installation @@ -26,7 +26,7 @@ oc login --token=sha256~TO3QCeoLSbprlGZARBOBVAoaKFeb9Ag0RxztYifAcjE --server=htt 2. Install the cluster-scoped custom resource definitions (CRDs). This step is only required once per cluster. ```shell -oc apply -n entando -f https://raw.githubusercontent.com/entando/entando-releases/v7.0.0/dist/ge-1-1-6/namespace-scoped-deployment/cluster-resources.yaml +oc apply -n entando -f https://raw.githubusercontent.com/entando/entando-releases/v7.0.1/dist/ge-1-1-6/namespace-scoped-deployment/cluster-resources.yaml ``` 3. Create the project for your application @@ -38,9 +38,9 @@ Note: If you choose a different name for your project, adjust the commands below The remaining steps in this tutorial can be performed by a user with project-level access, rather than a cluster admin. ## Configure the Project -1. Install the namespace-scoped CRDs +1. Install the namespace-scoped custom resources ``` -oc apply -n entando -f https://raw.githubusercontent.com/entando/entando-releases/v7.0.0/dist/ge-1-1-6/namespace-scoped-deployment/namespace-resources.yaml +oc apply -n entando -f https://raw.githubusercontent.com/entando/entando-releases/v7.0.1/dist/ge-1-1-6/namespace-scoped-deployment/namespace-resources.yaml ``` 2. (Optional) A ConfigMap can be used to modify the behavior of the Entando Operator. Refer to the [Entando Operator](../../tutorials/devops/entando-operator.md) page for more information. @@ -48,7 +48,7 @@ oc apply -n entando -f https://raw.githubusercontent.com/entando/entando-release ## Configure the Entando Application 1. Download the `entando-app.yaml` template ```sh -curl -sLO "https://raw.githubusercontent.com/entando/entando-releases/v7.0.0/dist/ge-1-1-6/samples/entando-app.yaml" +curl -sLO "https://raw.githubusercontent.com/entando/entando-releases/v7.0.1/dist/ge-1-1-6/samples/entando-app.yaml" ``` 2. Determine the hostname for your application, YOUR-HOST-NAME