# Creating Deployments
## OpenAPI Specification
```yaml
openapi: 3.0.1
info:
title: ''
description: ''
version: 1.0.0
paths:
/be/v1/deployments:
post:
summary: Creating Deployments
deprecated: false
description: >-
This endpoint registers a new ROCKIT Edge deployment. A deployment must
contain an origin configuration describing where the generated ROCKIT
Images and ROCKIT Patches should be published.
It may also contain a download authentication group in case ROCKIT Edge
should also handle the CDN download authentication, for example for
using the ROCKIT StreamInstaller.
### File structure on deployment:
The generated file structure can be obtained from `GET /be/v1/apps`. It
returns all relevant information to access ROCKIT images via an
`dxfName` as well as the available patches in an array
`fromBuildId`-`toBuildId`. ROCKITPLAY deploys the files according to the
following file structure to your origin:
DxF path: `originPrefix`/dxf/`orgName`/`appName`/`iCurBuild`/`dxfName`/*
Patch path:
`originPrefix`/pat/`orgName`/`appName`/`toBuildId`/`fromBuildId`/*
with
originPrefix: is defined when you call `POST /be/v1/deployments`
orgName: "is defined when creating an organization"
appName: is defined when you call `POST /be/v1/apps`
`dxfName`, `fromBuildId`-`toBuildId`, `iCurBuild`: can be obtained from
`GET /be/v1/apps`
in paths buildIds are masked as 4 digit number, e.g. iCurBuild = 1
becomes 0001 in path
### Important:
If incorrect credentials are used when creating a deployment, the
deployment will still be created without errors. However, this issue
will surface later during the app creation and build import process
(e.g., with `POST /be/v1/apps` and `POST /be/v1/builds`).
**Common Problem Indicators:**
If an app tries to deploy but cannot, it will enter an error state.
Checking `GET /be/v1/apps` will show that the app is in an error state.
`GET /be/v1/tasks` can be used to inspect which task failed.
**Solution:**
If an app fails to deploy due to incorrect credentials or deployment
issues, you can resolve it in one of the following ways:
1. Update the Deployment Credentials & Retry the Task
- Use `PATCH /deployments` to update the deployment with the correct
credentials.
- Use [Retry
Task](https://edge.api.cloud.rockitplay.com/retry-task-12373263e0.md) to
trigger the failed task again.
- If the task now succeeds, the app will no longer be in an error state.
2. Deregister the Faulty Deployment & Retry the Task
- Deregister the incorrect deployment(s) from the app with `PATCH
/apps`.
- Use [Retry
Task](https://edge.api.cloud.rockitplay.com/retry-task-12373263e0.md) to
redeploy the app to all correctly registered deployments.
- If successful, the app will no longer be in an error state.
### Additional Notes
In order that AWS S3 buckets work correctly, please make sure the
hostname does
not contain the bucket name and contains the region, i.e.
s3.us-east-1.amazonaws.com.
Currently no other region than us-east-1 is supported for the original
AWS S3.
### Required Permissions
`deployments.create`
See [Roles](https://edge.api.cloud.rockitplay.com/roles-3618377f0.md)
for more details.
tags:
- ROCKIT Edge - Backend API/Deployments
parameters:
- name: Authorization
in: header
description: >-
Use the access token obtained from [`POST
/be/v1/login`](https://edge.api.cloud.rockitplay.com/user-login-org-11611254e0.md)
or [`POST
/be/v1/refresh`](https://edge.api.cloud.rockitplay.com/refresh-11630082e0.md)
as Bearer token.
Mutually excluded with `x-rockit-api-key`.
required: false
example: Bearer {{_edge_org_admin_access_token}}
schema:
type: string
- name: x-rockit-tenant
in: header
description: >
Unique and immutable tenancy identifier obtained from the ROCKIT
Edge administrator.
Requires `x-rockit-username`,
`x-rockit-orgname` and `x-rockit-api-key`.
required: false
example: '{{EDGE_TENANT_NAME}}'
schema:
type: string
- name: x-rockit-orgname
in: header
description: >
Unique and immutable organization identifier obtained from the
ROCKIT Edge administrator.
Requires `x-rockit-tenant`,
`x-rockit-username` and `x-rockit-api-key`.
required: false
example: '{{EDGE_ORG_NAME}}'
schema:
type: string
- name: x-rockit-username
in: header
description: >
Unique and immutable username which is associated with the apikey.
Requires `x-rockit-tenant`, `x-rockit-orgname` and
`x-rockit-api-key`.
required: false
example: adminPrincipal
schema:
type: string
- name: x-rockit-api-key
in: header
description: >-
Unique and immutable apikey which is associated with an machine
user.
Mutually excluded with `Authorization` header. Requires
`x-rockit-tenant`, `x-rockit-username` and `x-rockit-orgname`.
required: false
example: '{{_adminPrincipal_apiKey}}'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
pattern: /^[A-Za-z0-9_]{2,50}$/
label:
type: string
origin:
type: object
properties:
s3:
type: object
properties:
hostname:
type: string
accessKey:
type: string
secretKey:
type: string
region:
type: string
bucket:
type: string
prefix:
type: string
required:
- hostname
- accessKey
- secretKey
- region
- bucket
x-apidog-orders:
- hostname
- accessKey
- secretKey
- region
- bucket
- prefix
x-apidog-ignore-properties: []
netstorage:
type: object
properties:
hostname:
type: string
uploadAccount:
type: string
apiKey:
type: string
cpCode:
type: number
prefix:
type: string
x-apidog-orders:
- hostname
- uploadAccount
- apiKey
- cpCode
- prefix
required:
- hostname
- uploadAccount
- apiKey
- cpCode
x-apidog-ignore-properties: []
x-apidog-orders:
- s3
- netstorage
x-apidog-ignore-properties: []
dlAuth:
type: object
properties:
gcore:
type: object
properties:
baseUrl:
type: string
secureToken:
type: string
bucket:
type: string
prefix:
type: string
required:
- baseUrl
- secureToken
- bucket
x-apidog-orders:
- baseUrl
- secureToken
- bucket
- prefix
x-apidog-ignore-properties: []
akamai:
type: object
properties:
hostname:
type: string
authKey:
type: string
prefix:
type: string
x-apidog-orders:
- hostname
- authKey
- prefix
required:
- hostname
- authKey
x-apidog-ignore-properties: []
required:
- gcore
- akamai
x-apidog-orders:
- gcore
- akamai
x-apidog-ignore-properties: []
dTDeletionSec:
type: number
minimum: 0
validateOnly:
type: boolean
required:
- name
- label
- origin
x-apidog-orders:
- name
- label
- origin
- dlAuth
- dTDeletionSec
- validateOnly
x-apidog-ignore-properties: []
example:
name: gcore
label: Gcore Object Storage / Gcore CDN
origin:
s3:
hostname: '{{EDGE_ORIGIN_GCORE_HOSTNAME}}'
accessKey: '{{EDGE_ORIGIN_GCORE_ACCESS_KEY}}'
secretKey: '{{EDGE_ORIGIN_GCORE_SECRET_KEY}}'
location: '{{EDGE_ORIGIN_GCORE_LOCATION}}'
bucket: '{{EDGE_ORIGIN_GCORE_BUCKET}}'
prefix: '{{EDGE_ORIGIN_GCORE_PREFIX}}'
dlAuth:
gcore:
baseUrl: '{{EDGE_ORIGIN_GCORE_BASE_URL}}'
secureToken: '{{EDGE_ORIGIN_GCORE_SECURE_TOKEN}}'
bucket: '{{EDGE_ORIGIN_GCORE_BUCKET}}'
prefix: '{{EDGE_ORIGIN_GCORE_PREFIX}}'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
A string that confirms the deployment creation was
successful.
message:
type: string
description: >-
A confirmation message (e.g., "deployment created")
indicating that the new deployment has been registered
successfully.
required:
- status
- message
x-apidog-orders:
- status
- message
x-apidog-ignore-properties: []
examples:
'1':
summary: '200: success'
value:
status: success
message: deployment created
'2':
summary: '400: invalid-param'
value:
status: failed
error: invalid-param
message: name invalid
detail: >-
body parameter name does not match pattern
"/^([A-Za-z][A-Za-z0-9]{3,19})$/"
'3':
summary: '409: item-exists'
value:
status: failed
error: item-exists
message: cannot create deployment
detail: deployment with name 'akamaiNetstorage' exists already
'4':
summary: Unautharized(401)
value:
status: string
error: string
message: string
headers: {}
x-apidog-name: '200: success'
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
Reflects that the creation failed due to one or more
invalid or missing parameters in the request.
error:
type: string
description: Contains an error identifier. (e.g., "invalid-param")
message:
type: string
description: >-
Explains the nature of the invalid input (for example,
"name invalid").
detail:
type: string
description: >-
Offers further context on the error. (e.g., expected
pattern for the organization name)
x-apidog-orders:
- 01JQNGYP5BES6NSNBS95MYYTTG
required:
- status
- error
- message
- detail
x-apidog-refs:
01JQNGYP5BES6NSNBS95MYYTTG:
$ref: '#/components/schemas/Invalid%20Param'
x-apidog-ignore-properties:
- status
- error
- message
- detail
headers: {}
x-apidog-name: '400: invalid-param'
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
Indicates that the organization creation request was
rejected because of authentication problems.
error:
type: string
description: Contains an error identifier. (e.g."unauthorized")
message:
type: string
description: >-
Provides details such as "invalid token" to help diagnose
the failure.
x-apidog-orders:
- 01JQNGZEHPEXZJZMZXBSG95BVT
required:
- status
- error
- message
x-apidog-refs:
01JQNGZEHPEXZJZMZXBSG95BVT:
$ref: '#/components/schemas/unauthorized'
x-apidog-ignore-properties:
- status
- error
- message
headers: {}
x-apidog-name: Unauthorized
'409':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
Indicates that the request failed because an organization
with the same identifier already exists or is protected.
error:
type: string
description: Contains an error identifier. (e.g., "item exists")
message:
type: string
description: >-
States that the organization cannot be created due to a
conflict.
detail:
type: string
description: Provides additional context.
x-apidog-orders:
- 01JQNGZ2TWP2G8XV2GQQ75AVRE
required:
- status
- error
- message
- detail
x-apidog-refs:
01JQNGZ2TWP2G8XV2GQQ75AVRE:
$ref: '#/components/schemas/Item-exists'
x-apidog-ignore-properties:
- status
- error
- message
- detail
headers: {}
x-apidog-name: '409: item-exists'
security: []
x-apidog-folder: ROCKIT Edge - Backend API/Deployments
x-apidog-status: released
x-run-in-apidog: https://app.apidog.com/web/project/732774/apis/api-11747958-run
components:
schemas:
Invalid Param:
type: object
properties:
status:
type: string
description: >-
Reflects that the creation failed due to one or more invalid or
missing parameters in the request.
error:
type: string
description: Contains an error identifier. (e.g., "invalid-param")
message:
type: string
description: >-
Explains the nature of the invalid input (for example, "name
invalid").
detail:
type: string
description: >-
Offers further context on the error. (e.g., expected pattern for the
organization name)
required:
- status
- error
- message
- detail
x-apidog-orders:
- status
- error
- message
- detail
x-apidog-ignore-properties: []
x-apidog-folder: ''
Item-exists:
type: object
properties:
status:
type: string
description: >-
Indicates that the request failed because an organization with the
same identifier already exists or is protected.
error:
type: string
description: Contains an error identifier. (e.g., "item exists")
message:
type: string
description: States that the organization cannot be created due to a conflict.
detail:
type: string
description: Provides additional context.
required:
- status
- error
- message
- detail
x-apidog-orders:
- status
- error
- message
- detail
x-apidog-ignore-properties: []
x-apidog-folder: ''
unauthorized:
type: object
properties:
status:
type: string
description: >-
Indicates that the organization creation request was rejected
because of authentication problems.
error:
type: string
description: Contains an error identifier. (e.g."unauthorized")
message:
type: string
description: >-
Provides details such as "invalid token" to help diagnose the
failure.
required:
- status
- error
- message
x-apidog-orders:
- status
- error
- message
x-apidog-ignore-properties: []
x-apidog-folder: ''
securitySchemes:
Bearer token:
type: bearer
scheme: bearer
description: >-
Enter your Access Token. You can obtain this by calling the /be/v1/login
endpoint. Use the Refresh token to get a new Access token when it
expires.
servers:
- url: https://Example-Server.com
description: Default
security: []
```