Using ResourcePlacement to deploy namespace-scoped resources (preview)

This article describes the ResourcePlacement API, which enables fine-grained control over namespace-scoped Kubernetes resources across member clusters using Azure Kubernetes Fleet Manager.

Overview

ResourcePlacement is a namespace-scoped API that enables dynamic selection and multi-cluster propagation of namespace-scoped resources. It provides fine-grained control over how specific resources within a namespace are distributed across member clusters in a fleet.

Key characteristics:

• Namespace-scoped: Both the ResourcePlacement object and the resources it manages exist within the same namespace.
• Selective: Can target specific resources by type, name, or labels rather than entire namespaces.
• Declarative: Uses the same placement patterns as ClusterResourcePlacement for consistent behavior.

A ResourcePlacement consists of three core components:

• Resource Selectors: Define which namespace-scoped resources to include.
• Placement Policy: Determine target clusters using PickAll, PickFixed, or PickN strategies.
• Rollout Strategy: Control how changes propagate across selected clusters.

When to use ResourcePlacement

ResourcePlacement is ideal for scenarios requiring granular control over namespace-scoped resources:

• Selective resource distribution: Deploy specific ConfigMaps, Secrets, or Services without affecting the entire namespace.
• Multi-tenant environments: Allow different teams to manage their resources independently within shared namespaces.
• Configuration management: Distribute environment-specific configurations across different cluster environments.
• Compliance and governance: Apply different policies to different resource types within the same namespace.
• Progressive rollouts: Safely deploy resource updates across clusters with zero-downtime strategies.

In multi-cluster environments, workloads often consist of both cluster-scoped and namespace-scoped resources that need to be distributed across different clusters. While ClusterResourcePlacement (CRP) handles cluster-scoped resources effectively, entire namespaces and their contents, there are scenarios where you need more granular control over namespace-scoped resources within existing namespaces.

ResourcePlacement (RP) was designed to address this gap by providing:

• Namespace-scoped resource management: Target specific resources within a namespace without affecting the entire namespace.
• Operational flexibility: Allow teams to manage different resources within the same namespace independently.
• Complementary functionality: Work alongside CRP to provide a complete multi-cluster resource management solution.

Real-world namespace usage patterns

While CRP assumes that namespaces represent application boundaries, real-world usage patterns are often more complex. Organizations frequently use namespaces as team boundaries rather than application boundaries, leading to several challenges that ResourcePlacement directly addresses:

Multi-application namespaces: In many organizations, a single namespace contains multiple independent applications owned by the same team. These applications might have:

• Different lifecycle requirements (one application might need frequent updates while another remains stable).
• Different cluster placement needs (development vs. production applications).
• Independent scaling and resource requirements.
• Separate compliance or governance requirements.

Individual scheduling decisions: Many workloads, particularly AI/ML jobs, require individual scheduling decisions:

• AI Jobs: Machine learning workloads often consist of short-lived, resource-intensive jobs that need to be scheduled based on cluster resource availability, GPU availability, or data locality.
• Batch Workloads: Different batch jobs within the same namespace might target different cluster types based on computational requirements.

Complete application team control: ResourcePlacement provides application teams with direct control over their resource placement without requiring platform team intervention:

• Self-service operations: Teams can manage their own resource distribution strategies.
• Independent deployment cycles: Different applications within a namespace can have independent rollout schedules.
• Granular override capabilities: Teams can customize resource configurations per cluster without affecting other applications in the namespace.

This granular approach ensures that ResourcePlacement can adapt to diverse organizational structures and workload patterns while maintaining the simplicity and power of the Fleet scheduling framework.

Key differences between ResourcePlacement and ClusterResourcePlacement

The following table highlights the key differences between ResourcePlacement and ClusterResourcePlacement:

Both ResourcePlacement and ClusterResourcePlacement share the same core capabilities for all other aspects not listed in the differences table.

Working with ClusterResourcePlacement

ResourcePlacement is designed to work in coordination with ClusterResourcePlacement (CRP) to provide a complete multi-cluster resource management solution. Understanding this relationship is crucial for effective fleet management.

Namespace prerequisites

Typical workflow:

1. Platform Admin: Uses ClusterResourcePlacement to deploy namespaces across the fleet.
2. Application Teams: Use ResourcePlacement to manage specific resources within those established namespaces.

The following examples show how to coordinate CRP and RP:

Platform Admin: First, create the namespace using ClusterResourcePlacement:

apiVersion: placement.kubernetes-fleet.io/v1beta1
kind: ClusterResourcePlacement
metadata:
  name: app-namespace-crp
spec:
  resourceSelectors:
    - group: ""
      kind: Namespace
      name: my-app
      version: v1
      selectionScope: NamespaceOnly # only namespace itself is placed, no resources within the namespace
  policy:
    placementType: PickAll # If placement type is not PickAll, the application teams needs to know what are the clusters they can place their applications.

Application Team: Then, manage specific resources within the namespace using ResourcePlacement:

apiVersion: placement.kubernetes-fleet.io/v1beta1
kind: ResourcePlacement
metadata:
  name: app-configs-rp
  namespace: my-app
spec:
  resourceSelectors:
    - group: ""
      kind: ConfigMap
      version: v1
      labelSelector:
        matchLabels:
          app: my-application
  policy:
    placementType: PickFixed
    clusterNames:
    - cluster1
    - cluster2

Best practices

When using ResourcePlacement with ClusterResourcePlacement, follow these best practices:

• Establish namespaces first: Always ensure namespaces are deployed via CRP before creating ResourcePlacement objects.
• Monitor dependencies: Use Fleet monitoring to ensure namespace-level CRPs are healthy before deploying dependent RPs.
• Coordinate policies: Align CRP and RP placement policies to avoid conflicts (for example, if CRP places namespace on clusters A, B, C, RP can target any subset of those clusters).
• Team boundaries: Use CRP for platform-managed resources (namespaces, RBAC) and RP for application-managed resources (app configs, secrets).

This coordinated approach ensures that ResourcePlacement provides the flexibility teams need while maintaining the foundational infrastructure managed by platform operators.

Resource selection, placement, and rollout

ResourcePlacement uses the same placement patterns as ClusterResourcePlacement:

• Placement types: PickAll, PickFixed, and PickN strategies work identically for both APIs.
• Rollout strategy: Control how updates propagate across clusters with the same rolling update mechanisms.
• Status and observability: Monitor deployment progress using kubectl describe resourceplacement <name> -n <namespace>.
• Advanced features: Use tolerations, resource overrides, topology spread constraints, and affinity rules.

The key difference is in resource selection scope. While ClusterResourcePlacement typically selects entire namespaces and their contents, ResourcePlacement provides fine-grained control over individual namespace-scoped resources.

For complete details on these capabilities, refer to the ClusterResourcePlacement documentation.

Next steps

• Use ResourcePlacement to deploy namespace-scoped resources across multiple clusters
• Using ClusterResourcePlacement to deploy cluster-scoped resources
• Multi-cluster resource placement using cluster resource placement
• Use overrides to customize namespace-scoped resources
• Defining a rollout strategy for resource placement
• Cluster resource placement FAQs