From 68c8ac100c9d2488f252dee1b67829128217577c Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Wed, 5 Apr 2023 14:40:14 -0500 Subject: [PATCH 01/11] ENDOC-673 first draft --- .../docs/next/tutorials/consume/mt-cds.md | 223 ++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 vuepress/docs/next/tutorials/consume/mt-cds.md diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md new file mode 100644 index 0000000000..68bc7621e6 --- /dev/null +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -0,0 +1,223 @@ +--- +sidebarDepth: 2 +--- + +# Content Delivery Server (CDS) Integration + + +You can use a client software or a custom script to set up the content deliver service for your application. + + +## Setting up the CDS + +### Descriptors +Typically, four descriptors are required for the CDS, as described below. + +#### Keycloak Descriptor YAML +1. Go to Keycloak admin console and log in +2. From the left sidebar, `Realm Settings` → `Keys`. Click on `public Key for `rsa-generated` provider and copy the content. +3. Copy this public key to the descriptor file as shown in the sample below. + +--- + +
Sample Keycloak Descriptor + + +``` yaml +apiVersion: v1 +kind: Secret +metadata: + name: YOUR-KC-SECRET + namespace: YOUR-NAMESPACE +type: Opaque +stringData: + KC_PUBLIC_KEY: "YOUR-PUBLIC-KEY" + // YOUR-PUBLIC-KEY will be a base64 encoded string +``` +
+ +--- + + +#### Persistent Volume Descriptor +The cds-pvc.yaml should provide specificationS for the persistent volume claim including accessModes and resources storage limits. + +``` +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + labels: + deployment: YOUR-CDS-DEPLOYMENT + name: YOUR-PVC-CLAIM + namespace: YOUR-NAMESPACE +spec: + accessModes: + - ReadWriteOnce + resources: + limits: + storage: PVC-SIZE + requests: + storage: PVC-SIZE + #storageClassName: standard +``` + +#### Deployment Descriptor +Create the deployment descriptor YAML with the specifications required for your environment in a K3s implementation. + +``` +apiVersion: v1 +kind: Service +metadata: + name: YOUR-CDS-DEPLOYMENT + namespace: YOUR-NAMESPACE + labels: + app: YOUR-CDS-DEPLOYMENT +spec: + ports: + - port: 8080 + name: internal-port + protocol: TCP + targetPort: 8080 + - port: 8081 + name: public-port + protocol: TCP + targetPort: 8081 + selector: + app: YOUR-CDS-DEPLOYMENT +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: YOUR-CDS-DEPLOYMENT + namespace: YOUR-NAMESPACE + labels: + app: YOUR-CDS-DEPLOYMENT +spec: + selector: + matchLabels: + app: YOUR-CDS-DEPLOYMENT + template: + metadata: + labels: + app: YOUR-CDS-DEPLOYMENT + spec: + containers: + - readinessProbe: + httpGet: + port: 8081 + path: /health/health_check + scheme: HTTP + failureThreshold: 1 + initialDelaySeconds: 5 + periodSeconds: 5 + successThreshold: 1 + timeoutSeconds: 5 + env: + - name: RUST_LOG + value: actix_web=info,actix_server=info,actix_web_middleware_keycloak_auth=trace + - name: KEYCLOAK_PUBLIC_KEY + valueFrom: + secretKeyRef: + key: KC_PUBLIC_KEY + name: YOUR-PUBLIC-KEY + - name: CORS_ALLOWED_ORIGIN + value: All + - name: CORS_ALLOWED_ORIGIN_END_WITH + value: "$CORS" + name: cds + image: docker.io/entando/cds:1.0.4 + imagePullPolicy: IfNotPresent + livenessProbe: + httpGet: + scheme: HTTP + port: 8081 + path: /health/health_check + timeoutSeconds: 5 + successThreshold: 1 + periodSeconds: 30 + initialDelaySeconds: 5 + failureThreshold: 1 + ports: + - containerPort: 8080 + name: internal-port + - containerPort: 8081 + name: public-port + resources: + limits: + cpu: 1000m + memory: 500Mi + requests: + cpu: 500m + memory: 500Mi + volumeMounts: + - mountPath: /entando-data + name: cds-data-volume + volumes: + - name: cds-data-volume + persistentVolumeClaim: + claimName: YOUR-PVC-CLAIM + readOnly: false + replicas: 1 +``` + +#### Ingress Descriptor +``` +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: YOUR-INGRESS-NAME + namespace: YOUR-NAMSPACE + annotations: + nginx.ingress.kubernetes.io/configuration-snippet: | + proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for; + proxy_set_header X-Scheme \$scheme; + proxy_set_header X-Forwarded-Proto \$scheme; + add_header Content-Security-Policy upgrade-insecure-requests; + nginx.ingress.kubernetes.io/proxy-body-size: "150m" + nginx.org/client-max-body-size: "150m" +spec: + $INGRESS_CLASS_FIELD + rules: + - host: cds-YOUR-APP-NAME.YOUR-HOST-ADDRESS + http: + paths: + - backend: + service: + name: YOUR-APP-NAME-cds-YOUR-TENANT-CODE-service + port: + number: 8081 + pathType: Prefix + path: /$TN + - backend: + service: + name: $APP-cds-$TN-service + port: + number: 8080 + pathType: Prefix + path: /api/v1/ +# tls: +# - hosts: +# - cds-$APP.$HOST +# secretName: cds-tls +``` + +### Resource and Assets Archive +You will need an archive of the resources and assets required by your application. +In the archive, the resources folder must be named `public` and a confidential information must be provided in the `private` folder. + +### APIs or Postman example steps??? + +## Configure the Entando App Engine +1. scale to 0 the de-app deployment +2. open deployment of de-app and add these variables (check the right value of CDS_PUBLIC_URL): +``` + - name: CDS_ENABLED + value: "true" + - name: CDS_PUBLIC_URL + value: http://cds.10-219-168-241.nip.io/primary + - name: CDS_PRIVATE_URL + value: http://cds:8080 + - name: CDS_PATH + value: /api/v1 + +3. scale to 1 the de-app deployment and check the system, that the assets/resources provided by portal-ui are served by their CDS service From 883c35979546109f148b7395612f6cac08d29b8b Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 27 Apr 2023 16:06:52 -0500 Subject: [PATCH 02/11] ENDOC-673 mt-cds tutorial --- vuepress/docs/.vuepress/next.js | 3 +- .../docs/next/tutorials/consume/mt-cds.md | 162 ++++++++++++------ 2 files changed, 114 insertions(+), 51 deletions(-) diff --git a/vuepress/docs/.vuepress/next.js b/vuepress/docs/.vuepress/next.js index d4e100ba3b..eb1a615851 100644 --- a/vuepress/docs/.vuepress/next.js +++ b/vuepress/docs/.vuepress/next.js @@ -439,7 +439,8 @@ module.exports = { path + 'consume/high-avail-tutorial.md', path + 'consume/external-id-management.md', path + 'consume/entando-operator.md', - path + 'consume/invoking-api.md' + path + 'consume/invoking-api.md', + path + 'consume/mt-cds.md' ] }, { diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index 68bc7621e6..9581238a38 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -2,26 +2,36 @@ sidebarDepth: 2 --- -# Content Delivery Server (CDS) Integration +# Content Delivery Server for Multitenancy +You can create a content delivery server (CDS) using descriptors or a custom script to set up the configuration. Then adapt the Entando App Engine to integrate the service for your multitenant application. This tutorial applies descriptors to build the CDS. +## Prerequisites +* [A working instance of Entando.](../../../docs/getting-started/README.md) with the default Tomcat server image. -You can use a client software or a custom script to set up the content deliver service for your application. +## Create the CDS Descriptors +Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS. +### Keycloak Descriptor YAML +1. Go to Keycloak admin console and log in +2. From the left sidebar, `Realm Settings` → `Keys`. Click on `Public Key` for `rsa-generated` provider and copy the content. -## Setting up the CDS +
Alternate Method to find the Public Key -### Descriptors -Typically, four descriptors are required for the CDS, as described below. +1. Retrieve you ingress: +``` +kubectl get ing | grep default-sso | awk '{print $3} +``` +The result of this query will be YOUR-INGRESS -#### Keycloak Descriptor YAML -1. Go to Keycloak admin console and log in -2. From the left sidebar, `Realm Settings` → `Keys`. Click on `public Key for `rsa-generated` provider and copy the content. -3. Copy this public key to the descriptor file as shown in the sample below. +2. Retrieve your public key: ---- +``` +curl "http://YOUR-INGRESS/auth/realms/YOUR-NAMESPACE" | jq '.public_key' +``` + +
-
Sample Keycloak Descriptor - +3. Add the public key to your descriptor file, following the example shown here: ``` yaml apiVersion: v1 @@ -32,17 +42,12 @@ metadata: type: Opaque stringData: KC_PUBLIC_KEY: "YOUR-PUBLIC-KEY" - // YOUR-PUBLIC-KEY will be a base64 encoded string ``` -
---- +### Persistent Volume Claim Descriptor +This descriptor should provide specifications for the persistent volume claim, including accessModes and resources storage limits. - -#### Persistent Volume Descriptor -The cds-pvc.yaml should provide specificationS for the persistent volume claim including accessModes and resources storage limits. - -``` +``` yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: @@ -58,13 +63,12 @@ spec: storage: PVC-SIZE requests: storage: PVC-SIZE - #storageClassName: standard ``` -#### Deployment Descriptor -Create the deployment descriptor YAML with the specifications required for your environment in a K3s implementation. +### Service and Deployment Descriptor +Create the service and deployment descriptor YAML with the specifications required for your environment in a K3s implementation. -``` +``` yaml apiVersion: v1 kind: Service metadata: @@ -120,10 +124,10 @@ spec: secretKeyRef: key: KC_PUBLIC_KEY name: YOUR-PUBLIC-KEY - - name: CORS_ALLOWED_ORIGIN - value: All - - name: CORS_ALLOWED_ORIGIN_END_WITH - value: "$CORS" + - name: CORS_ALLOWED_ORIGIN # use for external CDS service + value: All # enter your Entando app domain name + - name: CORS_ALLOWED_ORIGIN_END_WITH # use for wildcard domain name + value: "$CORS" # enter wildcard domain name for your Entando app, e.g. *domain.com name: cds image: docker.io/entando/cds:1.0.4 imagePullPolicy: IfNotPresent @@ -144,7 +148,7 @@ spec: name: public-port resources: limits: - cpu: 1000m + cpu: 500m memory: 500Mi requests: cpu: 500m @@ -160,8 +164,8 @@ spec: replicas: 1 ``` -#### Ingress Descriptor -``` +### Ingress Descriptor +``` yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: @@ -173,8 +177,9 @@ metadata: proxy_set_header X-Scheme \$scheme; proxy_set_header X-Forwarded-Proto \$scheme; add_header Content-Security-Policy upgrade-insecure-requests; - nginx.ingress.kubernetes.io/proxy-body-size: "150m" - nginx.org/client-max-body-size: "150m" + nginx.ingress.kubernetes.io/proxy-body-size: "150m" # edit according to the file size you require + + nginx.org/client-max-body-size: "150m" # edit according to the file size you require spec: $INGRESS_CLASS_FIELD rules: @@ -195,29 +200,86 @@ spec: number: 8080 pathType: Prefix path: /api/v1/ -# tls: +# tls: # Optional; if used, the user needs to customize the Entando operator ConfigMap to also use TLS # - hosts: # - cds-$APP.$HOST # secretName: cds-tls ``` -### Resource and Assets Archive -You will need an archive of the resources and assets required by your application. -In the archive, the resources folder must be named `public` and a confidential information must be provided in the `private` folder. +
Alternate ConfigMap for TLS -### APIs or Postman example steps??? +This example ConfigMap is suggested for direct integration on Kubernetes. +``` +apiVersion: v1 +kind: ConfigMap +metadata: + name: entando-operator-config +data: + entando.pod.completion.timeout.seconds: "2000" + entando.pod.readiness.timeout.seconds: "2000" + entando.requires.filesystem.group.override: "true" + entando.ingress.class: "nginx" + entando.tls.secret.name: YOUR-TLS-SECRET + +# More.. +# entando.k8s.operator.image.pull.secrets: sample-pull-secret +# entando.docker.registry.override: "docker.io" +# entando.ca.secret.name: sample-ca-cert-secret +# entando.assume.external.https.provider: "true" +# entando.k8s.operator.impose.limits: "true" +``` + +
+ +## Apply the Descriptors +Install the CDS descriptors in the order listed below. +``` bash +kubectl apply -f YOUR-CDS-PVC.yaml +kubectl apply -f YOUR-CDS-KEYCLOAK-SECRET.yaml +kubectl apply -f YOUR-CDS-DEPLOYMENT.yaml +kubectl apply -f YOUR-CDS-INGRESS.yaml +``` +**can these be done at once** + +## Create the Assets Archive +Create an archive of the resources and assets for your application. Within it, the resources folder must be named `public` and sensitive information should be stored in the `private` folder. + +## APIs +Create API requests to include these fields: + * `CDS_PATH` : # the base path of the new CDS + * `KC_URI` : # the url of token service of the tenant1 realm + * `KC_CLIENT_ID` : # the clientId of the reserved client used by the entando-de-app in tenant1 realm + **what is the reserved client???** + * `KC_CLIENT_SECRET` : # the secret of that client ## Configure the Entando App Engine -1. scale to 0 the de-app deployment -2. open deployment of de-app and add these variables (check the right value of CDS_PUBLIC_URL): +1. Scale to 0 the de-app deployment +2. Open `entando-de-app` and add these environment variables using the : +``` yaml +spec: + env: + - name: CDS_ENABLED + value: "true" + - name: CDS_PUBLIC_URL + value: http://cds.YOUR-HOSTNAME/primary + - name: CDS_PRIVATE_URL + value: http://cds:8080 + - name: CDS_PATH + value: /api/v1 +``` +3. Delete the following two volume specifications related to the quickstart deployment: +``` yaml + volumeMounts: + - mountPath: /entando-data + name: quickstart-server-volume ``` - - name: CDS_ENABLED - value: "true" - - name: CDS_PUBLIC_URL - value: http://cds.10-219-168-241.nip.io/primary - - name: CDS_PRIVATE_URL - value: http://cds:8080 - - name: CDS_PATH - value: /api/v1 - -3. scale to 1 the de-app deployment and check the system, that the assets/resources provided by portal-ui are served by their CDS service +``` yaml + volumes: + - name: quickstart-server-volume + persistentVolumeClaim: + claimName: quickstart-server-pvc +``` + +4. Scale the `entando-de-app` deployment back to 1 and check the system. The assets and resources provided by the portal UI should be served by the CDS service. + + From c105a3109e6fed6131bf8fe8cc7d3de99a64b221 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 4 May 2023 16:16:26 -0500 Subject: [PATCH 03/11] ENDOC-673 test edits, removed API bit, placeholder names --- .../docs/next/tutorials/consume/mt-cds.md | 144 +++++++++--------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index 9581238a38..74ca890ce0 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -3,45 +3,46 @@ sidebarDepth: 2 --- # Content Delivery Server for Multitenancy -You can create a content delivery server (CDS) using descriptors or a custom script to set up the configuration. Then adapt the Entando App Engine to integrate the service for your multitenant application. This tutorial applies descriptors to build the CDS. +To create a content delivery server (CDS), use descriptors or a custom script to set up the configuration. A CDS is required for a multitenant application. Then the Entando App Engine deployment is edited to integrate the service. This tutorial describes the steps required to create and apply the CDS descriptors to support a multitenant application. ## Prerequisites * [A working instance of Entando.](../../../docs/getting-started/README.md) with the default Tomcat server image. +* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` + ## Create the CDS Descriptors Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS. +Here is a list of placeholders that will need to be replaced in the descriptor files. Use names that describe your primary tenant and the service it pertains to. +| Placeholder | Descriptions +|:--|:-- +| YOUR-APPNAME | Your app name, or the name of the entando-de-app deployment +| YOUR-HOSTNAME | Host name (e.g., k8s-entando.org) +| YOUR-NAMESPACE | Namespace used for the multitenancy application +| YOUR-PRIMARY-KC-SECRET | Name of Keycloak secret for the primary tenant +| YOUR-PRIMARY-CDS-DEPLOYMENT | CDS deployment for the primary tenant +| YOUR-PRIMARY-PVC | Name of PVC claim of the primary tenant +| YOUR-PRIMARY-CDS-SERVICE | The CDS service for the primary tenant +| YOUR-PRIMARY-CDS-DEPLOYMENT | The CDS deployment of the primary tenant +| YOUR-PRIMARY-CDS-INGRESS | The CDS ingress for the primary tenant +| YOUR-PRIMARY-TENANT | Name of the primary tenant and primary tenant code +| YOUR-PUBLIC-KEY | Keycloak RSA generated string for your realm + ### Keycloak Descriptor YAML 1. Go to Keycloak admin console and log in 2. From the left sidebar, `Realm Settings` → `Keys`. Click on `Public Key` for `rsa-generated` provider and copy the content. -
Alternate Method to find the Public Key - -1. Retrieve you ingress: -``` -kubectl get ing | grep default-sso | awk '{print $3} -``` -The result of this query will be YOUR-INGRESS - -2. Retrieve your public key: - -``` -curl "http://YOUR-INGRESS/auth/realms/YOUR-NAMESPACE" | jq '.public_key' -``` - -
- -3. Add the public key to your descriptor file, following the example shown here: +3. Create a descriptor using this example. Replace `YOUR-PUBLIC-KEY` with the result from the previous step, following the `---BEGIN ... END---\n` format shown below: ``` yaml apiVersion: v1 kind: Secret metadata: - name: YOUR-KC-SECRET + name: YOUR-PRIMARY-KC-SECRET namespace: YOUR-NAMESPACE type: Opaque stringData: - KC_PUBLIC_KEY: "YOUR-PUBLIC-KEY" + KC_PUBLIC_KEY: "-----BEGIN PUBLIC KEY-----\nYOUR-PUBLIC-KEY\n-----END PUBLIC KEY-----\n" ``` ### Persistent Volume Claim Descriptor @@ -52,30 +53,30 @@ apiVersion: v1 kind: PersistentVolumeClaim metadata: labels: - deployment: YOUR-CDS-DEPLOYMENT - name: YOUR-PVC-CLAIM + deployment: YOUR-PRIMARY-CDS-DEPLOYMENT + name: YOUR-PRIMARY-PVC namespace: YOUR-NAMESPACE spec: accessModes: - ReadWriteOnce resources: limits: - storage: PVC-SIZE + storage: 1Gi requests: - storage: PVC-SIZE + storage: 1Gi ``` ### Service and Deployment Descriptor -Create the service and deployment descriptor YAML with the specifications required for your environment in a K3s implementation. +Create the service and deployment descriptor YAML with the specifications required for your environment in a K3s implementation. For convenience, the service and deployment has been combined into a single descriptor `YOUR-PRIMARY-CDS-DEPLOYMENT.yaml`, but this is a matter of preference. ``` yaml apiVersion: v1 kind: Service metadata: - name: YOUR-CDS-DEPLOYMENT + name: YOUR-PRIMARY-CDS-SERVICE namespace: YOUR-NAMESPACE labels: - app: YOUR-CDS-DEPLOYMENT + app: YOUR-PRIMARY-CDS-SERVICE spec: ports: - port: 8080 @@ -87,25 +88,33 @@ spec: protocol: TCP targetPort: 8081 selector: - app: YOUR-CDS-DEPLOYMENT + app: YOUR-PRIMARY-CDS-DEPLOYMENT --- apiVersion: apps/v1 kind: Deployment metadata: - name: YOUR-CDS-DEPLOYMENT + name: YOUR-PRIMARY-CDS-DEPLOYMENT namespace: YOUR-NAMESPACE labels: - app: YOUR-CDS-DEPLOYMENT + app: YOUR-PRIMARY-CDS-DEPLOYMENT spec: selector: matchLabels: - app: YOUR-CDS-DEPLOYMENT + app: YOUR-PRIMARY-CDS-DEPLOYMENT template: metadata: labels: - app: YOUR-CDS-DEPLOYMENT + app: YOUR-PRIMARY-CDS-DEPLOYMENT spec: - containers: + initContainers: + - name: init-cds-data + image: busybox + imagePullPolicy: IfNotPresent + command: ['sh', '-c', 'wget --no-check-certificate https://raw.github.com/entando-ps/cds/pr-it-317/entando-data/entando720.tar.gz; tar -xf entando720.tar.gz; rm entando720.tar.gz '] + volumeMounts: + - mountPath: /entando-data + name: cds-data-volume + containers: - readinessProbe: httpGet: port: 8081 @@ -123,11 +132,11 @@ spec: valueFrom: secretKeyRef: key: KC_PUBLIC_KEY - name: YOUR-PUBLIC-KEY - - name: CORS_ALLOWED_ORIGIN # use for external CDS service + name: YOUR-PRIMARY-KC-SECRET + - name: CORS_ALLOWED_ORIGIN # # use for external CDS service value: All # enter your Entando app domain name - name: CORS_ALLOWED_ORIGIN_END_WITH # use for wildcard domain name - value: "$CORS" # enter wildcard domain name for your Entando app, e.g. *domain.com + value: "YOUR-CORS-BASEURL" # enter wildcard domain name for your Entando app, e.g. "nip.io" name: cds image: docker.io/entando/cds:1.0.4 imagePullPolicy: IfNotPresent @@ -159,7 +168,7 @@ spec: volumes: - name: cds-data-volume persistentVolumeClaim: - claimName: YOUR-PVC-CLAIM + claimName: YOUR-PRIMARY-PVC readOnly: false replicas: 1 ``` @@ -169,8 +178,8 @@ spec: apiVersion: networking.k8s.io/v1 kind: Ingress metadata: - name: YOUR-INGRESS-NAME - namespace: YOUR-NAMSPACE + name: YOUR-PRIMARY-CDS-INGRESS + namespace: YOUR-NAMESPACE annotations: nginx.ingress.kubernetes.io/configuration-snippet: | proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for; @@ -181,29 +190,29 @@ metadata: nginx.org/client-max-body-size: "150m" # edit according to the file size you require spec: - $INGRESS_CLASS_FIELD + ingressClassName: nginx rules: - - host: cds-YOUR-APP-NAME.YOUR-HOST-ADDRESS + - host: cds-YOUR-APP-NAME.YOUR-HOSTNAME http: paths: - backend: service: - name: YOUR-APP-NAME-cds-YOUR-TENANT-CODE-service + name: YOUR-PRIMARY-CDS-SERVICE port: number: 8081 pathType: Prefix - path: /$TN + path: /YOUR-PRIMARY-CDS-SERVICE ** is this correct?? ** - backend: service: - name: $APP-cds-$TN-service + name: YOUR-PRIMARY-CDS-SERVICE port: number: 8080 pathType: Prefix path: /api/v1/ -# tls: # Optional; if used, the user needs to customize the Entando operator ConfigMap to also use TLS +# tls: # Optional; the user needs to customize the Entando operator ConfigMap to also use TLS is used here # - hosts: -# - cds-$APP.$HOST -# secretName: cds-tls +# - cds-YOUR-APP-NAME.YOUR-HOSTNAME +# secretName: cds-tls ** should this be YOUR-TLS-SECRET ** ```
Alternate ConfigMap for TLS @@ -228,58 +237,49 @@ data: # entando.assume.external.https.provider: "true" # entando.k8s.operator.impose.limits: "true" ``` -
+ ## Apply the Descriptors -Install the CDS descriptors in the order listed below. +Install the CDS descriptors in the order listed below: ``` bash -kubectl apply -f YOUR-CDS-PVC.yaml -kubectl apply -f YOUR-CDS-KEYCLOAK-SECRET.yaml -kubectl apply -f YOUR-CDS-DEPLOYMENT.yaml -kubectl apply -f YOUR-CDS-INGRESS.yaml +kubectl apply -f YOUR-PRIMARY-PVC.yaml -n YOUR-NAMESPACE +kubectl apply -f YOUR-PRIMARY-KC-SECRET.yaml -n YOUR-NAMESPACE +kubectl apply -f YOUR-PRIMARY-CDS-DEPLOYMENT.yaml -n YOUR-NAMESPACE +kubectl apply -f YOUR-PRIMARY-CDS-INGRESS.yaml -n YOUR-NAMESPACE ``` -**can these be done at once** - -## Create the Assets Archive -Create an archive of the resources and assets for your application. Within it, the resources folder must be named `public` and sensitive information should be stored in the `private` folder. - -## APIs -Create API requests to include these fields: - * `CDS_PATH` : # the base path of the new CDS - * `KC_URI` : # the url of token service of the tenant1 realm - * `KC_CLIENT_ID` : # the clientId of the reserved client used by the entando-de-app in tenant1 realm - **what is the reserved client???** - * `KC_CLIENT_SECRET` : # the secret of that client ## Configure the Entando App Engine 1. Scale to 0 the de-app deployment -2. Open `entando-de-app` and add these environment variables using the : +2. Open `entando-de-app` and add these environment variables: ``` yaml spec: env: - name: CDS_ENABLED value: "true" - name: CDS_PUBLIC_URL - value: http://cds.YOUR-HOSTNAME/primary + value: http://cds-YOUR-APP-NAME.YOUR-HOSTNAME/YOUR-PRIMARY-TENANT - name: CDS_PRIVATE_URL value: http://cds:8080 - name: CDS_PATH value: /api/v1 ``` -3. Delete the following two volume specifications related to the quickstart deployment: +3. Delete the following two volume specifications related to the original `entando-de-app` deployment: ``` yaml volumeMounts: - mountPath: /entando-data - name: quickstart-server-volume + name: YOUR-APPNAME-server-volume ``` ``` yaml volumes: - - name: quickstart-server-volume + - name: YOUR-APPNAME-server-volume persistentVolumeClaim: - claimName: quickstart-server-pvc + claimName: YOUR-APPNAME-server-pvc ``` -4. Scale the `entando-de-app` deployment back to 1 and check the system. The assets and resources provided by the portal UI should be served by the CDS service. +4. Scale the deployment back to 1 and check the system. The assets and resources provided by the portal UI should be served by the CDS service. +## Create the Assets Archive +Create an archive of the resources and assets for your application. Within it, the resources folder must be named `public` and sensitive information should be stored in the `private` folder. +## APIs From 94e401b27ff0a1b82683fad2d343ef6435d26c4e Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Fri, 5 May 2023 10:09:42 -0500 Subject: [PATCH 04/11] ENDOC-673 minor edits --- vuepress/docs/next/tutorials/consume/mt-cds.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index 74ca890ce0..a65e9276ff 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -212,7 +212,7 @@ spec: # tls: # Optional; the user needs to customize the Entando operator ConfigMap to also use TLS is used here # - hosts: # - cds-YOUR-APP-NAME.YOUR-HOSTNAME -# secretName: cds-tls ** should this be YOUR-TLS-SECRET ** +# secretName: cds-tls ** should this be YOUR-TLS-SECRET to match the name for the ConfigMap below?** ```
Alternate ConfigMap for TLS @@ -239,7 +239,6 @@ data: ```
- ## Apply the Descriptors Install the CDS descriptors in the order listed below: ``` bash @@ -281,5 +280,3 @@ spec: ## Create the Assets Archive Create an archive of the resources and assets for your application. Within it, the resources folder must be named `public` and sensitive information should be stored in the `private` folder. - -## APIs From 08e13c30b524861c31a907ed6319a9d41efa93e1 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Fri, 5 May 2023 10:16:46 -0500 Subject: [PATCH 05/11] ENDOC-673 edit tar file address --- vuepress/docs/next/tutorials/consume/mt-cds.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index a65e9276ff..c447aa24f7 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -107,10 +107,10 @@ spec: app: YOUR-PRIMARY-CDS-DEPLOYMENT spec: initContainers: - - name: init-cds-data + - name: init-cds-data image: busybox imagePullPolicy: IfNotPresent - command: ['sh', '-c', 'wget --no-check-certificate https://raw.github.com/entando-ps/cds/pr-it-317/entando-data/entando720.tar.gz; tar -xf entando720.tar.gz; rm entando720.tar.gz '] + command: ['sh', '-c', 'wget --no-check-certificate https://github.com/entando-ps/cds/blob/entando720/entando-data/entando720.tar.gz?raw=true; tar -xf entando720.tar.gz; rm entando720.tar.gz '] volumeMounts: - mountPath: /entando-data name: cds-data-volume @@ -239,6 +239,7 @@ data: ``` + ## Apply the Descriptors Install the CDS descriptors in the order listed below: ``` bash From 5dbaef15f1189e8fab643787e38fb8bbe777ff17 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Fri, 5 May 2023 10:23:57 -0500 Subject: [PATCH 06/11] ENDOC-673 fix link --- vuepress/docs/next/tutorials/consume/mt-cds.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index c447aa24f7..42268a74b9 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -6,9 +6,9 @@ sidebarDepth: 2 To create a content delivery server (CDS), use descriptors or a custom script to set up the configuration. A CDS is required for a multitenant application. Then the Entando App Engine deployment is edited to integrate the service. This tutorial describes the steps required to create and apply the CDS descriptors to support a multitenant application. ## Prerequisites -* [A working instance of Entando.](../../../docs/getting-started/README.md) with the default Tomcat server image. +* [A working instance of Entando.](../../docs/getting-started/README.md) with the default Tomcat server image. -* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` +* Verify dependencies with the [Entando CLI](../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` ## Create the CDS Descriptors Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS. From 2b5bb8d33f51631de05759be4c54a9e6a4bb59d6 Mon Sep 17 00:00:00 2001 From: Nathan Shaw Date: Mon, 8 May 2023 13:33:39 -0400 Subject: [PATCH 07/11] ENDOC-673 WIP --- .../docs/next/tutorials/consume/mt-cds.md | 41 +++++++++---------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index 42268a74b9..02c4da6d00 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -3,7 +3,7 @@ sidebarDepth: 2 --- # Content Delivery Server for Multitenancy -To create a content delivery server (CDS), use descriptors or a custom script to set up the configuration. A CDS is required for a multitenant application. Then the Entando App Engine deployment is edited to integrate the service. This tutorial describes the steps required to create and apply the CDS descriptors to support a multitenant application. +An Entando Content Delivery Server (CDS) is required in order to enable multiple tenants in the same Entando application. This tutorial describes the steps required to setup CDS and configure the Entando App Engine to use it. ## Prerequisites * [A working instance of Entando.](../../docs/getting-started/README.md) with the default Tomcat server image. @@ -11,20 +11,19 @@ To create a content delivery server (CDS), use descriptors or a custom script to * Verify dependencies with the [Entando CLI](../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` ## Create the CDS Descriptors -Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS. +Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS. See the [Appendix](#appendix) for a list of required text placeholders. -Here is a list of placeholders that will need to be replaced in the descriptor files. Use names that describe your primary tenant and the service it pertains to. +Here is a list of placeholders that will need to be replaced in the descriptor files. | Placeholder | Descriptions |:--|:-- -| YOUR-APPNAME | Your app name, or the name of the entando-de-app deployment -| YOUR-HOSTNAME | Host name (e.g., k8s-entando.org) -| YOUR-NAMESPACE | Namespace used for the multitenancy application -| YOUR-PRIMARY-KC-SECRET | Name of Keycloak secret for the primary tenant -| YOUR-PRIMARY-CDS-DEPLOYMENT | CDS deployment for the primary tenant -| YOUR-PRIMARY-PVC | Name of PVC claim of the primary tenant -| YOUR-PRIMARY-CDS-SERVICE | The CDS service for the primary tenant -| YOUR-PRIMARY-CDS-DEPLOYMENT | The CDS deployment of the primary tenant +| YOUR-APPNAME | Your application name, e.g. quickstart, entando, etc. +| YOUR-HOSTNAME | Host name (e.g., your-domain.com) +| YOUR-NAMESPACE | Namespace used for the multitenancy application, e.g. entando +| YOUR-PRIMARY-KC-SECRET | Name of the Keycloak secret for the primary tenant +| YOUR-PRIMARY-CDS-DEPLOYMENT | Name of the CDS deployment for the primary tenant +| YOUR-PRIMARY-CDS-SERVICE | The name of the CDS service for the primary tenant | YOUR-PRIMARY-CDS-INGRESS | The CDS ingress for the primary tenant +| YOUR-PRIMARY-PVC | Name of the PVC claim of the primary tenant | YOUR-PRIMARY-TENANT | Name of the primary tenant and primary tenant code | YOUR-PUBLIC-KEY | Keycloak RSA generated string for your realm @@ -32,7 +31,7 @@ Here is a list of placeholders that will need to be replaced in the descriptor f 1. Go to Keycloak admin console and log in 2. From the left sidebar, `Realm Settings` → `Keys`. Click on `Public Key` for `rsa-generated` provider and copy the content. -3. Create a descriptor using this example. Replace `YOUR-PUBLIC-KEY` with the result from the previous step, following the `---BEGIN ... END---\n` format shown below: +3. Create a descriptor, e.g. primary-kc.yaml, using this example. Replace `YOUR-PUBLIC-KEY` with the result from the previous step, following the `---BEGIN ... END---\n` format shown below: ``` yaml apiVersion: v1 @@ -46,7 +45,7 @@ stringData: ``` ### Persistent Volume Claim Descriptor -This descriptor should provide specifications for the persistent volume claim, including accessModes and resources storage limits. +This descriptor should provide specifications for the persistent volume claim, including accessModes and resource storage limits. ``` yaml apiVersion: v1 @@ -67,7 +66,7 @@ spec: ``` ### Service and Deployment Descriptor -Create the service and deployment descriptor YAML with the specifications required for your environment in a K3s implementation. For convenience, the service and deployment has been combined into a single descriptor `YOUR-PRIMARY-CDS-DEPLOYMENT.yaml`, but this is a matter of preference. +Create the service and deployment descriptor YAML with the specifications required for your environment. (Note: for convenience, the service and deployment have been combined into a single descriptor YAML.) ``` yaml apiVersion: v1 @@ -108,12 +107,12 @@ spec: spec: initContainers: - name: init-cds-data - image: busybox - imagePullPolicy: IfNotPresent - command: ['sh', '-c', 'wget --no-check-certificate https://github.com/entando-ps/cds/blob/entando720/entando-data/entando720.tar.gz?raw=true; tar -xf entando720.tar.gz; rm entando720.tar.gz '] - volumeMounts: - - mountPath: /entando-data - name: cds-data-volume + image: busybox + imagePullPolicy: IfNotPresent + command: ['sh', '-c', 'wget --no-check-certificate https://github.com/entando-ps/cds/blob/entando720/entando-data/entando720.tar.gz?raw=true; tar -xf entando720.tar.gz; rm entando720.tar.gz '] + volumeMounts: + - mountPath: /entando-data + name: cds-data-volume containers: - readinessProbe: httpGet: @@ -201,7 +200,7 @@ spec: port: number: 8081 pathType: Prefix - path: /YOUR-PRIMARY-CDS-SERVICE ** is this correct?? ** + path: /YOUR-PRIMARY-CDS-SERVICE - backend: service: name: YOUR-PRIMARY-CDS-SERVICE From 95588b80c89d94640ab2b4d2f729284bab6223f2 Mon Sep 17 00:00:00 2001 From: Nathan Shaw Date: Mon, 8 May 2023 17:05:30 -0400 Subject: [PATCH 08/11] ENDOC-673 Work towards a simpler model for the template files re CDS --- .../docs/next/tutorials/consume/mt-cds.md | 277 ++---------------- 1 file changed, 32 insertions(+), 245 deletions(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index 02c4da6d00..3b5969cce2 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -3,280 +3,67 @@ sidebarDepth: 2 --- # Content Delivery Server for Multitenancy -An Entando Content Delivery Server (CDS) is required in order to enable multiple tenants in the same Entando application. This tutorial describes the steps required to setup CDS and configure the Entando App Engine to use it. +An Entando Content Delivery Server (CDS) is required in order to enable multiple tenants to be served by the same Entando application. This tutorial describes the steps required to setup CDS and configure the Entando App Engine to use it. ## Prerequisites * [A working instance of Entando.](../../docs/getting-started/README.md) with the default Tomcat server image. * Verify dependencies with the [Entando CLI](../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` -## Create the CDS Descriptors -Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS. See the [Appendix](#appendix) for a list of required text placeholders. +## Create the CDS Resources +Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS in order to separate the users and static assets for each tenant. -Here is a list of placeholders that will need to be replaced in the descriptor files. -| Placeholder | Descriptions -|:--|:-- -| YOUR-APPNAME | Your application name, e.g. quickstart, entando, etc. -| YOUR-HOSTNAME | Host name (e.g., your-domain.com) -| YOUR-NAMESPACE | Namespace used for the multitenancy application, e.g. entando -| YOUR-PRIMARY-KC-SECRET | Name of the Keycloak secret for the primary tenant -| YOUR-PRIMARY-CDS-DEPLOYMENT | Name of the CDS deployment for the primary tenant -| YOUR-PRIMARY-CDS-SERVICE | The name of the CDS service for the primary tenant -| YOUR-PRIMARY-CDS-INGRESS | The CDS ingress for the primary tenant -| YOUR-PRIMARY-PVC | Name of the PVC claim of the primary tenant -| YOUR-PRIMARY-TENANT | Name of the primary tenant and primary tenant code -| YOUR-PUBLIC-KEY | Keycloak RSA generated string for your realm - -### Keycloak Descriptor YAML -1. Go to Keycloak admin console and log in -2. From the left sidebar, `Realm Settings` → `Keys`. Click on `Public Key` for `rsa-generated` provider and copy the content. - -3. Create a descriptor, e.g. primary-kc.yaml, using this example. Replace `YOUR-PUBLIC-KEY` with the result from the previous step, following the `---BEGIN ... END---\n` format shown below: - -``` yaml -apiVersion: v1 -kind: Secret -metadata: - name: YOUR-PRIMARY-KC-SECRET - namespace: YOUR-NAMESPACE -type: Opaque -stringData: - KC_PUBLIC_KEY: "-----BEGIN PUBLIC KEY-----\nYOUR-PUBLIC-KEY\n-----END PUBLIC KEY-----\n" -``` - -### Persistent Volume Claim Descriptor -This descriptor should provide specifications for the persistent volume claim, including accessModes and resource storage limits. - -``` yaml -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - labels: - deployment: YOUR-PRIMARY-CDS-DEPLOYMENT - name: YOUR-PRIMARY-PVC - namespace: YOUR-NAMESPACE -spec: - accessModes: - - ReadWriteOnce - resources: - limits: - storage: 1Gi - requests: - storage: 1Gi -``` - -### Service and Deployment Descriptor -Create the service and deployment descriptor YAML with the specifications required for your environment. (Note: for convenience, the service and deployment have been combined into a single descriptor YAML.) - -``` yaml -apiVersion: v1 -kind: Service -metadata: - name: YOUR-PRIMARY-CDS-SERVICE - namespace: YOUR-NAMESPACE - labels: - app: YOUR-PRIMARY-CDS-SERVICE -spec: - ports: - - port: 8080 - name: internal-port - protocol: TCP - targetPort: 8080 - - port: 8081 - name: public-port - protocol: TCP - targetPort: 8081 - selector: - app: YOUR-PRIMARY-CDS-DEPLOYMENT ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: YOUR-PRIMARY-CDS-DEPLOYMENT - namespace: YOUR-NAMESPACE - labels: - app: YOUR-PRIMARY-CDS-DEPLOYMENT -spec: - selector: - matchLabels: - app: YOUR-PRIMARY-CDS-DEPLOYMENT - template: - metadata: - labels: - app: YOUR-PRIMARY-CDS-DEPLOYMENT - spec: - initContainers: - - name: init-cds-data - image: busybox - imagePullPolicy: IfNotPresent - command: ['sh', '-c', 'wget --no-check-certificate https://github.com/entando-ps/cds/blob/entando720/entando-data/entando720.tar.gz?raw=true; tar -xf entando720.tar.gz; rm entando720.tar.gz '] - volumeMounts: - - mountPath: /entando-data - name: cds-data-volume - containers: - - readinessProbe: - httpGet: - port: 8081 - path: /health/health_check - scheme: HTTP - failureThreshold: 1 - initialDelaySeconds: 5 - periodSeconds: 5 - successThreshold: 1 - timeoutSeconds: 5 - env: - - name: RUST_LOG - value: actix_web=info,actix_server=info,actix_web_middleware_keycloak_auth=trace - - name: KEYCLOAK_PUBLIC_KEY - valueFrom: - secretKeyRef: - key: KC_PUBLIC_KEY - name: YOUR-PRIMARY-KC-SECRET - - name: CORS_ALLOWED_ORIGIN # # use for external CDS service - value: All # enter your Entando app domain name - - name: CORS_ALLOWED_ORIGIN_END_WITH # use for wildcard domain name - value: "YOUR-CORS-BASEURL" # enter wildcard domain name for your Entando app, e.g. "nip.io" - name: cds - image: docker.io/entando/cds:1.0.4 - imagePullPolicy: IfNotPresent - livenessProbe: - httpGet: - scheme: HTTP - port: 8081 - path: /health/health_check - timeoutSeconds: 5 - successThreshold: 1 - periodSeconds: 30 - initialDelaySeconds: 5 - failureThreshold: 1 - ports: - - containerPort: 8080 - name: internal-port - - containerPort: 8081 - name: public-port - resources: - limits: - cpu: 500m - memory: 500Mi - requests: - cpu: 500m - memory: 500Mi - volumeMounts: - - mountPath: /entando-data - name: cds-data-volume - volumes: - - name: cds-data-volume - persistentVolumeClaim: - claimName: YOUR-PRIMARY-PVC - readOnly: false - replicas: 1 -``` - -### Ingress Descriptor -``` yaml -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: YOUR-PRIMARY-CDS-INGRESS - namespace: YOUR-NAMESPACE - annotations: - nginx.ingress.kubernetes.io/configuration-snippet: | - proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for; - proxy_set_header X-Scheme \$scheme; - proxy_set_header X-Forwarded-Proto \$scheme; - add_header Content-Security-Policy upgrade-insecure-requests; - nginx.ingress.kubernetes.io/proxy-body-size: "150m" # edit according to the file size you require - - nginx.org/client-max-body-size: "150m" # edit according to the file size you require -spec: - ingressClassName: nginx - rules: - - host: cds-YOUR-APP-NAME.YOUR-HOSTNAME - http: - paths: - - backend: - service: - name: YOUR-PRIMARY-CDS-SERVICE - port: - number: 8081 - pathType: Prefix - path: /YOUR-PRIMARY-CDS-SERVICE - - backend: - service: - name: YOUR-PRIMARY-CDS-SERVICE - port: - number: 8080 - pathType: Prefix - path: /api/v1/ -# tls: # Optional; the user needs to customize the Entando operator ConfigMap to also use TLS is used here -# - hosts: -# - cds-YOUR-APP-NAME.YOUR-HOSTNAME -# secretName: cds-tls ** should this be YOUR-TLS-SECRET to match the name for the ConfigMap below?** +1. Login to the Keycloak admin console and get the RSA key for your realm by going to `Realm Settings` → `Keys`. +2. Click on `Public Key` for `rsa-generated` provider and copy the content. This will be `YOUR-PUBLIC-KEYCLOAK-KEY` below. +3. Download the CDS descriptors template +``` bash +TODO ``` +4. Replace the following placeholders with the appropriate values for your environment: -
Alternate ConfigMap for TLS +Conventions: +* The default CDS ingress URL is the following: YOUR-APP-NAME-cds.YOUR-HOSTNAME/YOUR-TENANT-ID +* The storage limit and request is set to 1Gi and can be modified on the persistent volume claim +* The file upload size limit is set to 150m and can be configured via the ingress annotations +* In order to enable TLS, add a TLS secret and configure it on the ingress -This example ConfigMap is suggested for direct integration on Kubernetes. -``` -apiVersion: v1 -kind: ConfigMap -metadata: - name: entando-operator-config -data: - entando.pod.completion.timeout.seconds: "2000" - entando.pod.readiness.timeout.seconds: "2000" - entando.requires.filesystem.group.override: "true" - entando.ingress.class: "nginx" - entando.tls.secret.name: YOUR-TLS-SECRET - -# More.. -# entando.k8s.operator.image.pull.secrets: sample-pull-secret -# entando.docker.registry.override: "docker.io" -# entando.ca.secret.name: sample-ca-cert-secret -# entando.assume.external.https.provider: "true" -# entando.k8s.operator.impose.limits: "true" -``` -
+| Placeholder | Descriptions +|:--|:-- +| YOUR-APP-NAME | The name of the application, e.g. quickstart +| YOUR-HOST-NAME | The base host name of the application, e.g. your-domain.com +| YOUR-TENANT-ID | The identifier for the tenant, e.g. mysite1 +| YOUR-PUBLIC-KEYCLOAK-KEY | The public RSA key for the corresponding Keycloak instance. Make sure to retain the wrapping text with linefeeds: `---BEGIN PUBLIC KEY... END PUBLIC KEY---\n`. +The preceding steps can be used to create additional tenants as well, simply by providing a new tenant identifier. The same Keycloak public key can be used if the tenants share a Keycloak instance using different realms. -## Apply the Descriptors -Install the CDS descriptors in the order listed below: -``` bash -kubectl apply -f YOUR-PRIMARY-PVC.yaml -n YOUR-NAMESPACE -kubectl apply -f YOUR-PRIMARY-KC-SECRET.yaml -n YOUR-NAMESPACE -kubectl apply -f YOUR-PRIMARY-CDS-DEPLOYMENT.yaml -n YOUR-NAMESPACE -kubectl apply -f YOUR-PRIMARY-CDS-INGRESS.yaml -n YOUR-NAMESPACE -``` +# Configure the Entando App Engine to use CDS +The Entando App Engine has to be reconfigured to use CDS. This is only required when creating the initial or primary tenant in a multi-tenant setup. -## Configure the Entando App Engine -1. Scale to 0 the de-app deployment -2. Open `entando-de-app` and add these environment variables: +1. Scale the AppEngine (entando-de-app) to 0 replicas +2. Edit the EntandoApp deployment and add these environment variables: (TODO: shouldn't this be set on the EntandoApp CR instead of the deployment? Or use the configmap option?) ``` yaml spec: env: - name: CDS_ENABLED value: "true" - name: CDS_PUBLIC_URL - value: http://cds-YOUR-APP-NAME.YOUR-HOSTNAME/YOUR-PRIMARY-TENANT + value: http://YOUR-APP-NAME-cds.YOUR-HOST-NAME/YOUR-TENANT-ID - name: CDS_PRIVATE_URL - value: http://cds:8080 + value: http://YOUR-TENANT-ID-cds-service:8080 - name: CDS_PATH value: /api/v1 ``` -3. Delete the following two volume specifications related to the original `entando-de-app` deployment: +3. (Optional - is this needed if we modify the app itself?) The following two volume specifications can be removed to avoid leftover resources in the namespace. These are automaticaly created in the initial `entando-de-app` deployment: ``` yaml volumeMounts: - mountPath: /entando-data - name: YOUR-APPNAME-server-volume + name: YOUR-APP-NAME-server-volume ``` ``` yaml volumes: - - name: YOUR-APPNAME-server-volume + - name: YOUR-APP-NAME-server-volume persistentVolumeClaim: - claimName: YOUR-APPNAME-server-pvc + claimName: YOUR-APP-NAME-server-pvc ``` -4. Scale the deployment back to 1 and check the system. The assets and resources provided by the portal UI should be served by the CDS service. - -## Create the Assets Archive -Create an archive of the resources and assets for your application. Within it, the resources folder must be named `public` and sensitive information should be stored in the `private` folder. +4. Scale the deployment back to 1 and check the system. The assets and resources provided by the AppEngine should be served by the CDS service. From 1bd8a09147029013b9fece78b03ead4f5eaed879 Mon Sep 17 00:00:00 2001 From: Nathan Shaw Date: Tue, 9 May 2023 16:04:35 -0400 Subject: [PATCH 09/11] ENDOC-673 Refine the CDS tutorial using the new entando-releases template --- vuepress/docs/.vuepress/config.js | 3 +- .../docs/next/tutorials/consume/mt-cds.md | 65 ++++++++++++------- 2 files changed, 42 insertions(+), 26 deletions(-) diff --git a/vuepress/docs/.vuepress/config.js b/vuepress/docs/.vuepress/config.js index 08d9c5e8fc..eb92f44f45 100644 --- a/vuepress/docs/.vuepress/config.js +++ b/vuepress/docs/.vuepress/config.js @@ -177,7 +177,8 @@ module.exports = { entando: { fixpack: { "v70": "v7.0.2", - "v71": "v7.1.5" + "v71": "v7.1.5", + "v72": "v7.2.0" }, logoLink: "https://entando.com", section: "Docs", diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index 3b5969cce2..3b92cd24c2 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -6,28 +6,25 @@ sidebarDepth: 2 An Entando Content Delivery Server (CDS) is required in order to enable multiple tenants to be served by the same Entando application. This tutorial describes the steps required to setup CDS and configure the Entando App Engine to use it. ## Prerequisites -* [A working instance of Entando.](../../docs/getting-started/README.md) with the default Tomcat server image. - -* Verify dependencies with the [Entando CLI](../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` +* [A working instance of Entando](../../docs/getting-started/README.md) based on the default Tomcat server image. ## Create the CDS Resources -Descriptors for Keycloak access, ingress, service/deployment, and persistent volume claim are required for the CDS in order to separate the users and static assets for each tenant. +A set of resources are necessary to separate the storage and user data for each tenant. 1. Login to the Keycloak admin console and get the RSA key for your realm by going to `Realm Settings` → `Keys`. 2. Click on `Public Key` for `rsa-generated` provider and copy the content. This will be `YOUR-PUBLIC-KEYCLOAK-KEY` below. -3. Download the CDS descriptors template -``` bash -TODO -``` -4. Replace the following placeholders with the appropriate values for your environment: +3. Download the template `entando-cds.yaml`: + +curl -sLO "https://raw.githubusercontent.com/entando/entando-releases/{{ $site.themeConfig.entando.fixpack.v72 }}/dist/ge-1-1-6/samples/entando-cds.yaml" + +4. Replace the placeholders in `entando-cds.yaml` with the appropriate values for your environment: Conventions: -* The default CDS ingress URL is the following: YOUR-APP-NAME-cds.YOUR-HOSTNAME/YOUR-TENANT-ID * The storage limit and request is set to 1Gi and can be modified on the persistent volume claim * The file upload size limit is set to 150m and can be configured via the ingress annotations * In order to enable TLS, add a TLS secret and configure it on the ingress -| Placeholder | Descriptions +| Placeholder | Description |:--|:-- | YOUR-APP-NAME | The name of the application, e.g. quickstart | YOUR-HOST-NAME | The base host name of the application, e.g. your-domain.com @@ -36,24 +33,37 @@ Conventions: The preceding steps can be used to create additional tenants as well, simply by providing a new tenant identifier. The same Keycloak public key can be used if the tenants share a Keycloak instance using different realms. +5. Create the CDS resources +``` bash +kubectl apply -f entando-cds-YOUR-TENANT-ID.yaml -n YOUR-NAMESPACE +``` + # Configure the Entando App Engine to use CDS -The Entando App Engine has to be reconfigured to use CDS. This is only required when creating the initial or primary tenant in a multi-tenant setup. +::: tip +The Entando App Engine needs to be reconfigured just for the initial or primary tenant so all tenants use CDS in the same way. +::: + +1. Scale the EntandoApp deployment down to 0 replicas: +``` bash +kubectl scale deploy/YOUR-APP-NAME-deployment --replicas=0 -n YOUR-NAMESPACE +``` -1. Scale the AppEngine (entando-de-app) to 0 replicas -2. Edit the EntandoApp deployment and add these environment variables: (TODO: shouldn't this be set on the EntandoApp CR instead of the deployment? Or use the configmap option?) +2. Edit the deployment YAML +3. Add these environment variables: ``` yaml spec: - env: - - name: CDS_ENABLED - value: "true" - - name: CDS_PUBLIC_URL - value: http://YOUR-APP-NAME-cds.YOUR-HOST-NAME/YOUR-TENANT-ID - - name: CDS_PRIVATE_URL - value: http://YOUR-TENANT-ID-cds-service:8080 - - name: CDS_PATH - value: /api/v1 + containers: + - env: + - name: CDS_ENABLED + value: "true" + - name: CDS_PUBLIC_URL + value: http://YOUR-APP-NAME-cds.YOUR-HOST-NAME/YOUR-TENANT-ID + - name: CDS_PRIVATE_URL + value: http://YOUR-TENANT-ID-cds-service:8080 + - name: CDS_PATH + value: /api/v1 ``` -3. (Optional - is this needed if we modify the app itself?) The following two volume specifications can be removed to avoid leftover resources in the namespace. These are automaticaly created in the initial `entando-de-app` deployment: +3. Remove the volume and volumeMount which were automatically created by the initial install process: ``` yaml volumeMounts: - mountPath: /entando-data @@ -66,4 +76,9 @@ spec: claimName: YOUR-APP-NAME-server-pvc ``` -4. Scale the deployment back to 1 and check the system. The assets and resources provided by the AppEngine should be served by the CDS service. +4. Scale the deployment back up to 1 or more replicas: +``` bash +kubectl scale deploy/YOUR-APP-NAME-deployment --replicas=1 -n YOUR-NAMESPACE +``` + +5. Go to the home page of the Entando Application. Any images (e.g. the icons on the home page) or other static resources should be served from the CDS_PUBLIC_URL. From 074e83a5a5277d0ea2799784e2007aa79902669d Mon Sep 17 00:00:00 2001 From: Nathan Shaw Date: Wed, 10 May 2023 10:22:23 -0400 Subject: [PATCH 10/11] Update vuepress/docs/next/tutorials/consume/mt-cds.md ENDOC-673 Apply PR feedback Co-authored-by: Avdev4J <37835668+avdev4j@users.noreply.github.com> --- vuepress/docs/next/tutorials/consume/mt-cds.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index 3b92cd24c2..cf6de5dac8 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -81,4 +81,4 @@ spec: kubectl scale deploy/YOUR-APP-NAME-deployment --replicas=1 -n YOUR-NAMESPACE ``` -5. Go to the home page of the Entando Application. Any images (e.g. the icons on the home page) or other static resources should be served from the CDS_PUBLIC_URL. +5. Go to the home page of the Entando Application. Any images (e.g. the icons on the home page) or other static resources should be served from the `CDS_PUBLIC_URL`. From 294f35625bb04aca2da2bf41b75a45c1d7ac583b Mon Sep 17 00:00:00 2001 From: Nathan Shaw Date: Wed, 10 May 2023 16:11:30 -0400 Subject: [PATCH 11/11] ENDOC-673 Apply additional PR feedback --- vuepress/docs/next/tutorials/consume/mt-cds.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/tutorials/consume/mt-cds.md b/vuepress/docs/next/tutorials/consume/mt-cds.md index cf6de5dac8..d941d51e0e 100644 --- a/vuepress/docs/next/tutorials/consume/mt-cds.md +++ b/vuepress/docs/next/tutorials/consume/mt-cds.md @@ -22,7 +22,7 @@ A set of resources are necessary to separate the storage and user data for each Conventions: * The storage limit and request is set to 1Gi and can be modified on the persistent volume claim * The file upload size limit is set to 150m and can be configured via the ingress annotations -* In order to enable TLS, add a TLS secret and configure it on the ingress +* In order to enable TLS, add a TLS secret and configure it on the ingress. Note that public URLs (e.g. `CDS_PUBLIC_URL`) should use the same protocol (`http` or `https`) as the Entando Application, whereas private/cluster-level URls (e.g. `CDS_PRIVATE_URL`) should use `http`. | Placeholder | Description |:--|:-- @@ -81,4 +81,4 @@ spec: kubectl scale deploy/YOUR-APP-NAME-deployment --replicas=1 -n YOUR-NAMESPACE ``` -5. Go to the home page of the Entando Application. Any images (e.g. the icons on the home page) or other static resources should be served from the `CDS_PUBLIC_URL`. +5. You can confirm CDS is working by checking that any digital assets are served from the `CDS_PUBLIC_URL`. This includes images displayed on the sample page created by the [Welcome Wizard](../../docs/compose/welcome-wizard.md).