Multitenancy is the ability to create isolated environments (projects) within a Kubernetes cluster. Projects are similar to namespaces but offer more capabilities. While namespaces are used for logical separation of resources in Kubernetes, they do not, for example, restrict network communication, pod resource consumption, or host directory mounts. These limitations make namespaces insufficient for modern development needs. By default, namespaces also do not include logging, auditing, and vulnerability scanning.
Using projects helps address these limitations and offers the following benefits:
- For platform administrators:
- Consistency: Administrators can create projects using a shared template, which ensures consistency and simplifies management.
- Security: Projects ensure isolation for resources and access policies between different tenants, supporting a secure multitenant environment.
- Resource consumption: Administrators can easily set resource quotas and limits for each project to prevent resource overconsumption.
- For platform users:
- Immediate start: Developers can request projects created per templates from administrators to quickly start developing new applications.
- Isolation: Each project provides an isolated environment, allowing developers to deploy and test their applications without affecting others.
Secret copying across all namespaces is incompatible with projects in multitenancy mode.
This mode creates isolated environments for users within their projects, while secret-copier automatically distributes secrets to all namespaces. If sensitive data is present in a user’s private environment, it could lead to a data leak and a security model breach.
Additional namespaces
A project is not limited to a single namespace: if an application needs several namespaces (for example, a separate one for a cache or a queue), a cluster administrator, a project administrator or a project manager (d8:project:manager) can add them to the project as additional namespaces. Access grants and namespaced template policies (network isolation, log shipping) automatically apply to every namespace of the project, not just the main one. For details, refer to the Administration section.
Creating a project
- To create a project, create a Project custom resource
and specify the project template name in the
.spec.projectTemplateNamefield. - Set the standard fields —
.spec.administratorsand.spec.quota— which are managed directly by the Project resource regardless of the template. -
In the
.spec.parametersfield, specify parameter values for the.spec.parametersSchema.openAPIV3Schemasection of theProjectTemplatecustom resource.Example of creating a project using Project from the
defaultProjectTemplate:apiVersion: deckhouse.io/v1alpha3 kind: Project metadata: name: my-project spec: description: This is an example from the Deckhouse documentation. projectTemplateName: default # Standard fields, managed by the Project resource itself, independently of the template. administrators: - kind: Group name: k8s-admins quota: requests.cpu: "5" requests.memory: 5Gi requests.storage: 1Gi limits.cpu: "5" limits.memory: 5Gi # Template-specific parameters. parameters: networkPolicy: Isolated podSecurityProfile: Restricted extendedMonitoringEnabled: true -
To check the project status, run the following command:
d8 k get projects my-projectA successfully created project should have the
Deployed(synchronized) status. If theErrorstatus is displayed, add the-o yamlflag to the command (for example,d8 k get projects my-project -o yaml) to get more details about the cause of the error.
Automatically creating a project from a namespace
A namespace created directly (for example, d8 k create ns test) automatically becomes a project with the same name — no annotation is required. The project parameters are filled in from the current state of the namespace, so nothing inside it changes; from then on the project is the source of truth for it.
Users can create a namespace directly only while the allowNamespacesWithoutProjects parameter of the multitenancy-manager module is true (the default). With false, only cluster administrators and system components create namespaces directly, and other users create a Project or a ProjectNamespace instead.
The namespace of such a project cannot be deleted directly. To remove the environment, delete the Project: d8 k delete project <NAME> deletes the namespace with it.
For example:
-
Create a new namespace:
d8 k create ns test -
Check that the project was created:
d8 k get projectsIn the output list of projects, you should see the newly created project corresponding to the namespace:
NAME STATE PROJECT TEMPLATE DESCRIPTION AGE deckhouse Deployed virtual This is a virtual project 181d default Deployed virtual This is a virtual project 181d test Deployed simple 1m
To change the template of such a project, set another template in .spec.projectTemplateName.
If the namespace already has an object of the same kind and name as one that the new template creates, for example the isolated NetworkPolicy, the project switches to Error, and the ResourcesUpgraded condition names the object. Delete or rename the object first.
For details on project templates and their creation, refer to the Administration section.
Viewing available cluster-wide resources
A cluster administrator can restrict the use of cluster-wide resources in projects. For example, the administrator can define which StorageClasses, ClusterIssuers, and ClusterRoles are available to a project.
To view the cluster-wide resources available to a project, run the following command:
d8 k get available -n <PROJECT_NAME>
To view available resources of a specific type and the value used by default, specify the corresponding AvailableClusterResource. For example, for StorageClass:
d8 k get available storageclasses -n <PROJECT_NAME> -o yaml
If you see a message such as [multitenancy] <KIND> "<OBJECT_NAME>" references "<RESOURCE_NAME>" which is not available to project "<PROJECT_NAME>" when creating or modifying a resource, the specified cluster-wide resource is unavailable to the project. Select an available resource from the corresponding AvailableClusterResource or ask the cluster administrator to add it.
For some fields, automatic default value assignment can be configured. For example, if storageClassName is not specified when creating a PersistentVolumeClaim, the StorageClass used by default in the project can be automatically assigned to this field.
For more information about using available cluster-wide resources, refer to the multitenancy-manager module documentation.