Namespaces reference
Namespaces partition resources within Sensu. Sensu entities, checks, handlers, and other namespaced resources belong to a single namespace.
Namespaces help teams use different resources (like entities, checks, and handlers) within Sensu and impose their own controls on those resources. A Sensu instance can have multiple namespaces, each with their own set of managed resources. Resource names must be unique within a namespace but do not need to be unique across namespaces.
Namespace configuration applies to sensuctl, the API, and the web UI.
To create and manage namespaces, configure sensuctl as the default admin
user or create a cluster role with namespaces
permissions.
Namespace example
This example shows the resource definition for a production
namespace.
You can use this example with sensuctl create
to create a production
namespace in your Sensu deployment:
---
type: Namespace
api_version: core/v2
metadata: {}
spec:
name: production
{
"type": "Namespace",
"api_version": "core/v2",
"metadata": {},
"spec": {
"name": "production"
}
}
Best practices for namespaces
Use namespaces for isolation, not organization
Use namespaces to enforce full isolation of different groups of resources, not to organize resources. An agent cannot belong to two namespaces or execute checks in two different namespaces. To organize resources, use labels rather than multiple namespaces.
Default namespaces
Every Sensu backend includes a default
namespace.
All resources created without a specified namespace are created within the default
namespace.
At startup, Sensu also creates the sensu-system
namespace to contain backend entities.
The sensu-system
namespace and backend entities facilitate backend error reporting and make Sensu deployments more observable by enabling backend-generated status and metrics events.
Only cluster admins have access to the sensu-system
namespace.
If you have cluster admin permissions, you can use sensuctl and the web UI to access backend entities like other entities.
Manage namespaces
You can use sensuctl to view, create, and delete namespaces. To get help with managing namespaces with sensuctl:
sensuctl namespace help
View namespaces
Use sensuctl to view all namespaces within Sensu:
sensuctl namespace list
COMMERCIAL FEATURE: In the packaged Sensu Go distribution, sensuctl namespace list
lists only the namespaces for which the current user has access.
For more information, read Get started with commercial features.
Create namespaces
Use sensuctl to create a namespace.
For example, the following command creates a namespace called production
:
sensuctl namespace create production
Namespace names can contain alphanumeric characters and hyphens and must begin and end with an alphanumeric character.
Delete namespaces
To delete a namespace:
sensuctl namespace delete <namespace-name>
Namespaces must be empty before you can delete them.
If the response to sensuctl namespace delete
is Error: resource is invalid: namespace is not empty
, the namespace may still contain events or other resources.
To remove all resources and events so that you can delete a namespace, run this command (replace <namespace-name>
with the namespace you want to empty):
sensuctl dump entities,events,assets,checks,filters,handlers,secrets/v1.Secret --namespace <namespace-name> | sensuctl delete
Assign a resource to a namespace
You can assign a resource to a namespace in the resource definition. Only resources that belong to a namespaced resource type (like checks, filters, and handlers) can be assigned to a namespace.
For example, to assign a check called check-cpu
to the production
namespace, include the namespace
attribute in the check definition:
---
type: CheckConfig
api_version: core/v2
metadata:
name: check-cpu
namespace: production
spec:
check_hooks: null
command: check-cpu.sh -w 75 -c 90
handlers:
- slack
interval: 30
subscriptions:
- system
timeout: 0
ttl: 0
{
"type": "CheckConfig",
"api_version": "core/v2",
"metadata": {
"name": "check-cpu",
"namespace": "production"
},
"spec": {
"check_hooks": null,
"command": "check-cpu.sh -w 75 -c 90",
"handlers": ["slack"],
"interval": 30,
"subscriptions": ["system"],
"timeout": 0,
"ttl": 0
}
}
Read the reference docs for the corresponding resource type to create resource definitions.
PRO TIP: If you omit the namespace
attribute from resource definitions, you can use the senusctl create --namespace
flag to specify the namespace for a group of resources at the time of creation.
This allows you to replicate resources across namespaces without manual editing.
Read the sensuctl reference for more information.
Namespace specification
Top-level attributes
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. The api_version should always be core/v2 . |
required | true |
type | String |
example |
|
metadata | |
---|---|
description | Top-level collection of metadata about the namespace. For namespaces, the metatdata should always be empty. |
required | true |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the namespace’s spec attributes. |
required | true |
type | Map of key-value pairs |
example |
|
type | |
---|---|
description | Top-level attribute that specifies the resource type. Namespaces should always be type Namespace . |
required | true |
type | String |
example |
|
Spec attributes
name | |
---|---|
description | Name of the namespace. Names can contain alphanumeric characters and hyphens and must begin and end with an alphanumeric character. |
required | true |
type | String |
example |
|