Multitenancy

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.

Limitations

Projects has several limitations:

• Creating more than one namespace within a project is not supported. If you need multiple namespaces, create a separate project for each of them.
• Template resources are applied only to a single namespace whose name matches the project name.

Creating a project

1. To create a project, create a Project custom resource and specify the project template name in the .spec.projectTemplateName field.

2. In the .spec.parameters field, specify parameter values for the .spec.parametersSchema.openAPIV3Schema section of the ProjectTemplate custom resource.

   Example of creating a project using Project from the default ProjectTemplate:

   apiVersion: deckhouse.io/v1alpha2
   kind: Project
   metadata:
     name: my-project
   spec:
     description: This is an example from the Deckhouse documentation.
     projectTemplateName: default
     parameters:
       resourceQuota:
         requests:
           cpu: 5
           memory: 5Gi
           storage: 1Gi
         limits:
           cpu: 5
           memory: 5Gi
       networkPolicy: Isolated
       podSecurityProfile: Restricted
       extendedMonitoringEnabled: true
       administrators:
       - subject: Group
         name: k8s-admins
   

3. To check the project status, run the following command:

   d8 k get projects my-project
   

   A successfully created project will have a Deployed status. If the Error status is displayed instead, run the same command with the -o yaml flag to get details about the cause:

   d8 k get projects my-project -o yaml
   

Automatically creating a project from a namespace

You can create a new project from a namespace by adding the projects.deckhouse.io/adopt annotation to it. For example:

1. Create a new namespace:

   d8 k create ns test
   

2. Annotate it:

   d8 k annotate ns test projects.deckhouse.io/adopt=""
   

3. Check that the project was created:

   d8 k get projects
   

   In 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   empty                                                                     1m
   

You can change the template of the created project to an existing one.

For details on project templates and their creation, refer to the Administration section.