# Namespaces

> Octelium documentation. Canonical page: <https://octelium.com/docs/octelium/latest/management/core/namespace>.

Each *Service* belongs to a single *Namespace*. *Namespaces* are a way of grouping a collection of *Services* according to a common functionality (e.g. project names, environments such as production or staging, regions, etc...) and you are free to create as many *Namespaces* as you want. A *Namespace* also affects the domain name of *Services* as it acts as the parent domain for *Services* belonging to it (read more about *Service* DNS [here](https://octelium.com/docs/octelium/latest/management/core/service/overview.md#dns)). By default, if you do not explicitly specify a *Namespace*, the *Service* will automatically belong to the `default` *Namespace* which is created automatically upon the *Cluster*'s installation. Here is an example for a *Service* that belongs to the `default` *Namespace*:

```yaml
kind: Service
metadata:
  name: webapp
spec:
  mode: WEB
  config:
    upstream:
      url: http://nginx.local
```

## Creating a Namespace

You can create a *Namespace* as follows:

```yaml
kind: Namespace
metadata:
  name: production
spec: {}
```

Here is an example of a *Service* with the same name (i.e. `webapp`) but belongs to the *Namespace* `production` we just created:

```yaml
kind: Service
metadata:
# !mark
  name: webapp.production
spec:
  mode: WEB
  config:
    upstream:
      url: http://nginx.local
```

## Listing Namespaces

You can list the *Cluster*'s *Namespaces* (read more about listing resources [here](https://octelium.com/docs/octelium/latest/management/core/overview.md#listing-resources)) as follows:

```bash
octeliumctl get namespace
# Or simply
octeliumctl get ns

# Show a certain Namespace
octeliumctl get ns <NAME>
```

## Policies

*Policies* (read more about *Policies* and access control [here](https://octelium.com/docs/octelium/latest/management/core/policy.md)) can be created and/or attached to *Namespaces* where they can act as resource-based policies for all the *Services* belonging to a certain *Namespace*. Here is an example:

```yaml
kind: Namespace
metadata:
  name: production
spec:
  authorization:
    policies: ["policy-1", "policy-2"]
    inlinePolicies:
      - spec:
          rules:
            - effect: ALLOW
              condition:
                match: '"group-1" in ctx.user.spec.groups'
```

## Attributes

You can extend the information of a *Namespace* by feeding it additional information manually or dynamically via the APIs (read more [here](https://octelium.com/docs/octelium/latest/management/guide/sdk.md)) from external sources (e.g. IAM platforms, SIEM tools, threat intelligence tools, incident alerting and on-call management tools, etc...). Such additional information can be especially useful for extending access control and making it as fine-grained and dynamic as you wish (read more [here](https://octelium.com/docs/octelium/latest/management/core/policy.md#extending-access-control)). Here is an example:

```yaml
kind: Namespace
metadata:
  name: production
spec:
  attrs:
    isProduction: true
    priority: 1000
    someKey:
      key1: val1
      key2: 100
      key3: true
      key4:
        subKey1: subVal1
```

> **Note:**
>
> The `attrs` field is also available for *Groups*, *Services* and *Users*.

## Public DNS

For *Services* that enable the public BeyondCorp mode (read more [here](https://octelium.com/docs/octelium/latest/management/core/service/clientless.md)) and belong to *Namespaces* other than `default`, they need to manually have their public DNS entries set.

## TLS Certificate

For *Services* that enable TLS (read more [here](https://octelium.com/docs/octelium/latest/management/core/service/overview.md#listening-over-tls)) and belong to *Namespaces* other than `default`, they need to use a separate TLS certificate dedicated for that *Namespace*. You can read more about *Namespace* TLS certificates [here](https://octelium.com/docs/octelium/latest/install/cluster/tls-certificate.md#namespace-certificates).

## API Reference

[Namespace JSON Schema (Octelium core/v1, latest documentation)](https://octelium.com/schemas/octelium/latest/core.v1.Namespace.schema.json)