Schemas

In Ctrlplane, schema registration for resources allows you to define and enforce consistent structures for the configuration properties of your resources. This ensures that all resources of a particular kind adhere to a standardized schema, making it easier to manage and consume these resources in your deployment pipelines.

Key Concepts

• Kind: The kind field represents the type of resource (e.g., “EKS Cluster,” “Kubernetes Namespace,” “Custom Resource”).
• Version: The version field indicates the schema version, allowing for backward compatibility as your schemas evolve (e.g., “kubernetes/v1”, “terraform/v2”).
• Config: The config section contains the actual configuration properties of your resource, adhering to the defined JSON schema.

Schema Structure

The schema for a resource is a standard JSON Schema definition. It outlines the required and optional properties, their data types, validation rules, and any additional constraints. The schema is specifically applied to the config section of your resource.

Pre-built Schemas

Ctrlplane comes with a set of pre-built schemas for common resource types, saving you time and effort in defining your own. These schemas cover widely used configurations, ensuring consistency and ease of use across different projects.

Why Use Schema Registration?

Schema registration offers several benefits:

• Consistency: Enforces a uniform structure for resources of the same kind, ensuring predictable configuration across your deployments.
• Validation: Automatically validates the configuration of new or updated resources against the registered schema, preventing errors and inconsistencies.
• Documentation: Provides a clear and structured definition of the expected configuration, aiding collaboration and understanding among team members.
• Versioning: Allows for gradual evolution of your schemas without breaking existing pipelines that rely on older versions.

How It Works

• Schema Definition: Create a JSON Schema that defines the structure of the config section for a specific kind and version of resource.
• Schema Registration: Register the schema with Ctrlplane using the API or UI.
• Resource Creation/Update: When creating or updating a deployment resource, Ctrlplane automatically validates the config section against the registered schema. If the configuration is invalid, an error is raised, preventing the resource from being created or updated.

Best Practices

• Start Simple: Begin with a basic schema and gradually add more properties and validation rules as your needs evolve.
• Use Versioning: When updating a schema, increment the version to maintain backward compatibility with existing deployments.
• Document Your Schemas: Provide clear documentation for each schema, explaining the purpose and usage of each property.