Operator scope configuration

Save PDF

Last Updated: July 13, 2026
4 minute read

MarkLogic Server
Documentation

The MarkLogic Operator can be deployed in cluster-scoped mode or in namespace-scoped mode.

Cluster-scoped mode (default)

In cluster-scoped mode, the operator watches and manages MarkLogic resources across all namespaces in the Kubernetes cluster.

When to use cluster-scoped mode

Use cluster-scoped mode when you:

Want to manage MarkLogic clusters across multiple namespaces from a single operator.
Have cluster-admin privileges.
Prefer centralized management.

Requirements

To use cluster-scoped mode, you must have:

ClusterRole and ClusterRoleBinding permissions.
Cluster-admin or equivalent privileges to create cluster-wide resources.

Deployment

To deploy the MarkLogic Operator with the default cluster-scoped configuration, use this command:

# Install with default cluster-scoped configuration
helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operator-system \
  --create-namespace

Deployment with explicit values

To deploy the MarkLogic Operator with explicit values, use this command:

helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operator-system \
  --create-namespace \
  --set scope.type=cluster

Namespace-scoped mode

In namespace-scoped mode, the operator watches and manages MarkLogic resources only in a specific namespace.

When to use namespace-scoped mode

Use namespace-scoped mode when you:

Have limited permissions (no cluster-admin access).
Want to isolate operator permissions to a single namespace.
Prefer decentralized management with multiple operators per cluster.
Are working in a multi-tenant environment.

Requirements

To use namespace-scoped mode, you must have:

Role and RoleBinding permissions (namespace-level only).
Permission to create resources in the target namespace.

Deployment examples

Watch the namespace where the operator is deployed

helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-prod \
  --create-namespace \
  --set scope.type=namespace

Watch a different namespace than where the operator is deployed

# Operator deployed in marklogic-operator-system, watching marklogic-prod
helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operator-system \
  --create-namespace \
  --set scope.type=namespace \
  --set scope.watchNamespaces=marklogic-prod

Watch multiple specific namespaces

# Using comma-separated string
helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operators \
  --create-namespace \
  --set scope.type=namespace \
  --set scope.watchNamespaces="team-a-ns,team-b-ns,team-c-ns"

# Or using a values file with array
cat > values.yaml <<EOF
scope:
  type: namespace
  watchNamespaces:
    - team-a-ns
    - team-b-ns
    - team-c-ns
EOF

helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operators \
  --create-namespace \
  -f values.yaml

Note:

When watching different namespaces, ensure the following:

The watched namespaces exist.
The operator ServiceAccount has the required Role and RoleBinding in each watched namespace. Helm should create these resources automatically.

Configuration parameters

`values.yaml` parameters

scope:
  # Deployment scope: "cluster" or "namespace"
  type: cluster # or "namespace"

  # Only applicable when scope.type is "namespace"
  # If empty, defaults to the release namespace
  # Supports single namespace, comma-separated list, or array
  watchNamespaces: "" # for example, "marklogic-prod" or "ns1,ns2,ns3" or ["ns1", "ns2", "ns3"]

Verification

After deploying the MarkLogic Operator, verify the scope configuration by running this command:

# Check operator logs
kubectl logs -n <operator-namespace> deployment/marklogic-operator-controller-manager -c manager

The log output includes one of the following messages:

Cluster-scoped: operator will watch resources in all namespaces
Namespace-scoped: operator will watch resources in namespace <watched-namespace>

RBAC resources created

These resources are created when the operator is deployed:

Cluster-scoped mode

ClusterRole: marklogic-operator-manager-role
ClusterRoleBinding: marklogic-operator-manager-rolebinding

Namespace-scoped mode

Role: marklogic-operator-manager-role (in watched namespace)
RoleBinding: marklogic-operator-manager-rolebinding (in watched namespace)

Migration between scopes

From cluster to namespace

# Uninstall cluster-scoped operator
helm uninstall marklogic-operator -n marklogic-operator-system

# Install namespace-scoped operator
helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-prod \
  --set scope.type=namespace

From namespace to cluster

# Uninstall namespace-scoped operator
helm uninstall marklogic-operator -n marklogic-prod

# Install cluster-scoped operator
helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operator-system \
  --set scope.type=cluster

Watching multiple namespaces with namespace-scoped mode

You can watch multiple namespaces with a single operator or multiple operators.

Single operator (recommended)

Use this configuration to set up one operator to watch multiple specific namespaces:

# Single operator watching multiple namespaces
helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operators \
  --create-namespace \
  --set scope.type=namespace \
  --set scope.watchNamespaces="namespace-a,namespace-b,namespace-c"

# Or using array in values file
cat > values.yaml <<EOF
scope:
  type: namespace
  watchNamespaces:
    - namespace-a
    - namespace-b
    - namespace-c
EOF

helm install marklogic-operator ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operators \
  --create-namespace \
  -f values.yaml

Note:

The operator automatically creates the required Role and RoleBinding resources in each watched namespace.

Multiple operators (one per namespace)

Alternatively, use this configuration to deploy separate operators for complete isolation:

# Operator 1 watching namespace-a
helm install marklogic-operator-a ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operators \
  --set scope.type=namespace \
  --set scope.watchNamespaces=namespace-a

# Operator 2 watching namespace-b
helm install marklogic-operator-b ./charts/marklogic-operator-kubernetes \
  --namespace marklogic-operators \
  --set scope.type=namespace \
  --set scope.watchNamespaces=namespace-b

Troubleshooting

Issue: operator not watching resources

Check:

Verify the WATCH_NAMESPACE environment variable:

kubectl get deployment marklogic-operator-controller-manager -n <namespace> -o jsonpath='{.spec.template.spec.containers[?(@.name=="manager")].env[?(@.name=="WATCH_NAMESPACE")].value}'

Note:

For multiple namespaces, this should show a comma-separated list (for example, "ns1,ns2,ns3").

Verify RBAC permissions:

# For namespace-scoped (check each watched namespace)
kubectl get role,rolebinding -n <watched-namespace> | grep marklogic-operator

# For cluster-scoped
kubectl get clusterrole,clusterrolebinding | grep marklogic-operator

Check operator logs for watched namespaces:

kubectl logs -n <operator-namespace> deployment/marklogic-operator-controller-manager -c manager | grep "watch"

Issue: permission denied errors

Solution:

For namespace-scoped: Ensure the operator has Role permissions in the watched namespace.
For cluster-scoped: Ensure you have cluster-admin privileges or the appropriate ClusterRole is created.

Best practices

Use cluster-scoped mode when you have cluster-admin access and want centralized management.
Use namespace-scoped mode in multi-tenant environments or when you have limited permissions.
Keep the operator namespace separate from application namespaces for better isolation.
Use meaningful namespace names to avoid confusion in multi-namespace setups.
Monitor operator logs during initial deployment to confirm scope configuration.

MarkLogic® Server on Kubernetes