Exporting Components

This blog series introduces you to Entando’s Command Line Interface (ENT) which simplifies building and deploying applications for Kubernetes.

Edward Shin - Montag, 4. Oktober 2021
Tags: Technical

ENT CLI Series

  1. Simplify App Development on Kubernetes with ENT CLI
  2. Quickstart Environment
  3. Packaging and Deployment
  4. Working with Multiple Environments
  5. Exporting Components → This lesson
  6. Utilities & Diagnostics

What You’ll Learn

In this lesson, we’ll learn how to use ENT CLI to export any component from an Entando application including up to an entire application for migration to other environments.

Concept Review

Entando is an application composition platform that enables developers to compose applications from containerized components like microservices and micro frontends. Entando packages components together for deployment to Kubernetes into bundles.

Working With Bundles

Today, we’ll explore the bundler command to extract any component from an Entando application into a bundle.

$ ent bundler -h Usage: entando-bundle [options] [command] A tool to interact with Entando's Digital-Exchange bundles Options: -V, --version output the version number -h, --help output usage information Commands: from-npm [options] Generates an Entando's Content Digital-Exchange bundle k8s custom resource from-git [options] Generates an Entando's Content Digital-Exchange bundle k8s custom resource using repository from-env [options] Generates an Entando Bundle from an existing environment into the current or selected location

Entando Bundler has 3 primary commands:

  1. from-npm: For legacy support. No longer used in the latest version (6.3+).
  2. from-git: For packaging components for deployment to Kubernetes.
  3. from-env: For exporting application components for migration to other environments.

Note: Entando’s Digital-Exchange is now the Entando Component Repository. Think of this as the nexus or hub to share ready-to-use components with other development teams across one or more Entando applications.

Exporting Components From Your Application

Let’s take a look at the from-env sub command to find out how to export components from a running Entando application.

$ ent bundler from-env -h Usage: entando-bundle from-env [options] Generates an Entando Bundle from an existing environment into the current or selected location Options: --env The location for the env.json file containing the description of the environment to export (default: "env.json") --location The location for where to store the generated Bundle (default: "./") --code The code (unique identifier) for the Bundle --description The description of the Bundle -h, --help output usage information

Configure Environment Access

To configure access to your Entando application, we’ll need:

  1. Authorization
  2. Access to Entando APIs
  3. Access to Kubernetes APIs

These are configured by creating an env.json file.

{ # Access to Entando APIs "coreBaseApi": "http:///entando-de-app", # Access to Entando Cluster Infrastructure APIs "k8ssvcApi": "http:///k8s", # Keycloak Client ID to access Entando APIs "clientId": "", # Keycloak Secret "clientSecret": "" }

Authorization

To grant authorization to access Entando’s APIs, create a Keycloak Client with the relevant roles.

Entando APIs

Entando’s APIs are exposed via the Entando App Engine. We can find the URL for the Entando App Engine from the ingress:

ent kubectl get ingress -n entando -o jsonpath='{.items[2].spec.rules[*].host}{.items[2].spec.rules[*].http.paths[0].path}{"\n"}'

Sample Output: quickstart-entando.192.168.64.40.nip.io/entando-de-app

Note: The jsonpath is a convenience command to get the URL directly, but you can also look up the URLs using standard kubectl commands.

ent kubectl get ingress -n entando -o yaml

Kubernetes APIs

Finally, we can access the Kubernetes APIs via the Entando Cluster Infrastructure.

ent kubectl get ingress -n entando -o jsonpath='{.items[1].spec.rules[*].host}{.items[1].spec.rules[*].http.paths[*].path}{"\n"}'

Sample Output: quickstart-eci-entando.192.168.64.40.nip.io/k8s

Sample env.json

Here’s what your env.json should look like one you’ve completed the steps:

{ "coreBaseApi": "http://quickstart-entando.192.168.64.40.nip.io/entando-de-app", "k8ssvcApi": "http://quickstart-eci-entando.192.168.64.40.nip.io/k8s", "clientId": "entando-bundler", "clientSecret": "da95278e-40db-4be4-9aaf-88eaf2b6070b" }

Interactive Command Line

The Entando Bundler can be run as an interactive terminal application or as a single command for scripting.

$ ent bundler ? What do you want to do? (Use arrow keys) Generate a custom-resource based on an existing bundle project ❯ Create a new bundle using components from an environment

In our case, let’s export the components from an existing environment.

Entando Environment

? Please select an env.json file with the environment variables: (env.json)

Press enter to select the default location to read your env.json from the current working directory.

Select Components

? Which type of components do you want to add to the bundle? (Use arrow keys) ❯ All components Pages Page templates UX Fragments Microfrontends / Widgets Microservices Content Types Contents CMS Assets Groups Categories Labels

Select “All components” to export the entire application.

Collecting all components from the provided environment... Collecting widgets Collecting pageModels Collecting fragments Collecting pages Collecting groups Collecting contentTypes Collecting contentModels Collecting assets Collecting contents Collecting plugins Collecting categories Collecting labels Collecting languages ? Do you want to generate the Bundle with the selected components? (Y/n) y

Bundle Directory

? Where do you want to generate the Bundle? (./)

Press enter to generate the bundle and its components in the current working directory.

Unique Identifier

? What's the code for the Bundle?

Enter a unique identifier for the bundle (e.g., “export-bundle”).

Bundle Description

? Please add a description to the Bundle:

Enter a description for the bundle (e.g., “Sample Export Bundle”).

Sample Output

Once you’ve finished entering the prompts, ENT will generate a bundle with all of the frontend and backend components needed to recreate your Entando application.

Generating bundle... Collecting File: ... Processing widget: hello-widget ... Processing pageModel: 1-2-column ... Processing fragment: breadcrumb ... Processing page: homepage ... Processing contentType: bnr ... Processing content: bnr2 ... Processing contentModel: 2-column-content ... Processing labels Processing languages Saving bundle descriptor at ./descriptor.yaml

Run as a Single Command

You can also run the bundler as a single command for scripting.

$ ent bundler from-env \ --env env.json \ --code export-bundle \ --description "Sample Export Bundle"

ent-cli-generated-bundle.png

How to Use

The ability to export an entire Entando application as frontend and backend components opens up several practical uses for developers.

Backup & Restore

In addition to backing up individual components, developers can export an Entando application at a specific point in time including all application level code like microservices and JavaScript micro frontends as well as page templates and user editable content. Developers are able to “image” an entire Entando application as code, version it in a Git repository, and create multiple restore points.

Data Migration

Infrastructure teams can use the bundler command to:

  1. Migrate an entire Entando application including all data, content, and styling from DEV to QA to PROD.
  2. Take an exact snapshot of a running Entando application in a production environment including any user editable content.
  3. Create a staging environment where content editors can make changes and preview website updates before pushing those changes live.

Unlike typical scenarios where the data, file system, and code are backed up separately, ENT simplifies life for infrastructure teams by enabling backup, restore, and migration with a single command.

Packaged Business Capabilities

System integrators can create “solution templates” for business teams to quickly bring up an HR Portal, generate sites that are customized to the organization’s needs and requirements, and deliver Packaged Business Capabilities that deliver a specific business need or value that can be installed by one or more Entando applications.

Packaging Components For Deployment to Kubernetes

In a previous blog post in this series, we covered how ENT makes it easy for developers to deploy application updates to Kubernetes:

  1. Build project: ent prj init
  2. Publish to GitHub: ent prj pbs-publish
  3. Deploy to Kubernetes: ent prj deploy
  4. Install in your Entando Application: ent prj install

Behind the scenes, ENT uses the bundler “from-git” command to package the components for deployment to Kubernetes during the deploy step.

ent bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml

The output of the command is a Kubernetes Custom Resource yaml. Developers should use the “ent prj” commands to simplify their development lifecycle, but we’ll also cover how Entando uses Kubernetes Custom Resources to deploy updates to your application.

How Entando Deploys Application Updates to Kubernetes

  1. Package your components for deployment as a bundle.
    (Kubernetes Custom Resource: EntandoDeBundle)
  2. Apply the Custom Resource in your cluster (kubectl apply).
  3. Get the list of available bundles (Custom Resources) from the Entando Component Repository (ECR).
  4. Install the bundle from the ECR.
    1. Pull CMS assets from the specified GitHub repository, and add them to Entando’s database.
    2. Pull static resources from the specified GitHub repository, and upload them to Entando’s File Browser.
    3. (Microservices): Read the manifest and install or update the pod for that image, and add the corresponding service and ingress.

What’s Next?

In this blog, we learned how to use the bundler command to:

  1. Backup and restore an Entando application.
  2. Migrate an Entando application across environments.
  3. Create Packaged Business Capabilities. → Bundled solutions that meet a specific business need or value.
  4. Package updates for deployment to Kubernetes.

In the next lesson, we’ll cover the diagnostics and utilities ENT provides to help debug problems in your Entando application.

WHITE PAPER

CIO Alert - There is an Application Composition Platform in your Future

By Massimo Pezzini, Independent IT Advisor

HERUNTERLADEN

White-Paper-Pattern_mockup 3.png