Skip to content

Commit 8b5df9f

Browse files
vrabbivrabbi
committed
Add ArgoCD BAckstage plugin docs
1 parent 3009081 commit 8b5df9f

File tree

1 file changed

+374
-0
lines changed
  • docs/component-docs/backstage/plugin-docs/argocd

1 file changed

+374
-0
lines changed

‎docs/component-docs/backstage/plugin-docs/argocd/overview.md‎

Lines changed: 374 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,374 @@
1+
# ArgoCD Plugins
2+
There is a frontend and a backend plugin for this integration.
3+
4+
<details>
5+
<summary>Backend Plugin</summary>
6+
7+
# Red Hat ArgoCD Backend Plugin for Backstage
8+
9+
This plugin enables integration between Backstage and ArgoCD instances, allowing you to monitor your ArgoCD applications.
10+
11+
## Installation
12+
13+
This plugin is installed via the `@backstage-community/plugin-redhat-argocd-backend` package. To install it to your backend package, run:
14+
15+
```bash
16+
# From your root directory
17+
yarn --cwd packages/backend add @backstage-community/plugin-redhat-argocd-backend
18+
```
19+
20+
Then add the plugin to your backend in `packages/backend/src/index.ts`:
21+
22+
```ts
23+
const backend = createBackend();
24+
// ...
25+
backend.add(import('@backstage-community/plugin-redhat-argocd-backend'));
26+
```
27+
28+
## Configuration
29+
30+
### Basic Setup
31+
32+
The simplest configuration requires just a URL and authentication details for your ArgoCD instance:
33+
34+
```yaml
35+
argocd:
36+
# Default fallback credentials
37+
username: ${ARGOCD_USERNAME}
38+
password: ${ARGOCD_PASSWORD}
39+
appLocatorMethods:
40+
- type: 'config'
41+
instances:
42+
- name: primary
43+
url: https://argocd.example.com
44+
```
45+
46+
## Authentication Options
47+
48+
The plugin supports three authentication methods, in order of priority (highest to lowest):
49+
50+
1. Instance-specific access token
51+
2. Instance-specific username/password
52+
3. Default username/password
53+
54+
### Using Access Tokens (Recommended)
55+
56+
```yaml
57+
argocd:
58+
appLocatorMethods:
59+
- type: 'config'
60+
instances:
61+
- name: instanceA
62+
url: https://instance-a.com
63+
token: ${ARGOCD_AUTH_TOKEN}
64+
```
65+
66+
### Using Instance-Specific Credentials
67+
68+
```yaml
69+
argocd:
70+
appLocatorMethods:
71+
- type: 'config'
72+
instances:
73+
- name: instanceA
74+
url: https://instance-a.com
75+
username: ${ARGOCD_USERNAME}
76+
password: ${ARGOCD_PASSWORD}
77+
```
78+
79+
### Default username and password
80+
81+
```yaml
82+
argocd:
83+
username: ${ARGOCD_USERNAME}
84+
password: ${ARGOCD_PASSWORD}
85+
appLocatorMethods:
86+
- type: 'config'
87+
instances:
88+
- name: instanceA
89+
url: https://instance-a.com
90+
- name: instanceB
91+
url: https://instance-b.com
92+
```
93+
94+
## Multiple ArgoCD instances
95+
96+
You can connect to multiple ArgoCD instances by configuring multiple entries:
97+
98+
```yaml
99+
argocd:
100+
# Default fallback credentials
101+
username: ${ARGOCD_USERNAME}
102+
password: ${ARGOCD_PASSWORD}
103+
appLocatorMethods:
104+
- type: 'config'
105+
instances:
106+
- name: production
107+
url: https://argocd-prod.example.com
108+
token: ${ARGOCD_PROD_TOKEN}
109+
- name: staging
110+
url: https://argocd-staging.example.com
111+
username: ${ARGOCD_STAGING_USERNAME}
112+
password: ${ARGOCD_STAGING_PASSWORD}
113+
```
114+
115+
**Note**: When using multiple instances, specify the target instance in your entity using the `argocd/instance-name` annotation. If not specified, the first configured instance will be used.
116+
117+
## Development
118+
119+
### Local Development
120+
121+
For local development without HTTPS, add `localDevelopment: true` to your configuration:
122+
123+
```yaml
124+
argocd:
125+
# Default username and password
126+
localDevelopment: true
127+
username: ${ARGOCD_USERNAME}
128+
password: ${ARGOCD_PASSWORD}
129+
appLocatorMethods:
130+
- type: 'config'
131+
instances:
132+
- name: instanceA
133+
url: https://instance-a.com
134+
token: ${ARGOCD_AUTH_TOKEN}
135+
```
136+
137+
## Running the plugin
138+
139+
Run the plugin in standalone mode:
140+
141+
```bash
142+
yarn start
143+
```
144+
145+
Run the entire Backstage application including this plugin:
146+
147+
```bash
148+
# From the root workspace directory
149+
yarn start:backstage
150+
```
151+
</details>
152+
153+
<details>
154+
<summary>Frontend Plugin</summary>
155+
156+
# Argo CD plugin for Backstage
157+
158+
## Getting started
159+
160+
Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/argocd/deployment-lifecycle](http://localhost:3000/argocd/deployment-lifecycle).
161+
162+
You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
163+
This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
164+
It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
165+
166+
## For Administrators
167+
168+
### Installation and configuration
169+
170+
#### Prerequisites
171+
172+
Please install and configure the frontend and backend Kubernetes plugins by following the [installation](https://backstage.io/docs/features/kubernetes/installation/) and [configuration](https://backstage.io/docs/features/kubernetes/configuration/) guides.
173+
174+
### Argo CD backend
175+
176+
Please see [the backend documentation](../argocd-backend/README.md) for more information.
177+
178+
### [Optional] Enable Argo Rollouts feature
179+
180+
- Install the kubernetes backend plugin `@backstage/plugin-kubernetes-backend` and configure it by following the [installation](https://backstage.io/docs/features/kubernetes/installation/) and [configuration](https://backstage.io/docs/features/kubernetes/configuration/) guides.
181+
182+
- The following customResources component is added under the kubernetes configuration in the app-config.yaml file:
183+
184+
```
185+
kubernetes:
186+
...
187+
customResources:
188+
- group: 'argoproj.io'
189+
apiVersion: 'v1alpha1'
190+
plural: 'rollouts'
191+
- group: 'argoproj.io'
192+
apiVersion: 'v1alpha1'
193+
plural: 'analysisruns'
194+
```
195+
196+
- The [ClusterRole](https://backstage.io/docs/features/kubernetes/configuration/#role-based-access-control) must be granted for custom resources (Rollouts and AnalysisRuns) to ServiceAccount accessing the cluster.
197+
198+
- If you have the Backstage Kubernetes Plugin configured, then the ClusterRole is already granted.
199+
200+
You can use the following code to grant the ClusterRole for custom resources:
201+
202+
```
203+
apiVersion: rbac.authorization.k8s.io/v1
204+
kind: ClusterRole
205+
metadata:
206+
name: backstage-read-only
207+
rules:
208+
- apiGroups:
209+
- argoproj.io
210+
resources:
211+
- rollouts
212+
- analysisruns
213+
verbs:
214+
- get
215+
- list
216+
```
217+
218+
> Tip: You can use the [prepared manifest for a read-only ClusterRole](https://raw.githubusercontent.com/backstage/community-plugins/main/workspaces/redhat-argocd/plugins/argocd/manifests/clusterrole.yaml), which provides access for both Kubernetes plugin and Argo CD plugin.
219+
220+
### Frontend-specific Configurations
221+
222+
By default this plugin removes duplicate entries being shown in the "Deployment history" section.
223+
To view the full deployment history you set the following:
224+
225+
```yaml
226+
argocd:
227+
fullDeploymentHistory: true # false by default
228+
```
229+
230+
### Annotations
231+
232+
- The following annotation is added to the entity's `catalog-info.yaml` file to identify whether an entity contains the Kubernetes resources:
233+
234+
```yaml
235+
annotations:
236+
...
237+
238+
backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>
239+
```
240+
241+
You can also add the `backstage.io/kubernetes-namespace` annotation to identify the Kubernetes resources using the defined namespace.
242+
243+
```yaml
244+
annotations:
245+
...
246+
247+
backstage.io/kubernetes-namespace: <RESOURCE_NS>
248+
```
249+
250+
- A custom label selector can be added, which Backstage uses to find the Kubernetes resources. The label selector takes precedence over the ID annotations.
251+
252+
```yaml
253+
annotations:
254+
...
255+
256+
backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end'
257+
```
258+
259+
### Labels
260+
261+
- The following label is added to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity:
262+
263+
```yaml
264+
labels:
265+
...
266+
267+
backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>`
268+
```
269+
270+
- To Map the Argo rollouts to a particular GitOps Application, the following label is added to the rollout resources:
271+
272+
```yaml
273+
labels:
274+
...
275+
276+
app.kubernetes.io/instance: <GITOPS_APPLCATION_NAME>`
277+
```
278+
279+
***
280+
281+
**NOTE**
282+
283+
When using the label selector, the mentioned labels must be present on the resource.
284+
285+
***
286+
287+
## How to add Argo CD frontend plugin to Backstage app
288+
289+
1. Install the Argo CD plugin using the following command:
290+
291+
```bash
292+
yarn workspace app add @backstage-community/plugin-redhat-argocd
293+
```
294+
295+
2. Add deployment summary and deployment lifecycle compoennt to the `entityPage.tsx` source file:
296+
297+
```ts
298+
// packages/app/src/components/catalog/EntityPage.tsx
299+
import {
300+
ArgocdDeploymentSummary,
301+
ArgocdDeploymentLifecycle,
302+
isArgocdConfigured,
303+
} from '@backstage-community/plugin-redhat-argocd';
304+
305+
const overviewContent = (
306+
<Grid container spacing={3} alignItems="stretch">
307+
...
308+
<EntitySwitch>
309+
<EntitySwitch.Case if={e => Boolean(isArgocdConfigured(e))}>
310+
<Grid item sm={12}>
311+
<ArgocdDeploymentSummary />
312+
</Grid>
313+
</EntitySwitch.Case>
314+
</EntitySwitch>
315+
...
316+
</Grid>
317+
);
318+
319+
const cicdcontent = (
320+
<EntitySwitch>
321+
{/* ... */}
322+
{/* highlight-add-start */}
323+
...
324+
<EntitySwitch.Case if={e => Boolean(isArgocdConfigured(e))}>
325+
<Grid item sm={12}>
326+
<ArgocdDeploymentLifecycle />
327+
</Grid>
328+
</EntitySwitch.Case>
329+
{/* highlight-add-end */}
330+
</EntitySwitch>
331+
);
332+
```
333+
334+
- Add one of the following annotations to the entity's `catalog-info.yaml` file to enable Argo CD features in the backstage instance:
335+
336+
- To get all the applications matching the metadata labels.
337+
338+
```yaml
339+
annotations:
340+
...
341+
342+
argocd/app-selector: 'rht-gitops.com/janus-argocd=quarkus-app' # format: `label.key=label.value`
343+
344+
```
345+
346+
**or**
347+
348+
- To fetch a single application, use the following annotation in `catalog-info.yaml` file:
349+
350+
```yaml
351+
annotations:
352+
...
353+
354+
argocd/app-name: 'quarkus-app'
355+
356+
```
357+
358+
> [!Note] > **You should not add both the annotations in the same catalog, adding both annotations will result in error in the plugin.**
359+
360+
You can use these additional annotations with the base annotations:
361+
362+
- `argocd/project-name`: The name of the Application's project
363+
- `argocd/app-namespace`: The namespace of the Application
364+
365+
- To switch between argocd instances, you can use the following annotation
366+
367+
```yaml
368+
annotations:
369+
...
370+
argocd/instance-name: 'argoInstance2'
371+
```
372+
373+
> [!Note] > **If this annotation is not set, the plugin will default to the first Argo CD instance configured in the `app.config.yaml`**
374+
</details>

0 commit comments

Comments
 (0)