multicluster-runtime Documentation

Table of Contents

1. Introduction

• Overview: What is multicluster-runtime?
• Architecture: Understanding the "One Pod, Many Clusters" model.
• Why multicluster-runtime?: Comparison with single-cluster controllers and other multi-cluster solutions.
• Key Concepts: Manager, Providers, Clusters, and Reconcilers.

2. Getting Started

• Prerequisites: Go version, Kubernetes environment.
• Installation: Adding the dependency to your project.
• Quickstart: Building your first multi-cluster controller with the kind provider.
  • Setting up the Manager.
  • Writing a simple Reconciler.
  • Running against a local Kind cluster fleet.

3. Core Concepts

• The Multi-Cluster Manager:
  • Differences from controller-runtime Manager.
  • Initializing with a Provider.
• Providers:
  • The Provider interface.
  • How providers discover and engage clusters.
• The Cluster Object:
  • Accessing Clients, Caches, and Event Recorders for specific clusters.
• The Reconcile Loop:
  • Handling mcreconcile.Request.
  • Context and ClusterName.

4. Controller Patterns

• Uniform Reconcilers:
  • Running the same logic across all clusters.
  • Use cases: Compliance checks, standardizing resources.
• Multi-Cluster Aware Reconcilers:
  • Centralized logic managing resources in remote clusters.
  • Use cases: Federated deployments, data aggregation.
• Using the Builder: mcbuilder for configuring controllers.

5. Providers Reference

• Kind Provider: For local development and testing.
• Kubeconfig Provider: For static or filesystem-based cluster lists.
• Cluster API Provider: Dynamic discovery via CAPI Clusters.
• Cluster Inventory API Provider: Using ClusterProfile (KEP-4322) for inventory management.
• File Provider: Simple file-based discovery.
• Custom Providers: Implementing your own provider.

6. Advanced Topics

• Event Handling:
  • EnqueueRequestForObject in a multi-cluster context.
  • Cross-cluster watches and mapping.
• Authentication: How credentials and identities are handled (KEP-5339).
• Cluster Identification: Understanding ClusterIDs and ClusterSets (KEP-2149).
• Testing: Writing unit and integration tests for multi-cluster logic.

7. Contributing

• Development Guide: Setting up the dev environment.
• Provider Ecosystem: How to contribute new providers.