KubeFleet

KubeFleet core CRDs are served at multiple API versions. For example, the placement.kubernetes-fleet.io and cluster.kubernetes-fleet.io groups serve both v1 and v1beta1.

• v1: The stable, externally promoted surface returned by kubectl by default.
• v1beta1: The current storage version.

Both versions refer to the same underlying objects. KubeFleet follows the Kubernetes API deprecation policy for its API maturity and deprecation windows.

The hub-agent supports two modes for managing webhook certificates:

Automatic Certificate Generation (Default)

• Mechanism: Generates certificates automatically at startup.
• Pros: No external dependencies; works out of the box; 10-year validity.
• Cons: Only supports single replica deployment (replicaCount must be 1).

cert-manager (Optional)

• Mechanism: Uses cert-manager to manage certificates.
• Pros: Supports high availability (replicaCount > 1); automatic 90-day rotation; industry-standard practices.
• Requirements: Requires useCertManager=true, enableWorkload=true, and enableWebhook=true.

By default, the member-agent verifies the TLS server certificate of the hub API server (tlsClientInsecure=false). This requires a valid config.hubCA value. If the placeholder in values.yaml is not replaced with actual CA data, the agent will fail at startup.

Only set tlsClientInsecure=true in explicitly trusted test environments where certificate verification cannot be configured, as this bypasses security checks.

KubeFleet primarily operates using lazy consensus. However, formal votes may be required for specific actions or changes. Votes can be conducted via the developer mailing list, the private Maintainer mailing list (for security or conduct), or during developer meetings.

Voting Thresholds:

• Simple Majority: Required for most votes, including new Maintainer approvals and CNCF resource requests. This means more than half of the Maintainers.
• Two-Thirds (2/3) Majority: Required for:
  • Removing a Maintainer.
  • Modifying the Project Governance charter.
• Any Maintainer has the right to demand a vote.

A KubeFleet deployment consists of a hub-agent (control plane) and a member-agent (worker/kubelet).

KubeFleet supports a symmetric, single-minor skew. This means the hub-agent and member-agent may run adjacent minor versions—at most one minor apart, in either direction.

Supported Examples:

• Hub v0.5.z with Member v0.4.z (Supported)
• Hub v0.5.z with Member v0.6.z (Supported)
• Hub v0.5.z with Member v0.3.z (Unsupported)

Important: Do not skip minor versions during upgrades. Upgrade through each minor version in turn to maintain compatibility.

KubeFleet uses Semantic Versioning (vMAJOR.MINOR.PATCH). Because the project is in the 0.y.z series, minor version bumps (0.Y → 0.Y+1) may include breaking changes. Patch releases (0.Y.Z → 0.Y.Z+1) are strictly for backward-compatible bug fixes and security patches.

Version Bump Reference

KubeFleet is composed of two primary components deployed via Helm:

• hub-agent: The central controller running on the hub cluster. It manages placement decisions, scheduling, and cluster inventory.
• member-agent: The agent running on each member cluster. It applies workloads and reports cluster status back to the hub.

KubeFleet Maintainers (the 'Maintainer Council') manage project resources and contributors. They have write access to the GitHub repository and are expected to participate in weekly public developer meetings.

Removal and Resignation:

• Resignation: Maintainers may resign at any time.
• Removal: A Maintainer may be removed by a 2/3 vote of the remaining maintainers for reasons including:
  • Inactivity (defined as very low or no activity for 6 months or more without a return plan).
  • Failure to fulfill responsibilities.
  • Violating the Code of Conduct.
• Emeritus Status: Depending on the reason for removal, a Maintainer may be converted to 'Emeritus' status, allowing them to be consulted on project matters and potentially return to full status later.

To get started with KubeFleet using kind (Kubernetes in Docker), follow the official getting started guide. This will walk you through the initial setup and environment preparation.

https://kubefleet-dev.github.io/website/docs/getting-started/kind/

While clusterloader2 automatically deletes generated namespaces by default, it does not automatically delete Custom Resource Definitions (CRPs) created during the test. To clean up these remaining resources, use the provided cleanup.sh script.

Ensure your KUBECONFIG environment variable is set to the correct path before running the script.

export KUBECONFIG=<your path to the kubeconfig file>
./cleanup.sh

You can also use a traditional Helm repository hosted on GitHub Pages. This requires adding the repository and updating your local cache before installation.

# Add the KubeFleet Helm repository
helm repo add kubefleet https://kubefleet-dev.github.io/kubefleet/charts

# Update your local Helm chart repository cache
helm repo update

# Install hub-agent
helm install hub-agent kubefleet/hub-agent \
  --namespace fleet-system \
  --create-namespace

# Install member-agent
helm install member-agent kubefleet/member-agent \
  --namespace fleet-system \
  --create-namespace \
  --set config.hubURL=https://<hub-api-server> \
  --set config.hubCA=<base64-encoded-hub-ca> \
  --set config.memberClusterName=<member-cluster-name>