Merge branch 'master' into feature/EKSCatalog

Signed-off-by: Jonah Back <jonah@jonahback.com>
2022-06-20 14:57:55 -07:00
parent 151aeea845 89cd5f8a36
commit 953e2e356d
824 changed files with 25469 additions and 9812 deletions
@@ -33,10 +33,14 @@ const serviceEntityPage = (
  <EntityLayout>
    {/* other tabs... */}
    <EntityLayout.Route path="/kubernetes" title="Kubernetes">
-      <EntityKubernetesContent />
+      <EntityKubernetesContent refreshIntervalMs={30000} />
    </EntityLayout.Route>
 ```

+**Notes:**
+
+- The optional `refreshIntervalMs` property on the `EntityKubernetesContent` defines the interval in which the content automatically refreshes, if not set this will default to 10 seconds.
+
 That's it! But now, we need the Kubernetes Backend plugin for the frontend to
 work.

@@ -18,7 +18,7 @@ If you haven't setup Backstage already, start

 ```bash
 # From your Backstage root directory
-yarn add --cwd packages/app @backstage/plugin-search
+yarn add --cwd packages/app @backstage/plugin-search @backstage/plugin-search-react
 ```

 Create a new `packages/app/src/components/search/SearchPage.tsx` file in your
@@ -33,7 +33,7 @@ import {
  SearchResult,
  DefaultResultListItem,
  SearchFilter,
-} from '@backstage/plugin-search';
+} from '@backstage/plugin-search-react';
 import { CatalogResultListItem } from '@backstage/plugin-catalog';

 export const searchPage = (
@@ -213,7 +213,7 @@ apiRouter.use('/search', await search(searchEnv));

 ### Frontend

-The Search Plugin exposes several default filter types as static properties,
+The Search Plugin web library (`@backstage/plugin-search-react`) exposes several default filter types as static properties,
 including `<SearchFilter.Select />` and `<SearchFilter.Checkbox />`. These allow
 you to provide values relevant to your Backstage instance that, when selected,
 get passed to the backend.
@@ -237,7 +237,7 @@ If you have advanced filter needs, you can specify your own filter component
 like this (although new core filter contributions are welcome):

 ```tsx
-import { useSearch, SearchFilter } from '@backstage/plugin-search';
+import { useSearch, SearchFilter } from '@backstage/plugin-search-react';

 const MyCustomFilter = () => {
  // Note: filters contain filter data from other filter components. Be sure
@@ -102,6 +102,31 @@ import { Client } from '@elastic/elastic-search';
 const client = searchEngine.newClient(options => new Client(options));
 ```

+#### Set custom index template
+
+The elasticsearch engine gives you the ability to set a custom index template if needed.
+
+> Index templates define settings, mappings, and aliases that can be applied automatically to new indices.
+
+```typescript
+// app/backend/src/plugins/search.ts
+const searchEngine = await ElasticSearchSearchEngine.initialize({
+  logger: env.logger,
+  config: env.config,
+});
+
+searchEngine.setIndexTemplate({
+  name: '<name-of-your-custom-template>',
+  body: {
+    index_patterns: ['<your-index-pattern>'],
+    template: {
+      mappings: {},
+      settings: {},
+    },
+  },
+});
+```
+
 ## Example configurations

 ### AWS
@@ -55,6 +55,7 @@ metadata:
    - url: https://admin.example-org.com
      title: Admin Dashboard
      icon: dashboard
+      type: admin-dashboard
 spec:
  type: website
  lifecycle: production
@@ -83,7 +84,8 @@ This is the same entity as returned in JSON from the software catalog API:
      {
        "url": "https://admin.example-org.com",
        "title": "Admin Dashboard",
-        "icon": "dashboard"
+        "icon": "dashboard",
+        "type": "admin-dashboard"
      }
    ],
    "tags": ["java"],
@@ -353,6 +355,7 @@ Fields of a link are:
 | `url`   | String | [Required] A `url` in a standard `uri` format (e.g. `https://example.com/some/page`) |
 | `title` | String | [Optional] A user friendly display name for the link.                                |
 | `icon`  | String | [Optional] A key representing a visual icon to be displayed in the UI.               |
+| `type`  | String | [Optional] An optional value to categorize links into specific groups.               |

 _NOTE_: The `icon` field value is meant to be a semantic key that will map to a
 specific icon that may be provided by an icon library (e.g. `material-ui`
@@ -362,6 +365,8 @@ Backstage integrator will ultimately be left to provide the appropriate icon
 component mappings. A generic fallback icon would be provided if a mapping
 cannot be resolved.

+The semantics of the `type` field are undefined. The adopter is free to define their own set of types and utilize them as they wish. Some potential use cases can be to utilize the type field to validate certain links exist on entities or to create customized UI components for specific link types.
+
 ## Common to All Kinds: Relations

 The `relations` root field is a read-only list of relations, between the current
@@ -33,8 +33,8 @@ tracked in source control, or use some existing open source or commercial
 software.

 A component can implement APIs for other components to consume. In turn it might
-depend on APIs implemented by other components, or resources that are attached
-to it at runtime.
+consume APIs implemented by other components, or directly depend on components or
+resources that are attached to it at runtime.

 ### API

@@ -353,6 +353,19 @@ to `scm-only`, the plugin will only take into account files stored in source
 control (e.g. ignoring generated code). If set to `enabled`, all files covered
 by a coverage report will be taken into account.

+### vault.io/secrets-path
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    vault.io/secrets-path: test/backstage
+```
+
+The value of this annotation contains the path to the secrets of the entity in
+Vault. If not present when the Vault plugin is in use, a message will be shown
+instead, letting the user know what is missing in the `catalog-info.yaml`.
+
 ## Deprecated Annotations

 The following annotations are deprecated, and only listed here to aid in
@@ -397,6 +397,29 @@ There's also the ability to pass additional scopes when requesting the `oauth`
 token from the user, which you can do on a per-provider basis, in case your
 template can be published to multiple providers.

+Note, that you will need to configure an [authentication provider](../../auth/index.md#configuring-authentication-providers), alongside the
+[`ScmAuthApi`](../../auth/index.md#scaffolder-configuration-software-templates) for your source code management (SCM) service to make this feature work.
+
+### Accessing the signed-in users details
+
+Sometimes when authoring templates, you'll want to access the user that is running the template, and get details from the profile or the users `Entity` in the Catalog.
+
+If you have enabled a sign in provider and have a [sign in resolver](../../auth/identity-resolver.md) that points to a user in the Catalog, then you can use the `${{ user.entity }}` templating expression to access the raw entity from the Catalog.
+
+This can be particularly useful if you have processors setup in the Catalog to write `spec.profile.email` of the `User Entities` to reference them and pass them into actions like below:
+
+```yaml
+  steps:
+    action: publish:github
+    ...
+    input:
+        ...
+        gitAuthorName: ${{ user.entity.metadata.name }}
+        gitAuthorEmail: ${{ user.entity.spec.profile.email }}
+```
+
+You also have access to `user.entity.metadata.annotations` too, so if you have some other additional information stored in there, you reference those too.
+
 ### The Owner Picker

 When the scaffolder needs to add new components to the catalog, it needs to have
@@ -95,7 +95,7 @@ See [TechDocs Architecture](architecture.md) to get an overview of where the bel
 [techdocs/frontend-library]: https://github.com/backstage/backstage/blob/master/plugins/techdocs-react
 [techdocs/backend]: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend
 [techdocs/container]: https://github.com/backstage/techdocs-container
-[techdocs/cli]: https://github.com/backstage/techdocs-cli
+[techdocs/cli]: https://github.com/backstage/backstage/blob/master/packages/techdocs-cli

 ## Get involved