Services /
Create combined service
Required permission
Project > Services > General > Create
Path parameters
projectId
string requiredID of the project
Request body
- {object}
name
string requiredThe name of the service.
min length3max length20pattern^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$description
stringA description of the service.
max length200pattern^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$billing
{object} requireddeploymentPlan
string requiredThe ID of the deployment plan to use.
pattern^[A-Za-z0-9-]+$deployment
{object} requiredinstances
integer requiredThe number of instances to run the service on.
cmdOverride
stringIf set, the service runs a custom command rather than one defined in the Dockerfile.
entrypointOverride
stringIf set, the service runs a custom entrypoint rather than one defined in the Dockerfile.
storage
{object}ephemeralStorage
{object}storageSize
integerEphemeral storage per container in MB
one of1024, 5120, 10240, 20480min1024max20480ports
[array]- {object}
name
string requiredThe name used to identify the port.
min length3max length8pattern^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$internalPort
integer requiredThe port number.
min1max65535public
booleanIf true, the port will be exposed publicly.
security
{object}credentials
[array]An array of credentials to access the service.
- {object}
username
string requiredThe username to access the service
min length3max length20pattern^[a-zA-Z0-9]+$password
string requiredThe password to access the service with this username.
type
string requiredThe type of authentication used
one ofbasic-authpolicies
[array]An array of IP address policies.
- {object}
addresses
[array] requiredAn array of IP addresses used for this rule
- string
An IP address used by this rule
action
string requiredThe action for this rule.
one ofALLOW, DENYdomains
[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
booleanDisable routing on the default code.run domain for public HTTP ports with custom domains.
protocol
string requiredThe protocol to use for the port.
one ofHTTP, HTTP/2, TCP, UDPvcsData
{object} requiredprojectUrl
string requiredURL 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 requiredThe VCS provider to use.
one ofbitbucket, gitlab, github, self-hostedselfHostedVcsId
stringIf projectType is self-hosted, the ID of the self-hosted vcs to use.
pattern^[A-Za-z0-9-]+\/[A-Za-z0-9-]+$accountLogin
stringBy 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 requiredThe name of the branch to use.
buildSettings
(multiple options) required- {object}
Build from a Dockerfile
dockerfile
{object} requiredbuildEngine
stringBuild engine to use. Defaults to recommended build engine
kaniko
one ofkaniko, buildkituseCache
booleanShould intermediate image layers be cached? Only supported by Kaniko.
dockerFilePath
string requiredThe file path of the Dockerfile.
pattern^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]+$dockerWorkDir
string requiredThe working directory of the Dockerfile.
pattern^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]*$- {object}
Build from a Buildpack
buildpack
{object} requiredbuilder
stringBuildpack stack to use. Defaults to recommended stack
HEROKU_20
.one ofHEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_BASE, PAKETO_FULLbuildpackLocators
[array]Array of custom Buildpacks to use.
- string
Url or registry identifier of custom Buildpack.
buildContext
stringThe 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
OR
Response body
- {object}
Response object.
data
{object} requiredResult data.
id
string requiredIdentifier for the service
appId
string requiredFull identifier used for service deployment
name
string requiredService name
description
stringA short description of the service
projectId
string requiredID of the project that the service belongs to
createdAt
date requiredThe time the service was created.
disabledCI
boolean requiredWhether Continuous Integration is disabled
disabledCD
boolean requiredWhether Continuous Deployment is disabled
billing
{object} requireddeploymentPlan
string requiredID of the billing plan used by this service
status
{object} requiredDetails about the current service status.
build
{object}Details about the status of the most recent build.
status
string requiredThe current status of the build.
one ofPENDING, STARTING, CLONING, BUILDING, UPLOADING, ABORTED, FAILURE, SUCCESS, CRASHEDlastTransitionTime
dateThe timestamp of when the build reached this status.
deployment
{object}Details about the current deployment status.
status
string requiredThe current status of the deployment.
one ofIN_PROGRESS, COMPLETEDreason
string requiredThe reason the current deployment was started.
one ofSCALING, DEPLOYINGlastTransitionTime
dateThe timestamp of when the deployment reached this status.
servicePaused
boolean requiredIs the service paused?
serviceType
string requiredType of the service (combined, build or deployment)
one ofcombined, build, deploymentvcsData
{object}projectUrl
string requiredURL of the repository being built
projectType
string requiredVCS provider for the repo being built
one ofbitbucket, gitlab, github, self-hostedselfHostedVcsId
stringID of the self-hosted VCS, if applicable.
projectBranch
stringBranch of the repo being built
publicRepo
booleanWhether the repo is being accessed without authentication.
dockerWorkDir
string requiredWorking directory used by the dockerfile
dockerFilePath
string requiredFile path of the Dockerfile
deployment
{object}region
stringRegion where this service is deployed and/or built
instances
integerNumber of instances/replicas running
internal
{object}nfObjectId
string requiredDatabase ID of deployed entity
nfObjectType
string requiredType of deployed entity
one ofservicerepository
string requiredURL of the repository being deployed
branch
string requiredBranch of the repo being deployed
buildSHA
string requiredCommit SHA to be deployed. 'latest' means the latest commit is automatically being deployed.
deployedSHA
string requiredCurrently deployed commit SHA. If buildSHA is set to 'latest', this will show the SHA of the latest commit.
buildConfiguration
{object} requiredpathIgnoreRules
[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} requiredbuildEngine
stringThe build engine used.
one ofbuildpack, kaniko, buildkitbuildpack
{object}Details about Buildpack settings.
builder
stringThe Buildpack stack used.
one ofHEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_BASE, PAKETO_FULLbuildpackLocators
[array]Array of custom Buildpacks used.
- string
Url or registry identifier of custom Buildpack.
kaniko
{object}Details about Kaniko settings.
useCache
booleanShould intermediate image layers be cached?
buildInitiated
boolean requiredWhether the service will be built immediately
buildId
stringThe ID of the initial build of the service.
POST /v1/projects/{projectId}/services/combined
Example request
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
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