v1
Double column
API
CLI
JS Client

Services /

Create deployment service

Creates a new 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
      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

      (multiple options) required

      Deployment type

      • {object}

        Internal deployment

        • instances

          integer required

          The number of instances to run the service on.

        • internal

          {object}
          • id

            string required

            Internal ID of the build service to deploy

            pattern
            ^[A-Za-z0-9-]+$
          • branch

            string

            Branch to deploy

          • buildSHA

            string

            Commit SHA to deploy, or 'latest' to deploy the most recent commit

        OR

      • {object}

        External deployment

        • instances

          integer required

          The number of instances to run the service on.

        • external

          {object}
          • imagePath

            string required

            Path of the external image

          • credentials

            string

            ID of the saved credentials to use to access this external image.

            pattern
            ^[A-Za-z0-9-]+$

        OR

      • {object}

        Choose later

        • 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
          1
          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
    • environment

      {object}

      An object containing the environment variables 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

        • serviceType

          string required

          Type of the service (combined, build or deployment)

          one of
          combined, build, deployment
        • deployment

          {object}
          • region

            string

            Region where this service is deployed and/or built

          • instances

            integer

            Number of instances/replicas running

          • external

            {object}

            Data about a deployment from an external registry.

            • imagePath

              string required

              Path of the external image excluding the hostname

            • registryProvider

              string required

              Registry provider hosting the external image

              one of
              dockerhub, gcr-eu, gcr-us, gitlab, github, custom
            • privateImage

              boolean required

              Does the image require authentication

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

    API
    CLI
    JS Client

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

    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,"internal":{"id":"example-build-service","branch":"master","buildSHA":"latest"}},"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"}],"environment":{"VARIABLE_1":"abcdef","VARIABLE_2":"12345"}}' \
      https://api.northflank.com/v1/projects/{projectId}/services/deployment

    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"
        },
        "serviceType": "deployment",
        "deployment": {
          "region": "europe-west",
          "instances": 1,
          "external": {},
          "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"
          }
        }
      }
    }

    Example response

    400 Bad Request

    Unable to verify external image

    Example response

    409 Conflict

    There is already a service with the same derived identifier

    © 2021 Northflank Ltd. All rights reserved.