Skip to main content

​
Overview

By default, all organizations share the same Kubernetes namespace (defined by K8S_NAMESPACE). Multi-org namespace isolation allows each organization to use a dedicated namespace, providing stronger isolation between organizations. This feature is optional. Organizations that do not require isolation will continue using the shared namespace as before.

​
Prerequisites

  • K8S_NAMESPACE environment variable is set in your Helm values (e.g., crewai)
  • The k8s_namespace_isolation Flipper feature flag is enabled globally

​
Enable the Feature Flag

kubectl exec -it deploy/crewai-web -- \
  bin/rails runner "Flipper.enable(:k8s_namespace_isolation)"

​
Namespace Naming Convention

When isolation is enabled, each organization gets a dedicated namespace using the format: 
{K8S_NAMESPACE}-org-{organization_id}
For example, if K8S_NAMESPACE=crewai and the organization ID is 4, the namespace will be crewai-org-4. You can find the organization ID and the expected namespace name on the organization’s admin page in the warning banner.

​
Setting Up a New Organization Namespace

For each organization that will use namespace isolation, perform the following steps:

​
1. Create the Namespace

kubectl create namespace {K8S_NAMESPACE}-org-{id}

​
2. Grant the Service Account Access

The platform’s service account needs permissions to manage resources in the new namespace: 
kubectl create rolebinding crewai-sa-edit \
  --clusterrole=edit \
  --serviceaccount={YOUR_SERVICE_ACCOUNT_HERE} \
  --namespace={K8S_NAMESPACE}-org-{id}

​
3. Copy the Registry Secret

The new namespace needs access to the container image registry to pull automation images: 
kubectl get secret docker-registry -n {K8S_NAMESPACE} -o yaml \
  | sed 's/namespace: .*/namespace: {K8S_NAMESPACE}-org-{id}/' \
  | kubectl apply -f -

​
Example

Setting up namespace isolation for organization 4 with K8S_NAMESPACE=crewai: 
# Create the namespace
kubectl create namespace crewai-org-4

# Grant service account access
kubectl create rolebinding crewai-sa-edit \
  --clusterrole=edit \
  --serviceaccount={YOUR_SERVICE_ACCOUNT_HERE} \
  --namespace=crewai-org-4

# Copy the registry secret
kubectl get secret docker-registry -n crewai -o yaml \
  | sed 's/namespace: .*/namespace: crewai-org-4/' \
  | kubectl apply -f -

​
Verification

After setting up the namespace, deploy an automation to the organization. The deployment should target the new namespace. You can verify with: 
# Check pods in the org namespace
kubectl get pods -n {K8S_NAMESPACE}-org-{id}

# Check pods by org label
kubectl get pods -l org-id=org-{id} --all-namespaces
The warning banner on the organization’s admin page will disappear after the first successful deployment.

​
Troubleshooting

​
Deployment Fails with Forbidden Error

The service account does not have permissions in the org namespace. Verify the rolebinding exists: 
kubectl get rolebinding -n {K8S_NAMESPACE}-org-{id}

​
Secrets Forbidden Error

If you see an error like: 
secrets "docker-registry" is forbidden: User "system:serviceaccount:..." cannot get resource "secrets" in the namespace "...-org-{id}"
This means the namespace and rolebinding were not set up for this organization. Follow the setup steps to create the namespace, grant the service account access, and copy the registry secret.

​
Image Pull Errors

The registry secret is missing from the org namespace. Re-run the secret copy step: 
kubectl get secret docker-registry -n {K8S_NAMESPACE} -o yaml \
  | sed 's/namespace: .*/namespace: {K8S_NAMESPACE}-org-{id}/' \
  | kubectl apply -f -