-
Notifications
You must be signed in to change notification settings - Fork 151
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: acr plugin documentation (#683)
- Loading branch information
1 parent
a830edc
commit 0073471
Showing
2 changed files
with
88 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,74 +1,100 @@ | ||
| # Azure Container Registry plugin for Backstage | ||
|
|
||
| This plugin will show you information about your container images within Azure Container Registry | ||
| The Azure Container Registry (ACR) plugin displays information about your container images available in the Azure Container Registry. | ||
|
|
||
| ## For administrators | ||
|
|
||
| ### Installing and configuring the ACR plugin | ||
|
|
||
| 1. Run the following command to install the ACR plugin: | ||
|
|
||
| ```bash | ||
| yarn workspace app add @janus-idp/backstage-plugin-acr | ||
| ``` | ||
|
|
||
| 1. Set the proxy to the desired ACR server in the `app-config.yaml` file as follows: | ||
|
|
||
| ```yaml | ||
| # app-config.yaml | ||
| proxy: | ||
| '/acr/api': | ||
| target: 'https://mycontainerregistry.azurecr.io/acr/v1/' | ||
| 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 | ||
| ``` | ||
| 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 to convert the credentials into a 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. | ||
| - Set the generated token as `ACR_AUTH_TOKEN` in environment variables. | ||
|
|
||
| 1. Enable an additional tab on the entity view page using the `packages/app/src/components/catalog/EntityPage.tsx` file as follows: | ||
|
|
||
| ```ts | ||
| // packages/app/src/components/catalog/EntityPage.tsx | ||
| import { AcrPage, isAcrAvailable } from '@janus-idp/backstage-plugin-acr'; | ||
| const websiteEntityPage = ( | ||
| <EntityPageLayout> | ||
| // ... | ||
| <EntityLayout.Route path="/acr" title="ACR"> | ||
| <Grid container spacing={3} alignItems="stretch"> | ||
| <EntitySwitch> | ||
| <EntitySwitch.Case if={e => Boolean(isAcrAvailable(e))}> | ||
| <Grid item sm={12}> | ||
| <AcrPage /> | ||
| </Grid> | ||
| </EntitySwitch.Case> | ||
| </EntitySwitch> | ||
| </Grid> | ||
| </EntityLayout.Route> | ||
| </EntityPageLayout> | ||
| ); | ||
| ``` | ||
|
|
||
| 1. Annotate your entity using the following annotations: | ||
| ```yaml | ||
| metadata: | ||
| annotations: | ||
| 'azure-container-registry/repository-name': `<REPOSITORY-NAME>', | ||
| ``` | ||
| ### Development | ||
| The ACR plugin is a front-end plugin. You can use the following command to start the live development session from your root repository: | ||
| ### Installation | ||
| ``` | ||
| yarn workspace @janus-idp/backstage-plugin-acr run start | ||
| ``` | ||
|
|
||
| 1. Install the Azure Container Registry plugin using the following command: | ||
| ## For users | ||
|
|
||
| ```bash | ||
| yarn workspace app add @janus-idp/backstage-plugin-acr | ||
| ``` | ||
| ### Using the ACR plugin in Backstage | ||
|
|
||
| ### 2. Configuration | ||
|
|
||
| 1. Set the proxy to the desired Azure Container Registry server in the `app-config.yaml` file as follows: | ||
|
|
||
| ```yaml | ||
| # app-config.yaml | ||
| proxy: | ||
| '/acr/api': | ||
| target: 'https://mycontainerregistry.azurecr.io/acr/v1/' | ||
| 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 | ||
| ``` | ||
| ACR is a front-end plugin that enables you to view information about the container images from your Azure Container Registry in Backstage. | ||
|
|
||
| 2. Authorization: | ||
| Basic Authorization: Go to your Azure Container Registry portal, and go to the `Access Keys` tab. Get the `username` and the `password` of the `Admin User`, and use this [tool](https://www.debugbear.com/basic-auth-header-generator) to covert them into a token, and make it as the `ACR_AUTH_TOKEN` in environment variables. | ||
|
|
||
| OAuth2: You can following the [link](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-authentication?tabs=azure-cli) to get the bearer access token, and make it as `ACR_AUTH_TOKEN`. | ||
|
|
||
| 3. Enable an additional tab on the entity view page in `packages/app/src/components/catalog/EntityPage.tsx`: | ||
|
|
||
| ```ts | ||
| // packages/app/src/components/catalog/EntityPage.tsx | ||
| import { AcrPage, isAcrAvailable } from '@janus-idp/backstage-plugin-acr'; | ||
| const websiteEntityPage = ( | ||
| <EntityPageLayout> | ||
| // ... | ||
| <EntityLayout.Route path="/acr" title="ACR"> | ||
| <Grid container spacing={3} alignItems="stretch"> | ||
| <EntitySwitch> | ||
| <EntitySwitch.Case if={e => Boolean(isAcrAvailable(e))}> | ||
| <Grid item sm={12}> | ||
| <AcrPage /> | ||
| </Grid> | ||
| </EntitySwitch.Case> | ||
| </EntitySwitch> | ||
| </Grid> | ||
| </EntityLayout.Route> | ||
| </EntityPageLayout> | ||
| ); | ||
| ``` | ||
| #### Prerequisites | ||
|
|
||
| 4. Annotate your entity with the following annotations: | ||
| - Your Backstage application is installed and running. | ||
| - You have installed the ACR plugin. For installation instructions, see [Installing and configuring the ACR plugin](#installing-and-configuring-the-acr-plugin). | ||
|
|
||
| ```yaml | ||
| metadata: | ||
| annotations: | ||
| 'azure-container-registry/repository-name': `<REPOSITORY-NAME>', | ||
| ``` | ||
| #### Procedure | ||
|
|
||
| ## Development | ||
| 1. Open your Backstage application and select a component from the Catalog page. | ||
|
|
||
| In [Backstage plugin terminology](https://backstage.io/docs/local-dev/cli-build-system#package-roles), this is a `frontend-plugin`. You can start a live dev session from the repository root using following commands: | ||
| 1. Go to the **ACR** tab. | ||
|
|
||
| ``` | ||
| yarn workspace @janus-idp/backstage-plugin-acr run start | ||
| ``` | ||
|  | ||
|
|
||
| The **ACR** tab in the Backstage UI contains a list of container images and related information, such as **TAG**, **CREATED**, **LAST MODIFIED**, and **MANIFEST**. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.