Namespaces

What namespaces are

Namespaces in Stronghold let you split one server into several isolated logical areas. Each namespace works as a separate virtual Stronghold with its own:

• Policies
• Mount paths
• Secrets
• Auth methods
• Tokens and sessions

All namespaces are managed by a single Stronghold instance and form a hierarchy with the root namespace at the top.

Key properties

Namespaces have the following properties:

• Namespaces form a tree in which each namespace can have a parent and child namespaces.
• Data and configuration are isolated between namespaces.
• An administrator of a parent namespace can manage its child namespaces.
• Users and services work only within their own namespace and its child namespaces, if policies allow it.

To address a specific namespace:

• In the CLI, use the -namespace=<NAMESPACE_PATH> parameter.
• In the REST API, pass the X-Vault-Namespace: <NAMESPACE_PATH> header.

The commands on this page use the following placeholders:

• <NAMESPACE_PATH>: Full path of the namespace, for example, ns1/ns2
• <PARENT_NAMESPACE>: Absolute path of the parent namespace
• <NEW_NAMESPACE>: Name of the namespace to create
• <NAMESPACE>: Name of the namespace relative to the parent namespace
• <UNLOCK_KEY>: unlock_key value returned when the namespace was locked

Creating a namespace

To create a new namespace, you need read and write permissions on the /namespaces path in the current namespace.

The name of the new namespace must not overlap with existing paths. Once created, the namespace can be addressed by its full path in the hierarchy.

Using the CLI

To create a namespace, run the following command:

d8 stronghold namespace create -namespace=<PARENT_NAMESPACE> -custom-metadata=key="value" <NEW_NAMESPACE>

stronghold namespace create -namespace=<PARENT_NAMESPACE> -custom-metadata=key="value" <NEW_NAMESPACE>

Example response:

Key                Value
---                -----
custom_metadata    map[key:value]
id                 c88b1992-d9d3-4160-8283-77163a4e7fae
path               <NEW_NAMESPACE>/

Parameters:

• -namespace: Absolute path of the parent namespace in which the new namespace is created. If the parameter is not specified, the namespace is created in root.
• -custom-metadata: Arbitrary namespace metadata in the key=value format.

Using the REST API

To create a namespace, send a POST request to sys/namespaces:

curl --header "X-Vault-Token: $STRONGHOLD_TOKEN" --header "X-Vault-Namespace: <PARENT_NAMESPACE>" --request POST --data @payload.json $STRONGHOLD_ADDR/v1/sys/namespaces/<NEW_NAMESPACE> | jq -r ".data"

Parameters:

• X-Vault-Namespace: Absolute path of the parent namespace in which the new nested namespace is created.
• payload.json: JSON describing the namespace metadata.

Reading and listing namespaces

Reading using the CLI

To read the namespace properties, run the following command:

d8 stronghold namespace lookup -namespace=<PARENT_NAMESPACE> <NAMESPACE>

stronghold namespace lookup -namespace=<PARENT_NAMESPACE> <NAMESPACE>

Example response:

Key                Value
---                -----
custom_metadata    map[key:value]
id                 c88b1992-d9d3-4160-8283-77163a4e7fae
path               <NAMESPACE>/

Reading using the REST API

To read the namespace properties, send a GET request to sys/namespaces:

curl --header "X-Vault-Token: $STRONGHOLD_TOKEN" --header "X-Vault-Namespace: <PARENT_NAMESPACE>" --request GET $STRONGHOLD_ADDR/v1/sys/namespaces/<NAMESPACE>

Listing using the CLI

To list the child namespaces, run the following command:

d8 stronghold namespace list -namespace=<PARENT_NAMESPACE>

stronghold namespace list -namespace=<PARENT_NAMESPACE>

Example response:

Keys
----
ns1/
ns2/

Listing using the REST API

To list the child namespaces, send a LIST request to sys/namespaces:

curl --header "X-Vault-Token: $STRONGHOLD_TOKEN" --header "X-Vault-Namespace: <PARENT_NAMESPACE>" --request LIST $STRONGHOLD_ADDR/v1/sys/namespaces

Deleting a namespace

Using the CLI

To delete a namespace, run the following command:

d8 stronghold namespace delete -namespace=<PARENT_NAMESPACE> <NAMESPACE>

stronghold namespace delete -namespace=<PARENT_NAMESPACE> <NAMESPACE>

The -namespace parameter sets the parent namespace that contains the namespace being deleted. If the parameter is not specified, the namespace is deleted from root.

Using the REST API

To delete a namespace, send a DELETE request to sys/namespaces:

curl --header "X-Vault-Token: $STRONGHOLD_TOKEN" --header "X-Vault-Namespace: <PARENT_NAMESPACE>" --request DELETE $STRONGHOLD_ADDR/v1/sys/namespaces/<NAMESPACE>

Namespace API lock

Namespace API Lock lets you temporarily block all API requests to the selected namespace and all its child namespaces.

When a namespace is locked, Stronghold returns a one-time unlock_key. Save it to remove the lock later. Unlocking can also be performed with a root token without unlock_key.

Locking using the CLI

Lock the current namespace and all its child namespaces:

d8 stronghold namespace lock

stronghold namespace lock

Lock a specific child namespace, for example, ns1/ns2/:

d8 stronghold namespace lock ns1/ns2

stronghold namespace lock ns1/ns2

Example response:

Key            Value
---            -----
unlock_key     7Hk3xQ9mR2pN5vL8wY4tZa

Locking using the REST API

Lock the <NAMESPACE> namespace from the root namespace:

curl --header "X-Vault-Token: $STRONGHOLD_TOKEN" --request POST $STRONGHOLD_ADDR/v1/sys/namespaces/api-lock/lock/<NAMESPACE> | jq -r ".data"

Lock the current namespace defined by the X-Vault-Namespace header:

curl --header "X-Vault-Token: $STRONGHOLD_TOKEN" --header "X-Vault-Namespace: <NAMESPACE>" --request POST $STRONGHOLD_ADDR/v1/sys/namespaces/api-lock/lock | jq -r ".data"

Example response:

{
  "unlock_key": "7Hk3xQ9mR2pN5vL8wY4tZa"
}

Unlocking using the CLI

Unlock the current namespace using the key:

d8 stronghold namespace unlock -unlock-key=<UNLOCK_KEY>

stronghold namespace unlock -unlock-key=<UNLOCK_KEY>

Unlock the current namespace using a root token:

d8 stronghold namespace unlock

stronghold namespace unlock

Unlock a specific child namespace:

d8 stronghold namespace unlock -unlock-key=<UNLOCK_KEY> ns1/ns2

stronghold namespace unlock -unlock-key=<UNLOCK_KEY> ns1/ns2

Unlocking using the REST API

Using unlock_key:

curl --header "X-Vault-Token: $STRONGHOLD_TOKEN" --request POST --data '{"unlock_key": "<UNLOCK_KEY>"}' $STRONGHOLD_ADDR/v1/sys/namespaces/api-lock/unlock/<NAMESPACE>

Using a root token:

curl --header "X-Vault-Token: $STRONGHOLD_ROOT_TOKEN" --request POST $STRONGHOLD_ADDR/v1/sys/namespaces/api-lock/unlock/<NAMESPACE>

Lock API parameters

The lock and unlock endpoints accept the following parameters:

Lock and unlock example

The following example creates a namespace, locks it, and unlocks it with the key:

# Create a namespace.
d8 stronghold namespace create production

# Lock it.
d8 stronghold namespace lock production
# Key            Value
# ---            -----
# unlock_key     7Hk3xQ9mR2pN5vL8wY4tZa

# Any requests to production are now blocked.
d8 stronghold secrets list -namespace=production
# Error: API access to this namespace has been locked by an administrator...

# Unlock it with the key.
d8 stronghold namespace unlock -unlock-key=7Hk3xQ9mR2pN5vL8wY4tZa production

# Access is restored.
d8 stronghold secrets list -namespace=production

# Create a namespace.
stronghold namespace create production

# Lock it.
stronghold namespace lock production
# Key            Value
# ---            -----
# unlock_key     7Hk3xQ9mR2pN5vL8wY4tZa

# Any requests to production are now blocked.
stronghold secrets list -namespace=production
# Error: API access to this namespace has been locked by an administrator...

# Unlock it with the key.
stronghold namespace unlock -unlock-key=7Hk3xQ9mR2pN5vL8wY4tZa production

# Access is restored.
stronghold secrets list -namespace=production

Additional resources

• Multi-tenancy with namespaces
• Usage examples