Target Metadata

Target metadata in Ctrlplane are key-value pairs that provide a flexible way to categorize and organize your deployment targets. They play a crucial role in defining deployment strategies, filtering targets, and applying configurations selectively.

Configs vs Metadata

In Ctrlplane, it’s important to understand the distinction between configs and metadata, as they serve different purposes and are used in different contexts. This distinction is similar to the difference between the spec and metadata sections in Kubernetes.

Configs

Configs are essential for interacting with the target and should be standardized across all types of targets. This standardization ensures that if the same pipeline is given two different targets of the same kind, it can use the properties in the config to interact with them consistently.

In some cases, you might need additional data outside the standard context to determine how to interact with the target. In such scenarios, it is acceptable to include this extra data in the config, but it should be limited to variants of a given target and should not impact the primary configuration or behavior.

In Ctrlplane, configs are used within CI/CD pipelines to interact with targets. They define how to deploy or provision the target. It is crucial that values in the config are used to guide these interactions and not to store arbitrary metadata.

Examples of Configs:

This is how the kubernetes schema currently defines interacting to a kubernetes cluster. Thes properties are required for a pipeline to connect to clusters.

name: my-kubernetes-cluster
cluster:
  endpoint: https://...
  certificateAuthorityData: ...

For clusters hosted on Google Cloud (or any cloud provider), you might want to include metadata about the project associated with the cluster. This metadata can then be used in the pipeline to generate the necessary access token for authenticating with the cluster.

Metadata

Metadata in Ctrlplane is used to provide additional information about a target. It consists of key-value pairs that help categorize and organize targets. Metadata is not used to define the behavior or configuration of the target but rather to describe it.

Examples of Metadata:

• region: us-west
• role: web-server
• tier: frontend

When to Use Metadata:

• To group targets by specific attributes (e.g., environment, region).
• To filter and select targets for deployment or management tasks.
• To apply variable values to specific targets during deployment.
• To provide descriptive information that helps in organizing and querying targets.

Summary

• Metadata: Descriptive information used for categorization, organization, and filtering. It does not affect the target’s behavior.
• Configs: Operational parameters and desired state definitions that dictate how the target should function, used in CI/CD pipelines for interacting with targets.

By understanding the difference between metadata and configs, you can effectively organize and manage your deployment targets in Ctrlplane, ensuring that each target is properly described and configured according to your requirements.

Understanding Target Metadata

Metadata is attached to targets, allowing you to group and select targets based on various criteria. They are particularly useful for:

• Organizing targets by environment, region, or purpose
• Applying configurations to specific groups of targets
• Filtering targets for deployment or management tasks
• Applying variable values to specific targets during deployment

How Metadata Works in Ctrlplane

1. Definition: Metadata are defined as key-value pairs on individual targets.
2. Flexibility: You can assign multiple key-value pairs to a single target.
3. Querying: Ctrlplane allows you to query and filter targets based on their metadata.
4. Selective Application: Use metadata to apply configurations or run deployments on specific subsets of targets.

Examples of Target Metadata

Here are some common examples of how you might use metadata in Ctrlplane:

environment: production
region: us-west
role: web-server
tier: frontend
---
environment: staging
region: eu-central
role: database
tier: backend

Best Practices for Using Metadata

1. Consistency: Establish a consistent metadata scheme across your organization.
2. Granularity: Use metadata that provide the right level of detail for your needs.
3. Documentation: Maintain clear documentation of your metadata taxonomy.
4. Avoid Overloading: Don’t try to encode too much information in a single metadata key.
5. Regular Review: Periodically review and update your metadata strategy as your infrastructure evolves.

By effectively using target metadata in Ctrlplane, you can create more flexible, manageable, and scalable deployment strategies that adapt to your organization’s evolving needs.

Special Labels

In Ctrlplane, we have special labels that can be added to targets to enhance the user experience in the UI. These labels do not change the core functionality of Ctrlplane but provide additional features and visual cues for better usability.