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]((-|\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

      (multiple options) required

      Deployment type

      • {object}

        Internal deployment

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

          {object} required
          • id

            string

            ID of the build service to deploy

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

            string

            Branch to deploy

          • buildSHA

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

          • buildId

            string

            ID of the build that should be deployed

        OR

      • {object}

        External deployment

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

          {object} required
          • imagePath

            string required

            Image to be deployed. When not deploying from Dockerhub the URL must be specified.

            pattern
            ^(?:(?:https?:\/\/)?([a-zA-Z0-9\-]+\.[a-zA-Z0-9\.\-]+)(\/v1)?)?(?:\/)?([a-zA-Z/-9\.\-_]+)(?:\:([a-zA-Z/-9\.\-_\:]+)|\@([a-zA-Z/-9\.\-_\:]+))$
          • 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.

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

      {object}

      An object containing the runtime environment to set for the service

      • runtimeFiles

        {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
          • 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, gcr-eu, gcr-us, gitlab, github, custom
              • privateImage

                boolean required

                Does the image require authentication

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

            • docker

              {object}

              Details about the Docker overrides for this deployment.

              • cmd

                {object} required

                Details about the CMD override for this deployment.

                • enabled

                  boolean required

                  Whether the CMD override is enabled.

                • value

                  string required

                  The CMD to run instead of the default if CMD override is enabled.

              • entrypoint

                {object} required

                Details about the entrypoint override for this deployment.

                • enabled

                  boolean required

                  Whether the entrypoint override is enabled.

                • value

                  string required

                  The CMD to run instead of the default if entrypoint override is enabled.

            • storage

              {object}

              Details about storage settings for this deployment.

              • ephemeralStorage

                {object}

                Details about ephemeral storage settings for this deployment.

                • storageSize

                  number required

                  Ephemeral storage per container in MB

      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,"cmdOverride":"nginx -g","entrypointOverride":"/custom-entrypoint.sh","storage":{"ephemeralStorage":{"storageSize":1024}},"internal":{"id":"example-build-service","branch":"master","buildSHA":"latest","buildId":"premium-guide-6393"}},"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"}],"runtimeEnvironment":{"VARIABLE_1":"abcdef","VARIABLE_2":"12345"},"runtimeFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}}}' \
        http://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"
          },
          "status": {
            "build": {
              "status": "SUCCESS",
              "lastTransitionTime": "2021-11-29T11:47:16.624Z"
            },
            "deployment": {
              "status": "COMPLETED",
              "reason": "DEPLOYING",
              "lastTransitionTime": "2021-11-29T11:47:16.624Z"
            }
          },
          "serviceType": "deployment",
          "deployment": {
            "region": "europe-west",
            "instances": 1,
            "external": {},
            "internal": {
              "nfObjectId": "5f3bd676b84798d54472d1cc",
              "nfObjectType": "service",
              "repository": "https://github.com/northflank/gatsby-with-northflank",
              "branch": "master",
              "buildSHA": "latest",
              "deployedSHA": "262ed9817b3cad5142fbceabe0c9e371e390d616"
            },
            "docker": {
              "cmd": {
                "enabled": true,
                "value": "nginx -g"
              },
              "entrypoint": {
                "enabled": true,
                "value": "/docker-entrypoint.sh"
              }
            },
            "storage": {
              "ephemeralStorage": {
                "storageSize": 1024
              }
            }
          }
        }
      }

      Example response

      400 Bad Request

      Unable to verify external image

      Example response

      409 Conflict

      There is already a service with the same derived identifier

      © 2022 Northflank Ltd. All rights reserved.