Chrism/docs/guide bestpractices metadata

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6027
GitOrigin-RevId: 6186ea1de1964a4b91b05a8417983ec312ca53f7

docs/docs/guides/best-practices-for-production/index.mdx

@@ -15,5 +15,6 @@ sidebar_label: Best Practices for Production Environments
 
 Best practices are the goal of all organizations with many different facets benefiting from those practices.  This is particularly true with enterprise software and Hasura is no different.  The guides below are broken down by category.
 
+- [Metadata](/guides/best-practices-for-production/metadata.mdx)
 - [Observability](/guides/best-practices-for-production/observability.mdx)
 - [Security](/guides/best-practices-for-production/security.mdx)

docs/docs/guides/best-practices-for-production/metadata.mdx

@@ -0,0 +1,57 @@
+---
+description: Metadata best practices
+keywords:
+  - hasura
+  - docs
+  - best practices
+sidebar_label: Metadata
+---
+
+# Metadata Best Practices
+
+Proper Metadata management ensures the Hasura GraphQL Engine operates appropriately and as expected. You can use several different patterns to manage Metadata successfully. However, the below do's, and don'ts have been gathered through real-world practices, user experiences, and challenges when managing enterprise-scale Hasura ecosystems.
+
+### Recommended patterns
+- Use the [Hasura CLI](/hasura-cli/index.mdx) to manage and export Metadata.
+  - The CLI exports [YAML files](/migrations-metadata-seeds/manage-metadata.mdx) which is much more source-control friendly than JSON (exported by the Console and API).
+  - Using the [Hasura CLI Console](/hasura-cli/commands/hasura_console.mdx) will capture all Metadata changes in the local file system as the changes are made.
+
+- Use the [Hasura CLI Console](/hasura-cli/commands/hasura_console.mdx) as your development Console.
+  - [Disable the Hasura GraphQL default Console](/deployment/production-checklist.mdx#disable-console).
+  - Changes via the CLI Console will be detected and will update the local file system.
+
+- Leverage a version control solution such as GitHub or GitLab as the source of truth for the Metadata configuration.
+  - Local files updated by the CLI Console are then committed to the source control solution.
+- We recommend retaining the CLI-exported file structure for ease of use.
+
+- Automate deployments using tools such as GitHub Actions, Jenkins, or the [CLI-migrations image](/migrations-metadata-seeds/auto-apply-migrations.mdx).
+
+:::info Note
+
+Hasura Cloud users can leverage the [GitHub integration](/deployment/hasura-cloud/github-integration.mdx) to automate deployments.
+
+:::
+
+- Ensure good regression testing is implemented as part of the deployment workflow.
+  - [graphqurl](https://github.com/hasura/graphqurl) is a simple tool that can be used to execute GraphQL queries and compare the results to known values.
+
+Use the Enterprise Edition for local development if the other Hasura tiers are Enterprise Edition. Using this image is required to allow for the configuration of Hasura Enterprise features (i.e., read-replicas), so the Hasura CLI will include the configurations in the exported Metadata.
+
+### Patterns to avoid
+
+- Don't use the Console or API to export Metadata.
+  - The Console and API export JSON files that are not as source-control friendly as YAML (exported by the CLI).
+
+- Don't use the Hasura GraphQL default Console as your development Console.
+  - Changes made via the Hasura GraphQL default Console will not capture Metadata changes and can easily cause systems to be out of sync.
+
+- Don't rely on the local file system or the Hasura Metadata database as the source of truth for the Metadata configuration.
+  - Local files can easily be unintentionally modified, corrupted, or lost.
+  - You can unintentionally modify the Hasura Metadata database through misapplication of Metadata changes.
+  - The Hasura Metadata database could be unintentionally lost if you accidentally delete the supporting database or persistent volume.
+
+- Don't manually deploy. While this will work in practice, it will quickly grow beyond a reasonable level of effort as the system's complexity and frequency of deployments increase.
+
+- Don't skip good regression testing as Metadata changes can easily change the fundamental way the Hasura GraphQL Engine operates.  Queries you structure differently may return unexpected results.  You could modify security policies such as RBAC permissions or allowed queries via Metadata changes that cause unexpected behavior.
+
+- Don't apply Metadata generated from the Community Edition to an Enterprise Edition system that has EE features configured (e.g., read-replicas). Hasura stores these configurations in the Metadata, and the Community Edition cannot configure these features. The resulting exported Metadata will not contain these values, and this Metadata would overwrite the Enterprise Edition configurations if you applied it.