Services /

Create combined service

Creates a new combined 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
20
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\\/'"()[\];`%^&*\-_:!]+$
billing
{object} required

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

deployment
{object} required

instances
integer required
The number of instances to run the service on.
cmdOverride
string
If set, the service runs a custom command rather than one defined in the Dockerfile.
entrypointOverride
string
If set, the service runs a custom entrypoint rather than one defined in the Dockerfile.
storage
{object}

ephemeralStorage
{object}

storageSize
integer
Ephemeral storage per container in MB
one of
1024, 5120, 10240, 20480
min
1024
max
20480

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
20
pattern
^[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

vcsData
{object} required

projectUrl
string required
URL of the Git repo to build.
pattern
^(https:\/\/)?((www(\.[a-zA-Z0-9\-]{2,})+\.)?[a-zA-Z0-9\-]{2,})(\.([a-zA-Z0-9\-]{2,}))+(\/([a-zA-Z0-9\-._]{2,}))+?$
projectType
string required
The VCS provider to use.
one of
bitbucket, gitlab, github, self-hosted
selfHostedVcsId
string
If projectType is self-hosted, the ID of the self-hosted vcs to use.
pattern
^[A-Za-z0-9-]+\/[A-Za-z0-9-]+$
accountLogin
string
By default, if you have multiple version control accounts of the same provider linked, Northflank will pick a linked account that has access to the repository. If accountLogin is provided, Northflank will instead use your linked account with that login name.
projectBranch
string required
The name of the branch to use.

buildSettings
(multiple options) required

{object}

Build from a Dockerfile

dockerfile
{object} required

buildEngine
string
Build engine to use. Defaults to recommended build engine kaniko
one of
kaniko, buildkit
useCache
boolean
Should intermediate image layers be cached? Only supported by Kaniko.
dockerFilePath
string required
The file path of the Dockerfile.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]+$
dockerWorkDir
string required
The working directory of the Dockerfile.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]*$

{object}

Build from a Buildpack

buildpack
{object} required

builder
string
Buildpack stack to use. Defaults to recommended stack HEROKU_20.
one of
HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_BASE, PAKETO_FULL
buildpackLocators
[array]
Array of custom Buildpacks to use.

string
Url or registry identifier of custom Buildpack.

buildContext
string
The working directory to build in.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]*$

buildConfiguration
{object}

pathIgnoreRules
[array]
An array of path ignore rules. A commit will only be built if a file has been changed that does not match any of the ignore rules. Path ignore rules follow .gitignore syntax.

string
A path ignore rule, following .gitignore syntax. For example, *.md will ignore all files ending with .md.

runtimeEnvironment
{object}
An object containing the runtime environment to set for the service. Keys must only contain letters and numbers separated with underscores, may not start with a number

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

buildArguments
{object}
An object containing the build arguments to set for the service. Keys must only contain letters and numbers separated with underscores, may not start with a number

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

Response body

{object}
Response object.

data
{object} required
Result data.

id
string required
Identifier for the service
appId
string required
Full identifier used for service deployment
name
string required
Service name
description
string
A short description of the service
projectId
string required
ID of the project that the service belongs to
createdAt
date required
The time the service was created.
disabledCI
boolean required
Whether Continuous Integration is disabled
disabledCD
boolean required
Whether Continuous Deployment is disabled
billing
{object} required

deploymentPlan
string required
ID of the billing plan used by this service

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

build
{object}
Details about the status of the most recent build.

status
string required
The current status of the build.
one of
PENDING, STARTING, CLONING, BUILDING, UPLOADING, ABORTED, FAILURE, SUCCESS, CRASHED
lastTransitionTime
date
The timestamp of when the build reached this status.

deployment
{object}
Details about the current deployment status.

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

servicePaused
boolean required
Is the service paused?
serviceType
string required
Type of the service (combined, build or deployment)
one of
combined, build, deployment
vcsData
{object}

projectUrl
string required
URL of the repository being built
projectType
string required
VCS provider for the repo being built
one of
bitbucket, gitlab, github, self-hosted
selfHostedVcsId
string
ID of the self-hosted VCS, if applicable.
projectBranch
string
Branch of the repo being built
publicRepo
boolean
Whether the repo is being accessed without authentication.
dockerWorkDir
string required
Working directory used by the dockerfile
dockerFilePath
string required
File path of the Dockerfile

deployment
{object}

region
string
Region where this service is deployed and/or built
instances
integer
Number of instances/replicas running
internal
{object}

nfObjectId
string required
Database ID of deployed entity
nfObjectType
string required
Type of deployed entity
one of
service
repository
string required
URL of the repository being deployed
branch
string required
Branch of the repo being deployed
buildSHA
string required
Commit SHA to be deployed. 'latest' means the latest commit is automatically being deployed.
deployedSHA
string required
Currently deployed commit SHA. If buildSHA is set to 'latest', this will show the SHA of the latest commit.

buildConfiguration
{object} required

pathIgnoreRules
[array]
An array of path ignore rules. A commit will only be built if a file has been changed that does not match any of the ignore rules. Path ignore rules follow .gitignore syntax.

string
A path ignore rule, following .gitignore syntax. For example, *.md will ignore all files ending with .md.

buildEngineConfiguration
{object} required

buildEngine
string
The build engine used.
one of
buildpack, kaniko, buildkit
buildpack
{object}
Details about Buildpack settings.

builder
string
The Buildpack stack used.
one of
HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_BASE, PAKETO_FULL
buildpackLocators
[array]
Array of custom Buildpacks used.

string
Url or registry identifier of custom Buildpack.

kaniko
{object}
Details about Kaniko settings.

useCache
boolean
Should intermediate image layers be cached?

buildInitiated
boolean required
Whether the service will be built immediately
buildId
string
The ID of the initial build of the service.

API

CLI

JS Client

POST /v1/projects/{projectId}/services/combined

Example request

Request body

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Service","description":"A service description","billing":{"deploymentPlan":"nf-compute-20"},"deployment":{"instances":1,"cmdOverride":"nginx -g","entrypointOverride":"/custom-entrypoint.sh","storage":{"ephemeralStorage":{"storageSize":1024}}},"ports":[{"name":"port-1","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"}],"vcsData":{"projectUrl":"https://github.com/northflank/gatsby-with-northflank","projectType":"github","accountLogin":"github-user","projectBranch":"master"},"buildSettings":{"dockerfile":{"buildEngine":"kaniko","useCache":false,"dockerFilePath":"/Dockerfile","dockerWorkDir":"/"}},"buildConfiguration":{"pathIgnoreRules":["README.md"]},"runtimeEnvironment":{"VARIABLE_1":"abcdef","VARIABLE_2":"12345"},"runtimeFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"buildArguments":{"ARGUMENT_1":"abcdef","ARGUMENT_2":"12345"},"buildFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}}}' \
  http://api.northflank.com/v1/projects/{projectId}/services/combined

Example response

200 OK

Details about the newly created service.

JSON

{
  "data": {
    "id": "example-service",
    "appId": "/example-user/default-project/example-service",
    "name": "Example Service",
    "description": "This is the service description",
    "projectId": "default-project",
    "createdAt": "2021-01-20T11:19:53.175Z",
    "disabledCI": false,
    "disabledCD": false,
    "billing": {
      "deploymentPlan": "nf-compute-20"
    },
    "status": {
      "build": {
        "status": "SUCCESS",
        "lastTransitionTime": "2021-11-29T11:47:16.624Z"
      },
      "deployment": {
        "status": "COMPLETED",
        "reason": "DEPLOYING",
        "lastTransitionTime": "2021-11-29T11:47:16.624Z"
      }
    },
    "serviceType": "combined",
    "vcsData": {
      "projectUrl": "https://github.com/northflank/gatsby-with-northflank",
      "projectType": "github",
      "selfHostedVcsId": "example-team/self-hosted-vcs",
      "projectBranch": "master",
      "publicRepo": false,
      "dockerWorkDir": "/",
      "dockerFilePath": "/Dockerfile"
    },
    "deployment": {
      "region": "europe-west",
      "instances": 1,
      "internal": {
        "nfObjectId": "5f3bd676b84798d54472d1cc",
        "nfObjectType": "service",
        "repository": "https://github.com/northflank/gatsby-with-northflank",
        "branch": "master",
        "buildSHA": "latest",
        "deployedSHA": "262ed9817b3cad5142fbceabe0c9e371e390d616"
      }
    },
    "buildConfiguration": {
      "pathIgnoreRules": [
        "README.md"
      ]
    },
    "buildEngineConfiguration": {
      "buildEngine": "buildpack",
      "buildpack": {
        "builder": "HEROKU_20",
        "buildpackLocators": [
          "https://buildpack-registry.heroku.com/cnb/mars/create-react-app"
        ]
      },
      "kaniko": {}
    },
    "buildInitiated": true,
    "buildId": "joyous-view-6290"
  }
}

Example response

409 Conflict

There is already a service with the same derived identifier