🙏 Help Wanted: Documentation for New Backend System Everywhere

[awanlin]

With the New Backend System being the default when you create a new Backstage instance we need to update all the related backend documentation with proper examples and guidance. This will also help out existing Adopters who are migrating as there are still more advanced cases that haven't been covered yet.

We need help getting all the documentation up to date so that new and existing Adopters can find the information they need!

Process

The process is to identify an area that needs to be updated and provide the needed documentation for it. Please add [NBS Docs] to the tittle of your PR so that way we have an easy way to identify it.

The next section will list out areas that need work, please check for any active PRs before starting.

Pages Needing Updates

The following is a list of pages that need to be updated (as of 2024-04-11):

• Core Features:
  • https://backstage.io/docs/features/software-catalog/extending-the-model
  • https://backstage.io/docs/features/search/getting-started
  • https://backstage.io/docs/features/search/search-engines
  • https://backstage.io/docs/features/search/how-to-guides
• Integrations:
  • https://backstage.io/docs/integrations/aws-s3/discovery
  • https://backstage.io/docs/integrations/azure/discovery - [NBS Docs] Updated the Azure and Microsoft Graph Integration Docs #24222
  • https://backstage.io/docs/integrations/azure/org - [NBS Docs] Updated the Azure and Microsoft Graph Integration Docs #24222
  • https://backstage.io/docs/integrations/bitbucketCloud/discovery - new backend system: events service #22344
  • https://backstage.io/docs/integrations/bitbucketServer/discovery
  • https://backstage.io/docs/integrations/gerrit/discovery
  • https://backstage.io/docs/integrations/github/discovery - [NBS Docs] Updated GitHub Integrations Docs #24573
  • https://backstage.io/docs/integrations/github/org - [NBS Docs] Updated GitHub Integrations Docs #24573
  • https://backstage.io/docs/integrations/gitlab/discovery - Add event support for the Catalog Plugin GitLab Discovery Entity providers #23373
  • https://backstage.io/docs/integrations/gitlab/org - Add event support for the Catalog Plugin GitLab Discovery Entity providers #23373
  • https://backstage.io/docs/integrations/ldap/org (I don't think the LDAP plugin has been migrated to the new backend system yet)
• Plugins
  • https://backstage.io/docs/plugins/integrating-search-into-plugins
  • https://backstage.io/docs/plugins/proxying
  • https://backstage.io/docs/plugins/backend-plugin (fix: adjust the backend plugin docs for new backend #24069)
  • https://backstage.io/docs/plugins/url-reader
  • https://backstage.io/docs/plugins/observability (Health check)
• Auth (most of these just need to add details about the signIn.resolvers)
  • https://backstage.io/docs/auth/auth0/provider (not migrated to new backend system yet)
  • https://backstage.io/docs/auth/atlassian/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/microsoft/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/microsoft/easy-auth - Add auth-backend-module-azure-easyauth-provider #23909
  • https://backstage.io/docs/auth/bitbucket/provider (not migrated to new backend system yet)
  • https://backstage.io/docs/auth/bitbucketServer/provider (not migrated to new backend system yet)
  • https://backstage.io/docs/auth/cloudflare/provider - auth-backend: extract the cloudflare access auth provider #23997
  • https://backstage.io/docs/auth/github/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/gitlab/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/google/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/google/gcp-iap-auth - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/okta/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/oauth2-proxy/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/onelogin/provider (not migrated to new backend system yet)
  • https://backstage.io/docs/auth/vmware-cloud/provider - [NBS Docs] Added SingIn Resolvers Config Details #24221
  • https://backstage.io/docs/auth/oidc
  • https://backstage.io/docs/auth/add-auth-provider
  • https://backstage.io/docs/auth/service-to-service-auth - implement external token access #24257
• Permissions
  • https://backstage.io/docs/permissions/getting-started - [NBS Docs] Updating getting-started permissions docs to new backend! #24229
  • https://backstage.io/docs/permissions/writing-a-policy
  • https://backstage.io/docs/permissions/custom-rules
  • https://backstage.io/docs/permissions/plugin-authors/01-setup
  • https://backstage.io/docs/permissions/plugin-authors/02-adding-a-basic-permission-check
  • https://backstage.io/docs/permissions/plugin-authors/03-adding-a-resource-permission-check
  • https://backstage.io/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data
• Tutorials
  • https://backstage.io/docs/tutorials/setup-opentelemetry

Note: if there is something missing from this list please feel free to mention it or even better submit a PR with the updates and mention it here 👍

[elaine-mattos]

Hi !

I believe this PR would already deal with the docu for https://backstage.io/docs/integrations/gitlab/discovery and
https://backstage.io/docs/integrations/gitlab/org ?

[awanlin]

Thanks @elaine-mattos, I've updated the list with that PR 🚀

[Parsifal-M]

Hey! 👋

QQ - Is the idea to completely overwrite the old docs with the new ways? Or is the idea to add the new way somewhere in the old docs?

Thanks! 👏

[awanlin]

Hi @Parsifal-M, I've been just adding on the new backend system examples, my thinking is that being able to seem them together could be helpful.

[freben]

I made a stab at making an --old file that's not in the sidebar but can be linked to.

#24154

[awanlin]

PR #24221 covers the auth pages for: Atlassian, GCP IAP, GitHub, GitLab, Google, Microsoft, oauth2 Proxy, Okta, and VMware Cloud 🚀

[awanlin]

I've asked that they update the azure-easyauth docs as part of this PR #23909

[awanlin]

I've asked that they update the cloudflare docs as part of this PR #23997

[awanlin]

PR #24222 covers the integration pages for Azure and MS Graph

[awanlin]

I've started work on the Service to Service auth page but need a bit of guidance on this - #24223

[ManuInNZ]

I can add things for the GitHub Org data using GH app and multi orgs/apps eventually

[Parsifal-M]

#24229 started working on the permissions pages, also FYI @vinzscam ❤️ LMK!

Also not sure if I should make a copy and add the --old to it as @freben did, I do like that idea so that its there... 🤔

[razvanonet]

@ManuInNZ I'm really eager to learn how the GitHub Org data using GH app is set up using the new backend system. If you've done some progress on that in a PR or something, please put it here

[prasoon-pxc]

I am also looking doc of GithHub Org data using GH-App, as earlier instruction not working for new-backend system

[awanlin]

I've got a PR to update the GitHub Discovery and Org integration pages - #24573 - feel free to take a look.

@ManuInNZ, sorry, I know you posted that you would be working on this but we are seeing a lot of questions here and on Discord so I felt we needed to get moving. Feel free to review my PR, feedback would be very welcome.

@razvanonet @prasoon-pxc feel free to try out that PR, perhaps it can help you out, if not maybe add comments so I can improve it.

[prasoon-pxc]

@awanlin , I have tried out the updated doc for user&group ingestion, but it's not working for me, have not added any events-support and custom-transformer things

I have also tried discovery doc and it's working

[awanlin]

Hi @prasoon-pxc, you have an existing issue for this, right? Can you post there with what you have done and what the results are please? Just so we can keep this issue focused on tracking the docs updates. Thanks!

[prasoon-pxc]

Hi @awanlin , Yes I have existing issue for this,
I have setup Github-integration with github app using this doc also provide required permissions for Github-app to ingest users and teams

After that added below package:

yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github-org

added below line in packages/backend/src/index-tx

backend.add(import('@backstage/plugin-catalog-backend-module-github-org'));

app-config.yaml

integrations:
  github:
    - host: github.com
      apps:
        - $include: my-big-org.yaml

[awanlin]

@prasoon-pxc can you please post this here: #24559

[riginoommen]

LDAP i am actively looking for the docs. regarding the documentation with new backend system and with the usage of the transformers are needed

[ManuInNZ]

I've got a PR to update the GitHub Discovery and Org integration pages - #24573 - feel free to take a look.

@ManuInNZ, sorry, I know you posted that you would be working on this but we are seeing a lot of questions here and on Discord so I felt we needed to get moving. Feel free to review my PR, feedback would be very welcome.

@razvanonet @prasoon-pxc feel free to try out that PR, perhaps it can help you out, if not maybe add comments so I can improve it.

Sorry, I got side tracked on contributing to another project. Will review but I am sure it is great.

[awanlin]

Hi everyone, 20 out of the 48 pages have been updated or have a pending PR. We aren't even half way yet so if you can help out please do! 🙏

[aramissennyeydd]

@awanlin I think we can remove https://backstage.io/docs/auth/troubleshooting/ and https://backstage.io/docs/plugins/call-existing-api from the list. AFAICT they're both backend system agnostic - they definitely need a revamp but I think that can be a separate issue.

[awanlin]

Sure @aramissennyeydd, I've removed those two 👍