Create an administrative namespace

Grant access to a predefined subset of privileged system backend endpoints in the Vault API with an administrative namespace.

Before you start

• You must have Vault Enterprise 1.15+ installed and running.
• You must have access to your Vault configuration file.
• You must have permission to create and manage namespaces for your Vault instance.

Step 1: Create your namespace

Use the namespace create CLI command to create a new namespace:

$ vault namespace create YOUR_NAMESPACE_NAME

For example, to create a namespace called "ns_admin" under the root namespace:

$ vault namespace create ns_admin

Step 2: Give the namespace admin permission

To create an administrative namespace, set the administrative_namespace_path parameter in your Vault configuration with the absolute path of your new namespace. We recommend setting the namespace path with the other string assignments in your configuration file. For example:

ui = true
api_addr = "https://127.0.0.1:8200"
administrative_namespace_path = "ns_admin/"

Step 3: Verify the new permissions

To verify permissions for the administrative namespace, compare API responses from a restricted endpoint from your new namespace and another namespace without elevated permissions.

1. If you do not already have a namespace you can use for testing, create a test namespace called "ns_test" with the namespace create CLI command:

   $ vault namespace create ns_test
   

2. Use the monitor CLI command to call the /sys/monitor endpoint from your test namespace:

   $ env VAULT_NAMESPACE="ns_test" vault monitor –log-level=debug
   

   You should see an unsupported path error:

   $ env VAULT_NAMESPACE="ns_test" vault monitor –log-level=debug
   
   Error starting monitor: Error making API request.
   Namespace: ns_test/
   URL: GET http://127.0.0.1:8400/v1/sys/monitor?log_format=standard&log_level=debug
   Code: 404. Errors:
   * 1 error occurred:
     * unsupported path
   

3. Now use the monitor command to call the sys/monitor endpoint from your administrative namespace:

   $ env VAULT_NAMESPACE="ns_admin" vault monitor –log-level=debug
   

   You should see log data from your Vault instance streaming to the terminal:

   $ env VAULT_NAMESPACE="ns_admin" vault monitor –log-level=debug
   
   2023-08-31T11:54:41.846+0200 [DEBUG] replication.index.perf: saved checkpoint: num_dirty=0
   2023-08-31T11:54:41.961+0200 [DEBUG] replication.index.local: saved checkpoint: num_dirty=0
   

Next steps

• Follow the Secure multi-tenancy with namespaces tutorial to provide additional security and ensure teams can self-manage their own environments.
• Read more about managing namespaces in Vault Enterprise.