Namespace Microservices

Use the CDAP Namespace Microservices to create, list, and delete namespaces in the CDAP instance.

Namespaces, their use and examples, are described in the Namespaces.

The definition of namespace names supported by this API is described under Names and Characters for Namespace Identifiers.

All methods or endpoints described in this API have a base URL (typically http://<host>:11015 or https://<host>:10443) that precedes the resource identifier, as described in the Microservices Conventions. These methods return a status code, as listed in the Microservices Status Codes.

Create a Namespace

To create a namespace, submit an HTTP PUT request:

1 PUT /v3/namespaces/<namespace-id>

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

The namespace-id must be of the limited character set for namespaces, as described in the Introduction. Properties for the namespace are passed in the JSON request body:

Parameter

Description

Default Value (if not defined)

Parameter

Description

Default Value (if not defined)

description

Display description of the namespace

An empty string ("")

config

Configuration preferences for the namespace

A JSON string of configuration key-value pairs

If a namespace with the same name already exists, the method will still return 200 OK, but with a message that the Namespace '<namespace-id>' already exists.

HTTP Responses

Status Codes

Description

Status Codes

Description

200 OK

The event successfully called the method, and the namespace was created

List Existing Namespaces

To list all of the existing namespaces, issue an HTTP GET request:

1 GET /v3/namespaces

This will return a JSON String map that lists each namespace with its name and description (reformatted to fit):

1 2 [{"name": "default", "description": "Default Namespace", "config": {"scheduler.queue.name": ""}}, {"name": "demo_namespace", "description": "My Demo Namespace", "config": {"scheduler.queue.name": "demo"}}]

Details of a Namespace

For detailed information on a specific namespace, use:

1 GET /v3/namespaces/<namespace-id>

The information (namespacedescriptionconfig) will be returned in the body of the response, such as:

1 {"name":"default","description":"Default Namespace","config":{"scheduler.queue.name":""}}

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

HTTP Responses

Status Codes

Description

Status Codes

Description

200 OK

The event successfully called the method, and the body contains the results

Editing a Namespace

To edit an existing namespace, submit an HTTP PUT request to:

1 PUT /v3/namespaces/<namespace-id>/properties

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

The namespace-id must be the name of an existing namespace. Properties for the namespace are passed in the JSON request body, as described for when you Create a Namespace.

Property

Description

Property

Description

description

Display description of the namespace

config

Configuration properties, with a JSON map of key-value pairs.

HTTP Responses

Status Codes

Description

Status Codes

Description

200 OK

Namespace properties were changed successfully

400 Bad Request

The request was not created correctly

404 Not Found

The Namespace does not exist

Example

HTTP Method

PUT /v3/namespaces/dev/properties:

1 2 3 4 5 6 { "description": "Namespace for development of applications", "config": { "scheduler.queue.name": "A", }, }

Description

Set the description property of the Namespace named dev, and set the scheduler.queue.name to A.

Deleting a Namespace

To delete an existing namespace (including all pipelines, applications, datasets, metrics, and other components), submit an HTTP DELETE request to:

1 DELETE /v3/unrecoverable/namespaces/<namespace-id>

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

To prevent accidental use of this method, it will only work if the cdap-site.xml parameter enable.unrecoverable.reset has been enabled. This method must be exercised with extreme caution, as there is no recovery from it.

Both the CDAP CLI and the CDAP UI expose this function. They also require the parameter to be enabled in order for their functions to work.

In the case of the default namespace, after everything has been deleted, the default namespace is retained, as it is always available in CDAP.

To delete only the datasets of a namespace, there is a specific dataset endpoint for that.

Namespace Configurations

When creating or editing a namespace, namespace configurations can be supplied as part of the request body. These are in the form of a JSON string of configuration key-value pairs. Note that the values for these keys cannot be modified once the namespace has been created, with the exception of the property scheduler.queue.name.

Namespace Configurations

Configuration Name

Description

Configuration Name

Description

hbase.namespace

The pre-existing HBase namespace to be used for the namespace (CDAP Distributed mode only)

hive.database

The pre-existing Hive database to be used for the namespace

keytabURI

The URI of the Kerberos keytab file for the namespace

principal

The Kerberos principal for the namespace

groupName

The group name for the namespace. If present, the namespace's data directory is created with this group name, and read, write, and execute permissions are given to the group. The namespace principal must be a member of this group.

root.directory

The pre-existing file-system directory to be used for the namespace

scheduler.queue.name

Scheduler queue for CDAP programs and CDAP explore queries run in the namespace. See Scheduler queue for details.