Schema Checks

When inigo check or inigo apply is run for a Gateway, Subgraph, or Service (with schema_files), Inigo will trigger a Schema Check Pipeline in the cloud that runs through four stages of checks:

1. Validation Check: Makes sure all subgraph schemas can be parsed and are valid
   • Cannot be bypassed
2. Composition Check: Makes sure all subgraph schemas can be composed to a single federated schema
   • Can bypass by using the inigo bypass command
   • In the case where composition is bypassed, no operational checks will take place
3. Operational Check: Makes sure there are no breaking changes in the schema
   • GraphQL client history over the last X days (default and maximum is 30) is checked against the current schema changes
   • These checks help prevent the removal of fields, types, and other high-impact schema changes that may negatively impact active GraphQL clients
   • By default, removal of an unused field will trigger a warning and a failure unless configured differently using Checks
   • Can bypass by using the inigo bypass command
4. Evaluation Check: Makes sure all Inigo schema directive configurations are valid, including access control and rate limiting
   • Cannot be bypassed

First, you should run inigo check to identify any breaking changes. Then, after inigo check passes, you can then run inigo apply. These checks always run for both inigo check and inigo apply as a safeguard to make sure no breaking changes are introduced for either command.

inigo check Command

The inigo check command can be run to check for Validation, Composition, Operational, and Evaluation errors on your local machine or for Continuous Integration (CI) purposes. The intent for inigo check is not to apply any changes, only to check for potential errors. For example, you could implement CI to prevent the merging of code into a branch if there are failures when running inigo check.

inigo check can be run against Gateway, Subgraph, and Service, all which can have a schema_files configuration to check against.

On your local machine, you can manually run the checks as shown in this example:

inigo check services/inventory/subgraph.yaml --label dev

The expected output from this example would be:

Service: inventory:dev

Changelog:
----------
subgraph/schema_files  updated  

Steps:
------
Validation:   passed
Composition:  failed
Operational:  omitted
Evaluation:   omitted

Field marked @requires must have 'Product.weight' marked as @external.
        subgraph:  inventory
        location:  ./schema.graphql:9:5
        attribute: Product.shippingEstimate

Execute the below command to ignore this failure on the next run:
>  inigo bypass 5ff2725174d65274063ce6307b732bf2518e244a

Check out the report in the UI:
https://app.inigo.io/000/config/activity/5678

error: check failed, see report above for details

Additionally, you will see the results in the Inigo cloud, as shown in Figure 1.

Figure 1. Results of the inigo check command.

Note: The inigo check command does not attempt to apply the changes to the Inigo cloud. A successful inigo check will not have any side effects.

inigo apply Command

When running inigo apply, the schema checks will happen exactly like they do with inigo check. The difference is that if the checks pass, the schema changes will be applied. In the case of federated schemas, the supergraph schema will be applied, but not published.

inigo bypass Command

The inigo bypass command allows an administrator to bypass failing checks for inigo check and inigo apply as necessary. Here are two examples of when you may need to run inigo bypass:

1. Schema refactoring that forces a temporary failure of composition checks (i.e. moving types from one subgraph to another)
2. Schema changes that create a failed operational check, but you know that the changes will not impact any of your GraphQL clients

Note: The inigo bypass command requires the admin or reviewer or role to run

Override a Check Failure

The inigo bypass command can be run with the ID outputted from the inigo check or inigo apply as shown in the following example:

inigo bypass 5ff2725174d65274063ce6307b732bf2518e244a

The expected output will be:

Feel free to re-run check or apply of the same config again!

The original inigo apply or inigo check command can now be run again to bypass the original check that failed.

Customizing Checks

Checks are customizable allowing one to change the level of failure and the timeframe Operational Checks will use for failure. Example 4 shows how to tweak the operational checks to only fail_on an error and sets a time_range of 14d.

kind: Checks
name: apollo-gateway-fed-2-demo
spec:
  steps:
    operational:
      fail_on: error
      time_range: 14d

Example 4. Checks configuration changing the Operational Check.