Reconciliation

It is possible that certain namespaces were created prior to the cluster being imported into the controller. There are also scenarios where namespaces have to be created outside of the controller (out-of-band). For both cases, it is possible to sync back namespaces to the controller. Two modes are supported, Managed and Unmanaged.

With Managed mode, lifecycle for the namespaces synced to the controller can be managed in the same manner as the ones that were created from within the controller.

Unmanaged mode allows management of lifecycle of these namespaces out of band while being able to reference these namespaces for operations such as role assignment/Zero-Trust Access, add-on deployment.

Namespace Sync (Console)¶

'Namespace sync' can be enabled through a setting in Blueprint configuration. It is disabled by default.

To enable Namespace Sync,

Navigate to Blueprints
Create a new blueprint or a new version of an existing blueprint
Under Namespace Configuration, select Enable Namespace Sync
Click Save Changes

Post blueprint sync completion, any pre-existing namespaces (that were created outside of the controller) or new namespaces created out of band are instantaneously synced back to the controller.

If the Namespace sync feature is disabled later, any new namespaces created out-of-band beyond that point are not synced back to the controller.

Namespace Sync

Important

Certain namespaces are not synced when this feature is enabled. Examples includes "default", "kube-system", "kube-public", "kube-node-lease", "rafay-system" and "rafay-infra".

Namespace Sync (RCTL CLI)¶

You can alternatively enable namespace sync (in managed or unmanaged mode) by using the declarative blueprint spec YAML. For more information on automation via RCTL CLI, refer here

apiVersion: infra.k8smgmt.io/v3
kind: Blueprint
metadata:
  name: demo-blueprint
  project: defaultproject
spec:
  base:
    name: default
    version: 2.3.0
  defaultAddons:
    csiSecretStoreConfig:
      providers: {}
    enableIngress: false
    enableLogging: false
    enableMonitoring: true
    enableVM: false
  drift:
    action: Deny
    enabled: true
  sharing:
    enabled: false
  version: v1
  namespaceConfig:    
    enableSync: true
    syncType: managed

Syncing a namespace to a specific project¶

If a cluster is shared between projects and the namespace that is created out-of-band needs to be synced to a specific project, you can do so by configuring the k8smgmt.io/project label with the project name within the namespace spec.

Scenarios with namespace sync feature enabled¶

Scenario	Expected Behavior
Cluster is imported to the cluster with pre-existing namespaces	Namespaces are synced to the controller instantaneously
Namespace is created out-of-band	Namespace is synced to the controller instantaneously
Namespace is created out-of-band without the k8smgmt.io/project label and the cluster is shared between multiple projects	Namespace is synced to the project where the cluster was initially provisioned or imported into
Namespace is created out-of-band with the k8smgmt.io/project label (with project name as the value) and the cluster is part of the project	Namespace is synced to the project specified in the label
Namespace is created out-of-band with the k8smgmt.io/project label (with project name as the value) and the cluster is not part of the project	Namespace is synced to the project specified in the label with status as 'No Clusters'
Namespace is created out-of-band and does not have resource quotas configured	Namespace is synced to the controller and any resource quotas configured as part of Project Settings are enforced (resource quotas are enforced only when the namespaces are synced in managed mode)
Namespace is created out-of-band and has resource quotas configured	Namespace is synced to the controller and any resource quotas configured as part of Project Settings are enforced (resource quotas are enforced only when the namespaces are synced in managed mode)
Namespace pre-exists and has resource quotas configured	Namespace is synced to the controller and any resource quotas configured as part of Project Settings are enforced(resource quotas are enforced only when the namespaces are synced in managed mode)
Namespace pre-exists and resource utilization exceeds quotas configured as part of Project Settings	New resource creation is blocked if it exceeds the enforced quota
Changes are made to the Namespace out-of-band	Is prevented for namespaces synced in managed mode, allowed for namespaces synced in unmanaged mode
Namespace is deleted out-of-band	Is prevented for namespaces synced in managed mode, allowed for namespaces synced in unmanaged mode
Namespace is deleted from the controller	Namespace is deleted from both the controller and the clusters for namespaces synced in managed mode, only from the controller for namespaces synced in unmanaged mode

Project Label for Namespace¶

For scenarios where a cluster is "shared" across multiple projects and users create namespaces on the shared cluster out of band of the platform using Kubectl, it can become impossible to determine which project this namespace needs to be assigned to.

Creating a namespace via kubectl using the "zero trust kubectl kubeconfig" will automatically inject the cluster’s project information as a project-label allowing for automatic assignment to the appropriate project.

Select the required cluster and click KUBECTL
Run the command create ns <namespace_name> and this creates a namespace
Check the cluster resources page to view the project-labels. An illustrative example is given below

Namespace Sync

Unmanaged Namespaces¶

Users who want to sync namespaces in unmanaged mode from the clusters can create a blueprint with the unmanaged namespace configuration enabled and deploy the blueprint during cluster provisioning. Upon successful sync, namespaces synced in unmanaged mode are listed, as shown in the image below, with an Info button. Clicking on that Info button shows the namespace synced from the cluster as Unmanaged

Remove Namespace

Important

Upgrading the blueprint to use a base version of 2.3+ is a pre-requisite for this feature.

When users edit a namespace from the cluster in unmanaged mode, it's crucial to consider certain concepts, particularly when creating placements with custom labels. In a scenario with two clusters featuring overlapping labels, the system's response is contingent on the chosen label combination. If the selected labels align with clusters and there's at least one cluster without the namespace (a viable cluster), the system allows the update and publishing of the namespace. Conversely, if all clusters in the chosen label combination already have the namespace, the system prevents unnecessary update and publish actions. For instance, if a user selects labels corresponding to both Cluster 1 and Cluster 2, and Cluster 1 lacks the namespace while Cluster 2 has it, the system facilitates updating and publishing onto Cluster 1. However, if both clusters possess the namespace, the system blocks these actions to maintain efficiency and prevent redundancy.

When a namespace synced in unmanaged mode to the controller is deleted from the cluster, it is also removed from the controller. However, if namespace also exists in other cluster(s), only the cluster information is deleted from the namespace status.

Users can view the logs of managed/unmanaged namespace sync in the Audit Logs page as shown below

Remove Namespace