diff --git a/docs/federation/_category_.json b/docs/federation/_category_.json new file mode 100644 index 000000000..2990aa86a --- /dev/null +++ b/docs/federation/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Federation", + "position": 11, + "className": "federation-icon", + "customProps": { + "sidebar_pathname": "federation" + } +} diff --git a/docs/federation/architecture.mdx b/docs/federation/architecture.mdx new file mode 100644 index 000000000..40e1b46c7 --- /dev/null +++ b/docs/federation/architecture.mdx @@ -0,0 +1,149 @@ +--- +sidebar_position: 2 +description: "Understand the architecture of subgraph federation in Hasura DDN and how it enables efficient data +management across multiple subgraphs, promoting a collaborative development environment." +keywords: + - subgraph federation + - supergraph architecture + - data management + - collaborative development + - hasura ddn + - graphql api + - data connectors + - subgraph composition + - schema stitching + - modular development +seoFrontMatterUpdated: true +--- + +# Federation Architecture + +import Thumbnail from "@site/src/components/Thumbnail"; + +## Introduction + +Federation in Hasura DDN upgrades how you build and manage your API. + +It is the process of combining multiple subgraphs with multiple data sources into a single supergraph to create a +unified GraphQL API that provides access to all your data domains through a single endpoint. + +This architecture enables more collaborative workflows and allows teams to independently develop and deploy subgraphs +while maintaining strong governance over the development process. + +:::warning DDN Advanced plan required + +Independent subgraph development is only available on the [DDN Advanced plan](https://hasura.io/pricing/). + +::: + + + +## Benefits + +- **Modular Development:** Subgraphs promote modular development by allowing teams to independently develop, test, and + deploy their code without impacting the functionality of other subgraphs. This can also be done in independent + repositories for each subgraph, in a "multi-repo" setup. This modular approach simplifies code management and reduces + the risk of breaking changes. Subgraphs can be tested in context of the full supergraph to ensure that they work as + expected when combined. +- **Independent Deployment:** Subgraphs can also be deployed individually, ensuring that updates to one subgraph do not + require downtime for the entire supergraph. This flexibility allows for continuous integration and delivery (CI/CD) + practices that accelerate feature releases. +- **Improved Collaboration:** Subgraphs allow different teams to focus on their specialized data domains, fostering + collaboration by enabling them to share their APIs and data through a unified interface. This collaborative but + isolated workflow environment accelerates development times and reduces friction between teams. +- **Strong Governance:** Hasura DDN provides robust governance features, such as project collaboration roles and + permissions that ensure data integrity and security across subgraphs. These features enable teams to enforce data + policies and restrictions, protecting sensitive information and maintaining compliance with regulatory requirements. +- **Efficient Data Management:** Federation simplifies data management by enabling teams to work with smaller, more + manageable data domains. Teams can focus on their specific data requirements without being overwhelmed by the entire + data schema. + +## Subgraphs + +In Hasura DDN, a subgraph represents a self-contained module of metadata and its accompanying data connector(s) which +encapsulates a specific data domain. Subgraphs can be built completely independently of each other and also managed in +their own isolated repositories. + +Subgraph fields which are exposed to the full supergraph [can be prefixed](/federation/subgraph-prefixing.mdx) to +prevent conflicts in the schema. + +Data can be interlinked between subgraphs using [relationships](/supergraph-modeling/relationships.mdx) and even between +[subgraphs in separate repositories](/federation/cross-repo-relationships.mdx). + +## Globals subgraph + +When running the `ddn supergraph init` command, a `globals` subgraph is created by default for your convenience. This +subgraph is intended to hold global configuration objects for the supergraph, such as API configuration and auth +settings. + +These configuration objects are `AuthConfig`, `CompatibilityConfig` and `GraphqlConfig` as well as the `subgraph.yaml` +configuration file which defines the globals subgraph itself. + +These objects are located by default in the `globals` subgraph, but can be moved to any other subgraph if needed. + +## Subgraph-level authorization + +Authentication is managed at the supergraph level in Hasura DDN as defined by the `AuthConfig` object and cannot be +customized at the subgraph level. + +Authorization however, is managed at the subgraph level in Hasura DDN. This means that the permissions for models and +commands are defined within the context of those objects in their respective subgraphs, and do not affect other +subgraphs. + +Authorization rules in one subgraph can also be defined to reference data in a foreign subgraph even if that subgraph is +in another repository. + +## Data connectors + +[Data Connectors](/connectors/overview.mdx) connect subgraphs to data sources. They can communicate to data sources in +their native language, and are data source specific so we can leverage all the data source specific functionality. + +Each independent subgraph can have one or more data connectors. + +Data connectors are [available for a variety of data sources](https://hasura.io/connectors), including databases, +business logic functions, REST APIs, and GraphQL APIs. You can also create custom data connectors to integrate with +other data sources. + +The same underlying data source can be connected to multiple subgraphs via data connector instances in each. This allows +different teams to work with the same source from the perspective of different data domains. + +:::tip Read more about data connectors + +For a detailed overview of data connectors, check out our [Data Connectors Overview page](/connectors/overview.mdx) 📚 + +::: + +## Relationships + +Defining a [relationship](/supergraph-modeling/relationships.mdx) allows you to make queries across linked information +within and between subgraphs. + +As always when authoring metadata, the +[Hasura VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) can assist with +auto-complete and validation. When working with relationships across subgraphs in other repositories, there are some +differences to be aware of. Find out more about cross-repo relationships [here](/federation/cross-repo-relationships.mdx). + +## Example + +Imagine an e-commerce application with separate subgraphs for product catalog management, user profile information, and +order processing. + +1. **Product Catalog Subgraph:** A team dedicated to managing product information owns and maintains this subgraph. They + use a dedicated PostgreSQL data connector to connect to a relational database containing product details, images, and + inventory data. +2. **User Profile Subgraph:** The User Data team owns this subgraph, using a MongoDB data connector to interact with a + document database containing user profiles, preferences, and order history. +3. **Order Processing Subgraph:** Managed by the fulfillment team, this subgraph utilizes a custom TypeScript connector + to handle business logic related to order creation, payment processing, and shipment tracking, integrating with + external APIs and services. + +Each subgraph is developed, tested, and deployed independently, allowing teams to focus on their specific data domains +without interfering with other teams' work. The supergraph combines these subgraphs into a unified API that provides +access to all data domains through a single GraphQL endpoint. + +## Next steps + +- Learn more about git workflows when building supergraphs in [single-repo or multi-repo](/federation/independent-subgraph-development.mdx) + setups. +- Learn more about [subgraph prefixing](/federation/subgraph-prefixing.mdx) to avoid naming collisions in the schema. +- Learn more about [cross-repo relationships](/federation/cross-repo-relationships.mdx) to link data in subgraphs across diff --git a/docs/federation/build-commands.mdx b/docs/federation/build-commands.mdx new file mode 100644 index 000000000..c1abb97bc --- /dev/null +++ b/docs/federation/build-commands.mdx @@ -0,0 +1,74 @@ +--- +sidebar_position: 6 +sidebar_label: Build Commands +description: + "Commands for building supergraphs and subgraphs on Hasura DDN" +keywords: + - ddn + - build + - commands + - supergraph + - subgraph + - federation +seoFrontMatterUpdated: true +--- + +# Federation Build Command Examples + +A supergraph build is a combination of subgraph builds. + +This guide provides a overview of the commands available for building supergraphs and subgraphs on Hasura DDN. + +:::info Flags vs Context + +We are explicity using flags here to show what arguments are set, some of these can be set as +[context](/project-configuration/contexts.mdx). + +::: + +## Supergraph Builds + +#### Build the supergraph, all subgraphs and all connectors from the same single-repo project +```bash +ddn supergraph build create --supergraph supergraph.yaml +``` + +#### Build a Supergraph using explicitly specified subgraph builds (DDN Advanced only) +```bash +ddn supergraph build create --subgraph-version subA:4235698557 --subgraph-version subB:46241f2bd9 --subgraph-version subC:1ef62e5024 +``` + +#### Build a Supergraph using explicitly specified subgraph builds with an explicitly specified base supergraph version (DDN Advanced only) +```bash +ddn supergraph build create --subgraph-version globals:fc3ce56a69 --subgraph-version my_subgraph:ee738baa8f --base-supergraph-version 155e3569c4 +``` + +## Subgraph Builds + +#### Build a subgraph and all connectors in that subgraph on DDN +```bash +ddn subgraph build create --subgraph ./subgraph.yaml +``` + +#### Build a subgraph but skip rebuilding connectors in that subgraph +```bash +ddn subgraph build create --subgraph ./subgraph.yaml --no-build-connectors +``` + +#### Apply a subgraph build to a supergraph (Make it available for queries) +```bash +ddn subgraph build apply a1620044d7 +``` + +## Connector Builds + +#### Build a connector on DDN +```bash +ddn connector build create --connector ./connector.yaml +``` + +## Learn more + +- [Learn more about federation architecture](/federation/architecture.mdx) +- [Learn more about independent subgraph development](/federation/independent-subgraph-development.mdx) +- [Learn more about contexts](/project-configuration/contexts.mdx) diff --git a/docs/federation/cross-repo-relationships.mdx b/docs/federation/cross-repo-relationships.mdx new file mode 100644 index 000000000..aaeaf9957 --- /dev/null +++ b/docs/federation/cross-repo-relationships.mdx @@ -0,0 +1,120 @@ +--- +sidebar_label: Cross-repo Relationships +sidebar_position: 4 +description: "Learn how to create relationships across subgraphs in different repositories in Hasura DDN." +keywords: + - relationships + - cross-repo relationships + - subgraphs + - supergraph + - hasura ddn + - graphql api + - data connectors + - permissions + - federation + - multi-repo federation + - single-repo federation + - schema stitching + - modular development + - git workflows +seoFrontMatterUpdated: true +--- + +# Cross-repo Relationships + +## Connecting across subgraphs with relationships + +When you have multiple subgraphs, either in a single-repo or multi-repo setup, you can query across linked information. +This is done by creating a [`Relationship`](/supergraph-modeling/relationships.mdx) object in metadata which defines how +fields from one type map to a `model` or `command`. + +### Single-repo relationships + +In a single-repo setup, relationships are straightforward to manage. All subgraphs are in the same repository and the +[Hasura VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) can be used to assist +with authoring relationships, providing auto-complete and validation. + +### Cross-repo relationships + +:::info Advanced plan + +You will need a project on the [DDN Advanced plan](https://hasura.io/pricing) to use multi-repo federation and +cross-repo relationships. + +::: + +In a multi-repo setup, subgraphs that contain objects you want to relate can reside in different repositories, some of +which you may not have access to. In these cases the Hasura VS Code extension cannot validate the entirety of the +`Relationship` object and you will manually author cross-repo relationships and ensure that the field mappings are +correct. However, upon creating a supergraph build, all cross-subgraph metadata is validated to prevent mistakes from +being deployed to the final API. + +You can still easily use the Hasura DDN console to explore the supergraph and test relationships across subgraphs once +you have created a build. + +### Example + +Let's say you have a supergraph with two subgraphs, each managed in different repositories: `users` and `products`. + +The `users` subgraph in repo 'A' has a `User` type with a field called `user_favorite_product_id`. + +The `products` subgraph in repo 'B' has a `Product` type with a field called `id`. + +To create a relationship between these two types in different repositories, you would create a `Relationship` object in +the `users` subgraph metadata as normal. + +The LSP is able to understand that the `Product` type is in a different subgraph to which it does not have access and +will not give a warning on the foreign type. + +```yaml +kind: Relationship +version: v1 +definition: + name: favorite_product + sourceType: User + target: + model: + name: Product + subgraph: products + relationshipType: Object + mapping: + - source: + fieldPath: + - fieldName: user_favorite_product_id + target: + modelField: + - fieldName: id +``` + +This `Relationship` object defines a relationship called `favorite_product` from the `User` type to the `Product` type. +The `mapping` field specifies how the `user_favorite_product_id` field in the `User` type maps to the `id` field in the +`Product` type. + +After defining the cross-repo relationship, it's important to note that you won't be able to test this locally. To see +the relationship in action, you'll need to follow these steps: + +1. Create a new supergraph build on DDN using the `ddn supergraph build create` command. (Subgraph builds do not get an + API, so supergraph builds are required to test.) +2. You can then use the Hasura DDN console to explore and test the relationship across subgraphs. +3. If you have admin permissions, you can apply the subgraph to the supergraph with the `ddn subgraph apply` command. + +Remember, cross-repo relationships only come into effect when the subgraphs are combined in the DDN environment. Local +development and testing are limited to the scope of your current repository. + +With this relationship defined, you can now query the `favorite_product` field on the `User` type to retrieve the +related `Product`. + +```graphql +query { + users { + id + name + favorite_product { + id + name + } + } +} +``` + +For more information on how to create `Relationships` check out [this page](/supergraph-modeling/relationships.mdx). diff --git a/docs/federation/independent-subgraph-development.mdx b/docs/federation/independent-subgraph-development.mdx new file mode 100644 index 000000000..fd54d86b7 --- /dev/null +++ b/docs/federation/independent-subgraph-development.mdx @@ -0,0 +1,139 @@ +--- +sidebar_label: Independent Subgraph Development +sidebar_position: 3 +description: + "Learn how to manage your Git workflows for both single-repo and multi-repo federation in Hasura DDN. This guide will + walk you through setting up version control, collaborating with your team, and deploying your supergraph." +keywords: + - git workflows + - version control + - collaboration + - deployment + - single-repo federation + - multi-repo federation + - subgraphs + - supergraph + - hasura ddn + - data connectors + - permissions + - relationships +seoFrontMatterUpdated: true +--- + +# Independent Subgraph Development + +Teams working on larger projects may want a software development lifecycle (SDLC) and CI/CD which is independent of +other teams. This is where independent subgraph, multi-repo federation shines on the +[DDN Advanced plan](https://hasura.io/pricing) + +Subgraphs in this multi-repo federation are managed in their **own repository** for added governance, control and clean +separation from other teams work. Users and teams can be added to individual subgraphs on Hasura DDN as +[admins or developers](/getting-started/collaborate/invite.mdx), allowing them to work independently on their +subgraph and data connectors without affecting other subgraphs. Subgraphs would also typically be named for and +given responsibility over the data domain they encapsulate, such as `users`, `orders`, `products`, etc. + +:::warning DDN Advanced plan required + +You will need a project on the [DDN Advanced plan](https://hasura.io/pricing) to use independent subgraph development with a multi-repo setup. + +::: + +## Concepts to keep in mind + +- A supergraph build is a combination of subgraph builds. +- A supergraph build has an API and can be queried. +- A subgraph build has no API and cannot be queried in isolation. +- Building a subgraph will also build its associated data connectors. +- Supergraph and subgraph builds are immutable and have a unique id. +- Subgraph builds are added to the DDN project with the same name as defined in the subgraph's `subgraph.yaml` file. +- A subgraph must already exist in the DDN project in order to invite a collaborator to it. +- A supergraph must already be applied before a subgraph build can be made with it. +- A local independent subgraph development project must still have a supergraph with global objects defined (as in the + default `globals` subgraph). Its project context will reference the DDN project used for collaboration. +- Each subgraph is namespaced and internal metadata objects cannot conflict with other subgraphs. However, the GraphQL + API is where the subgraphs meet and conflicts can occur with root field and type names. Prefixing subgraphs will + remedy this automatically or it can be managed manually. + + +## Creating a new project with independent subgraph development + +### Creating the initial project + +The setup here is for a main supergraph repository to be created with the `globals` subgraph and placeholders for any +other subgraph which other teams will work on. Once on DDN, collaborators are added on the subgraph level giving +them permissions to only work on their subgraph. + +:::info Globals Subgraph Objects + +By convention, the globals subgraph contains supergraph-level metadata objects that apply to the entire supergraph. +These are `AuthConfig`, `CompatibilityConfig` and `GraphqlConfig` as well as the `Subgraph` object which defines the +globals subgraph itself. + +::: + +1. As a supergraph admin, [create a supergraph normally](/getting-started/quickstart.mdx), + [deploy](/getting-started/deployment/index.mdx) and apply on Hasura DDN, as per the + [getting started guide](/getting-started/build/index.mdx). +2. Create any other subgraphs which other teams will work on as placeholders so that they can be invited to them. You + can do this with [`ddn project subgraph create [flags]`](/cli/commands/ddn_subgraph_add.mdx) +3. Push the supergraph to a new Git repository. Do not add collaborators to this repo, they will be added to / create + their own subgraph repositories. +4. Invite subgraph collaborators to the Hasura DDN project with + [Subgraph Admin or Subgraph Developer permissions](/getting-started/collaborate/invite.mdx). + +### Joining the project + +Now, collaborators manage a separate local supergraph repo for development containing just their subgraph and changes +the supergraph context to reference the collaborative project on DDN. + +The supergraph enables local development but only contains their subgraph. They can then create subgraph builds on +the collaborative DDN project and, if permissions allow, apply the subgraph to the collaborative supergraph. + +1. [Accept the invitation](/getting-started/collaborate/invite.mdx) to the Hasura DDN supergraph project. +2. Create a new Git repository for a new supergraph. +3. Initialize a new supergraph with a subgraph locally. Make sure the subgraph is named the same as the subgraph + you were invited to work on. You can do this with: `ddn supergraph init . --create-subgraph ` +4. It's recommended to setup [subgraph prefixes](/federation/subgraph-prefixing.mdx) at this stage. +5. Run your supergraph locally and develop and test. +6. Map your local project to the existing project on DDN. You can do this with: + `ddn project init --with-project ` +7. [Create a subgraph build](/cli/commands/ddn_subgraph_build_create.mdx) on the existing Hasura DDN supergraph project. + You can do this with: `ddn subgraph build create` +8. Create a supergraph build on Hasura DDN. You can do this with: + `ddn supergraph build create --subgraph-version --base-supergraph-version ` +9. Deploy your subgraph changes if permissions allow. Otherwise, request the owner or admin to apply the subgraph. You + would do this with either `ddn subgraph build apply ` or + `ddn supergraph build apply ` + +:::tip Existing code repositories for new projects. + +If you already have an existing app or other repository to which you feel it appropriate to add your DDN project +configuration in a new directory, that's fine too! + +::: + +## Merging two existing projects + +If you have two existing projects on Hasura DDN which were developed independently that you would like to merge into a +single DDN project with independent subgraph development, you can do so by following these steps: + +1. Choose which project will be the main project and which will be the subgraph project. +2. In the main project, create a new subgraph placeholder for the subgraph project with + [`ddn project subgraph create [flags]`](/cli/commands/ddn_subgraph_add.mdx) +3. On DDN, invite the subgraph project collaborators with + [subgraph permissions](/getting-started/collaborate/invite.mdx). +4. Once the subgraph collaborators have accepted the invitation, they can + [set the project context](/project-configuration/contexts/) to the main project with `ddn context set project `. +5. Subgraph collaborators may also at this stage set [subgraph prefixes](/federation/subgraph-prefixing.mdx) to prevent + conflicts with the main project if needed. +6. The subgraph collaborators can then create a subgraph build on the main project with + [`ddn subgraph build create`](/cli/commands/ddn_subgraph_build_create.mdx). +6. The main project owner or admin can then apply the subgraph build to the main project with + [`ddn subgraph build apply `](/cli/commands/ddn_subgraph_build_apply.mdx). + +## Learn more + +- [Learn more about federation architecture](/federation/architecture.mdx) +- [Learn more about independent subgraph development](/federation/independent-subgraph-development.mdx) +- [Learn more about contexts](/project-configuration/contexts.mdx) +- [Learn more about build commands](/federation/build-commands.mdx) \ No newline at end of file diff --git a/docs/federation/overview.mdx b/docs/federation/overview.mdx new file mode 100644 index 000000000..092683fe8 --- /dev/null +++ b/docs/federation/overview.mdx @@ -0,0 +1,60 @@ +--- +sidebar_position: 1 +sidebar_label: Overview +description: + "Data federation in Hasura DDN enables you to combine data from multiple data sources and query it as if it was a + single entity." +keywords: + - hasura ddn + - graphql api +hide_table_of_contents: true +--- + +import { OverviewTopSectionIconNoVideo } from "@site/src/components/OverviewTopSectionIconNoVideo"; +import { OverviewPlainCard } from "@site/src/components/OverviewPlainCard"; +import Icon from "@site/static/icons/data_federation.svg"; + +# Federation + +} + links={[]} + intro={ +
+

The concept of data federation is intrinsic to Hasura DDN.

+

+ By adding multiple data sources, logic and third-party APIs to multiple subgraphs and stitching those subgraphs + together, you are able to bring together all your data domains owned by multiple teams into one supergraph and + query across all of them in a single elegant request. +

+

+ Our collaboration features also enable separate software development life cycles (SDLC) and CI/CD for each subgraph team in the DDN Advanced plan. +

+
+ } +/> + +
+ + + + + + + +
diff --git a/docs/federation/subgraph-prefixing.mdx b/docs/federation/subgraph-prefixing.mdx new file mode 100644 index 000000000..dd081420f --- /dev/null +++ b/docs/federation/subgraph-prefixing.mdx @@ -0,0 +1,47 @@ +--- +sidebar_position: 5 +sidebar_label: Subgraph Prefixing +description: + "Learn how to avoid naming collisions between subgraphs in Hasura DDN by customizing prefixes for root fields and type + names." +keywords: + - subgraph prefixing + - naming collisions + - subgraph.yaml + - graphqlRootFieldPrefix + - graphqlTypeNamePrefix + - supergraph modeling + - hasura ddn + - graphql api + - subgraphs + - supergraph + - data connectors + - permissions + - relationships +seoFrontMatterUpdated: true +--- + +# Subgraph Prefixing + +To avoid collisions between GraphQL root fields and type names across when federating subgraphs, you can optionally +customize the prefixes for each. For example, if two subgraphs both have a `Users` type, you can apply different +prefixes to distinguish one from the other. This ensures that each subgraph remains unique and prevents any naming +conflicts. + +You can make these modifications in the `subgraph.yaml` file for a subgraph. + +```yaml title="Add the highlighted lines:" +kind: Subgraph +version: v2 +definition: + name: my_subgraph + generator: + rootPath: . + #highlight-start + graphqlRootFieldPrefix: my_subgraph_ + graphqlTypeNamePrefix: My_subgraph_ + #highlight-end +``` + +By default, the `subgraph.yaml` file is generated without any prefixes. You can read more about these fields +[here](supergraph-modeling/build-configs.mdx#subgraph-subgraphgeneratorconfig). diff --git a/src/theme/DocSidebarItem/utils.js b/src/theme/DocSidebarItem/utils.js index c502ead02..f3aed570c 100644 --- a/src/theme/DocSidebarItem/utils.js +++ b/src/theme/DocSidebarItem/utils.js @@ -14,6 +14,7 @@ import GraphQLAPI from '@site/static/icons/graphql-logo.svg'; import ProjectConfiguration from '@site/static/icons/dataflow-01.svg'; import HasuraCLI from '@site/static/icons/terminal-square.svg'; import Observability from '@site/static/icons/eye.svg'; +import Federation from '@site/static/icons/data_federation.svg'; import Enterprise from '@site/static/icons/features/enterprise.svg'; import Glossary from '@site/static/icons/box.svg'; import Quickstart from '@site/static/icons/speedometer-04.svg'; @@ -81,6 +82,9 @@ export function addIconsToLabel(label, className) { case 'observability-icon': icons = ; break; + case 'federation-icon': + icons = ; + break; case 'enterprise-icon': icons = ; break; diff --git a/static/icons/data_federation.svg b/static/icons/data_federation.svg new file mode 100644 index 000000000..ff5a8723f --- /dev/null +++ b/static/icons/data_federation.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/static/img/federation/whole-supergraph-erd.png b/static/img/federation/whole-supergraph-erd.png new file mode 100644 index 000000000..812fe4ab3 Binary files /dev/null and b/static/img/federation/whole-supergraph-erd.png differ diff --git a/tsconfig.json b/tsconfig.json index 06f8016ba..76f67daa5 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -4,8 +4,8 @@ "compilerOptions": { "baseUrl": ".", "paths": { - "@site/*": ["./*"], - }, + "@site/*": ["./*"] + } }, - "noImplicitAny": true, + "noImplicitAny": true }