---
type: api
title: Create a role
description: Create a Blueprinter role.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/operation/operation-create-blueprinter-role
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/operation/operation-create-blueprinter-role
products:
  - Elastic Cloud Enterprise
---

# Create a role

## Paths

- `POST` `/platform/infrastructure/blueprinter/roles`

- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/authentication#basicauth)
- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/authentication#apikey)

## Description

Create a Blueprinter role.

## Request Body

`application/json`

The data you want to use for creating a role.

- `role` ({} Role) — required
  Describes whether certain runners are blessed to run a Role.
  - `id` (string) — required
    The unique id of this role
  - `auto_blessed` (boolean) — required
    Whether runners are automatically allowed to be assigned the containers of this role.
  - `containers` ([] ContainersEntry) — required
    The containers that are part of this role
    - `name` (string) — required
      Name of the association
    - `container_set_name` (string) — required
      The container set name (id)
    - `kind` (string) — required
      The kind of container set, should be one of 'docker', 'elasticsearch', 'kibana', or 'apm'
    - `options` ({} ContainersEntryOptions) — required
      Options for a ContainersEntry belonging to a role
      - `enabled` (boolean) — required
        Whether this allocation is active and should be created.
      - `auths` ([] ContainersEntryOptionsAuth) — required
        ZooKeeper Auths associated with this allocation
        - `scheme` (string) — required
          Scheme identifier, usually "digest"
        - `auth` (string) — required
          Plain-text auth. For the "digest" scheme
      - `acls` ([] ContainersEntryOptionsACL) — required
        ZooKeeper ACLs associated with this allocation
        - `id` (string) — required
          Identity within the provided scheme.
        - `perms` (integer) — required
          Permissions
        - `scheme` (string) — required
          Auth scheme, in Elastic Cloud this is usually "digest"
      - `runners_secret` (string) — optional
        Secret shared between the runners that have containers in this container set allocated.
      - `container_set_secret` (string) — optional
        Secret shared between the containers that are part of this container set.
      - `enabled_by_named_feature_flag` (string) — optional
        A named feature flag to check whether this container is enabled or not
      - `overrides` ({} ContainersEntryOptionsOverrides) — optional
        Overrides for the container allocation.
        - `container_config` ({} ContainersEntryOptionsContainerConfig) — optional
          Container config. Roughly corresponds to Docker container config
          - `env` ([] string) — required
            List of environment variables on the form KEY=value
          - `host_config` ({} ContainerConfigHostConfig) — optional
             Docker host config
            - `extra_hosts` ([] string) — required
              Ports that are exposed by the container.
            - `network_mode` (string) — optional
               Sets the networking mode for the container.
            - `cpu_period` (integer) — optional
              The length of a CPU period in microsecond
            - `restart_policy` ({} RestartPolicy) — optional
              A policy that is applied when a container unexpectedly exits
              - `name` (string) — required
                Identifier for the policy.
              - `maximum_retry_count` (integer) — optional
                Maximum number of times to re-try before giving up
            - `port_bindings` (map string to PortBinding) — required
              Map of ports that should be exposed on the host.
            - `binds` ([] string) — required
              Volume bindings for the container.
            - `privileged` (boolean) — required
              List of environment variables on the form KEY=value
- `blessings` ({} Blessings) — optional
  Describes whether certain runners are blessed to run a Role.
  - `runner_ids_to_blessing` (map string to Blessing) — required
    A mapping of Runner Ids to whether or not they are blessed to run the associated role
    Map values ({} Blessing)
    - `value` (boolean) — required
      Whether something is blessed or not

## Responses

#### `201`

The role aggregate that was just created.

`application/json`

- `id` (string)
  The unique id of this role
- `role` ({} RoleWithMeta)
  Persisted role along with metadata
  - `value` ({} Role)
    Describes whether certain runners are blessed to run a Role.
    Same fields as `role`
  - `meta` ({} Metadata)
    Metadata of an entity
    - `created_time` (string)
      Creation time
    - `modified_time` (string)
      Modification time
    - `version` (string)
      Version
- `blessings` ({} BlessingsWithMeta)
  Persisted Blessings along with metadata
  - `value` ({} Blessings)
    Describes whether certain runners are blessed to run a Role.
    - `runner_ids_to_blessing` (map string to Blessing)
      A mapping of Runner Ids to whether or not they are blessed to run the associated role
      Map values ({} Blessing)
      - `value` (boolean)
        Whether something is blessed or not
  - `meta` ({} Metadata)
    Metadata of an entity
    - `created_time` (string)
      Creation time
    - `modified_time` (string)
      Modification time
    - `version` (string)
      Version
- `pending` ({} PendingStatesWithMeta)
  Persisted pending states for a role along with metadata
  - `value` ({} PendingStates)
    Describes whether certain runners are waiting to be blessed.
    - `runner_ids_to_pending_state` (map string to PendingState)
      A mapping of Runner Ids to whether or not they are waiting to be blessed to run the associated role
      Map values ({} PendingState)
      - `value` (boolean)
        Whether a runner is pending blessings or not
  - `meta` ({} Metadata)
    Metadata of an entity
    - `created_time` (string)
      Creation time
    - `modified_time` (string)
      Modification time
    - `version` (string)
      Version
#### `409`

The role ID you specified is already in use. (code: `roles.already_exists`)

`application/json`

- `errors` ([] BasicFailedReplyElement)
  A list of errors that occurred in the failing request
  - `code` (string)
    A structured code representing the error type that occurred
  - `message` (string)
    A human readable message describing the error that occurred
  - `fields` ([] string)
    If the error can be tied to a specific field or fields in the user request, this lists those fields
##### Response Headers

- `x-cloud-error-codes` (enum)
  The error codes associated with the response

## Code Examples

#### Console

```console
POST /platform/infrastructure/blueprinter/roles
```

#### curl

```curl
curl -X POST "/platform/infrastructure/blueprinter/roles"
```