consul/website/source/api/namespaces.html.md

layout	page_title	sidebar_current	description
api	Namespace - HTTP API	api-namespaces	The /namespace endpoints allow for managing Consul Enterprise Namespaces.

Namespace - HTTP API

~> Enterprise Only! These API endpoints and functionality only exists in Consul Enterprise. This is not present in the open source version of Consul.

The functionality described here is available only in Consul Enterprise version 1.7.0 and later.

Create a Namespace

This endpoint creates a new ACL token.

Method	Path	Produces
PUT	/namespace	application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
NO	none	none	operator:write

Parameters

• Name (string: <required>) - The namespaces name. This must be a valid DNS hostname label.

• Description (string: "") - Free form namespaces description.

• ACLs (object: <optional>) - ACL configurations for this namespace. Rules from default policies and roles will be used only when there are no rules from directly linked policies, roles and service identities that are for the target resource and segment. Therefore if a directly linked policy grants read access to some resource and a default policy grants write access, the effective access for the token will be read due to the default policies not being checked. When there is no rule concerning the resource in either the directly linked policies, roles and service identities nor in those linked by the defaults, then the agents default policy configuration will be used for making the enforcement decision.

  • PolicyDefaults (array<ACLLink>) - This is the list of default policies that should be applied to all tokens created in this namespace. The ACLLink struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally.

  • RoleDefaults (array<ACLLink>) - This is the list of default roles that should be applied to all tokens created in this namespace. The ACLLink struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally.

• Meta (map<string|string>: <optional>) - Specifies arbitrary KV metadata to associate with the namespace.

Sample Payload

{
   "Name": "team-1",
   "Description": "Namespace for Team 1",
   "ACLs": {
      "PolicyDefaults": [
         {
            "ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
         },
         {
            "Name": "node-read"
         }
      ],
      "RoleDefaults": [
         {
            "ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
         },
         {
            "Name": "ns-team-2-read"
         }
      ]
   },
   "Meta": {
      "foo": "bar"
   }
}

Sample Request

$ curl -X PUT \
   -H "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   --data @payload.json \
   http://127.0.0.1:8500/v1/namespace

SampleResponse

{
    "Name": "team-1",
    "Description": "Namespace for Team 1",
    "ACLs": {
        "PolicyDefaults": [
            {
                "ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
                "Name": "service-read"
            },
            {
                "ID": "af937401-9950-fcae-8396-610ce047649a",
                "Name": "node-read"
            }
        ],
        "RoleDefaults": [
            {
                "ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
                "Name": "service-discovery"
            },
            {
                "ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
                "Name": "ns-team-2-read"
            }
        ]
    },
    "Meta": {
        "foo": "bar"
    },
    "CreateIndex": 55,
    "ModifyIndex": 55
}

Read a Namespace

This endpoint reads a Namespace with the given name.

Method	Path	Produces
GET	/namespace/:name	application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
YES	all	none	operator:read or namespace:*:read1

¹ Access can be granted to list the Namespace if the token used when making the request has been granted any access in the namespace (read, list or write).

Parameters

• name (string: <required>) - Specifies the namespace to read. This is required and is specified as part of the URL path.

Sample Request

$ curl -H "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
   http://127.0.0.1:8500/v1/namespace/team-1

SampleResponse

{
    "Name": "team-1",
    "Description": "Namespace for Team 1",
    "ACLs": {
        "PolicyDefaults": [
            {
                "ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
                "Name": "service-read"
            },
            {
                "ID": "af937401-9950-fcae-8396-610ce047649a",
                "Name": "node-read"
            }
        ],
        "RoleDefaults": [
            {
                "ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
                "Name": "service-discovery"
            },
            {
                "ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
                "Name": "ns-team-2-read"
            }
        ]
    },
    "Meta": {
        "foo": "bar"
    },
    "CreateIndex": 55,
    "ModifyIndex": 55
}

Update a Namespace

This endpoint updates a new ACL token.

Method	Path	Produces
PUT	/namespace/:name	application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
NO	none	none	operator:write

Parameters

• Name (string: <optional>) - The namespaces name. This must be a valid DNS hostname label. If present in the payload it must match what was given in the URL path.

• Description (string: "") - Free form namespaces description.

• ACLs (object: <optional>) - ACL configurations for this Namespace. Rules from default policies and roles will be used only when there are no rules from directly linked policies, roles and service identities that are for the target resource and segment. Therefore if a directly linked policy grants read access to some resource and a default policy grants write access, the effective access for the token will be read due to the default policies not being checked. When there is no rule concerning the resource in either the directly linked policies, roles and service identities nor in those linked by the defaults, then the agents default policy configuration will be used for making the enforcement decision.

  • PolicyDefaults (array<ACLLink>) - This is the list of default policies that should be applied to all tokens created in this namespace. The ACLLink struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally.

  • RoleDefaults (array<ACLLink>) - This is the list of default roles that should be applied to all tokens created in this namespace. The ACLLink struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally.

• Meta (map<string|string>: <optional>) - Specifies arbitrary KV metadata to associate with the namespace.

Sample Payload

{
   "Description": "Namespace for Team 1",
   "ACLs": {
      "PolicyDefaults": [
         {
            "ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
         },
         {
            "Name": "node-read"
         }
      ],
      "RoleDefaults": [
         {
            "ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
         },
         {
            "Name": "ns-team-2-read"
         }
      ]
   },
   "Meta": {
      "foo": "bar"
   }
}

Sample Request

$ curl -X PUT \
   -H "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   --data @payload.json \
   http://127.0.0.1:8500/v1/namespace/team-1

SampleResponse

{
    "Name": "team-1",
    "Description": "Namespace for Team 1",
    "ACLs": {
        "PolicyDefaults": [
            {
                "ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
                "Name": "service-read"
            },
            {
                "ID": "af937401-9950-fcae-8396-610ce047649a",
                "Name": "node-read"
            }
        ],
        "RoleDefaults": [
            {
                "ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
                "Name": "service-discovery"
            },
            {
                "ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
                "Name": "ns-team-2-read"
            }
        ]
    },
    "Meta": {
        "foo": "bar"
    },
    "CreateIndex": 55,
    "ModifyIndex": 55
}

Delete a Namespace

This endpoint marks a Namespace for deletion. Once marked Consul will deleted all the associated Namespaced data in the background. Only once all associated data has been deleted will the Namespace actually disappear. Until then, further reads can be performed on the namespace and a DeletedAt field will now be populated with the timestamp of when the Namespace was marked for deletion.

Method	Path	Produces
DELETE	/namespace/:name	N/A

This endpoint will return no data. Success or failure is indicated by the status code returned.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
NO	none	none	operator:write

Parameters

• name (string: <required>) - Specifies the namespace to delete. This is required and is specified as part of the URL path.

Sample Request

$ curl -X DELETE \
   -H "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
   http://127.0.0.1:8500/v1/namespace/team-1

Sample Read Output After Deletion Prior to Removal

{
    "Name": "team-1",
    "Description": "Namespace for Team 1",
    "ACLs": {
        "PolicyDefaults": [
            {
                "ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
                "Name": "service-read"
            },
            {
                "ID": "af937401-9950-fcae-8396-610ce047649a",
                "Name": "node-read"
            }
        ],
        "RoleDefaults": [
            {
                "ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
                "Name": "service-discovery"
            },
            {
                "ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
                "Name": "ns-team-2-read"
            }
        ]
    },
    "Meta": {
        "foo": "bar"
    },
    "DeletedAt": "2019-12-02T23:00:00Z",
    "CreateIndex": 55,
    "ModifyIndex": 100
}

List all Namespaces

This endpoint lists all the Namespaces. The output will be filtered based on the privileges of the ACL token used for the request.

Method	Path	Produces
GET	/namespaces	application/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
YES	all	none	operator:read or namespace:*:read1

¹ Access can be granted to list the Namespace if the token used when making the request has been granted any access in the namespace (read, list or write).

Sample Request

$ curl -H "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \
   http://127.0.0.1:8500/v1/namespaces

Sample Response

[
    {
        "Name": "default",
        "Description": "Builtin Default Namespace",
        "CreateIndex": 6,
        "ModifyIndex": 6
    },
    {
        "Name": "team-1",
        "Description": "Namespace for Team 1",
        "ACLs": {
            "PolicyDefaults": [
                {
                    "ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
                    "Name": "service-read"
                },
                {
                    "ID": "af937401-9950-fcae-8396-610ce047649a",
                    "Name": "node-read"
                }
            ],
            "RoleDefaults": [
                {
                    "ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
                    "Name": "service-discovery"
                },
                {
                    "ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
                    "Name": "ns-team-2-read"
                }
            ]
        },
        "Meta": {
            "foo": "bar"
        },
        "CreateIndex": 55,
        "ModifyIndex": 55
    }
]