Use managed namespaces (preview) in Azure Kubernetes Service (AKS)

• Listing existing namespaces to convert in the portal doesn't work with private clusters. You can add new namespaces.

Install the aks-preview CLI extension

To install the aks-preview extension, run the az extension add command.

az extension add --name aks-preview

Run the following command to update to the latest version of the extension released.

az extension update --name aks-preview

Register the feature flag

To use managed namespaces in preview, register the following flag using the az feature register command.

az feature register --namespace Microsoft.ContainerService --name ManagedNamespacePreview

Verify the registration status by using the az feature show command. It takes a few minutes for the status to show Registered.

az feature show --namespace Microsoft.ContainerService --name ManagedNamespacePreview

When the status reflects Registered, refresh the registration of the Microsoft.ContainerService resource provider by using the az provider register command.

az provider register --namespace Microsoft.ContainerService

Install the aks-preview CLI extension

To install the aks-preview extension, run the following command.

az extension add --name aks-preview

Run the following command to update to the latest version of the extension released.

az extension update --name aks-preview

Register the feature flag

To use managed namespaces in preview, register the following flag using the az feature register command.

az feature register --namespace Microsoft.ContainerService --name ManagedNamespacePreview

Verify the registration status by using the az feature show command. It takes a few minutes for the status to show Registered.

az feature show --namespace Microsoft.ContainerService --name ManagedNamespacePreview

When the status reflects Registered, refresh the registration of the Microsoft.ContainerService resource provider by using the az provider register command.

az provider register --namespace Microsoft.ContainerService

The following Bicep example demonstrates how to create a managed namespace as a subresource of a managed cluster. Make sure to select the appropriate value for defaultNetworkPolicy, adoptionPolicy, and deletePolicy. For more information about what those parameters mean, see the managed namespaces overview.

resource existingCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' existing = {
  name: 'contoso-cluster'
}

resource managedNamespace 'Microsoft.ContainerService/managedClusters/managedNamespaces@2025-05-02-preview' = {
  parent: existingCluster
  name: 'retail-team'
  location: location
  properties: {
    defaultResourceQuota: {
      cpuRequest: '1000m'
      cpuLimit: '2000m'
      memoryRequest: '512Mi'
      memoryLimit: '1Gi'
    }
    defaultNetworkPolicy: {
      ingress: 'AllowSameNamespace'
      egress: 'AllowAll'
    }
    adoptionPolicy: 'IfIdentical'
    deletePolicy: 'Keep'
    labels: {
      environment: 'dev'
    }
    annotations: {
      owner: 'retail'
    }
  }
}

Save the Bicep file managedNamespace.bicep to your local computer.

Deploy the Bicep file using the Azure CLI.

az deployment group create --resource-group <resource-group> --template-file managedNamespace.bicep

Define variables

Define the following variables to be used in the subsequent steps.

RG_NAME=cluster-rg
CLUSTER_NAME=contoso-cluster
NAMESPACE_NAME=retail-team
LABELS="environment=dev"
ANNOTATIONS="owner=retail"

Create the managed namespace

To customize its configuration, managed namespaces have various parameter options to choose from during creation. Make sure to select the appropriate value for ingress-network-policy, egress-network-policy, adoption-policy, and delete-policy. For more information about what those parameters mean, see the managed namespaces overview.

az aks namespace add \
    --name ${NAMESPACE_NAME} \
    --cluster-name ${CLUSTER_NAME} \
    --resource-group ${RG_NAME} \
    --cpu-request 1000m \
    --cpu-limit 2000m \
    --memory-request 512Mi \
    --memory-limit 1Gi \
    --ingress-policy [AllowSameNamespace|AllowAll|DenyAll] \
    --egress-policy [AllowSameNamespace|AllowAll|DenyAll] \
    --adoption-policy [Never|IfIdentical|Always] \
    --delete-policy [Keep|Delete] \
    --labels ${LABELS} \
    --annotations ${ANNOTATIONS}

Assign role

After the namespace is created, you can assign one of the built-in roles for the control plane and data plane.

ASSIGNEE="user@contoso.com"
NAMESPACE_ID=$(az aks namespace show --name ${NAMESPACE_NAME} --cluster-name ${CLUSTER_NAME} --resource-group ${RG_NAME} --query id -o tsv)

Assign a control plane role to be able to view the managed namespace in the portal, Azure CLI output, and ARM. This role also allows the user to retrieve the credentials to connect to this namespace.

az role assignment create \
  --assignee ${ASSIGNEE} \
  --role "Azure Kubernetes Service Namespace User" \
  --scope ${NAMESPACE_ID}

Assign data plane role to be able to get access to create resources within the namespace using the Kubernetes API.

az role assignment create \
  --assignee ${ASSIGNEE} \
  --role "Azure Kubernetes Service RBAC Writer" \
  --scope ${NAMESPACE_ID}

1. Sign in to the Azure portal.
2. On the Azure portal home page, select Create a resource.
3. In the Categories section, select Managed Kubernetes Namespaces.
4. On the Basics tab, under Project details configure the following settings:
   1. Select the target cluster to create the namespace on.
   2. If you're creating a new namespace, leave the default create new, otherwise choose change existing to managed to convert an existing namespace.
5. Configure the networking policy to be applied on the namespace.
6. Configure the resource requests and limits for the namespace.
7. Select the members (users or groups) and their role.
   1. Assign the Azure Kubernetes Service Namespace User role to give them access to view the managed namespace in the portal, Azure CLI output, and ARM. This role also allows the user to retrieve the credentials to connect to this namespace.
   2. Assign the Azure Kubernetes Service RBAC Writer role to give them access to create resources within the namespace using the Kubernetes API.
8. Select Review + create to run validation on the configuration. After validation completes, select Create.

List managed namespaces

You can list managed namespaces at different scopes using the Azure CLI.

At a subscription level

Run the following command to list all managed namespaces in a subscription.

az aks namespace list --subscription <subscription-id>

At a resource group level

Run the following command to list all managed namespaces in a specific resource group.

az aks namespace list --resource-group <rg-name>

At a cluster level

Run the following command to list all managed namespaces in a specific cluster.

az aks namespace list --resource-group <rg-name> --cluster-name <cluster-name>

List managed namespaces

You can list managed namespaces at different scopes using the Azure CLI.

At a subscription level

Run the following command to list all managed namespaces in a subscription.

az aks namespace list --subscription <subscription-id>

At a resource group level

Run the following command to list all managed namespaces in a specific resource group.

az aks namespace list --resource-group <rg-name>

At a cluster level

Run the following command to list all managed namespaces in a specific cluster.

az aks namespace list --resource-group <rg-name> --cluster-name <cluster-name>

Connect to the cluster

You can retrieve the credentials to connect to a namespace via the following command.

az aks namespace get-credentials --name <namespace-name> --resource-group <rg-name> --cluster-name <cluster-name>

Connect to the cluster

You can retrieve the credentials to connect to a namespace via the following command.

az aks namespace get-credentials --name <namespace-name> --resource-group <rg-name> --cluster-name <cluster-name>