Merge pull request #480 from entando/ENDOC-323

Endoc 323

vuepress/docs/next/docs/curate/ecr-bundle-details.md

@@ -4,7 +4,6 @@ sidebarDepth: 2
 
 # Bundle and Component Descriptors 
 
-## Overview
 The Entando Component Manager reads the `descriptor.yaml` file from the root of the bundle package and uses it to install any components and resources included in the bundle. 
 
 The different component types are shown below:
@@ -42,58 +41,59 @@ The bundle descriptor YAML file aggregates all included components and has the s
 
       # Optional. Use if the component requires deployment
       plugins:
-        - folder/you/want/my_plugin_descriptor.yaml
+        - folder/you/want/your_plugin_descriptor.yaml
         - folder/you/want/another_plugin_descriptor.yaml
 
       # To create Widgets, add references to the descriptor files 
       widgets:
-        - widgets/my_widget_descriptor.yaml
+        - widgets/your_widget_descriptor.yaml
         - widgets/another_widget_descriptor.yaml
 
       # To create Fragments, add references to the descriptor files 
       fragments:
-        - fragments/my_fragment.yaml
+        - fragments/your_fragment.yaml
 
       # To create Page Templates, add references to the descriptor files 
       pageModels:
-        - pageModels/my_page_model_descriptor.yaml
+        - pageModels/your_page_model_descriptor.yaml
         - pageModels/another_page_model_descriptor.yaml
 
       # To create and publish Pages, add references to the descriptor files 
       pages:
-        - page/my_page_descriptor.yaml
+        - page/your_page_descriptor.yaml
         - page/another_page_descriptor.yaml
 
-      # To create a CMS Asset, add a reference to the descriptor file in the same location as the image or file you want to upload
+      # To create a CMS Asset, add a reference to the descriptor file in the same location 
+      # as the image or file you want to upload
       assets:
-        - assets/my-asset/my_asset_descriptor.yaml
-        - assets/my-asset/my_image.jpg
+        - assets/your-asset/your_asset_descriptor.yaml
+        - assets/your-asset/your_image.jpg
 
       # To create Content Types, add references to the descriptor files
       contentTypes:
-        - contentTypes/my_content_type_descriptor.yaml
+        - contentTypes/your_content_type_descriptor.yaml
 
       # To create Content Templates, add references to the descriptor files
       contentModels:
-        - contentModels/my_content_model_descriptor.yaml
+        - contentModels/your_content_model_descriptor.yaml
         - contentModels/another_content_model_descriptor.yaml
 
       # To create and publish Contents, add references to the descriptor files
       contents:
-        - contents/my_content_descriptor.yaml
+        - contents/your_content_descriptor.yaml
         - contents/another_content_descriptor.yaml
         
       # To create Categories, add references to the descriptor files
       categories:
-        - categories/my_categories.yaml
+        - categories/your_categories.yaml
         
       # To create Groups, add references to the descriptor files
       groups:
-        - groups/my_groups.yaml
+        - groups/your_groups.yaml
         
       # To create Labels, add references to the descriptor files
       labels:
-        - labels/my_labels.yaml
+        - labels/your_labels.yaml
       
       # To enable Languages, add references to the descriptor files
       languages:
@@ -105,28 +105,55 @@ Here is an example of a plugin descriptor:
 
 **Plugin descriptor.yaml**
 
-    image: "entando/my-image:1.0.0" # The Docker image used to create the plugin
-    deploymentBaseName: "myplugin" # The base name to assign to pods that have to be created in Kubernetes
-    dbms: "postgresql" # The DBMS the plugin will use
-    roles: # The roles the plugin will expose in Keycloak
+
+    # Descriptor version field added in v3 and later. 
+    # To take advantage of the environment variables below, v4 will need to be specified.
+    descriptorVersion: "v4" 
+
+    # The Docker image used to create the plugin
+    image: "entando/your-image:1.0.0" 
+
+    # The base name to assign to pods that have to be created in Kubernetes
+    deploymentBaseName: "yourplugin" 
+
+    # The DBMS the plugin will use
+    dbms: "postgresql" 
+
+    # The roles the plugin will expose in Keycloak
+    roles: 
       - "task-list"
       - "task-get"
       - "connection-list"
       - "connection-get"
       - "connection-create"
       - "connection-delete"
       - "connection-edit"
-    healthCheckPath: "/actuator/health" # The health check path that Kubernetes will use to check the status of the plugin deployment
-    ingressPath: "/myhostname.io/entando-plugin" # the ingress path to assign to the plugin deployment
-    permissions: # a list of Keycloak clientIds / roles to bind to one another
+
+    # The health check path that Kubernetes will use to check the status 
+    # of the plugin deployment  
+    healthCheckPath: "/actuator/health" 
+
+    # The ingress path to assign to the plugin deployment 
+    ingressPath: "/your-plugin-path"
+
+    # A list of Keycloak clientIds/roles to bind to one another
+    permissions: 
       - clientId: realm-management
         role: manage-users
       - clientId: realm-management
         role: view-users
-    environmentVariables: # a set of environment variables that can be set inline or reference secrets in the namespace
-      - name: MY_SIMPLE_VAR
-        value: mySimpleValue
-        
+
+    # A set of environment variables that can be set inline or 
+    # referenced as Secrets in the namespace. Supported as of descriptorVersion v4.
+    environmentVariables:
+      - name: SIMPLE_VAR  # directly injects the value
+        value: yourSimpleValue
+      - name: SECRET_VAR  # leverages a secret value
+        valueFrom:
+          secretKeyRef:
+            name: YOUR-BUNDLE-ID-your-secret
+            key: yourSecretKey
+
 ::: tip  
  Entando uses the `healthCheckPath` to monitor the health of the plugin. A plugin in an Entando Bundle can use any technology, as long as it provides a health check service configured via the `healthCheckPath`. This path must be specified in the descriptor file and return an HTTP 200 or success status. This can be implemented by a Java service included with the Entando Blueprint in the Spring Boot application. You can also [use a Node.js service as shown here](https://github.com/entando-samples/ent-project-template-node-ms/blob/main/src/main/node/controller/health-controller.js). 
 :::
@@ -135,19 +162,6 @@ Here is an example of a plugin descriptor:
 See the [Plugin Environment Variables](../../tutorials/devops/plugin-environment-variables.md) tutorial to setup environment variables, either inline or based on Kubernetes Secrets.
 :::
 
-### Kubernetes Pod Names
-
-Each plugin is deployed into Kubernetes using composite names. The first string is created by reading the descriptor file. The second string is appended autonomously by Kubernetes and 31 characters long. Each Kubernetes pod name length must not exceed 63 characters or the deployment will fail.
-
-**DeploymentBaseName**
-
-Previously, the first segment of the pod name was generated by concatenating and manipulating the `image` field value. However, this approach could result in a pod name longer than 63 characters.
-To solve this problem, another (optional) property is available: `deploymentBaseName`, which accepts a string of up to 32 characters. If present, its value will be used as the first part of the pod name instead of the variant of the `image` value.
-
-If the `deploymentBaseName` property is not present in the previous descriptor example, a possible pod name is `entando-my-image-1-0-0-server-deployment-6f86f459wj9k`. If the `deploymentBaseName` property is present, a possible pod name is `myplugin-server-deployment-6f86f459wj9k`.
-
-If you are using the `deploymentBaseName` property and want to install more versions of the same plugin at the same time, you need to specify different values for `deploymentBaseName` (perhaps including the plugin version).
-
 ### Permissions
 
 The `permissions` property specifies a list of coupled `clientIds` and roles that will be bound in Keycloak. To find them, open the Keycloak console and navigate to `clients` → `awesomeplugin-server` → `Service Account Roles`.
@@ -170,7 +184,7 @@ Here is an example of a Widget descriptor:
 
     # Optional. The Custom UI
     customUi: >-
-        <h1>My custom Widget UI</h1>
+        <h1>Your Custom Widget UI</h1>
 
     # Optional. The ConfigUI
     configUi:
@@ -184,11 +198,11 @@ Here is an example of a Fragment descriptor:
 
 **Fragment descriptor.yaml**
 
-    code: my_fragment # The unique ID
+    code: your_fragment # The unique ID
 
     # Optional. The Fragment content
     guiCode: >-
-      "<div>Here the content</div>"
+      "<div>Here is the content</div>"
 
     # Optional. A path to a FreeMarker file containing the Fragment content
     guiCodePath: fragment.ftl
@@ -217,7 +231,7 @@ Here is an example of a Page Template descriptor:
             x2: 11
             y2: 1
           defaultWidget:
-            code: my-widget # the Widget code to apply when using the button "apply default widgets" in the page configuration UI
+            code: your-widget # the Widget code to apply when using the button "apply default widgets" in the page configuration UI
 
         # A simplified way to define a Frame
         - pos: 1
@@ -255,7 +269,7 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The
     code: dashboard
     parentCode: homepage
     titles:
-      en: My dashboard
+      en: your dashboard
       it: La mia Dashboard
     pageModel: dashboard
     ownerGroup: free
@@ -301,7 +315,7 @@ This descriptor contains the metadata required for uploading and updating a CMS
 
 **Asset descriptor.yaml**
 
-    correlationCode: 'my-reference-code'
+    correlationCode: 'your-reference-code'
     type: image
     # This file should be placed in the same folder as the descriptor.yaml
     name: 113f4437cac3b3f3d4db7229f12287a4_d3.png
@@ -453,21 +467,21 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and
         elements:
           - code: links
             value:
-              symbolicDestination: '#!U;http://www.mysite.com/!#'
+              symbolicDestination: '#!U;http://www.yoursite.com/!#'
               destType: 1
-              urlDest: 'http://www.mysite.com/'
+              urlDest: 'http://www.yoursite.com/'
               pageDest: null
               contentDest: null
               resourceDest: null
             values:
-              en: mio sito
+              en: vostro sito
           - code: links
             value:
-              symbolicDestination: '#!U;http://www.mysite.com/!#'
+              symbolicDestination: '#!U;http://www.yoursite.com/!#'
               destType: 1
-              urlDest: 'http://www.mysite.com/'
+              urlDest: 'http://www.yoursite.com/'
             values:
-              en: mio sito 2
+              en: vostro sito 2
       - code: attaches
         elements:
           - code: attaches
@@ -495,18 +509,18 @@ This descriptor contains a list of Groups:
 
 **Group descriptor.yaml**
 
-    - code: my_group # Identifies the Group
-      name: "My group" # The name of the Group
+    - code: your_group # Identifies the Group
+      name: "Your group" # The name of the Group
 
 ## Labels
 This descriptor contains a list of Labels:
 
 **Label descriptor.yaml**
 
-    - key: MY-FIRST-LABEL # Identifies the Label
+    - key: YOUR-FIRST-LABEL # Identifies the Label
       titles: # The titles on the Label
-        it: Mio Titolo # The title in Italian
-        en: My Title # The title in English
+        it: Vostro Titolo # The title in Italian
+        en: Your Title # The title in English
 
 ## Languages
 This descriptor contains a list of Languages to enable during the installation process:
@@ -535,7 +549,7 @@ In order to upload static files, you will need to create a folder called `resour
 
 Using the structure above, the resultant files in the Entando architecture will be:
 
-    yourbundleid/
+    your-bundle-id/
     ├ css/
     │ └ styles.css
     ├ js/
@@ -547,11 +561,11 @@ Using the structure above, the resultant files in the Entando architecture will
 
 > **Important**
 >
-> The `code` property `yourbundleid` is inside `descriptor.yaml`.
+> The `code` property `your-bundle-id` is inside `descriptor.yaml`.
 
 To use static files in a Widget or Page Template, use the FTL tag `<@wp.resourceURL />`:
 
-    <img src="<@wp.resourceURL />yourbundleid/images/logo.png">
-    <link rel="stylesheet" href="<@wp.resourceURL />yourbundleid/css/styles.css">
-    <link rel="shortcut icon" href="<@wp.resourceURL />yourbundleid/images/favicon.ico" type="image/x-icon"/>
-    <script type="application/javascript" src="<@wp.resourceURL />yourbundleid/js/script.js"></script>
+    <img src="<@wp.resourceURL />your-bundle-id/images/logo.png">
+    <link rel="stylesheet" href="<@wp.resourceURL />your-bundle-id/css/styles.css">
+    <link rel="shortcut icon" href="<@wp.resourceURL />your-bundle-id/images/favicon.ico" type="image/x-icon"/>
+    <script type="application/javascript" src="<@wp.resourceURL />your-bundle-id/js/script.js"></script>

vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md

@@ -70,10 +70,9 @@ ent jhipster --blueprints entando
           - If no database is selected you'll be building a stateless microservice, which is a valid choice, but the rest of this tutorial won't work.
     - `Which *production* database would you like to use?` (PostgreSQL or MySQL)
     - `Which *development* database would you like to use?` (H2 with disk-based persistence)
-    - `Which cache do you want to use? (Spring cache abstraction)` (Caffeine (local cache, for a single node))
+    - `Do you want to use the Spring cache abstraction?` (Yes, with the Caffeine implementation (local cache, for a single node))
     - `Do you want to use Hibernate 2nd level cache?` (Yes)
     - `Which other technologies would you like to use?` (**Don't select any other technologies**)
-    - `Which BE dependencies do you want to use?` (**Dependencies maintained by Entando (entando/entando-bundle-bom)**)
     - `What name would you give to the bundle to share on an Entando Component Repository?` (Up to you)
     - `Which is the organization name to use when publishing the docker image?` (**Enter the name of the organization where you are going to push your Docker image. If you're using your personal Docker hub account enter your username.**) <-- this can be changed later as needed
     - `Would you like to generate micro frontends when creating entities?` (Always)

vuepress/docs/next/tutorials/devops/plugin-environment-variables.md

@@ -46,7 +46,7 @@ environmentVariables:
         name: YOUR-BUNDLE-ID-my-secret
         key: mySecretKey
 ```
-4. [Build and deploy](../create/pb/publish-project-bundle.html) the updated bundle.
+4. [Build and deploy](../create/pb/publish-project-bundle.md) the updated bundle.
 
 ## Verify the Environment Variables
 

vuepress/docs/next/tutorials/solution/entando-hub.md

@@ -83,7 +83,7 @@ The key entities in the Entando Hub are:
 
 - `Bundle Group`: A Bundle Group is a group of one or more Entando Bundles. 
 - `Bundle Group Version`: A Bundle Group can have one or more versions, each with a particular status.
-- `Bundle`: A Bundle is the deployment unit within an Entando Application. A Bundle can contain one or multiple components such as micro frontends, microservices, or any of the [component types](../../docs/curate/ecr-bundle-details.md#overview) available in Entando. 
+- `Bundle`: A Bundle is the deployment unit within an Entando Application. A Bundle can contain one or multiple components such as micro frontends, microservices, or any of the [component types](../../docs/curate/ecr-bundle-details.md) available in Entando. 
 - `Category`: Each Bundle Group belongs to a specific category. The initial possible categories are Solution Template, Packaged Business Capability (PBC), or Component Collection. An admin of an Entando Hub can refine the available categories as desired.
 - `Organization`: Bundle Groups belong to a single organization. Authors and managers can only update Bundle Groups for their own organization.  
 - `User`: User identity is managed within Keycloak, where users are granted roles within the Hub. Users must be assigned to a specific organization.