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. Agents 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.

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

NOTE: For users on supported Sensu Go distributions,sensuctl namespace list lists only the namespaces that the current user has access to.

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]

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
  }
}

See 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. See the sensuctl reference for more information.

Namespace specification

Top-level attributes

type
description Top-level attribute that specifies the resource type. Namespaces should always be type Namespace.
required true
type String
example
type: Namespace
{
  "type": "Namespace"
}
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
api_version: core/v2
{
  "api_version": "core/v2"
}
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
metadata: {}
{
  "metadata": {}
}
spec
description Top-level map that includes the namespace’s spec attributes.
required true
type Map of key-value pairs
example
spec:
  name: production
{
  "spec": {
    "name": "production"
  }
}

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
name: production
{
  "name": "production"
}