Julius de Bruijn

## Prerequisites

- Docker installed for Docker deployment
- Kubernetes cluster and kubectl for Kubernetes deployment
- Helm installed for Kubernetes deployment
- Grafbase Access Token (if using schema registry, or dashboard analytics)
- Grafbase graph ref (if using schema registry), or a local federated schema file
- Locally built or downloaded extensions (from `grafbase extension install`) and a configuration file (`grafbase.toml`) with an extensions section

## Understanding Grafbase Gateway with Extensions

Grafbase Gateway is a GraphQL federation gateway that can be extended with custom functionality through extensions. Extensions allow you to add custom resolvers, authentication logic, and more to your GraphQL API.

Extensions are implemented as WebAssembly components that are loaded by the gateway at runtime. The extensions are installed in a directory named `grafbase_extensions`, which must be available to the gateway when it starts. Alternatively, you can define the extension to be in a specific path in `grafbase.toml` under the `extensions` section. This path must have a valid extension WebAssembly component, and the manifest file.

To set up a Grafbase Gateway with extensions, you need:

1. The `grafbase-gateway` binary
2. A `grafbase_extensions` directory containing installed extensions
3. A configuration file (typically `grafbase.toml`)
4. Either environment variables to fetch the schema from Grafbase's registry, or a local federated GraphQL schema file

## Docker Deployment

### Using Schema Registry with Docker

This approach uses the Schema Registry to fetch the graph schema based on a Graph Reference and Access Token. This method polls for changes to the schema automatically every ten seconds, and restarts the gateway with changes.

#### Step 1: Create a Dockerfile

Create a `Dockerfile` in the root of your project.

```dockerfile
FROM ghcr.io/grafbase/gateway:0.38.0 # or later version!

# Create directories
WORKDIR /app

# Copy the configuration file
COPY grafbase.toml /app/grafbase.toml

# Copy the extensions directory if you have custom extensions
COPY grafbase_extensions /app/grafbase_extensions

# Set default command
CMD ["--config", "/app/grafbase.toml"]
```

#### Step 2: Create a Grafbase Configuration File

Create a `grafbase.toml` file in the root of your project.

```toml
[graph]
introspection = true

[network]
listen_address = "0.0.0.0:5000"

[extensions]
rest = "0.4"
```

#### Step 3: Install Extensions

Before building the Docker image, install the extensions:

```bash
grafbase extension install
```

This will create or update the `grafbase_extensions` directory with the specified extensions.

#### Step 4: Create a Subgraph per Extension Instructions

Before deploying the gateway, create all subgraphs as needed, and publish them to the Schema Registry. For this simple example, we will create a subgraph that fetches country names from a public REST API.

Create a `subgraph.graphql` in the root of your project:

```graphql
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
  @link(url: "https://grafbase.com/extensions/rest/0.4.1", import: ["@restEndpoint", "@rest"])

@restEndpoint(
  name: "restCountries",
  baseURL: "https://restcountries.com/v3.1"
)

type Country {
  name: String!
}

type Query {
  listAllCountries: [Country!]! @rest(
    method: GET
    endpoint: "restCountries"
    path: "/all"
    selection: "[.[] | { name: .name.official }]"
  )
}
```

Publish the subgraph to the Schema Registry:

```bash
grafbase publish \
    --name restCountries \
    your-org/your-graph@branch \
    -m initx \
    --virtual \
    --schema subgraph.graphql
```

#### Step 5: Create a Docker Compose Configuration

Create a `compose.yml` in the root of your project:

```yaml
services:
  grafbase:
    build: .
    restart: always
    environment:
      GRAFBASE_GRAPH_REF: 'your-graph@branch'
      GRAFBASE_ACCESS_TOKEN: 'your-access-token'
    ports:
      - '5000:5000'
```

The access token should be created in the Grafbase dashboard, and scoped to have access to the graph.

#### Step 5: Build and Run

```bash
docker-compose up -d
```

### Using Local GraphQL Schema with Docker

This approach uses a local federated GraphQL schema file instead of fetching it from the Schema Registry. This step requires you to manually fetch the federated schema when it is updated. You can replace the schema file in the running container without restarting the gateway. The gateway will automatically reload the schema when it changes.

#### Step 1: Create a Dockerfile

Add the following content to the `compose.yml` file:

```dockerfile
FROM ghcr.io/grafbase/gateway:0.38.0 # or later

# Create directories
WORKDIR /app

# Copy the configuration file
COPY grafbase.toml /app/grafbase.toml

# Copy the federated schema
COPY federated-graph.graphql /app/federated-graph.graphql

# Copy the extensions directory
COPY grafbase_extensions /app/grafbase_extensions

# Set default command
CMD ["--config", "/app/grafbase.toml", "--schema", "/app/federated-graph.graphql"]
```

#### Step 2: Create a Grafbase Configuration File

Same as the previous example.

#### Step 3: Install Extensions

Same as the previous example.

#### Step 4: Create an Publish Subgraph

Same as the previous example.

#### Step 5: Fetch the Federated Schema

After successfully publishing a subgraph, fetch the federated schema using the following command:

```bash
grafbase schema your-org/your-graph@branch > federated-graph.graphql
```

#### Step 6: Create a Docker-compose.yml File

```yaml
version: '3'
services:
  grafbase:
    build: .
    restart: always
    ports:
      - '5000:5000'
    # keep the environment variables if you want dashboard
    # analytics. remove, if you want to run the gateway
    # totally air-gapped
    environment:
      GRAFBASE_GRAPH_REF: 'your-graph@branch'
      GRAFBASE_ACCESS_TOKEN: 'your-access-token'
    volumes:
      # Mount the schema file as a volume for easy updates
      - ./federated-graph.graphql:/app/federated-graph.graphql
```

#### Step 7: Build and Run

```bash
docker-compose up -d
```

## Kubernetes Deployment

### Using Schema Registry with Kubernetes

This method uses Helm to deploy the Grafbase Gateway that fetches the schema from the Schema Registry.

#### Step 1: Create a Custom Values File for Helm

Create a custom `values.yaml` file for Helm:

```yaml
replicaCount: 2

image:
  repository: ghcr.io/grafbase/gateway
  tag: 0.38.0 # or later version
  pullPolicy: Always

service:
  type: ClusterIP
  port: 80
  targetPort: 5000

gateway:
  externalSchema: true
  externalConfig: false
  config: |
    [graph]
    introspection = true

    [network]
    listen_address = "0.0.0.0:5000"

    [extensions]
    rest = "0.4"

secrets:
  enabled: true
  values:
    GRAFBASE_GRAPH_REF: "your-graph@branch"
    GRAFBASE_ACCESS_TOKEN: "your-access-token"

# Create a ConfigMap to store extensions
volumes:
  - name: extensions
    configMap:
      name: grafbase-extensions

volumeMounts:
  - name: extensions
    mountPath: /app/grafbase_extensions
```

#### Step 2: Prepare Extensions Directory

Install the extensions locally:

```bash
grafbase extension install
```

#### Step 3: Create a ConfigMap for Extensions

Create a ConfigMap from the extensions directory:

```bash
kubectl create configmap grafbase-extensions --from-file=grafbase_extensions/
```

Or define it in a YAML file:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: grafbase-extensions
data:
  # Content of each extension file, converted to base64
  # This would be automatically populated when using the kubectl create command
```

#### Step 4: Install the Helm Chart

```bash
helm install grafbase-gateway oci://ghcr.io/grafbase/helm-charts/gateway --version 0.2.5 -f values.yaml
```

### Using Local GraphQL Schema with Kubernetes

This method uses a local federated GraphQL schema file stored in a ConfigMap.

#### Step 1: Create a Custom Values File for Helm

Create a custom `values.yaml` file for Helm:

```yaml
replicaCount: 2

image:
  repository: ghcr.io/grafbase/gateway
  tag: 0.38.0 # or lateer
  pullPolicy: Always

service:
  type: ClusterIP
  port: 80
  targetPort: 5000

gateway:
  externalSchema: true
  externalConfig: false
  config: |
    [graph]
    introspection = true

    [network]
    listen_address = "0.0.0.0:5000"

    [extensions]
    rest = "0.4"

  args:
    - --config
    - /etc/grafbase/config/grafbase.toml
    - --schema
    - /etc/grafbase/schema/federated-graph.graphql

# Create volumes for config, schema, and extensions
volumes:
  - name: schema
    configMap:
      name: grafbase-schema
  - name: extensions
    configMap:
      name: grafbase-extensions

volumeMounts:
  - name: schema
    mountPath: /etc/grafbase/schema
  - name: extensions
    mountPath: /app/grafbase_extensions
```

#### Step 2: Prepare Your Configuration and Schema

Create ConfigMaps for the configuration, schema, and extensions:

```bash
# For the schema
kubectl create configmap grafbase-schema --from-file=federated-graph.graphql

# For extensions
grafbase extension install
kubectl create configmap grafbase-extensions --from-file=grafbase_extensions/
```

#### Step 3: Install the Helm Chart

```bash
helm install grafbase-gateway oci://ghcr.io/grafbase/helm-charts/gateway --version 0.2.5 -f values.yaml
```

## Additional Configuration

### Customizing Extensions

You can customize extensions by modifying your `grafbase.toml` file. For example, to configure the JWT extension:

```toml
[extensions.jwt]
version = "1.0"

[extensions.jwt.config]
jwks.url = "https://example.com/.well-known/jwks.json"
jwks.issuer = "example.com"
jwks.audience = "my-project"
jwks.poll_interval = 60

[extensions.jwt.config.header]
name = "Authorization"
value_prefix = "Bearer "
```

### Health Checks

Configure health checks in your `grafbase.toml`:

```toml
[health]
enabled = true
listen = "0.0.0.0:9668"
path = "/health"
```

### Advanced Telemetry

For production environments, you might want to set up telemetry:

```toml
[telemetry]
service_name = "my-federated-graph"

[telemetry.tracing]
enabled = true
sampling = 1

[telemetry.tracing.exporters.otlp]
enabled = true
endpoint = "http://my-otel-collector:4317"
protocol = "grpc"
timeout = 5
```

## Conclusion

This guide has demonstrated how to deploy Grafbase Gateway with extensions in both Docker and Kubernetes environments. By following these instructions, you can set up a flexible and extensible GraphQL federation gateway that meets your specific needs, whether you're using Grafbase's Schema Registry or a local schema file.

Deploy your Grafbase Gateway with Extensions to Docker, Kubernetes, or any other platform.

Get Started

Learn how to deploy Grafbase Gateway with Extensions to Docker, Kubernetes, or any other platform.

Deploying Grafbase Gateway with Extensions

GraphQL Federation combines the best features of monolith APIs and microservices into one API architecture. It gives you a single endpoint for all your services while keeping a distributed architecture. Federation delivers decoupled design, schema composition, and efficient data querying.

GraphQL Federation helps you combine multiple APIs into a single, federated graph. This federated graph allows clients to interact with your APIs through a single request. A client sends a request to the federated GraphQL API's single entry point - the Grafbase Gateway. The gateway orchestrates and distributes the request across your APIs and returns a unified response. For a client, querying the gateway feels identical to querying any GraphQL server.

Build three simple subgraphs: `accounts`, `products`, and `reviews`. Experience GraphQL Federation, publish subgraphs to a federated graph, join data between subgraphs, and add different federation directives to the schema.

## Prerequisites

Create a new account on the [Grafbase dashboard](/dashboard), and install the [Grafbase CLI](/docs/reference/grafbase-cli) and [Grafbase Gateway](/docs/reference/gateway/installation) before you start.

## Accounts Subgraph

Start by creating the `accounts` subgraph with Node.js and GraphQL Yoga. First, create a new directory and initialize a new Node.js project.

```bash
mkdir accounts && cd accounts
npm init -y
npm install graphql-yoga @apollo/subgraph graphql
```

Next, create a new file `index.js` and add the following code:

```javascript
import { createSchema, createYoga } from "graphql-yoga";
import { createServer } from "http";

const users = [
  {
    id: "1",
    email: "john@example.com",
    username: "john_doe",
  },
  {
    id: "2",
    email: "bob@example.com",
    username: "bob_dole",
  },
];

const schema = createSchema({
  typeDefs: /* GraphQL */ `
    type Query {
      users: [User!]!
    }

    type User {
      id: ID!
      email: String!
      username: String!
    }
  `,
  resolvers: {
    Query: {
      users: () => users,
    },
  },
});

const yoga = createYoga({ schema });
const server = createServer(yoga);

server.listen(4000, () => {
  console.log("🚀 Server ready at http://localhost:4000/graphql");
});
```

Launch the server by running `node index.js`. Access the GraphQL playground at [http://localhost:4000/graphql](http://localhost:4000/graphql).

The `accounts` subgraph is simple and not yet ready for Federation. A single query `users` returns all users in the subgraph:

```graphql
query {
  users {
    id
    email
    username
  }
}
```

Which returns:

```json
{
  "data": {
    "me": {
      "id": "1",
      "email": "john@example.com",
      "username": "john_doe"
    }
  }
}
```

While the Grafbase Gateway typically federates multiple subgraphs, you can create a configuration for a single subgraph and publish it to the schema registry. Use the [grafbase dev](/docs/reference/grafbase-cli/dev) command to start the local dev server. Add this to the `grafbase.toml` configuration file:

```toml
[subgraphs.accounts]
introspection_url = "http://localhost:4000/graphql"
```

Start the Grafbase dev server:

```bash
grafbase dev
```

Open Explorer and query the federated graph at `http://127.0.0.1:5000`.

### Federating the Account subgraph with the @key Directive

Define an identifier for a type to be part of federation. The `User` type has the `id` field as the identifier. Add the [`@key` directive](/docs/reference/graphql-directives#key) to the `User` type:

```graphql
type Query {
  me: User
}

type User @key(fields: "id") {
  id: ID!
  email: String!
  username: String!
}
```

Modify the Yoga server to accommodate federation. Use the `@apollo/subgraph` package to create a federated schema, parse the schema with `graphql` library and add the edge `__resolveReference` to the user type. The [`@key` directive](/docs/reference/graphql-directives#key) identifies `User` as an entity with the `id` field. Use the same `User` type in multiple subgraphs, with each subgraph resolving the `User` type by its `id`. The `__resolveReference` function resolves the user by the `id` field, returning the user object. It is called when the gateway needs to resolve a user reference.

```javascript
import { buildSubgraphSchema } from "@apollo/subgraph";
import { parse } from "graphql";
import { createYoga } from "graphql-yoga";
import { createServer } from "http";

const users = [
  {
    id: "1",
    email: "john@example.com",
    username: "john_doe",
  },
  {
    id: "2",
    email: "bob@example.com",
    username: "bob_dole",
  },
];

const typeDefs = parse(/* GraphQL */ `
  type Query {
    users: [User!]!
  }

  type User @key(fields: "id") {
    id: ID!
    email: String!
    username: String!
  }
`);

const resolvers = {
  Query: {
    users: () => users,
  },
  User: {
    __resolveReference: (user) => users.find((u) => u.id === user.id),
  },
};

const schema = buildSubgraphSchema({
  typeDefs,
  resolvers,
});

const yoga = createYoga({ schema });
const server = createServer(yoga);

server.listen(4000, () => {
  console.log("🚀 Server ready at http://localhost:4000/graphql");
});
```

Restart the yoga server after making changes. The Grafbase dev server automatically updates the subgraph.

## Products Subgraph

Create a new `products` directory and initialize a new Node.js project:

```bash
mkdir products && cd products
npm init -y
npm install graphql-yoga @apollo/subgraph graphql
```

Create a new file `index.js` and add this code:

```javascript
import { buildSubgraphSchema } from "@apollo/subgraph";
import { parse } from "graphql";
import { createYoga } from "graphql-yoga";
import { createServer } from "http";

const typeDefs = parse(`
  type Query {
    topProducts(first: Int = 5): [Product]
  }

  type Product @key(fields: "id") {
    id: String!
    upc: String!
    name: String!
    price: Int!
  }
`);

const products = [
  {
    id: "1",
    upc: "upc-1",
    name: "Product 1",
    price: 999,
  },
  {
    id: "2",
    upc: "upc-2",
    name: "Product 2",
    price: 1299,
  },
];

const resolvers = {
  Query: {
    topProducts: (_, { first = 5 }) => products.slice(0, first),
  },
  Product: {
    __resolveReference: (reference) => {
      return products.find((p) => p.id === reference.id);
    },
  },
};

const yoga = createYoga({
  schema: buildSubgraphSchema([
    {
      typeDefs,
      resolvers,
    },
  ]),
});

const server = createServer(yoga);

server.listen(4001, () => {
  console.log("🚀 Server ready at http://localhost:4001/graphql");
});
```

The `Product` type has two identifiers, `id` and `upc`, both required to resolve the type. A new query `topProducts` returns the top products. Edit the `grafbase.toml` file to include the new subgraph:

```toml
[subgraphs.accounts]
introspection_url = "http://localhost:4000/graphql"

[subgraphs.products]
introspection_url = "http://localhost:4001/graphql"
```

The Grafbase dev server now has two subgraphs, `accounts` and `products`. Access both by calling the `topProducts` query from the `products` subgraph and the `me` query from the `accounts` subgraph.

## Reviews Subgraph

Create the final `reviews` subgraph. Create a new directory `reviews` and initialize a new Node.js project:

```bash
mkdir reviews && cd reviews
npm init -y
npm install graphql-yoga @apollo/subgraph graphql
```

Create a new file `index.js` and add this code:

```javascript
import { buildSubgraphSchema } from "@apollo/subgraph";
import { parse } from "graphql";
import { createYoga } from "graphql-yoga";
import { createServer } from "http";

// Define the schema
const typeDefs = parse(`
  type Product @key(fields: "id") {
    id: String! @external
    reviews: [Review]
  }

  type User @key(fields: "id") {
    id: ID! @external
    email: String! @external
    username: String! @external
    reviews: [Review]
  }

  type Review {
    body: String!
    author: User!
    product: Product!
  }
`);

// Mock data
const reviews = [
  {
    body: "Great product!",
    authorId: "1",
    productId: "1",
  },
  {
    body: "Would recommend!",
    authorId: "2",
    productId: "2",
  },
];

// Define resolvers
const resolvers = {
  Product: {
    __resolveReference: (reference) => {
      return { id: reference.id };
    },
    reviews: (product) => {
      return reviews.filter((review) => review.productId === product.id);
    },
  },
  User: {
    __resolveReference: (reference) => {
      return { id: reference.id };
    },
    reviews: (user) => {
      return reviews.filter((review) => review.authorId === user.id);
    },
  },
  Review: {
    author: (review) => {
      return { id: review.authorId };
    },
    product: (review) => {
      return { id: review.productId };
    },
  },
};

// Create the yoga server
const yoga = createYoga({
  schema: buildSubgraphSchema([
    {
      typeDefs,
      resolvers,
    },
  ]),
});

// Create and start the server
const server = createServer(yoga);
server.listen(4002, () => {
  console.log("🚀 Server ready at http://localhost:4002/graphql");
});
```

This subgraph extends the `Product` and `User` types from the `products` and `accounts` subgraphs instead of defining queries. Fields with the `@external` directive resolve by the parent subgraph; this subgraph only provides reviews for products and users.

The Grafbase Gateway gets product reviews by sending the product id to find all reviews. The same applies to users.

The review object returns the author and product IDs. The gateway resolves the author and product based on these IDs.

Add the `reviews` subgraph to the `grafbase.toml` file:

```toml
[subgraphs.accounts]
introspection_url = "http://localhost:4000/graphql"

[subgraphs.products]
introspection_url = "http://localhost:4001/graphql"

[subgraphs.reviews]
introspection_url = "http://localhost:4002/graphql"
```

With three subgraphs in the federated graph, query and join data between them:

```graphql
query Users {
  users {
    id
    email
    username
    reviews {
      body
      product {
        id
        name
        price
        upc
      }
    }
  }
}
```

This query returns all users from `accounts`, their reviews from `reviews` and product information from `products`:

```json
{
  "data": {
    "topProducts": [
      {
        "id": "1",
        "name": "Product 1",
        "price": 999,
        "reviews": [
          {
            "author": {
              "id": "1",
              "email": "john@example.com",
              "username": "john_doe"
            },
            "body": "Great product!"
          }
        ]
      },
      {
        "id": "2",
        "name": "Product 2",
        "price": 1299,
        "reviews": [
          {
            "author": {
              "id": "2",
              "email": "bob@example.com",
              "username": "bob_dole"
            },
            "body": "Would recommend!"
          }
        ]
      }
    ]
  }
}
```

Click "Response Query Plan view" in Pathfinder to see the query plan:

![Query Plan](/images/docs/quickstart/query-plan.png)

The query plan shows how the federated graph resolves queries. It first gets `topProducts` from `products`, then gets `_entities` from `reviews` with product IDs from `topProducts`, and finally gets `_entities` from `accounts` with user IDs from `reviews`. The Grafbase Gateway minimizes requests and resolves data efficiently. If possible, it runs some queries in parallel to speed up response time.

## Using the @requires Directive

Our actual reviews graph does not hold the user ID. The `@requires` directive lets the reviews graph define what fields it requires when querying user reviews. The graph uses a secondary key with username and email to fetch reviews . Add the `@requires` directive to the `reviews` field in the `User` type. A different subgraph resolves the email and username fields marked with the `@external` directive.

```graphql
type User @key(fields: "id") {
  id: ID! @external
  email: String! @external
  username: String! @external
  reviews: [Review] @requires(fields: "email username")
}
```

We can now modify our reviews subgraph to use the `email` and `username` fields to fetch the reviews based on these fields:

```javascript
const resolvers = {
  User: {
    __resolveReference: (reference) => {
      return {
        // The gateway will call this edge first, providing us the email and username fields which we add to the response.
        email: reference.email,
        username: reference.username,
      };
    },
    reviews: (user) => {
      // We can now use the email and username fields to fetch the reviews.
      return reviews.filter(
        (review) =>
          review.email === user.email && review.username === user.username,
      );
    },
  },
};
```

We also need to modify the `User` type in the accounts subgraph to include the `email` and `username` fields as a secondary key:

```graphql
type User @key(fields: "id") @key(fields: "email username") {
  id: ID!
  email: String!
  username: String!
}
```

And finally modify the resolver for a `User` to allow querying by email and username:

```javascript
const resolvers = {
  User: {
    __resolveReference: (user) => {
      if (user.id) {
        return users.find((u) => u.id === user.id);
      } else {
        return users.find(
          (u) => u.email === user.email && u.username === user.username,
        );
      }
    },
  },
};
```

Restart the subgraph and run a query to see the results:

```graphql
query {
  topProducts {
    name
    price
    reviews {
      body
      author {
        id
        username
      }
    }
  }
}
```

Even if our reviews graph does not hold the user ID, the gateway can resolve the reviews based on the email and username fields. The ID of the author is fetched from the accounts subgraph.

## Publish the Federated Graph

After creating and testing the subgraphs, publish the graph to Grafbase Platform. Create a new graph in the [Grafbase Dashboard](/dashboard).

![Create New Graph](/images/docs/quickstart/create-graph.png)

Name the graph `quickstart` and click "Create Graph". Use the graph reference to publish the graph.

**Note**: for the following steps, we assume you have [installed the Grafbase CLI](/docs/reference/grafbase-cli#installation) and either [logged in](/docs/reference/grafbase-cli/login) or set the `GRAFBASE_ACCESS_TOKEN` environment variable to a valid access token. Access tokens can be created from the dashboard.

From the terminal, publish the subgraphs. First introspect the running `accounts` subgraph, then pipe output to publish. Provide the subgraph name, URL, commit message and `organization-name/graph` slug:

```bash
grafbase introspect http://localhost:4000/graphql \
    | grafbase publish \
        --name accounts \
        --url http://localhost:4000/graphql \
        --message "init accounts" \
        my-org/quickstart
```

Repeat for `products` and `reviews`:

```bash
grafbase introspect http://localhost:4001/graphql \
    | grafbase publish \
        --name products \
        --url http://localhost:4001/graphql \
        --message "init products" \
        my-org/quickstart

grafbase introspect http://localhost:4002/graphql \
    | grafbase publish \
        --name reviews \
        --url http://localhost:4002/graphql \
        --message "init reviews" \
        my-org/quickstart
```

The schema and subgraphs appear in the [Grafbase Dashboard](/dashboard) after publishing.

## Grafbase Gateway

The [Grafbase Gateway](/docs/reference/gateway/installation) deploys as a single binary in your infrastructure. The gateway optimizes for production while sharing code with dev. It automatically detects and updates on federated graph changes.

After installation, create an access token in organization settings:

![New Access Token](/images/docs/quickstart/access-tokens.png)

Export it and start the gateway:

```bash
export GRAFBASE_ACCESS_TOKEN="ey..."
grafbase-gateway --graph-ref quickstart
```

Use Pathfinder in the Grafbase Dashboard to query the federated graph. Set the endpoint URL to http://127.0.0.1:5000/graphql before the first query.

Deploy a production gateway to a server with proper domain and SSL. For testing, configure the local gateway to trace all requests. Edit `grafbase.toml`:

```toml
[telemetry.tracing]
sampling = 1
```

Restart the gateway:

```bash
grafbase-gateway --graph-ref quickstart --config grafbase.toml
```

Return to Pathfinder, run the previous query:

```graphql
query Users {
  users {
    id
    email
    username
    reviews {
      body
      product {
        id
        name
        price
        upc
      }
    }
  }
}
```

Click "Response Trace view" to see sequential queries to `accounts`, `reviews`, and `products`:

![Trace](/images/docs/quickstart/tracing.png)

## Schema Checks

It is a good practice to run schema checks before deploying changes to the federated graph.

Enable operation checks for the production branch in schema checks settings for best results:

![Operation checks](/images/docs/quickstart/schema-checks.png)

Try changing a queried field. Make the username optional in `accounts`:

```graphql
type Query {
  users: [User!]!
}

type User @key(fields: "id") {
  id: ID!
  email: String!
  username: String
}
```

Restart the `accounts` subgraph and run schema checks against the federated graph:

```bash
grafbase introspect http://localhost:4000/graphql \
    | grafbase check --name accounts my-org/quickstart
```

The check returns an error because clients queried `username` in the past seven days:

```
❌ [Error] The field `User.username` became optional, but clients do not expect null.
```

You can fix the error by making sure no clients query `username` for the configured period, or by making the field non-optional.

## Client Analytics

Define these headers in clients using the Grafbase Gateway federated graph:

- `x-grafbase-client-name` for client name
- `x-grafbase-client-version` for client version

These headers let Grafbase analytics show which clients access which fields, helping track field usage as schemas grow.

## Conclusion

This guide showed how to create and federate three subgraphs, use Grafbase Gateway to query them, and publish to Grafbase Enterprise Platform.

Grafbase Gateway leads the market in GraphQL gateway speed and aims for full GraphQL Federation v2 compatibility. We continuously improve and add features. [Contact us](/contact) with questions or feedback.

Learn how to build, federate, and publish GraphQL subgraphs with Grafbase Gateway.

Introduction to GraphQL Federation, a powerful tool for building scalable and distributed GraphQL APIs.

Introduction to GraphQL Federation

In this guide, we will walk you through how to install the Grafbase Enterprise Platform to a Kubernetes cluster. For simplicity, in this guide we use [kind](https://kind.sigs.k8s.io/) to create a local Kubernetes cluster.

## Prerequisites

Before you start the installation, make sure you have the following prerequisites:

- [Kubernetes IN Docker](https://kind.sigs.k8s.io/)
- [Helm](https://helm.sh/)

## Creating the Kind Cluster

First, create a kind cluster. Use the following configuration for the cluster:

```yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      # api
      - containerPort: 30080
        hostPort: 30080
        protocol: TCP
      # dashboard
      - containerPort: 30081
        hostPort: 30081
        protocol: TCP
      # postgres
      - containerPort: 30432
        hostPort: 30082
        protocol: TCP
      # clickhouse
      - containerPort: 30900
        hostPort: 30083
        protocol: TCP
      # minio api
      - containerPort: 30801
        hostPort: 30084
        protocol: TCP
      # minio console
      - containerPort: 30800
        hostPort: 30085
        protocol: TCP
      # gateway
      - containerPort: 30500
        hostPort: 30086
        protocol: TCP
      # telemetry sink
      - containerPort: 30431
        hostPort: 30087
        protocol: TCP
```

Save the configuration to a file, for example `kind-config.yaml`, and create the cluster:

```bash
kind create cluster --name grafbase-enterprise-platform --config kind-config.yaml
kubectl config use-context kind-grafbase-enterprise-platform
```

## Installing the Grafbase Enterprise Platform

Before you start the installation, log in to the grafbase enterprise repository:

```bash
helm registry login helm.grafbase.com --username me@company.com --password changeme
```

When done, download the Grafbase Enterprise Platform Helm chart:

```bash
helm pull oci://helm.grafbase.com/enterprise-platform/stable/enterprise-platform
```

Create a new file `values.yaml.gotmpl` with the following values:

```yaml
global:
  zitadel:
    enabled: true
  postgresql:
    enabled: true
  clickhouse:
    enabled: false
  minio:
    enabled: true
  wreplicated:
    enabled: true
  kafka:
    enabled: false
  telemetrySink:
    enabled: false
  otelCollector:
    enabled: false
  dashboard:
    enabled: true

api:
  configmap:
    values:
      AWS_ACCESS_KEY_ID: changeme
  service:
    type: NodePort
    nodePort: 30080
  secrets:
    values:
      AWS_SECRET_ACCESS_KEY: changeme

dashboard:
  service:
    type: NodePort
    nodePort: 30081

minio:
  service:
    type: NodePort
    nodePorts:
      api: 30800
      console: 30801
```

Install the Helm chart with the following command:

```bash
helm install grafbase-enterprise-platform enterprise-platform-*.tgz -f values.yaml.gotmpl
```

Wait a bit for the cluster to get ready, and you can see the API web worker crashing due to not being able to access the AWS S3 bucket:

```bash
> kubectl logs grafbase-enterprise-platform-api-web-69644fb98b-djgt2
{"timestamp":"2025-01-20T18:14:10.955429888+00:00","level":"INFO","fields":{"message":"API running at 0.0.0.0:8080"},"target":"api::runtime::std::serve","service":"grafbase-api","branch":"","environment":"local"}
{"timestamp":"2025-01-20T18:14:17.681903592+00:00","level":"ERROR","fields":{"message":"storage error: service error"},"target":"api::runtime::http::handlers","service":"grafbase-api","branch":"","environment":"local"}
```

In this example, use MiniIO as the S3 bucket, and create and set the access key and secret key to the secrets. Start first by opening [MinIO console](http://localhost:30084/login) and log in with user `grafbase` and password `grafbase`. Click on "Access Keys" and create a new access key. Copy the access key and secret key to the values:

```bash
api:
  configmap:
    values:
      AWS_ACCESS_KEY_ID: ACCESS KEY FROM MINIO
  secrets:
    values:
      AWS_SECRET_ACCESS_KEY: SECRET KEY FROM MINIO
```

Upgrade the Helm chart:

```bash
helm upgrade grafbase-enterprise-platform enterprise-platform-*.tgz -f values.yaml.gotmpl
```

After waiting a few seconds, check if the API is running:

```bash
> curl localhost:30080/health
"Healthy"
```

In a real scenario, use a real S3 bucket. Create a bucket `grafbase` in your storage provider, and set the access key and secret key with read and write access to the bucket. You can set the `RUNTIME_ASSETS_STORAGE` configmap value to point to the bucket URL.

The next step involves creating a new Zitadel organization. The official Zitadel chart does not yet support creating a nodePort, so do a trick to be able to access the Zitadel UI from our kind cluster. These steps do not apply to a real cluster, where you have an ingress setup for Zitadel and can access it with a domain name.

Add the following line to your `/etc/hosts` file:

```bash
127.0.0.1 grafbase-enterprise-platform-zitadel
```

Then, add port forwarding to the Zitadel service:

```bash
kubectl port-forward service/grafbase-enterprise-platform-zitadel 30550:8080
```

Open the first-time admin UI by visiting [http://localhost:30081/admin](http://localhost:30081/admin). Click "Run script" followed by "Manage single sign-on".

Log in to Zitadel with the username `zitadel-admin@zitadel.grafbase-enterprise-platform-zitadel` and password `Password1!`. Skip the 2-factor setup for now and enter a new password for the default user.

Next, you will need to set up an identity provider. Any identity provider supported by Zitadel will work. We have specific guides for [GitHub](/docs/guides/installing-grafbase-enterprise-platform/github-sso) and [Gitlab](/docs/guides/installing-grafbase-enterprise-platform/gitlab-sso).

## Installing the Telemetry Architecture

The Grafbase Enterprise Platform processes telemetry events from the Grafbase Gateway using a service called telemetry sink. To enable this service in your local installation, set the global values to `true` for both the sink and the opentelemetry collector in the `values.yaml.gotmpl` file:

```yaml
global:
  telemetrySink:
    enabled: true
  otelCollector:
    enabled: true
```

Add a node port for the sink to access the sink locally:

```yaml
telemetry-sink:
  service:
    type: NodePort
    nodePort: 30431
  configmap:
    values:
      GRAFBASE_KAFKA_BOOTSTRAP_SERVERS: "list_your_kafka_servers_here"
      GRAFBASE_KAFKA_USERNAME: "change me"
      GRAFBASE_KAFKA_MECHANISM: "SCRAM-SHA-256"
      GRAFBASE_KAFKA_SECURITY_PROTOCOL: "sasl_ssl"
  secrets:
    values:
      SYMMETRIC_ENCRYPTION_SECRET: "must be the same as in the API chart"
      PG_CONNECTION_STRING: "if not set, uses the local postgres"
      GRAFBASE_KAFKA_PASSWORD: "change me"
      CLICKHOUSE_CONNECTION_STRING: "if not set, uses the local clickhouse"
```

For the opentelemetry collector:

```yaml
opentelemetry-collector:
  extraEnvs:
    - name: KAFKA_BROKER
      value: "address of the broker"
    - name: KAFKA_USER
      value: "change me"
    - name: KAFKA_PASSWORD
      value: "change me"
    - name: KAFKA_SASL_MECHANISM
      value: SCRAM-SHA-256
    - name: KAFKA_TLS_INSECURE
      value: "false"
    - name: CLICKHOUSE_ENDPOINT
      value: "must be the same as in the telemetry-sink"
    - name: CLICKHOUSE_DB
      value: "must be the same as in the telemetry-sink"
    - name: CLICKHOUSE_USER
      value: "change me"
    - name: CLICKHOUSE_PASSWORD
      value: "change me"
```

Ensure your Kafka server has a user with the corresponding password having access to the topics: `otlp_metrics`, `otlp_spans`, and `otlp_logs`. After updating these values with Helm, perform a rolling restart of both the opentelemetry collector and the telemetry sink. Finally, verify the logs for both pods to ensure there are no Kafka errors in the output.

## Using Grafbase CLI with the Enterprise Platform

You can define your instance using the [Grafbase CLI](/docs/reference/grafbase-cli) by setting the URL to your local installation in the CLI login command:

```bash
grafbase login --url http://localhost:30081/
```

Now, you are ready to use the CLI with your local Grafbase Enterprise Platform installation.

## Using the Grafbase Gateway with the Enterprise Platform

To connect the Grafbase Gateway with the Grafbase Enterprise Platform, set the `GRAFBASE_OTEL_URL` environment variable to point to the telemetry sink URL.


## Setting up single-sign on with GitHub

Change the organization to "Grafbase" from the top navigation.

Navigate to "Settings", click "Identity Providers", then "GitHub". To use GitHub as an authentication provider, create a new OAuth application in GitHub. Go to [GitHub OAuth Apps](https://github.com/settings/applications/new), give the app a name and URL, and set the callback URL with the value from Zitadel. Now copy the client ID and the secret created in GitHub to the corresponding fields in Zitadel. Open optional settings, add the scope `user:email`, and check all the checkboxes. Click "Save", scroll up, and click "Activate".

To fetch the user email via GitHub, navigate to "Actions" and click "New". Name the action as "backfillEmail" and fill it with the following snippet:

```javascript
let http = require("zitadel/http")

function backfillEmail(ctx, api) {
  const { human } = ctx.v1.externalUser

  // This is an example of how email is added with GitHub auth
  if (!human.email?.length) {
    const emails = http.fetch('https://api.github.com/user/emails', {
      method: 'GET',
      headers: {
        "Authorization": `Bearer ${ctx.accessToken}`
      }
    }).json()

    const primaryEmailAddress = emails.find(email => email.primary)
    if (primaryEmailAddress) {
      api.setEmail(primaryEmailAddress.email)
    }
  }
}
```

Click "Add", then click the "Add trigger" button. Set the trigger type to "Post Authentication" and actions to "backfillEmail" and "backfillName". Click "Save".

Now navigate to the [Grafbase Dashboard](http://localhost:30081) and log in with your GitHub credentials. The dashboard should prompt you to create a new organization.


## Setting up single-sign on with GitLab

This guide applies to both self-hosted instances of GitLab and gitlab.com.

Once logged in to the Zitadel dashboard, change the organization to "Grafbase" from the top navigation. Navigate to "Settings", click "Identity Providers", then "Gitlab".

![Selecting the Grafbase organization](/images/docs/ep/gitlab-sso/select_grafbase_organization.png)

![Selecting the Gitlab provider](/images/docs/ep/gitlab-sso/select_gitlab_sso.png)

You will see a callback link, which you can already copy. Keep this tab open. Then navigate to Gitlab, and in group settings, select "Applications" and create a new application. Insert the callback link you copied from Zitadel, and create the app with the following scopes: `openid`, `profile`, `email`.

![Gitlab UI to create the application](/images/docs/ep/gitlab-sso/gitlab_group_applications.png)

![Copy the application id and secret from the Gitlab application creation screen](/images/docs/ep/gitlab-sso/gitlab_copy_access_key.png)

Gitlab will give you an application ID and secret. Copy these values, and go back to the Zitadel page where you copied the callback URL. Tick the "Automatic creation" and "Automatic update" boxes, and create the provider.

![Form to create the identity provider in Zitadel](/images/docs/ep/gitlab-sso/gitlab_provider_create.png)

You should now be able to sign in with Gitlab in the Grafbase dashboard. On first sign in, you will be prompted to create a new organization. Subsequent users will be able to log in with Gitlab, but there is a last step to complete before they are also automatically added to your organization.

Go back to the Zitadel dashboard. Navigate to the Grafbase organization, then to "Settings", then "Verified domains". Add the domain name used by the user emails associated to the Gitlab accounts you will use to log in.

In the postgres database used by your Enterprise Platform deployment, there should be a single row in the `accounts` table. Update the value for the `saml_domain` column to match the domain you just configured in Zitadel.

Now anytime someone logs in to the dashboard, and their email address matches the configured domain, they will automatically be added to your organization.

Also see the [Zitadel guide on using Gitlab as an IdP](https://zitadel.com/docs/guides/integrate/identity-providers/gitlab).

Learn how to install the Grafbase Enterprise Platform to a Kubernetes cluster

Installing the Grafbase Enterprise Platform

Grafbase Gateway provides hooks to extend the functionality of the gateway. Hooks are Rust functions that are called by the Grafbase Gateway engine at specific points in the request processing pipeline. Hooks can be used to implement custom logic, such as [authorization](/docs/features/security/hooks-authorization), [authentication](/docs/features/security/hooks-authentication), or [access logs](/docs/features/security/access-logs).

By compiling the hooks into WebAssembly components, you can extend the functionality of the gateway without modifying the gateway's source code. This allows you to implement custom logic in a safe and isolated environment without needing to compile the entire gateway and with your own custom licensing.

## Hooks Source Code Structure

Hooks are implemented as Rust functions that are compiled into WebAssembly components. The WebAssembly components are loaded by the Grafbase Gateway engine and called at specific points in the request processing pipeline.

Get a template project from the [Grafbase Gateway repository](https://github.com/grafbase/grafbase/tree/main/examples/hooks-template). Use this template as your starting point to implement hooks.

The project is structured as follows:

```
.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
    └── lib.rs
```

- `Cargo.toml`: The project manifest file that defines the project dependencies and configuration.
- `src/lib.rs`: The main Rust file that implements the hooks.

To compile the hooks, install these tools:

- [Rust compiler](https://www.rust-lang.org/tools/install)
- For Rust version 1.82 or earlier, [cargo-component subcommand](https://github.com/bytecodealliance/cargo-component)
- For Rust version 1.83 or later, the `wasm32-wasip2` target (`rustup target add wasm32-wasip2`)
- An editor or IDE for writing Rust code (e.g., Visual Studio Code, Zed, Emacs, Vim or Helix)
- [rust-analyzer](https://rust-analyzer.github.io/) for code autocomplete and checks

Download the template project to your computer and specify a project name in the `Cargo.toml` file.

The Grafbase Hooks SDK crate [grafbase-hooks](https://crates.io/crates/grafbase-hooks) defines the required types and traits. View the documentation [here](https://docs.rs/grafbase-hooks/latest/grafbase_hooks/). Keep in mind that updating the Grafbase Gateway might require updating the SDK crate. The gateway changelog should always mention the minimum required SDK version.

Add the `grafbase-hooks` crate to your `Cargo.toml` file if you aren't using the template project:

```bash
cargo add grafbase-hooks
```

After installing the required tools, the project should build successfully.

On Rust 1.83 or later:

```bash
cargo build --target wasm32-wasip2
```

On Rust 1.82 or earlier:

```bash
cargo component build
```

This will generate the WebAssembly component file.

- `target/wasm32-wasip1/debug/<project name>.wasm` with Rust 1.82 or earlier.
- `target/wasm32-wasip2/debug/<project name>.wasm` with Rust 1.83 or later.

## Implementing Hooks

For this example, we will implement the `gateway-request` hook, which is called before the gateway processes the request. The `gateway-request` hook can be used to implement custom logic, such as authentication, authorization, or request modification.

The simplest possible hook implementation looks like this:

```rust
use grafbase_hooks::{grafbase_hooks, register_hooks, Context, ErrorResponse, Headers, Hooks};

struct MyHooks;

#[grafbase_hooks]
impl Hooks for MyHooks {
    fn new() -> Self
    where
        Self: Sized,
    {
        MyHooks
    }

    fn on_gateway_request(&mut self, context: Context, headers: Headers) -> Result<(), ErrorResponse> {
        Ok(())
    }
}

register_hooks!(MyHooks);
```

We create a new struct for our hooks `MyHooks` and implement the `Hooks` trait to it. The only required method is `new`, which is called when a hook instance is initialized to the local pool. A running Grafbase Gateway instance can have multiple hook instances running in parallel. Any state stored in the hook instance is isolated from other instances.

You must add the `grafbase_hooks` attribute to the `Hooks` implementation, and register the hooks to the Gateway runtime with the `register_hooks!` macro.

The `Context` struct is passed to all hook methods and can be used to store state that is shared between hook methods.

This implementation does nothing and allows the engine to continue execution. You can add custom logic to the `on_gateway_request` function to implement your desired behavior. Let's add a simple check if a certain header value is present:

```rust
#[grafbase_hooks]
impl Hooks for MyHooks {
    fn on_gateway_request(&mut self, context: Context, headers: Headers) -> Result<(), ErrorResponse> {
        match headers.get("x-secret-header") {
            Some(ref value) if value == "secret" => Ok(()),
            _ => {
                let error = Error {
                    message: "Unauthorized".to_string(),
                    extensions: Vec::new(),
                };

                Err(ErrorResponse {
                    status_code: 403,
                    errors: vec![error],
                })
            },
        }
    }
}
```

This implementation checks if the `x-secret-header` is set to `secret`. If the header is not present or the value is different, the hook returns a HTTP 403 error code.

To use the hooks in the Grafbase Gateway, they must first be compiled in release mode.

On Rust 1.83 or later:

```bash
cargo build --target wasm32-wasip2 --release
```

On Rust 1.82 or earlier:

```bash
cargo component build --release
```

The compiled hooks will be in `target/wasm32-wasip1/release/<project name>.wasm` with Rust 1.82 or earlier, and in `target/wasm32-wasip2/release/<project name>.wasm` with Rust 1.83 or later. Copy the file to a place where the Grafbase Gateway can access it, and [configure](/docs/reference/gateway/configuration/hooks) the gateway to use the hooks.

Extend your gateway with custom hooks using Rust and WebAssembly.

Learn how to implement Grafbase Gateway Hooks in Rust using WebAssembly components

Implementing Gateway Hooks

Grafbase and Apollo GraphOS both implement the GraphQL Federation v2 spec. This means you can run a federated graph composed from the same subgraphs using either the Grafbase Gateway or Apollo Router. This guide will assist you in migrating from Apollo to Grafbase.

The major components are comparable:

| Component       | Apollo        | Grafbase          |
| --------------- | ------------- | ----------------- |
| Gateway         | Apollo Router | Grafbase Gateway  |
| Schema Registry | GraphOS       | Grafbase Platform |
| CLI             | Rover         | Grafbase CLI      |

Additionally, the Grafbase Platform can be fully self-hosted in your own infrastructure for maximum security and control. [Contact sales](/contact/sales) if you want to learn more about the Grafbase Enterprise Platform.

We will explore two scenarios: first, how to run the Grafbase Gateway without migrating any of your GraphOS setup, and second, how to migrate over your federated graph from GraphOS to Grafbase.

## Trying Grafbase Gateway only

If you want to try Grafbase Gateway without migrating your GraphOS setup, you can do so by starting Grafbase Gateway with your existing Federated Graph.

First, you need to [install Grafbase Gateway](/docs/reference/gateway/installation):

```bash
curl -fsSL https://grafbase.com/downloads/gateway | bash
```

Next, you will need the schema of your federated graph. You can download it from the GraphOS Studio UI or via the `rover` CLI:

```bash
rover supergraph fetch my-graph@my-variant > federated.graphql
```

Now you can start the Grafbase Gateway with your Federated Graph:

```bash
grafbase-gateway --schema federated.graphql
```

You are now up and running! You can send queries to the Grafbase Gateway and see it work with your Federated Graph. To explore all the features and configuration options of the gateway, check out the [relevant documentation](/docs/reference/gateway/installation).

When you are ready for a full migration, you can proceed to the next section. We're also happy to provide assistance, just [contact us](/contact)!

## Migrating a Federated Graph from Apollo GraphOS to Grafbase

This part of the guide will walk you through setting up your Federated Graph on Grafbase, assuming you already have running subgraphs that have been published to GraphOS.

### Step 1: Exporting your subgraph schemas

First, you will need the [Grafbase CLI](https://grafbase.com/cli). You can either use `npx grafbase` or install it with the following command:

```bash
curl -fsSL https://grafbase.com/downloads/cli | bash
```

You can list all your subgraphs as shown in the following example:

```bash
rover subgraph list Spotify-Demo-Graph-4m8tpk@current --format=plain
Listing subgraphs for Spotify-Demo-Graph-4m8tpk@current using credentials from the default profile.
┌──────────┬──────────────────────────────────────────────┬────────────────────────────┐
│   Name   │                 Routing Url                  │        Last Updated        │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ spotify  │ https://showcase-spotify.apollographql.com/  │ 2024-05-06 15:21:54 +02:00 │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ playback │ https://showcase-playback.apollographql.com/ │ 2024-05-06 15:21:54 +02:00 │
└──────────┴──────────────────────────────────────────────┴────────────────────────────┘
```

You can pick the subgraphs you want to migrate and publish them manually, or automate the process with a small script.

To publish manually, you can use `rover subgraph fetch` to download the schema of a subgraph, then `grafbase publish` to publish it:

```bash
rover subgraph fetch Spotify-Demo-Graph-4m8tpk@current > spotify.graphql
npx grafbase publish --schema spotify.graphql --url=https://showcase-spotify.apollographql.com/ --name=spotify
```

To automate the process, you can use a script like the following:

```bash
GRAPHOS_GRAPH_REF=Spotify-Demo-Graph-4m8tpk@current
GRAFBASE_GRAPH_REF=my-account/my-graph@main

rover subgraph list $GRAPHOS_GRAPH_REF --format=json | jq -c '.data.subgraphs[] | {name: .name, url: .url}' > subgraphs.json

while IFS= read -r line; do
  name=$(echo "$line" | jq -r '.name')
  url=$(echo "$line" | jq -r '.url')
  rover subgraph fetch $GRAPHOS_GRAPH_REF --name "$name" > "$name.graphql"
  grafbase publish $GRAFBASE_GRAPH_REF --name "$name" --url "$url" --schema "$name.graphql"
done < subgraphs.json
```

This takes care of the initial setup.

### Step 2: Setting up subgraph publishing

You should also make sure that you also publish to Grafbase in your release process wherever you already publish to GraphOS with `rover subgraph publish`. Read more on `grafbase publish` on [the dedicated docs page](/docs/features/federation/schema-registry#publishing-a-subgraph). This will ensure your subgraphs are up to date on both platforms for the duration of your migration.

### Step 3: Setting up schema checks

Similarly, you should set up schema checks on Grafbase. You can use the `grafbase check` command to check your schema against the Grafbase Platform. Read more on `grafbase check` on [the dedicated docs page](/docs/features/federation/schema-registry).

### Step 4: Setting up Grafbase Gateway

Whether you use the binary directly, the [official Docker image](https://github.com/grafbase/grafbase/pkgs/container/gateway), or your own preferred deployment method, you can start the Grafbase Gateway with the Federated Graph SDL directly, as in the previous section, or use the graph reference for your gateway to automatically pick up the latest Federated Graph schema whenever it gets published:

```bash
GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch
```

The `--config` argument is optional, but to start the gateway with a graph ref, the access token is mandatory. You can get an access token from the Grafbase dashboard.

For more information on the features, configuration options, and ways to run the gateway, see the dedicated [docs section](/docs/reference/gateway/installation).

You now have the schema registry populated and the gateway set up. You are running your Federated Graph on Grafbase!

## Common workflows

### Publishing a subgraph

Rover:

```bash
rover subgraph publish my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql --routing-url https://my-subgraph.example.comjk
```

Grafbase:

```bash
npx grafbase publish my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql --url https://my-subgraph.example.com
```

### Running schema checks

Rover:

```bash
rover subgraph check my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql
```

Grafbase:

```bash
npx grafbase check my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql
```

Migrate your federated graph to Grafbase in minutes.

Learn how to migrate your federated graph from Apollo to Grafbase.

Migrating from Apollo

Grafbase Gateway extensions give you powerful ways to extend your gateway's functionality. You can add custom logic like authentication, authorization, and data transformation.

This guide shows you how to implement a custom resolver extension for your Grafbase gateway. You'll create two new directives: `@restEndpoint` and `@rest`, which let you define REST endpoints and map them to GraphQL queries.

![Building your own Extension](/images/blog/introducing-grafbase-extensions-build.png)

## Prerequisites

Before you begin, you need:

- A working [Rust installation with rustup](https://rustup.rs/)
- The latest version of the [Grafbase CLI](/docs/reference/grafbase-cli)
- The latest version of the [Grafbase Gateway](/docs/reference/gateway/installation)

## Creating a Rest Extension

The `grafbase` command-line tool helps you create a new extension. Run this command:

```bash
grafbase extension init --type resolver rest
```

This creates a new `rest` directory with these files and directories:

```text
rest
├── Cargo.toml
├── definitions.graphql
├── extension.toml
├── src
│   └── lib.rs
└── tests
    └── integration_tests.rs
```

- `Cargo.toml` configures the Rust project. Add dependencies and build configuration here.
- `definitions.graphql` contains GraphQL directives and types for your extension.
- `extension.toml` configures the extension with its name, version, kind, and other options.
- `src/lib.rs` contains your extension's main implementation code.
- `tests/integration_tests.rs` contains integration tests for your extension.

For this demo we have to modify the grafbase-sdk dependency, and add the `jq-selection` feature flag to the `Cargo.toml` file:

```bash
cargo add grafbase-sdk --features jq-selection
```

## Extension Directives

The `rest` extension uses two directives to define the REST API endpoint and the HTTP method to use:

```graphql
extend schema @link(url: "https://specs.grafbase.com/grafbase", import: ["InputValueSet", "UrlTemplate"])

directive @restEndpoint(
  name: String,
  baseUrl: String!
) repeatable on SCHEMA

directive @rest(
  endpoint: String,
  method: HttpMethod
  path: UrlTemplate!
  selection: UrlTemplate
) on FIELD_DEFINITION

enum HttpMethod {
  GET
  POST
  PUT
  DELETE
}
```

- `@restEndpoint` defines the REST API endpoint. You can write this directive multiple times on the schema definition.
- `@rest` defines the REST API path and selects the endpoint to use. Add this directive to any field definition that should trigger the extension.

Save the directives and input types to a file called `definitions.graphql`.

An example of a subgraph schema using the directives:

```graphql
@restEndpoint(
  name: "restCountries",
  baseURL: "https://restcountries.com/v3.1"
)

type Country {
  name: String!
}

type Query {
  listAllCountries: [Country!]! @rest(
    endpoint: "restCountries",
    method: GET,
    path: "/all"
    selection: "[.[] | { name: .name.official }]"
  )
}
```

We created one REST endpoint called `restCountries`. In the `listAllCountries` field definition, we added the `@rest` directive to define the REST API path and endpoint to use, along with the HTTP method GET.

The `selection` argument defines the GraphQL selection set that transforms the REST API response into a GraphQL response. This follows the [jq query syntax](https://jqlang.org/manual/), which we implement in the extension.

## Extension Configuration

Add the following configuration to `extension.toml`:

```toml
[extension]
name = "rest"
version = "0.1.0"
kind = "resolver"

[directives]
definitions = "definitions.graphql"
field_resolvers = ["rest"]
```

- `name` identifies the extension.
- `version` specifies the extension version.
- `kind` sets the extension type to either `resolver` or `auth`.
- `definitions` points to the GraphQL schema file we created.
- `field_resolvers` lists the field resolver names that the extension provides and triggers.

## Implementation

Find up to date information on the Grafbase Rust SDK in the [official documentation](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/#resolver-example).

First install all the needed dependencies:

```bash
cargo add serde serde_json http
cargo add url --features serde_json
```

Open the `src/lib.rs` source code in an editor of your choice. We recommend using an editor with Rust IDE features, such as [RustRover](https://www.jetbrains.com/rust/) or any other editor with language server protocol support, combined with the [rust-analyzer](https://rust-analyzer.github.io/).

First create a struct that acts as a gateway resolver extension:

```rust
use grafbase_sdk::jq_selection::JqSelection;

#[derive(ResolverExtension)]
struct RestExtension {
    endpoints: Vec<RestEndpoint>,
    jq: JqSelection,
}
```

Our extension tracks all `@restEndpoint` directives in the `endpoints` field, and all compiled selection filters in the `filters` field. The `arena` is an arena allocator needed later for allocating memory for the selection parser.

Implement the `Extension` trait for the `RestExtension`:

```rust
impl Extension for RestExtension {
    fn new(schema_directives: Vec<Directive>, _: Configuration) -> Result<Self, Box<dyn std::error::Error>> {
        let mut endpoints = Vec::<RestEndpoint>::new();

        // Iterates over all `@restEndpoint` directives from the subgraph.
        for directive in schema_directives {
            // Creates a new `RestEndpoint` from the given `Directive`.
            let endpoint = RestEndpoint {
                subgraph_name: directive.subgraph_name().to_string(),
                args: directive.arguments()?,
            };

            endpoints.push(endpoint);
        }

        // Sorts the endpoints by name and subgraph name. This allows fast lookup
        // and good cache efficiency.
        endpoints.sort_by(|a, b| {
            let by_name = a.args.name.cmp(&b.args.name);
            let by_subgraph = a.subgraph_name.cmp(&b.subgraph_name);
            by_name.then(by_subgraph)
        });

        Ok(Self {
            endpoints,
            jq: JqSelection::default(),
        })
    }
}
```

The `RestEndpoint` struct uses [Serde](https://docs.rs/serde/latest/serde/) to deserialize the `@restEndpoint` directive:

```rust
#[derive(Debug)]
pub struct RestEndpoint {
    pub subgraph_name: String,
    pub args: RestEndpointArgs,
}

#[derive(serde::Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
pub struct RestEndpointArgs {
    pub name: String,
    #[serde(rename = "baseURL")]
    pub base_url: Url,
}
```

When we call the `arguments()` method from the `Directive` in the constructor, it deserializes the arguments into the `RestEndpointArgs` and `HttpSettings` structs.

Next implement the `Resolver` trait for the `RestExtension` struct:

```rust
impl Resolver for RestExtension {
    fn resolve_field(
        &mut self,
        _: SharedContext,
        directive: Directive,
        _: FieldDefinition,
        _field_inputs: FieldInputs<'_>,
    ) -> Result<FieldOutput, Error> {
        ...
    }

    fn resolve_subscription(
        &mut self,
        _: SharedContext,
        _: Directive,
        _: FieldDefinition,
    ) -> Result<Box<dyn Subscription>, Error> {
        unreachable!()
    }
}
```

We only need the `directive` argument, which contains the arguments provided in the `@rest` directive. We access the arguments using the `arguments()` method on the `Directive` struct:

```rust
let rest: Rest<'_> = directive.arguments().map_err(|e| Error {
    extensions: Vec::new(),
    message: format!("Could not parse directive arguments: {e}"),
})?;
```

This deserializes the arguments into the `Rest` struct, defined as:

```rust
#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Rest<'a> {
    pub endpoint: &'a str,
    pub method: HttpMethod,
    pub path: &'a str,
    pub selection: &'a str,
}

#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "UPPERCASE")]
pub enum HttpMethod {
    Get,
    Post,
    Put,
    Delete,
}
```

Next find an endpoint in the `@restEndpoint` directives. Every subgraph must define its own endpoints, but the extension sees all subgraphs and their endpoints. That's why we need to do the lookup with endpoint and subgraph names:

```rust
let Some(endpoint) = self.get_endpoint(rest.endpoint, directive.subgraph_name()) else {
    return Err(Error {
        extensions: Vec::new(),
        message: format!("Endpoint not found: {}", rest.endpoint),
    });
};
```

The easiest lookup method would use a `HashMap`, but for small amounts of endpoints a sorted vector can fit in the CPU cache, and provides faster lookup speed:

```rust
impl RestExtension {
    pub fn get_endpoint(&self, name: &str, subgraph_name: &str) -> Option<&RestEndpoint> {
        self.endpoints
            .binary_search_by(|e| {
                let by_name = e.args.name.as_str().cmp(name);
                let by_subgraph = e.subgraph_name.as_str().cmp(subgraph_name);

                by_name.then(by_subgraph)
            })
            .map(|i| &self.endpoints[i])
            .ok()
    }
}
```

Next combine the base URL with the endpoint path:

```rust
let mut url = endpoint.args.http.base_url.clone();
let path = rest.path.strip_prefix("/").unwrap_or(rest.http.path);

if !path.is_empty() {
    let mut path_segments = url.path_segments_mut().map_err(|_| Error {
        extensions: Vec::new(),
        message: "Could not parse URL".to_string(),
    })?;

    path_segments.push(path);
}
```

Now call the REST endpoint and parse the response:

```rust
// Build a new HTTP request, using the method from our deserialized `@rest` directive.
let request = HttpRequest::builder(url, rest.method.into()).build();

// Execute the HTTP request and handle any errors.
let result = http::execute(&request).map_err(|e| Error {
    extensions: Vec::new(),
    message: format!("HTTP request failed: {e}"),
})?;

// Check if the HTTP request succeeded.
if !result.status().is_success() {
    return Err(Error {
        extensions: Vec::new(),
        message: format!("HTTP request failed with status: {}", result.status()),
    });
}

// Parse the response body as arbitrary JSON.
let data: serde_json::Value = result.json().map_err(|e| Error {
    extensions: Vec::new(),
    message: format!("Error deserializing response: {e}"),
})?;
```

For the http method conversion, implement a `From` trait from our type to `http::Method`:

```rust
#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "UPPERCASE")]
pub enum HttpMethod {
    Get,
    Post,
    Put,
    Delete,
}

impl From<HttpMethod> for ::http::Method {
    fn from(method: HttpMethod) -> Self {
        match method {
            HttpMethod::Get => Self::GET,
            HttpMethod::Post => Self::POST,
            HttpMethod::Put => Self::PUT,
            HttpMethod::Delete => Self::DELETE,
        }
    }
}
```

Now continue our `resolve_field` implementation by using the filter we just created, and add the final JSON to the response:

```rust
let filtered = self
    .jq_selection
    .select(rest.selection, data)
    .map_err(|e| format!("Error selecting result value: {e}"))?
    .collect::<Result<Vec<_>, _>>();

Ok(match filtered {
    Ok(filtered) => {
        // Is a list or a single item expected here?
        if filtered.len() == 1 {
            FieldOutput::new(field_inputs, filtered.into_iter().next().unwrap())?
        } else {
            FieldOutput::new(field_inputs, filtered)?
        }
    }
    Err(error) => FieldOutput::error(field_inputs, format!("Failed to filter with selection: {}", error)),
})
```

Find the full example in the [grafbase repository](https://github.com/grafbase/grafbase/tree/main/extensions/rest/src).

## Testing

The Grafbase SDK includes test utilities for testing your extensions. `grafbase extension init` includes the required dependencies, but we need to add one more crate to start testing:

```bash
cargo add --dev wiremock
```

Find the tests in the `tests/integration_tests.rs` file. See the full example in the [grafbase repository](https://github.com/grafbase/grafbase/tree/main/extensions/rest/tests).

Let's write a test that:

- Starts a mock REST server in a separate thread
- Creates a virtual subgraph and configures the REST extension
- Creates a test runner that composes the subgraph and starts the Grafbase Gateway
- Runs a GraphQL query against the gateway and asserts the response

Here's the function that generates a virtual subgraph:

```rust
fn subgraph(rest_endpoint: &str) -> ExtensionOnlySubgraph {
    let extension_path = std::env::current_dir().unwrap().join("build");
    let path_str = format!("file://{}", extension_path.display());

    let schema = formatdoc! {r#"
        extend schema
          @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
          @link(url: "{path_str}", import: ["@restEndpoint", "@rest"])

        @restEndpoint(
          name: "endpoint",
          baseURL: "{rest_endpoint}"
        )

        type Query {{
          users: [User!]! @rest(
            endpoint: "endpoint",
            method: GET,
            path: "/users"
            selection: "[.[] | {{ id, name, age }}]"
          )
        }}

        type User {{
          id: ID!
          name: String!
          age: Int!
        }}
    "#};

    DynamicSchema::builder(schema)
        .into_extension_only_subgraph("test", &extension_path)
        .unwrap()
}
```

The schema takes the extension build directory and mock REST service URL as parameters.

With this function ready, we can write our first test:

```rust
#[tokio::test]
async fn get_all_fields() {
    // Our mock response from the REST service
    let response_body = json!([
        {
            "id": "1",
            "name": "John Doe",
            "age": 30,
        },
        {
            "id": "2",
            "name": "Jane Doe",
            "age": 25,
        }
    ]);

    let template = ResponseTemplate::new(200).set_body_json(response_body);
    let mock_server = mock_server("/users", template).await;

    // Generate the virtual subgraph with the URL our mock server is running on
    let subgraph = subgraph(&mock_server.uri());

    // Build a test config with the subgraph and enable networking. This tries to look for
    // the grafbase-gateway and grafbase binaries from the PATH. You can also point it to the specific
    // binaries by calling the `with_gateway` and `with_cli` methods.
    let config = TestConfig::builder()
        .with_subgraph(subgraph)
        .enable_networking()
        .build("")
        .unwrap();

    // Start the Grafbase Gateway and return a runner instance to run queries against.
    let runner = TestRunner::new(config).await.unwrap();

    let query = indoc! {r#"
        query {
          users {
            id
            name
            age
          }
        }
    "#};

    let result: serde_json::Value = runner.graphql_query(query).send().await.unwrap();

    insta::assert_json_snapshot!(result, @r#"
    {
      "data": {
        "users": [
          {
            "id": "1",
            "name": "John Doe",
            "age": 30
          },
          {
            "id": "2",
            "name": "Jane Doe",
            "age": 25
          }
        ]
      }
    }
    "#);
}
```

Run the tests with `cargo`:

```bash
cargo test
```

Make gateway errors visible by calling `enable_stdout` and `enable_stderr` methods on the `TestConfig` builder.

## Installation

Build the extension after completing development:

```bash
grafbase extension build
```

Copy the `build` directory to your Grafbase project:

```bash
cp -r build/* path/to/your/grafbase/project/rest/
```

Add the extension to the gateway configuration:

```toml
[extensions]
rest = { path = "rest" }
```

Launch the gateway:

```bash
grafbase-gateway --schema federated-schema.graphql --config grafbase.toml
```

Build custom gateway resolver extensions with Grafbase.

Learn how to implement a custom resolver extension for your Grafbase gateway.

Guides

Deploying Grafbase Gateway with Extensions

Introduction to GraphQL Federation

Installing the Grafbase Enterprise Platform

Implementing Gateway Hooks

Migrating from Apollo

Implementing a Gateway Resolver Extension