v1
Double column
API
CLI
JS Client

Jobs /

Create cron job

Creates a new cron job

Required permission

Project > Jobs > General > Create

Path parameters

    • projectId

      string required

      ID of the project

Request body

  • {object}
    • name

      string required

      The name of the job.

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

      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-]+$
    • backoffLimit

      integer required

      The number of attempts to rerun a job before it is marked as failed.

    • runOnSourceChange

      string

      Configure when the job should be run if the source image changes.

      one of
      never, cd-promote, always
    • activeDeadlineSeconds

      integer

      The maximum amount of time, in seconds, for a job to run before it is marked as failed.

      min
      1
    • deployment

      (multiple options)

      Where to deploy the job from.

      • {object}

        Deploy from version control

        • cmdOverride

          string

          If set, the job runs a custom command rather than one defined in the Dockerfile.

        • entrypointOverride

          string

          If set, the job 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
        • vcs

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

        OR

      • {object}

        Deploy from an external image

        • cmdOverride

          string

          If set, the job runs a custom command rather than one defined in the Dockerfile.

        • entrypointOverride

          string

          If set, the job 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}

        Deploy from a Northflank build service

        • cmdOverride

          string

          If set, the job runs a custom command rather than one defined in the Dockerfile.

        • entrypointOverride

          string

          If set, the job 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}

        Choose later

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

      • buildSettings

        (multiple options)
        • {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-._]*$
      • runtimeEnvironment

        {object}

        An object containing the runtime environment to set for the job. 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 job. 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

              • schedule

                string required

                The cron timer scheduling when to run the job.

                pattern
                (@(annually|yearly|monthly|weekly|daily|hourly))|((((\d+,)+\d+|(\d+(\/|-)\d+)|\d+|\*) ?){5})
              • concurrencyPolicy

                string required

                Whether this job should run when another instance of the job is already running. allow will enable multiple instances of this job to run. forbid will keep the current instance of the job running and stop a new instance from being run. replace will terminate any currently running instance of the job and start a new one.

                one of
                allow, forbid, replace

            Response body

            • {object}

              Response object.

              • data

                {object} required

                Result data.

                • id

                  string required

                  Identifier for the job

                • appId

                  string required

                  Full identifier used for job deployment

                • name

                  string required

                  Job name

                • description

                  string

                  A short description of the job

                • projectId

                  string required

                  ID of the project that the job belongs to

                • createdAt

                  date required

                  The time the job was created.

                • 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

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

                • buildEngineConfiguration

                  {object}
                  • 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?

                • disabledCI

                  boolean required

                  Whether Continuous Integration is disabled

                • disabledCD

                  boolean required

                  Whether Continuous Deployment is disabled

                • deployment

                  {object}
                  • region

                    string

                    Region where this job is deployed and built

                  • 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

                • billing

                  {object} required
                  • deploymentPlan

                    string required

                    ID of the billing plan used by this job

                • settings

                  {object} required

                  Job settings

                  • cron

                    {object}

                    Cron job specific settings

                    • schedule

                      string

                      The cron timer scheduling when to run the job.

                    • concurrencyPolicy

                      string

                      Whether this job should run when another instance of the job is already running.

                      one of
                      Allow, Forbid, Replace
                  • backoffLimit

                    integer required

                    The number of attempts to rerun a job before it is marked as failed.

                  • activeDeadlineSeconds

                    integer required

                    The maximum amount of time, in seconds, for a job to run before it is marked as failed.

                    min
                    1
                • jobType

                  string required

                  Type of the job (manual or cron)

                  one of
                  manual, cron
                • buildInitiated

                  boolean required

                  Whether the job will be built immediately

            API
            CLI
            JS Client

            POST /v1/projects/{projectId}/jobs/cron

            Example request

            Request body
            curl
            curl --header "Content-Type: application/json" \
              --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
              --request POST \
              --data '{"name":"Example Job","description":"A job description","billing":{"deploymentPlan":"nf-compute-20"},"backoffLimit":0,"runOnSourceChange":"never","activeDeadlineSeconds":600,"deployment":{"cmdOverride":"nginx -g","entrypointOverride":"/custom-entrypoint.sh","storage":{"ephemeralStorage":{"storageSize":1024}},"vcs":{"projectUrl":"https://github.com/northflank/gatsby-with-northflank","projectType":"github","accountLogin":"github-user","projectBranch":"master"}},"buildConfiguration":{"pathIgnoreRules":["README.md"]},"buildSettings":{"dockerfile":{"buildEngine":"kaniko","useCache":false,"dockerFilePath":"/Dockerfile","dockerWorkDir":"/"}},"runtimeEnvironment":{"variable1":"abcdef","variable2":"12345"},"runtimeFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"buildArguments":{"variable1":"abcdef","variable2":"12345"},"buildFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"schedule":"30 8 * * *","concurrencyPolicy":"forbid"}' \
              http://api.northflank.com/v1/projects/{projectId}/jobs/cron

            Example response

            200 OK

            Details about the newly created job.

            JSON

            {
              "data": {
                "id": "example-job",
                "appId": "/example-user/default-project/example-job",
                "name": "Example Job",
                "description": "This is the job description",
                "projectId": "default-project",
                "createdAt": "2021-01-20T11:19:53.175Z",
                "vcsData": {
                  "projectUrl": "https://github.com/northflank/gatsby-with-northflank",
                  "projectType": "github",
                  "selfHostedVcsId": "example-team/self-hosted-vcs",
                  "projectBranch": "master",
                  "publicRepo": false,
                  "dockerWorkDir": "/",
                  "dockerFilePath": "/Dockerfile"
                },
                "buildConfiguration": {
                  "pathIgnoreRules": [
                    "README.md"
                  ]
                },
                "buildEngineConfiguration": {
                  "buildEngine": "buildpack",
                  "buildpack": {
                    "builder": "HEROKU_20",
                    "buildpackLocators": [
                      "https://buildpack-registry.heroku.com/cnb/mars/create-react-app"
                    ]
                  },
                  "kaniko": {}
                },
                "disabledCI": false,
                "disabledCD": false,
                "deployment": {
                  "region": "europe-west",
                  "docker": {
                    "cmd": {
                      "enabled": true,
                      "value": "nginx -g"
                    },
                    "entrypoint": {
                      "enabled": true,
                      "value": "/docker-entrypoint.sh"
                    }
                  },
                  "storage": {
                    "ephemeralStorage": {
                      "storageSize": 1024
                    }
                  }
                },
                "billing": {
                  "deploymentPlan": "nf-compute-20"
                },
                "settings": {
                  "cron": {
                    "schedule": "30 8 * * *",
                    "concurrencyPolicy": "Allow"
                  },
                  "backoffLimit": 0,
                  "activeDeadlineSeconds": 600
                },
                "jobType": "cron",
                "buildInitiated": true
              }
            }

            © 2022 Northflank Ltd. All rights reserved.