Namespaces

All types in the Fleet manager are namespaced. The namespaces of the manager types do not correspond to the namespaces of the deployed resources in the downstream cluster. Understanding how namespaces are used in the Fleet manager is important to understand the security model and how one can use Fleet in a multi-tenant fashion.

GitRepos, Bundles, Clusters, ClusterGroups

The primary types are all scoped to a namespace. All selectors for GitRepo targets will be evaluated against the Clusters and ClusterGroups in the same namespaces. This means that if you give create or update privileges to a GitRepo type in a namespace, that end user can modify the selector to match any cluster in that namespace. This means in practice if you want to have two teams self manage their own GitRepo registrations but they should not be able to target each others clusters, they should be in different namespaces.

GitRepo Namespace

Git repos are added to the Fleet manager using the GitRepo custom resource type. The GitRepo type is namespaced. By default, Rancher will create two Fleet workspaces: fleet-default and fleet-local.

  • Fleet-default will contain all the downstream clusters that are already registered through Rancher.
  • Fleet-local will contain the local cluster by default.

If you are using Fleet in a single cluster style, the namespace will always be fleet-local. Check here for more on the fleet-local namespace.

For a multi-cluster style, please ensure you use the correct repo that will map to the right target clusters.

Namespace Creation Behavior in Bundles

When deploying a Fleet bundle, the specified namespace will automatically be created if it does not already exist.

Special Namespaces

An overview of the namespaces used by fleet and their resources.

Namespace

fleet-local (local workspace, cluster registration namespace)

The fleet-local namespace is a special namespace used for the single cluster use case or to bootstrap the configuration of the Fleet manager.

When fleet is installed the fleet-local namespace is created along with one Cluster called local and one ClusterGroup called default. If no targets are specified on a GitRepo, it is by default targeted to the ClusterGroup named default. This means that all GitRepos created in fleet-local will automatically target the local Cluster. The local Cluster refers to the cluster the Fleet manager is running on.

cattle-fleet-system (system namespace)

The Fleet controller and Fleet agent run in this namespace. All service accounts referenced by GitRepos are expected to live in this namespace in the downstream cluster.

cattle-fleet-clusters-system (system registration namespace)

This namespace holds secrets for the cluster registration process. It should contain no other resources in it, especially secrets.

Cluster Namespaces

For every cluster that is registered a namespace is created by the Fleet manager for that cluster. These namespaces are named in the form cluster-${namespace}-${cluster}-${random}. The purpose of this namespace is that all BundleDeployments for that cluster are put into this namespace and then the downstream cluster is given access to watch and update BundleDeployments in that namespace only.

Cross Namespace Deployments

It is possible to create a GitRepo that will deploy across namespaces. The primary purpose of this is so that a central privileged team can manage common configuration for many clusters that are managed by different teams. The way this is accomplished is by creating a BundleNamespaceMapping resource in a cluster.

If you are creating a BundleNamespaceMapping resource it is best to do it in a namespace that only contains GitRepos and no Clusters. It seems to get confusing if you have Clusters in the same repo as the cross namespace GitRepos will still always be evaluated against the current namespace. So if you have clusters in the same namespace you may wish to make them canary clusters.

A BundleNamespaceMapping has only two fields. Which are as below

  1. kind: BundleNamespaceMapping
  2. apiVersion: fleet.cattle.io/v1alpha1
  3. metadata:
  4.   name: not-important
  5.   namespace: typically-unique
  7. # Bundles to match by label.  The labels are defined in the fleet.yaml
  8. # labels field or from the GitRepo metadata.labels field
  9. bundleSelector:
  10.   matchLabels:
  11.    foo: bar
  13. # Namespaces to match by label
  14. namespaceSelector:
  15.   matchLabels:
  16.    foo: bar

If the BundleNamespaceMappings bundleSelector field matches a Bundles labels then that Bundle target criteria will be evaluated against all clusters in all namespaces that match namespaceSelector. One can specify labels for the created bundles from git by putting labels in the fleet.yaml file or on the metadata.labels field on the GitRepo.

Restricting GitRepos

A namespace can contain multiple GitRepoRestriction resources. All GitRepos created in that namespace will be checked against the list of restrictions. If a GitRepo violates one of the constraints its BundleDeployment will be in an error state and won’t be deployed.

This can also be used to set the defaults for GitRepo’s serviceAccount and clientSecretName fields.

  1. kind: GitRepoRestriction
  2. apiVersion: fleet.cattle.io/v1alpha1
  3. metadata:
  4.   name: restriction
  5.   namespace: typically-unique
  6. allowedClientSecretNames: []
  7. allowedRepoPatterns: []
  8. allowedServiceAccounts: []
  9. allowedTargetNamespaces: []
  10. defaultClientSecretName: ""
  11. defaultServiceAccount: ""

Allowed Target Namespaces

This can be used to limit a deployment to a set of namespaces on a downstream cluster. If an allowedTargetNamespaces restriction is present, all GitRepos must specify a targetNamespace and the specified namespace must be in the allow list. This also prevents the creation of cluster wide resources.