The module lifecycle stage: Preview

Managing access to cluster-wide resources

What should I do if a PersistentVolumeClaim is rejected with an “is not available to project” error?

The StorageClass specified in spec.storageClassName is unavailable to the project. The webhook rejects such a request with a message similar to the following:

[multitenancy] PersistentVolumeClaim "<OBJECT_NAME>" references "<RESOURCE_NAME>" which is not available to project "<PROJECT_NAME>". Ask the cluster administrator to grant it.

To view the available StorageClasses, run the following command:

d8 k get available storageclasses -n <PROJECT_NAME> -o yaml

If the required StorageClass is not in the list, use an available one or ask the cluster administrator to add it to the ClusterResourceGrantPolicy.

You can check the availability of other cluster-wide resources, such as ClusterIssuer, ClusterRole, and LoadBalancerClass, in the same way using the corresponding AvailableClusterResource.

How can I view access policies applied to a project?

A ClusterResourceGrantPolicy applies to a namespace of a project when every selector it sets matches: spec.projectSelector is matched against the labels of the Project, spec.namespaceSelector against the labels of the namespace. A policy with neither selector is a library policy and applies only through spec.grantPolicies of a ProjectTemplate. For details, refer to “How a policy selects namespaces”.

To view all policies and their selectors, run the following command:

d8 k get clusterresourcegrantpolicies -o yaml

You can view the resulting list of cluster-wide resources available to a specific project using AvailableClusterResource:

d8 k get available -n <PROJECT_NAME>

What happens to existing objects when access is restricted?

Existing objects continue to use their previously configured values. When an object is updated, only new values are checked, so changing an access policy does not disrupt existing objects. The same holds when access management is enabled on an existing cluster: existing objects do not need to be changed before access policies are created.

If an existing object needs to use a different cluster-wide resource, explicitly change the corresponding field to a value available to the project.

If an existing object uses a cluster-wide resource that is no longer available to the project, the ClusterResourceGrantPolicyViolation alert is triggered.

What does the ClusterResourceGrantPolicyViolation alert mean?

The alert indicates that one or more existing objects in a project use a cluster-wide resource that is no longer available to the project under the current policies.

Such objects continue to operate. To resolve the discrepancy, grant the project access to the cluster-wide resource in use or modify the object to use an available resource.

Detailed information about violations is available on the Grafana dashboard under “Security” → “Cluster Resource Grant Violations”. The d8_cluster_objects_grant_violated metric is used for monitoring; the module controller exports it, applying the same availability rules as the admission webhook.

How can I allow all StorageClasses except specific ones?

To deny specific StorageClasses while keeping the others available, use denied or deniedSelector. Deny rules take precedence over allow rules.

For a configuration example, refer to “Denying individual resources”.

What happens if there is no ClusterResourceGrantPolicy?

If no ClusterResourceGrantPolicy is configured for a resource, its availability is determined by its registration. The resource is available to all projects if defaultAvailability: All (the default value) is set in GrantableClusterResourceDefinition and the resource does not match the excluded or reserved filters.

For example, the clusterroles definition provided by Deckhouse Platform excludes every ClusterRole without the rbac.deckhouse.io/delegatable: "true" label. Therefore, such roles are unavailable in RoleBinding even when no policies are configured.

To restrict access, create a ClusterResourceGrantPolicy and specify the projects and the cluster-wide resources available to them.

I created a ClusterResourceGrantPolicy, but nothing changed — why?

Check the following:

  1. Selector match. Make sure the policy’s spec.projectSelector matches the labels of the Project, and its spec.namespaceSelector the labels of the namespace:

    Get the project and its labels:

    d8 k get project <PROJECT_NAME> --show-labels
    

    Filter the namespaces by the projects.deckhouse.io/project=<PROJECT_NAME> label and show their labels:

    d8 k get ns -l projects.deckhouse.io/project=<PROJECT_NAME> --show-labels
    

    In a v1alpha1 manifest, spec.projectSelector is what v1alpha2 calls spec.namespaceSelector. Also check the conditions in the policy status. The SelectorsValid condition is False when a selector is invalid. The NewNamespacesCovered condition is False when a restriction does not cover a new additional namespace of the project. The AllowedEffective condition is False when the GrantableClusterResourceDefinition excludes a name listed in allowed, for example a ClusterRole without the rbac.deckhouse.io/delegatable: "true" label. The message names it (see Restricting ClusterRoles for a project).

  2. Resources available to the project. Check whether AvailableClusterResource reflects the expected policy settings:

    d8 k get available <RESOURCE_NAME> -n <PROJECT_NAME> -o yaml
    
  3. Cluster-wide resource registration. Make sure a corresponding GrantableClusterResourceDefinition exists for the resourceName value.

  4. Reference registration. If a specific field is expected to be checked, make sure it is registered using GrantableClusterResourceReference and that the reference is successfully associated with the corresponding GrantableClusterResourceDefinition.

For information about registration status, refer to “Checking resource registration status”.

How does cluster-wide resource access management interact with RBAC?

These mechanisms operate independently. RBAC determines who can perform operations on an object, while cluster-wide resource access management determines which cluster-wide resources that object can use.

For example, to create a PersistentVolumeClaim, a user must have the appropriate RBAC permissions, and the StorageClass specified in .spec.storageClassName must be available to the project.

What happens if the multitenancy-manager module is disabled?

After the module is disabled, cluster-wide resource availability checks and automatic default value assignment are no longer performed. Existing objects remain unchanged.

Fields that use the x-deckhouse-grantable-resource extension in Deckhouse Platform application settings are no longer checked either.

The d8:dict role of the user-authz module continues to work.