v1
ApplicationAPI & CLI
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](-?[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.

    • 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

        • protocol

          string required

          The protocol to use for the port.

          one of
          HTTP, 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

          • 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_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.

    • environment

      {object}

      An object containing the environment variables to set for the service

      • buildArguments

        {object}

        An object containing the build arguments to set for the service

      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

            string 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

                string

                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

                string

                The timestamp of when the deployment reached this status.

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

              • appId

                string required

                Full identifier of deployed entity

              • 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

            • builder

              string

              The build engine used.

              one of
              buildpack, kaniko, buildkit

            • buildpack

              {object}

              • builder

                string

                The Buildpack stack used.

                one of
                HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_FULL

              • buildpackLocators

                [array]

                Array of custom Buildpacks used.

                • string

                  Url or registry identifier of custom Buildpack.

          • buildInitiated

            boolean required

            Whether the service will be built immediately

      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},"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"}]},"protocol":"HTTP"}],"vcsData":{"projectUrl":"https://github.com/northflank/gatsby-with-northflank","projectType":"github","accountLogin":"github-user","projectBranch":"master"},"buildSettings":{"dockerfile":{"buildEngine":"kaniko","dockerFilePath":"/Dockerfile","dockerWorkDir":"/"}},"buildConfiguration":{"pathIgnoreRules":["README.md"]},"environment":{"VARIABLE_1":"abcdef","VARIABLE_2":"12345"},"buildArguments":{"ARGUMENT_1":"abcdef","ARGUMENT_2":"12345"}}' \
  https://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": {
        "appId": "/example-user/default-project/example-service",
        "nfObjectId": "5f3bd676b84798d54472d1cc",
        "nfObjectType": "service",
        "repository": "https://github.com/northflank/gatsby-with-northflank",
        "branch": "master",
        "buildSHA": "latest",
        "deployedSHA": "262ed9817b3cad5142fbceabe0c9e371e390d616"
      }
    },
    "buildConfiguration": {
      "pathIgnoreRules": [
        "README.md"
      ]
    },
    "buildEngineConfiguration": {
      "builder": "buildpack",
      "buildpack": {
        "builder": "HEROKU_20",
        "buildpackLocators": [
          "https://buildpack-registry.heroku.com/cnb/mars/create-react-app"
        ]
      }
    },
    "buildInitiated": true
  }
}

      Example response

      409 Conflict

      There is already a service with the same derived identifier

      © 2022 Northflank Ltd. All rights reserved.

      northflank.comTermsPrivacyfeedback@northflank.com