Services /

Put deployment service

Creates or updates a deployment service.

Required permission

Project > Services > General > Create

Path parameters

projectId
string required
ID of the project

Request body

{object}

name
string required
The name of the service.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
A description of the service.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
tags
[array]
An array of previously defined tags to help identify and group the resource.

string
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

billing
{object} required

deploymentPlan
string required
The ID of the deployment plan to use.
pattern
^[A-Za-z0-9-]+$
gpu
{object}

enabled
boolean
configuration
{object}

gpuType
string required
timesliced
boolean

deployment
(multiple options: oneOf) required
Deployment type

{object}

Internal deployment

instances
integer required
The number of instances to run the service on.
buildpack
{object}
Allows for customization of buildpack runtime

configType
string required
Type of buildpack run configuration
one of
default, customProcess, customCommand, customEntrypointCustomCommand, originalEntrypointCustomCommand
customProcess
string
Custom process which should be run. Required in case where configType is customProcess
customEntrypoint
string
Custom entrypoint which should be run. Required in case where configType is customEntrypointCustomCommand
customCommand
string
Custom command which should be run. Required in case where configType is customCommand, customEntrypointCustomCommand or originalEntrypointCustomCommand

docker
{object}
Allows for customization of docker runtime

configType
string required
Type of entrypoint & command override configuration
one of
default, customEntrypoint, customCommand, customEntrypointCustomCommand
customEntrypoint
string
Custom entrypoint which should be used. Required in case where configType is customEntrypoint or customEntrypointCustomCommand
customCommand
string
Custom command which should be used. Required in case where configType is customCommand or customEntrypointCustomCommand

storage
{object}

ephemeralStorage
{object}

storageSize
integer
Ephemeral storage per container in MB
one of
1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 153600, 204800
min
1024
max
204800

shmSize
integer
Configures the amount of available memory-backed disk space available to /dev/shm
one of
64, 128, 256, 512, 1024, 2048, 5120, 10240
min
64
max
10240

strategy
{object}

type
string
Configures the instance roll out strategy of your service. Currently only available via feature flag.
one of
recreate, rollout-steady, rollout-balanced, rollout-fast

zonalRedundancy
string
Defines scheduling behaviour across different zones within the same region.
one of
preferred, disabled
gpu
{object}

enabled
boolean
configuration
{object}

gpuType
string required
timesliced
boolean

gracePeriodSeconds
integer
The maximum amount of time the process has to shut down after receiving a SIGTERM signal before it is forcefully shut down SIGKILL by the system.
min
15
max
600
internal
{object} required

id
string
ID of the build service to deploy
pattern
^[A-Za-z0-9-]+$
branch
string
Branch to deploy
buildSHA
(multiple options: oneOf)
Commit SHA to deploy, or 'latest' to deploy the most recent commit

string

min length

max length

string

one of

latest

buildId
string
ID of the build that should be deployed

{object}

External deployment

instances
integer required
The number of instances to run the service on.
buildpack
{object}
Allows for customization of buildpack runtime

configType
string required
Type of buildpack run configuration
one of
default, customProcess, customCommand, customEntrypointCustomCommand, originalEntrypointCustomCommand
customProcess
string
Custom process which should be run. Required in case where configType is customProcess
customEntrypoint
string
Custom entrypoint which should be run. Required in case where configType is customEntrypointCustomCommand
customCommand
string
Custom command which should be run. Required in case where configType is customCommand, customEntrypointCustomCommand or originalEntrypointCustomCommand

docker
{object}
Allows for customization of docker runtime

configType
string required
Type of entrypoint & command override configuration
one of
default, customEntrypoint, customCommand, customEntrypointCustomCommand
customEntrypoint
string
Custom entrypoint which should be used. Required in case where configType is customEntrypoint or customEntrypointCustomCommand
customCommand
string
Custom command which should be used. Required in case where configType is customCommand or customEntrypointCustomCommand

storage
{object}

ephemeralStorage
{object}

storageSize
integer
Ephemeral storage per container in MB
one of
1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 153600, 204800
min
1024
max
204800

shmSize
integer
Configures the amount of available memory-backed disk space available to /dev/shm
one of
64, 128, 256, 512, 1024, 2048, 5120, 10240
min
64
max
10240

strategy
{object}

type
string
Configures the instance roll out strategy of your service. Currently only available via feature flag.
one of
recreate, rollout-steady, rollout-balanced, rollout-fast

zonalRedundancy
string
Defines scheduling behaviour across different zones within the same region.
one of
preferred, disabled
gpu
{object}

enabled
boolean
configuration
{object}

gpuType
string required
timesliced
boolean

gracePeriodSeconds
integer
The maximum amount of time the process has to shut down after receiving a SIGTERM signal before it is forcefully shut down SIGKILL by the system.
min
15
max
600
external
{object} required

imagePath
string required
Image to be deployed. When not deploying from Dockerhub the URL must be specified.
pattern
^(?:(?:https?:\/\/)?([a-zA-Z0-9\-]+\.[a-zA-Z0-9\.\-]+)(\/v1)?)?(?:\/)?([a-zA-Z/-9\.\-_]+)(?:\:([a-zA-Z/-9\.\-_\:]+)|\@([a-zA-Z/-9\.\-_\:]+))$
credentials
string
ID of the saved credentials to use to access this external image.
pattern
^[A-Za-z0-9-]+$

{object}

Choose later

instances
integer required
The number of instances to run the service on.
buildpack
{object}
Allows for customization of buildpack runtime

configType
string required
Type of buildpack run configuration
one of
default, customProcess, customCommand, customEntrypointCustomCommand, originalEntrypointCustomCommand
customProcess
string
Custom process which should be run. Required in case where configType is customProcess
customEntrypoint
string
Custom entrypoint which should be run. Required in case where configType is customEntrypointCustomCommand
customCommand
string
Custom command which should be run. Required in case where configType is customCommand, customEntrypointCustomCommand or originalEntrypointCustomCommand

docker
{object}
Allows for customization of docker runtime

configType
string required
Type of entrypoint & command override configuration
one of
default, customEntrypoint, customCommand, customEntrypointCustomCommand
customEntrypoint
string
Custom entrypoint which should be used. Required in case where configType is customEntrypoint or customEntrypointCustomCommand
customCommand
string
Custom command which should be used. Required in case where configType is customCommand or customEntrypointCustomCommand

storage
{object}

ephemeralStorage
{object}

storageSize
integer
Ephemeral storage per container in MB
one of
1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 153600, 204800
min
1024
max
204800

shmSize
integer
Configures the amount of available memory-backed disk space available to /dev/shm
one of
64, 128, 256, 512, 1024, 2048, 5120, 10240
min
64
max
10240

strategy
{object}

type
string
Configures the instance roll out strategy of your service. Currently only available via feature flag.
one of
recreate, rollout-steady, rollout-balanced, rollout-fast

zonalRedundancy
string
Defines scheduling behaviour across different zones within the same region.
one of
preferred, disabled
gpu
{object}

enabled
boolean
configuration
{object}

gpuType
string required
timesliced
boolean

gracePeriodSeconds
integer
The maximum amount of time the process has to shut down after receiving a SIGTERM signal before it is forcefully shut down SIGKILL by the system.
min
15
max
600

ports
[array]

{object}

name
string required
The name used to identify the port.
min length
3
max length
8
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
internalPort
integer required
The port number.
min
1
max
65535
public
boolean
If true, the port will be exposed publicly.
security
{object}

credentials
[array]
An array of credentials to access the service.

{object}

username
string required
The username to access the service
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
password
string required
The password to access the service with this username.
type
string required
The type of authentication used
one of
basic-auth

policies
[array]
An array of IP address policies.

{object}

addresses
[array] required
An array of IP addresses used for this rule

string
An IP address used by this rule

action
string required
The action for this rule.
one of
ALLOW, DENY

domains
[array]
An array of domains to redirect to this port. Each domain must first be verified and registered to your account.

string
A domain to redirect to this port.

disableNfDomain
boolean
Disable routing on the default code.run domain for public HTTP ports with custom domains.
protocol
string required
The protocol to use for the port.
one of
HTTP, HTTP/2, TCP, UDP

runtimeEnvironment
{object}
An object containing the runtime environment to set for the service

runtimeFiles
{object}
Secret files as JSON object, encrypted at rest. File path must be absolute

healthChecks
[array]
An array of health checks.

{object}
A health check object.

protocol
string required
The protocol to access the health check with.
one of
HTTP, CMD, TCP
type
string required
The type of health check.
one of
livenessProbe, readinessProbe, startupProbe
path
string
The path of the health check endpoint. Required when protocol is HTTP.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]+$
cmd
string
The command to run for the health check. Required when protocol is CMD
port
integer
Port number for the health check endpoint. Required when protocol is HTTP.
min
1
initialDelaySeconds
integer required
Initial delay, in seconds, before the health check is first run.
min
1
max
180
periodSeconds
integer required
The time between each check, in seconds.
min
10
max
600
timeoutSeconds
integer required
The time to wait for a response before marking the health check as a failure.
min
1
max
60
failureThreshold
integer required
The maximum number of allowed failures.
min
1
max
255
successThreshold
integer
The number of successes required to mark the health check as a success.
min
1
max
255

autoscaling
{object}
Describes all autoscaling configurations

horizontal
{object}
Describes the horizontal autoscaling configuration

enabled
boolean required
Whether horizontal autoscaling should be enabled
minReplicas
number required
Minimum number of replicas which should be running at any time
min
1
maxReplicas
number required
Maximum number of replicas which can be running at any time
cpu
{object}

enabled
boolean required
Whether autoscaling should take into account cpu usage
thresholdPercentage
integer required
Threshold CPU usage percentage at which the workload will be scaled
min
10
max
100

memory
{object}

enabled
boolean required
Whether autoscaling should take into account memory usage
thresholdPercentage
integer required
Threshold memory usage percentage at which the workload will be scaled
min
10
max
100

rps
{object}

enabled
boolean required
Whether autoscaling should take into requests-per-second
thresholdValue
integer required
Threshold rps value on which the workload will be scaled
min
1

Response body

{object}
Response object.

data
{object} required
Result data.

name
string required
The name of the service.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
A description of the service.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
tags
[array]
An array of previously defined tags to help identify and group the resource.

string
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

billing
{object} required

deploymentPlan
string required
The ID of the deployment plan to use.
pattern
^[A-Za-z0-9-]+$
gpu
{object}

enabled
boolean
configuration
{object}

gpuType
string required
timesliced
boolean

ports
[array]

{object}

name
string required
The name used to identify the port.
min length
3
max length
8
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
internalPort
integer required
The port number.
min
1
max
65535
public
boolean
If true, the port will be exposed publicly.
security
{object}

credentials
[array]
An array of credentials to access the service.

{object}

username
string required
The username to access the service
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
password
string required
The password to access the service with this username.
type
string required
The type of authentication used
one of
basic-auth

policies
[array]
An array of IP address policies.

{object}

addresses
[array] required
An array of IP addresses used for this rule

string
An IP address used by this rule

action
string required
The action for this rule.
one of
ALLOW, DENY

domains
[array]
An array of domains to redirect to this port. Each domain must first be verified and registered to your account.

string
A domain to redirect to this port.

disableNfDomain
boolean
Disable routing on the default code.run domain for public HTTP ports with custom domains.
protocol
(multiple options: oneOf) required
The protocol to use for the port.

string

one of

HTTP, HTTP/2

string

one of

HTTP, HTTP/2, TCP, UDP

runtimeEnvironment
{object}
An object containing the runtime environment to set for the service

runtimeFiles
{object}
Secret files as JSON object, encrypted at rest. File path must be absolute

healthChecks
[array]
An array of health checks.

{object}
A health check object.

protocol
string required
The protocol to access the health check with.
one of
HTTP, CMD, TCP
type
string required
The type of health check.
one of
livenessProbe, readinessProbe, startupProbe
path
string
The path of the health check endpoint. Required when protocol is HTTP.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]+$
cmd
string
The command to run for the health check. Required when protocol is CMD
port
integer
Port number for the health check endpoint. Required when protocol is HTTP.
min
1
initialDelaySeconds
integer required
Initial delay, in seconds, before the health check is first run.
min
1
max
180
periodSeconds
integer required
The time between each check, in seconds.
min
10
max
600
timeoutSeconds
integer required
The time to wait for a response before marking the health check as a failure.
min
1
max
60
failureThreshold
integer required
The maximum number of allowed failures.
min
1
max
255
successThreshold
integer
The number of successes required to mark the health check as a success.
min
1
max
255

autoscaling
{object}
Describes all autoscaling configurations

horizontal
{object}
Describes the horizontal autoscaling configuration

enabled
boolean required
Whether horizontal autoscaling should be enabled
minReplicas
number required
Minimum number of replicas which should be running at any time
min
1
maxReplicas
number required
Maximum number of replicas which can be running at any time
cpu
{object}

enabled
boolean required
Whether autoscaling should take into account cpu usage
thresholdPercentage
integer required
Threshold CPU usage percentage at which the workload will be scaled
min
10
max
100

memory
{object}

enabled
boolean required
Whether autoscaling should take into account memory usage
thresholdPercentage
integer required
Threshold memory usage percentage at which the workload will be scaled
min
10
max
100

rps
{object}

enabled
boolean required
Whether autoscaling should take into requests-per-second
thresholdValue
integer required
Threshold rps value on which the workload will be scaled
min
1

deploymentSysctlSettings
{object}

vm.max_map_count
integer
min
1
max
1048576

serviceType
string required
Type of the service (combined, build or deployment)
one of
deployment
deployment
{object} required

instances
integer required
The number of instances to run the service on.
buildpack
{object}
Allows for customization of buildpack runtime

configType
string required
Type of buildpack run configuration
one of
default, customProcess, customCommand, customEntrypointCustomCommand, originalEntrypointCustomCommand
customProcess
string
Custom process which should be run. Required in case where configType is customProcess
customEntrypoint
string
Custom entrypoint which should be run. Required in case where configType is customEntrypointCustomCommand
customCommand
string
Custom command which should be run. Required in case where configType is customCommand, customEntrypointCustomCommand or originalEntrypointCustomCommand

docker
{object}
Allows for customization of docker runtime

configType
string required
Type of entrypoint & command override configuration
one of
default, customEntrypoint, customCommand, customEntrypointCustomCommand
customEntrypoint
string
Custom entrypoint which should be used. Required in case where configType is customEntrypoint or customEntrypointCustomCommand
customCommand
string
Custom command which should be used. Required in case where configType is customCommand or customEntrypointCustomCommand

storage
{object}

ephemeralStorage
{object}

storageSize
integer
Ephemeral storage per container in MB
one of
1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 153600, 204800
min
1024
max
204800

shmSize
integer
Configures the amount of available memory-backed disk space available to /dev/shm
one of
64, 128, 256, 512, 1024, 2048, 5120, 10240
min
64
max
10240

strategy
{object}

type
string
Configures the instance roll out strategy of your service. Currently only available via feature flag.
one of
recreate, rollout-steady, rollout-balanced, rollout-fast

zonalRedundancy
string
Defines scheduling behaviour across different zones within the same region.
one of
preferred, disabled
gpu
{object}

enabled
boolean
configuration
{object}

gpuType
string required
timesliced
boolean

gracePeriodSeconds
integer
The maximum amount of time the process has to shut down after receiving a SIGTERM signal before it is forcefully shut down SIGKILL by the system.
min
15
max
600
internal
{object}

id
string
ID of the build service to deploy
pattern
^[A-Za-z0-9-]+$
branch
string
Branch to deploy
buildSHA
(multiple options: oneOf)
Commit SHA to deploy, or 'latest' to deploy the most recent commit

string

min length

max length

string

one of

latest

buildId
string
ID of the build that should be deployed

external
{object}

imagePath
string required
Image to be deployed. When not deploying from Dockerhub the URL must be specified.
pattern
^(?:(?:https?:\/\/)?([a-zA-Z0-9\-]+\.[a-zA-Z0-9\.\-]+)(\/v1)?)?(?:\/)?([a-zA-Z/-9\.\-_]+)(?:\:([a-zA-Z/-9\.\-_\:]+)|\@([a-zA-Z/-9\.\-_\:]+))$
credentials
string
ID of the saved credentials to use to access this external image.
pattern
^[A-Za-z0-9-]+$

imageUrl
string
Image registry url of the deployed image.

id
string required
Identifier for the service
appId
string required
Full identifier used for service deployment
cluster
{object}

id
required
one of
aws-cluster-id
name
required
one of
AWS Cluster Name
namespace

one of
ns-krbfnmxfv5x8-

createdAt
string
time of creation
updatedAt
string
time of update
status
{object} required
Details about the current service status.

deployment
{object} required
Details about the current deployment status.

status
string required
The current status of the deployment.
one of
PENDING, IN_PROGRESS, COMPLETED, FAILED
reason
string required
The reason the current deployment was started.
one of
SCALING, DEPLOYING
lastTransitionTime
string
The timestamp of when the deployment reached this status.

API

CLI

JS Client

PUT /v1/projects/{projectId}/services/deployment

Example request

Request body

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request PUT \
  --data '{"name":"Example Service","description":"A service description","tags":["my-tag"],"billing":{"deploymentPlan":"nf-compute-20"},"deployment":{"instances":1,"docker":{"configType":"default"},"storage":{"ephemeralStorage":{"storageSize":1024}},"internal":{"id":"example-build-service","branch":"master","buildId":"premium-guide-6393"}},"ports":[{"name":"p01","internalPort":8080,"public":true,"security":{"credentials":[{"username":"admin","password":"password123","type":"basic-auth"}],"policies":[{"addresses":["127.0.0.1"],"action":"DENY"}]},"domains":["app.example.com"],"protocol":"HTTP"}],"runtimeEnvironment":{"VARIABLE_1":"abcdef","VARIABLE_2":"12345"},"runtimeFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"healthChecks":[{"protocol":"HTTP","type":"readinessProbe","path":"/health-check","port":8080,"initialDelaySeconds":10,"periodSeconds":60,"timeoutSeconds":1,"failureThreshold":3,"successThreshold":1}]}' \
  https://api.northflank.com/v1/projects/{projectId}/services/deployment

Example response

200 OK

Details about the created or updated service.

JSON

{
  "data": {
    "name": "Example Service",
    "description": "A service description",
    "tags": [
      "my-tag"
    ],
    "billing": {
      "deploymentPlan": "nf-compute-20"
    },
    "ports": [
      {
        "name": "p01",
        "internalPort": 8080,
        "public": true,
        "security": {
          "credentials": [
            {
              "username": "admin",
              "password": "password123",
              "type": "basic-auth"
            }
          ],
          "policies": [
            {
              "addresses": [
                "127.0.0.1"
              ],
              "action": "DENY"
            }
          ]
        },
        "domains": [
          "app.example.com"
        ]
      }
    ],
    "runtimeEnvironment": {
      "VARIABLE_1": "abcdef",
      "VARIABLE_2": "12345"
    },
    "runtimeFiles": {
      "/dir/fileName": {
        "data": "VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=",
        "encoding": "utf-8"
      }
    },
    "healthChecks": [
      {
        "protocol": "HTTP",
        "type": "readinessProbe",
        "path": "/health-check",
        "port": 8080,
        "initialDelaySeconds": 10,
        "periodSeconds": 60,
        "timeoutSeconds": 1,
        "failureThreshold": 3,
        "successThreshold": 1
      }
    ],
    "serviceType": "deployment",
    "deployment": {
      "instances": 1,
      "docker": {
        "configType": "default"
      },
      "storage": {
        "ephemeralStorage": {
          "storageSize": 1024
        }
      },
      "internal": {
        "id": "example-build-service",
        "branch": "master",
        "buildId": "premium-guide-6393"
      },
      "external": {
        "imagePath": "nginx:latest",
        "credentials": "example-credentials"
      }
    },
    "id": "example-service",
    "appId": "/example-user/default-project/example-service",
    "status": {
      "deployment": {
        "status": "COMPLETED",
        "reason": "DEPLOYING",
        "lastTransitionTime": "2021-11-29T11:47:16.624Z"
      }
    }
  }
}