Customizing OpenShift project creation

I recently attended an excellent training run by Red Hat’s Global Partner Enablement Team on advanced Red Hat OpenShift management. One of the most interesting elements of the training was how to customize default project creation. This article explains how to use OpenShift's projectRequestTemplate to add default controls for the resources that a project is allowed to consume.

First, a little bit of background. OpenShift projects are synonymous with Kubernetes namespaces and are used to isolate objects between projects. By default, users who are authenticated can create projects and consume resources up to the global ClusterResource limits. As a cluster administrator, you might want to add new default limits around the number of resources that can be consumed by a project. OpenShift provides a mechanism to achieve this setting by creating a template that is referenced by the projectRequestTemplate parameter in OpenShift’s project configuration resource.

Note: You can read more about this feature in the official documentation in configuring-project-creation. However, the default documentation can be lacking if you haven’t created or modified templates before.

This example outlines how to obtain a project creation template schema, and how to configure it to set default project limits and default container limits. For our example, the project limits for our example look like this:

• Use a maximum of 10 pods.
• Limit each project to six CPUs.
• Limit each project to 16GiB of RAM.
• Set a request for a project to four CPUs.
• Set a request for a project to 8GiB of RAM.
• Set a request for 20GB of persistent storage.

The container limits for our example look like this:

• Limit each container to one CPU.
• Limit each container to 1GiB of RAM.
• Set a default request for 500 milliCPU.
• Set a default request for 500MiB of RAM.

Note: To understand more about limits and quotas, read quotas-setting-per-project.

Before we can customize the template we need to obtain a schema. Run the following command as a user with cluster-admin permissions:

$ oc adm create-bootstrap-project-template -o yaml > template.yaml

Customize the template

Looking at the default template, you can see that it is bare-bones and only contains particular settings, such as NAME, DISPLAYNAME, DESCRIPTION, ADMIN_USER, and REQUESTING_USER, along with establishing sane role-based access controls (RBACs):

apiVersion: template.openshift.io/v1
kind: Template
metadata:
  creationTimestamp: null
  name: project-request
objects:
- apiVersion: project.openshift.io/v1
  kind: Project
  metadata:
    annotations:
      openshift.io/description: ${PROJECT_DESCRIPTION}
      openshift.io/display-name: ${PROJECT_DISPLAYNAME}
      openshift.io/requester: ${PROJECT_REQUESTING_USER}
    creationTimestamp: null
    name: ${PROJECT_NAME}
  spec: {}
  status: {}
- apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    creationTimestamp: null
    name: admin
    namespace: ${PROJECT_NAME}
  roleRef:
    apiGroup: rbac.authorization.k8s.io
    kind: ClusterRole
    name: admin
  subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: ${PROJECT_ADMIN_USER}
parameters:
- name: PROJECT_NAME
- name: PROJECT_DISPLAYNAME
- name: PROJECT_DESCRIPTION
- name: PROJECT_ADMIN_USER
- name: PROJECT_REQUESTING_USER

The important part when customizing this template is adding objects such as ResourceQuota and LimitRange under the objects stanza. First, craft the ResourceQuota and LimitRange as you would normally:

- apiVersion: v1
  kind: "LimitRange"
  metadata:
    name: project-limits
  spec:
    limits:
      - type: "Container"
        default:
          cpu: "1" 
          memory: "1Gi" 
        defaultRequest:
          cpu: "500m" 
          memory: "500Mi"
- apiVersion: v1
  kind: ResourceQuota
  metadata:
    name: project-quota
  spec:
    hard:
      pods: "10" 
      requests.cpu: "4" 
      requests.memory: 8Gi 
      limits.cpu: "6" 
      limits.memory: 16Gi
      requests.storage: "20G"

Now, add ResourceQuota and LimitRange objects under the objects section of the template. In this example, I have modified the name for each object by dynamically include the project name:

apiVersion: template.openshift.io/v1
kind: Template
metadata:
  creationTimestamp: null
  name: project-request
objects:
- apiVersion: project.openshift.io/v1
  kind: Project
  metadata:
    annotations:
      openshift.io/description: ${PROJECT_DESCRIPTION}
      openshift.io/display-name: ${PROJECT_DISPLAYNAME}
      openshift.io/requester: ${PROJECT_REQUESTING_USER}
    creationTimestamp: null
    name: ${PROJECT_NAME}
  spec: {}
  status: {}
- apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    creationTimestamp: null
    name: admin
    namespace: ${PROJECT_NAME}
  roleRef:
    apiGroup: rbac.authorization.k8s.io
    kind: ClusterRole
    name: admin
  subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: ${PROJECT_ADMIN_USER}
- apiVersion: v1
  kind: "LimitRange"
  metadata:
    name: ${PROJECT_NAME}-limits
  spec:
    limits:
      - type: "Container"
        default:
          cpu: "1" 
          memory: "1Gi" 
        defaultRequest:
          cpu: "500m" 
          memory: "500Mi"
- apiVersion: v1
  kind: ResourceQuota
  metadata:
    name: ${PROJECT_NAME}-quota
  spec:
    hard:
      pods: "10" 
      requests.cpu: "4" 
      requests.memory: 8Gi 
      limits.cpu: "6" 
      limits.memory: 16Gi
      requests.storage: "20G"
parameters:
- name: PROJECT_NAME
- name: PROJECT_DISPLAYNAME
- name: PROJECT_DESCRIPTION
- name: PROJECT_ADMIN_USER
- name: PROJECT_REQUESTING_USER

The next step is installing the config into the openshift-config project:

$ oc create -f template.yaml -n openshift-config

After this, associate the template with projectRequestTemplate in the project resource of the config.openshift.io/v1. Run the following command to edit the config:

$ oc edit project.config.openshift.io/cluster

Within the text editor, set the config spec to include the name for your template under projectRequestTemplate. The name of our template itself was project-request. Therefore, under the spec section, we would add:

apiVersion: config.openshift.io/v1
kind: Project
metadata:
  ...
spec:
  projectRequestTemplate:
    name: project-request

Confirm that the template works

The last step is to test your configuration. Keep in mind that the project creation template only applies to projects created after the template was installed and associated with the projectRequestTemplate. Previously created projects will not be modified:

$ oc new-project test
...
$ oc describe project test
Name:		test
Created:	40 seconds ago
...
Quota:
	Name:			test-quota
	Resource		Used	Hard
	--------		----	----
	limits.cpu		0	6
	limits.memory		0	16Gi
	pods			0	10
	requests.cpu		0	4
	requests.memory		0	8Gi
	requests.storage	0	20G
Resource limits:
	Name:		test-limits
	Type		Resource	Min	Max	Default Request	Default Limit	Max Limit/Request Ratio
	----		--------	---	---	---------------	-------------	-----------------------
	Container	cpu		-	-	500m		1		-
	Container	memory		-	-	500Mi		1Gi		-

The output above confirms that the quota and resource limits have automatically been applied to the project.