Schemas

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

Key Concepts

• Kind: The kind field represents the type of target (e.g., "EKS Cluster," "Kubernetes Namespace," "Custom Target").
• 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 target, adhering to the defined JSON schema.

Schema Structure

The schema for a target 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 target.

Pre-built Schemas

Ctrlplane comes with a set of pre-built schemas for common target 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.

You can learn about all the builtin kinds here.

Why Use Schema Registration?

Schema registration offers several benefits:

• Consistency: Enforces a uniform structure for targets of the same kind, ensuring predictable configuration across your deployments.
• Validation: Automatically validates the configuration of new or updated targets 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 target.
• Schema Registration: Register the schema with Ctrlplane using the API or UI.
• Target Creation/Update: When creating or updating a deployment target, Ctrlplane automatically validates the config section against the registered schema. If the configuration is invalid, an error is raised, preventing the target 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.