v1
Double column
API
CLI
JS Client

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-._]*$

        OR

      • {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

          © 2022 Northflank Ltd. All rights reserved.