feat(marketplace): add and show markdown content (description and ins…

…tallation) (redhat-developer#153)

Signed-off-by: Christoph Jerolimov <[email protected]>

workspaces/marketplace/examples/plugins/3scale.yaml

@@ -16,3 +16,52 @@ spec:
   type: frontend-plugin
   lifecycle: production
   owner: redhat
+  description: |
+    Synchronize 3scale content into the Backstage catalog.
+
+    3scale Backstage provider allows configuration of one or multiple providers using the `app-config.yaml` configuration file.
+  installation:
+    markdown: |
+      # Installation
+
+      Run the following command to install the 3scale Backstage provider plugin:
+
+      ```console
+      yarn workspace backend add @backstage-community/plugin-3scale-backend
+      ```
+
+      # Configuration
+
+      3scale Backstage provider allows configuration of one or multiple providers using the `app-config.yaml` configuration file of Backstage.
+
+      ## New Backend Procedure
+
+      1. Use a `threeScaleApiEntity` marker to start configuring the `app-config.yaml` file of Backstage:
+
+        ```yaml title="app-config.yaml"
+        catalog:
+          providers:
+            threeScaleApiEntity:
+              dev:
+                baseUrl: https://<TENANT>-admin.3scale.net
+                accessToken: <ACCESS_TOKEN>
+                schedule: # optional; same options as in TaskScheduleDefinition
+                  # supports cron, ISO duration, "human duration" as used in code
+                  frequency: { minutes: 30 }
+                  # supports ISO duration, "human duration" as used in code
+                  timeout: { minutes: 3 }
+        ```
+
+        **NOTE**
+        Make sure to configure the schedule inside the `app-config.yaml` file. The default schedule is a frequency of 30 minutes and a timeout of 3 minutes.
+
+      2. Add the following code to the `packages/backend/src/index.ts` file:
+
+        ```ts title="packages/backend/src/index.ts"
+        const backend = createBackend();
+
+        /* highlight-add-next-line */
+        backend.add(import('@backstage-community/plugin-3scale-backend'));
+
+        backend.start();
+        ```

workspaces/marketplace/examples/plugins/acr.yaml

@@ -12,3 +12,107 @@ spec:
     - Kubernetes
   developer: Red Hat
   icon: https://janus-idp.io/images/plugins/oci-acr.svg
+  description: |
+    # Azure Container Registry plugin for Backstage
+
+    The Azure Container Registry (ACR) plugin displays information about your container images available in the Azure Container Registry.
+
+    ## Using the ACR plugin in Backstage
+
+    ACR is a front-end plugin that enables you to view information about the container images from your Azure Container Registry in Backstage.
+
+    ## Procedure
+
+    1. Open your Backstage application and select a component from the Catalog page.
+
+    1. Go to the **ACR** tab.
+
+      ![acr-tab](https://github.com/backstage/community-plugins/raw/main/workspaces/acr/plugins/acr/images/acr-plugin-user1.png)
+
+    The **ACR** tab in the Backstage UI contains a list of container images and related information, such as **TAG**, **CREATED**, **LAST MODIFIED**, and **MANIFEST**.
+  installation:
+    markdown: |
+      # Installing and configuring the ACR plugin
+
+      1. Run the following command to install the ACR plugin:
+
+         ```bash
+         yarn workspace app add @backstage-community/plugin-acr
+         ```
+
+      1. Set the proxy to the desired ACR server in the `app-config.yaml` file as follows:
+
+         ```yaml
+         # app-config.yaml
+         proxy:
+           endpoints:
+             '/acr/api':
+               target: 'https://mycontainerregistry.azurecr.io/acr/v1/'
+               credentials: require
+               changeOrigin: true
+               headers:
+                 # If you use Bearer Token for authorization, please replace the 'Basic' with 'Bearer' in the following line.
+                 Authorization: 'Basic ${ACR_AUTH_TOKEN}'
+               # Change to "false" in case of using self hosted artifactory instance with a self-signed certificate
+               secure: true
+         ```
+
+         > [!NOTE]
+         > The value inside each route is either a simple URL string, or an object on the format accepted by [http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware). Additionally, it has an optional `credentials` key which can have the following values:
+         >
+         > - `require`: Callers must provide Backstage user or service credentials with each request. The credentials are not forwarded to the proxy target. This is the **default**.
+         > - `forward`: Callers must provide Backstage user or service credentials with each request, and those credentials are forwarded to the proxy target.
+         > - `dangerously-allow-unauthenticated`: No Backstage credentials are required to access this proxy target. The target can still apply its own credentials checks, but the proxy will not help block non-Backstage-blessed callers. If you also add allowedHeaders: ['Authorization'] to an endpoint configuration, then the Backstage token (if provided) WILL be forwarded.
+         >
+         > Note that if you have `backend.auth.dangerouslyDisableDefaultAuthPolicy` set to true, the credentials value does not apply; the proxy will behave as if all endpoints were set to dangerously-allow-unauthenticated.
+
+      1. Set the authorization using one of the following options:
+
+         - Basic authorization:
+
+           - Navigate to the ACR portal and go to the **Access Keys** tab.
+           - Retrieve the username and password of the Admin user and use the [Basic Auth Header Generator tool](https://www.debugbear.com/basic-auth-header-generator) or run `echo printf '<username>:<password>' | base64` in a terminal to convert the credentials into a basic token.
+           - Set the generated token as `ACR_AUTH_TOKEN` in environment variables.
+
+         - OAuth2: - Generate bearer access token using the process described in Authenticate with an Azure Container Registry.
+
+           - One method is to generate a bearer token using your basic authorization token, i.e.
+
+             ```bash
+                     curl --location 'https://<yourregistry>.azurecr.io/oauth2/token?scope=repository%3A*%3A*&service=<yourregistry>.azurecr.io' \
+             --header 'Authorization: Basic <basic_token>'
+             ```
+
+           - Set the generated token as `ACR_AUTH_TOKEN` in environment variables. Make sure to replace the `Basic` in the `app-config.yaml` with `Bearer`
+
+      1. Enable an additional tab on the entity view page using the `packages/app/src/components/catalog/EntityPage.tsx` file as follows:
+
+         ```tsx title="packages/app/src/components/catalog/EntityPage.tsx"
+         /* highlight-add-start */
+         import { AcrPage, isAcrAvailable } from '@backstage-community/plugin-acr';
+
+         /* highlight-add-end */
+
+         const serviceEntityPage = (
+           <EntityLayout>
+             // ...
+             {/* highlight-add-start */}
+             <EntityLayout.Route
+               if={e => Boolean(isAcrAvailable(e))}
+               path="/acr"
+               title="ACR"
+             >
+               <AcrPage />
+             </EntityLayout.Route>
+             {/* highlight-add-end */}
+           </EntityLayout>
+         );
+         ```
+
+      1. Annotate your entity using the following annotations:
+
+         ```yaml
+         metadata:
+           annotations:
+             'azure-container-registry/repository-name': `<REPOSITORY-NAME>',
+         ```

workspaces/marketplace/examples/plugins/keycloak.yaml

@@ -12,3 +12,173 @@ spec:
     - Auth
   developer: Red Hat
   icon: https://janus-idp.io/images/plugins/keycloak.svg
+  description: |
+    # Keycloak backend plugin for Backstage
+
+    The Keycloak backend plugin integrates Keycloak into Backstage.
+
+    ## Capabilities
+
+    The Keycloak backend plugin has the following capabilities:
+
+    - Synchronization of Keycloak users in a realm
+    - Synchronization of Keycloak groups and their users in a realm
+
+    ## Imported users and groups in Backstage using Keycloak plugin
+
+    After configuring the plugin successfully, the plugin imports the users and groups each time when started.
+
+    After the first import is complete, you can select **User** to list the users from the catalog page:
+
+    ![catalog-list](https://github.com/backstage/community-plugins/raw/main/workspaces/keycloak/plugins/catalog-backend-module-keycloak/images/users.jpg)
+
+    You can see the list of users on the page:
+
+    ![user-list](https://github.com/backstage/community-plugins/raw/main/workspaces/keycloak/plugins/catalog-backend-module-keycloak/images/user-list.jpg)
+
+    When you select a user, you can see the information imported from Keycloak:
+
+    ![user-profile](https://github.com/backstage/community-plugins/raw/main/workspaces/keycloak/plugins/catalog-backend-module-keycloak/images/user2.jpg)
+
+    You can also select a group, view the list, and select or view the information imported from Keycloak for a group:
+
+    ![group-profile](https://github.com/backstage/community-plugins/raw/main/workspaces/keycloak/plugins/catalog-backend-module-keycloak/images/group1.jpg)
+
+  installation:
+    markdown: |
+      # Installation
+
+      Install the Backstage package into the backend. When not integrating with a published package, clone the repository locally and add the Backstage as follows:
+
+      ```console
+      yarn workspace backend add @backstage-community/plugin-catalog-backend-module-keycloak
+      ```
+
+      ## Configuration
+
+      ### New Backend Configuration
+
+      1. Add the following configuration to the `app-config.yaml` file. The default schedule is a frequency of 30 minutes and a timeout of 3 minutes, please configure the schedule in the `app-config.yaml` as per your requirement.
+
+        ```yaml title="app-config.yaml"
+        catalog:
+          providers:
+            keycloakOrg:
+              default:
+                baseUrl: https://<keycloak_host>
+                loginRealm: ${KEYCLOAK_REALM}
+                realm: ${KEYCLOAK_REALM}
+                clientId: ${KEYCLOAK_CLIENTID}
+                clientSecret: ${KEYCLOAK_CLIENTSECRET}
+                schedule: # Optional (defaults to the configurations below if not provided); same options as in TaskScheduleDefinition
+                  # supports cron, ISO duration, "human duration" as used in code
+                  frequency: { minutes: 30 } # Customize this to fit your needs
+                  # supports ISO duration, "human duration" as used in code
+                  timeout: { minutes: 3 } # Customize this to fit your needs
+        ```
+
+      1. Register the plugin in the `packages/backend/src/index.ts` file:
+
+        ```ts title="packages/backend/src/index.ts"
+        const backend = createBackend();
+
+        /* highlight-add-next-line */
+        backend.add(
+          import('@backstage-community/plugin-catalog-backend-module-keycloak'),
+        );
+
+        backend.start();
+        ```
+
+      1. Optional: To configure custom transformer function for user/group to mutate the entity generated by the catalog-backend-module-keycloak. Create a new backend module with the `yarn new` command and add your custom user and group transformers to the `keycloakTransformerExtensionPoint`. Then install this new backend module into your backstage backend. Below is an example of how the backend module can be defined:
+
+        ```ts title="plugins/<module-name>/src/module.ts"
+        /* highlight-add-start */
+        import {
+          GroupTransformer,
+          keycloakTransformerExtensionPoint,
+          UserTransformer,
+        } from '@backstage-community/plugin-catalog-backend-module-keycloak';
+
+        const customGroupTransformer: GroupTransformer = async (
+          entity,
+          realm,
+          groups,
+        ) => {
+          /* apply transformations */
+          return entity;
+        };
+        const customUserTransformer: UserTransformer = async (
+          entity,
+          user,
+          realm,
+          groups,
+        ) => {
+          /* apply transformations */
+          return entity;
+        };
+        /* highlight-add-end */
+
+        export const keycloakBackendModuleTransformer = createBackendModule({
+          pluginId: 'catalog',
+          moduleId: 'keycloak-transformer',
+          register(reg) {
+            reg.registerInit({
+              deps: {
+                /* highlight-add-start */
+                keycloak: keycloakTransformerExtensionPoint,
+                /* highlight-add-end */
+              },
+              /* highlight-add-start */
+              async init({ keycloak }) {
+                keycloak.setUserTransformer(customUserTransformer);
+                keycloak.setGroupTransformer(customGroupTransformer);
+                /* highlight-add-end */
+              },
+            });
+          },
+        });
+        ```
+
+        ***
+
+        **IMPORTANT**
+
+        The `pluginId` for the module **MUST** be set to `catalog` to match the `pluginId` of the `catalog-backend-module-keycloak` or else the module will fail to initialize.
+
+        ***
+
+      Communication between Backstage and Keycloak is enabled by using the Keycloak API. Username/password or client credentials are supported authentication methods.
+
+      The following table describes the parameters that you can configure to enable the plugin under `catalog.providers.keycloakOrg.<ENVIRONMENT_NAME>` object in the `app-config.yaml` file:
+
+      | Name             | Description                                                        | Default Value | Required                                             |
+      | ---------------- | ------------------------------------------------------------------ | ------------- | ---------------------------------------------------- |
+      | `baseUrl`        | Location of the Keycloak server, such as `https://localhost:8443`. | ""            | Yes                                                  |
+      | `realm`          | Realm to synchronize                                               | `master`      | No                                                   |
+      | `loginRealm`     | Realm used to authenticate                                         | `master`      | No                                                   |
+      | `username`       | Username to authenticate                                           | ""            | Yes if using password based authentication           |
+      | `password`       | Password to authenticate                                           | ""            | Yes if using password based authentication           |
+      | `clientId`       | Client ID to authenticate                                          | ""            | Yes if using client credentials based authentication |
+      | `clientSecret`   | Client Secret to authenticate                                      | ""            | Yes if using client credentials based authentication |
+      | `userQuerySize`  | Number of users to query at a time                                 | `100`         | No                                                   |
+      | `groupQuerySize` | Number of groups to query at a time                                | `100`         | No                                                   |
+
+      When using client credentials, the access type must be set to `confidential` and service accounts must be enabled. You must also add the following roles from the `realm-management` client role:
+
+      - `query-groups`
+      - `query-users`
+      - `view-users`
+
+      ### Limitations
+
+      If you have self-signed or corporate certificate issues, you can set the following environment variable before starting Backstage:
+
+      `NODE_TLS_REJECT_UNAUTHORIZED=0`
+
+      ---
+
+      **NOTE**
+      The solution of setting the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable is not recommended.
+
+      ---