Skip to content

Commit

Permalink
m4
Browse files Browse the repository at this point in the history
  • Loading branch information
jayachristina committed Dec 10, 2024
1 parent 5e761d1 commit ceeedf8
Show file tree
Hide file tree
Showing 6 changed files with 53 additions and 58 deletions.
Binary file modified content/modules/ROOT/assets/images/m4/import-templates-list.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified content/modules/ROOT/assets/images/m4/nav-create.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified content/modules/ROOT/assets/images/m4/nav-register-wizard.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions content/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@
** xref:module-03.7.adoc[3.7 Platform Engineer Activity: Setup RBAC]
* xref:m4/module-04.0.adoc[4. Accelerate Developer Inner-Loop]
** xref:m4/module-04.1.adoc[4.1 Import Existing API/Apps]
** xref:m4/module-04.2.adoc[4.2 Onboard parasol application]
** xref:m4/module-04.1.adoc[4.1 Introduction to Concepts]
** xref:m4/module-04.2.adoc[4.2 Platform Engineer Activity: Setup Software Templates]
** xref:m4/module-04.3.adoc[4.3 Developer environment]
Expand Down
75 changes: 35 additions & 40 deletions content/modules/ROOT/pages/m4/module-04.2.adoc
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
:imagesdir: ../../assets/images


= Module 4.2: Import Existing API/Apps
== Platform Engineer Activity: Setup Software Templates Import Existing API/Apps

include::../style.adoc[]

Platform Engineering team creates two templates for importing existing Apps/Services and APIs into Developer Hub. While it is possible to use the same template to import both of them, there are some key differences in data gathered. As best practice, Platform Engg team creates as many Software Templates as necessary to assist developers.

== Explore and Import the `import-existing-api` Software Template

== Register the Import API/App Software Templates

Since you have already learnt how to create a Software Template, we will walk through a template that has been built for you.

Expand All @@ -30,36 +29,32 @@ image:m4/st-api-steps.png[width=70%]
Gitlab allows only one type of action (such as Amend/Update) in a given Merge Request (MR). Therefore, we need a one MR to _create_ the the new catalog-info and TechDocs file, and another MR to _update_ the envelope location file with a reference to the catalog-info.yaml file
====


== Add the the `import-api-catalog` Software Template to Developer Hub
=== Register Import API Software Template

* Access Red Hat Developer Hub (https://backstage-backstage.{openshift_cluster_ingress_domain}[click here^, window="_rhdh"]) and login using `pe1/{common_password}`
* Click on the Create menu on the left-hand navigation.

image::./m4/nav-create.png[]
+
image::m4/nav-create.png[]
* Click on the `Register Existing Component` button on the top-right of the page to launch the *Register an existing component* wizard

image::./m4/nav-register-wizard.png[]
* Paste the following URL into the `Select URL` field and click on *Analyze* button
+
image::m4/nav-register-wizard.png[]
* Paste the following URL into the `Select URL` field and click on *Analyze* button. This URL points to Software Template's https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/import-existing-api-template/-/blob/main/template.yaml[template.yaml, window="gitlab"] file.
+
[source,bash,role=execute,subs="attributes"]
----
https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/import-existing-api-template/-/blob/main/template.yaml
----
* Review, and Import the template by clicking on the *Import* button
+
image::m4/nav-register-import.png[]

image::./m4/nav-register-import.png[]

* Click on *import-api-catalog* to launch the API

image::./m4/nav-access-api-template.png[]

* Let us now register the import-app template as well

* The *import-api-catalog* Template is successfully registered
+
image::m4/nav-access-api-template.png[]

== Explore and Import the `import-existing-app` Software Template
=== Register Import App Software Template

* Repeat the same steps to import the `import-existing-app-template`
* Let us now register the import-app template as well similar to the *Import API* template.
* Click *Create* (left hand nav) -> *Register Existing Component* (top right)
* Paste the following URL
+
Expand All @@ -69,46 +64,46 @@ https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/import-existing-ap
----
* Review, and Import the template by clicking on the *Import* button

== View available templates
=== View the imported templates

* Navigate back to *Create* (left hand nav) and you should be able to see both the templates for importing APIs and Apps to Developer hub

image::./m4/import-templates-list.png[width=70%]
+
image::m4/import-templates-list.png[width=70%]


== Setup Developer Hub config

== Prepare Red Hat Developer Hub with the right Dynamic Plugin
=== Enable Dynamic Plugins

The templates described above need a couple of Dynamic Plugins.
The Import API/APP templates described above need a couple of Dynamic Plugins.

*What are Dynamic Plugins?* +
* The `roadiehq-scaffolder-backend-module-utils-dynamic` plugin helps in manipulating file system, and in this case helps in update the the Catalog Envelope file with references to the new component being imported.
* The `backstage-plugin-catalog-backend-module-gitlab-dynamic` plugin helps to discover catalog files located in your GitLab instance.
+
.What are Dynamic Plugins?
[%collapsible]
====
The Red Hat Developer Hub application offers a unified platform with various plugins. Plugins extend functionality, streamline development workflows, and improve the developer experience. You can add and configure plugins in RHDH to access various software development tools. RHDH provides both static and dynamic plugins that enhance its functionality. Static plugins are integrated into the core of the RHDH application, while dynamic plugins can be side-loaded into your Developer Hub instance without the need to recompile your code or rebuild the container.
====

The import-existing-app/api templates need 2 dynamic plugins that are described below.

1. `roadiehq-scaffolder-backend-module-utils-dynamic`: This plugin helps in manipulating file system, and in this case helps in update the the Catalog Envelope file with references to the new component being imported
2. `backstage-plugin-catalog-backend-module-gitlab-dynamic`: This plugin helps to discover catalog files located in your GitLab instance. In the next step we will turn ON the auto-discovery feature.


=== Update RHDH config

. Visit your https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/developer-hub-config/-/edit/main/values.yaml[rhdh/developer-hub-config repository on GitLab^, window="_gitlab"].
. Visit your https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/developer-hub-config/-/edit/main/values.yaml[rhdh/developer-hub-config repository on GitLab^, window="_gitlab"]. If prompted, login using `pe1/{common_password}`.
. You should already be in Edit mode of the `values.yaml` file.
. Locate the comment `--- DYNAMIC_PLUGINS_IMPORT_COMPONENTS ---`
. Highlight the YAML as shown in the below screenshot, and comment those lines. Type `CMD + / or CTRL + /` command to do so.
+
image::./m4/uncomment-dynamic-plugin.png[width=60%]
image::m4/uncomment-dynamic-plugin.png[width=60%]
. Don't Save yet. We need to next turn on auto-discovery

== Turn auto-discovery
== Turn on auto-discovery
. Locate the comment `--- AUTO_DISCOVERY_IMPORT_COMPONENTS ---`
. Highlight the YAML as shown in the below screenshot, and comment those lines. Type `CMD + / or CTRL + /` command to do so.
+
image::./m4/uncomment-auto-discovery.png[width=60%]
image::m4/uncomment-auto-discovery.png[width=60%]
. This YAML snippet enables auto-discovery for all files named *envelope.yaml* [entityFilename] where the repo name starts with the word *envelope* [projectPattern]. The Catalog Envelope for Parasol is called *envelope-catalog-parasol*
. Go ahead and commit the file now using the *Commit Changes* button at the bottom of the page.
+
image::./m4/commit-rhdh-config.png[]
image::m4/commit-rhdh-config.png[]

== Refresh RHDH on Argo

Expand All @@ -119,7 +114,7 @@ Argo is tuned to pull changes from the repo every two minutes or so. Instead of
* *Password* : {openshift_gitops_password}
* Click on the *Refresh* button of the *backstage* stage to trigger a refresh; this will sync the content from Gitlab.
+
image::./m4/rhdh-argo-refresh.png[]
image::m4/rhdh-argo-refresh.png[]
* The card will turn green when it is ready. Go ahead and refresh RHDH. This might take a minute or so, since the backstage pod gets redeployed with the new configuration


Expand All @@ -136,7 +131,7 @@ https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/rhdh-entities/-/bl
----
. Click *Import* in the Review section.
+
image::./m4/rhdh-system.png[width=60%]
image::m4/rhdh-system.png[width=60%]
. The Systems and Domain are setup. These help form an important abstraction level to help us reason about software ecosystems.
* _systems_ are the basic level of encapsulation for related entities
* _domains_ are useful to group a collection of systems that share terminology, domain models, business purpose etc.
Expand Down
32 changes: 16 additions & 16 deletions content/modules/ROOT/pages/m4/module-04.4.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -35,82 +35,82 @@ https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/parasol-store-dev-
* Click here to access the repo https://gitlab-gitlab.{openshift_cluster_ingress_domain}/parasol/parasol-store
* Click on the *(+)* button as shown in the screenshot below, and click on *New branch* menu
+
image:./m4/create-branch.png[width=65%]
image:m4/create-branch.png[width=65%]

* Name the branch as `my-feature-branch` so as to make it easier to follow the rest of the instructions
+
image:./m4/create-branch-name.png[width=70%]
image:m4/create-branch-name.png[width=70%]

=== Onboard the Feature Branch using template

* In {product_name_rhdh}, choose the *Create* side-menu, and you will see the *Parasol Store Development* template. Click on *Choose*

image:./m4/choose-parasol-store-template.png[width=30%]
image:m4/choose-parasol-store-template.png[width=30%]

* In *Step 1: Provide Information for the isolated dev environment deployment*
** Enter the feature-branch name `my-feature-branch` or the name you have picked for your branch.

image:./m4/choose-parasol-store-template-step1.png[]
image:m4/choose-parasol-store-template-step1.png[]

* In *Step 2: Provide database information*
** Keep all the fields as it is - no need to make changes. The parameters are already set based on the OpenShift Service names from the existing deployments of the application

image:./m4/choose-parasol-store-template-step2.png[]
image:m4/choose-parasol-store-template-step2.png[]

* Click on *Review*, and proceed to *Create*

image:./m4/choose-parasol-store-template-step3.png[]
image:m4/choose-parasol-store-template-step3.png[]

* Click on the *Open component on catalog* link

image:./m4/parasol-branch-component.png[]
image:m4/parasol-branch-component.png[]

** You can see under the *CI* tab, a pipeline is already running
+
image:./m4/parasol-branch-first-pipeline.png[]
image:m4/parasol-branch-first-pipeline.png[]
+
and turns green when it finishes the run successfully
+
image:./m4/parasol-branch-first-pipeline-success.png[]
image:m4/parasol-branch-first-pipeline-success.png[]

** Explore the other tabs to see how RHDH allows a single pane of glass for the Developers' isolated environment

* If you are curious to view the deployment on OpenShift: https://console-openshift-console.{openshift_cluster_ingress_domain}/k8s/ns/parasol-store-my-feature-branch/apps%7Ev1%7EDeployment[click here^, window="_console"]

image:./m4/parasol-branch-deployment1.png[]
image:m4/parasol-branch-deployment1.png[]


=== Enhancing the application

* Click on the *< > View Source* button on the Component Overview page to open the source repository
+
image:./m4/parasol-branch-component-overview.png[]
image:m4/parasol-branch-component-overview.png[]

* Switch to the *my-feature-branch*
+
image:./m4/parasol-switchbranch.png[]
image:m4/parasol-switchbranch.png[]

* Click on the Web IDE of the *my-feature-branch* to access the code via the inbuilt editor
+
image:./m4/parasol-webide.png[]
image:m4/parasol-webide.png[]

* For the sake of the workshop, let us make some changes to the README file. +
E.g. add this text to the README file `This service store provides the core services of Parasol web-app`

* Click on the *Source Control* menu on the left-hand (highlighted below), add a Commit Message *Chore: Improved README file*, and click the *Commit and push to "my-feature-branch"* button
+
image:./m4/parasol-webide-paste-commit.png[width=80%]
image:m4/parasol-webide-paste-commit.png[width=80%]
* You can now close the gitlab browser.

=== View component on RHDH
* In RHDH, navigate to the `parasol-store` component. You can https://backstage-backstage.{openshift_cluster_ingress_domain}/catalog/default/component/parasol-store/ci[click here^, window="_rhdh"] to access it.
* Access the CI tab to view the pipeline
+
image:./m4/parasol-innerloop-pipeline1.png[width=80%]
image:m4/parasol-innerloop-pipeline1.png[width=80%]

* Very shortly, the pipeline will be marked as *Succeeded*
+
image:./m4/parasol-innerloop-pipeline-ok.png[width=80%]
image:m4/parasol-innerloop-pipeline-ok.png[width=80%]
+
NOTE: The first pipeline was triggered when you registered using the s.w template. and the next is by git commit

Expand Down

0 comments on commit ceeedf8

Please sign in to comment.