Project / Harnesses /

Get harness

Gets information about the given harness

Required permission

Project > Harnesses > General > Read

Path parameters

projectId
string required
ID of the project
harnessId
string required
ID of the harness

Response body

{object}
Response object.

data
{object} required
Result data.

name
string required
The name of the harness.
min length
3
max length
54
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
A description of the harness.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
tags
[array]
An array of previously defined tags to help identify and group the resource.

string
min length
3
max length
100
pattern
^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$

billing
{object} required

deploymentPlan
string required
The ID of the deployment plan to use.
min length
3
max length
100
pattern
^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$
gpu
{object}

enabled
boolean
Whether GPUs are enabled for this workload.
configuration
{object}

gpuType
string required
The type of GPU to use.
gpuCount
integer
The number of GPUs to allocate.
timesliced
boolean
Whether GPU timeslicing is enabled.

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
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[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

ip
[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

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

sso
{object}
Configure port authentication via SSO

organizationId
string
ID of the SSO organization that the user will have to be a member of
directoryGroupIds
[array]
Array of directory groups that will have access

string

allowAnyOrgUsers
boolean
Allow entire organization to access this service
validateInternalTraffic
boolean
Enforce internal traffic through SSO authentication flow
setCookieOnRootDomain
boolean
Set SSO authentication cookie on root domain
allowInternalTrafficViaPublicDns
boolean
Allow internal traffic from same or shared projects via public DNS to skip SSO authentication flow

headers
[array]
List of header authentication settings, it checks the presence of all headers and compares it against the expected value. Wildcard (*) is supported.

(multiple options: anyOf)

{object}

Matches provided headers as strings.

regexMode
boolean
name
string required
pattern
^[a-zA-Z0-9_\-%$+]+$
value
string required

{object}

Matches provided headers as regex.

regexMode
boolean
name
string required
value
string required

verificationMode
string
Mode used to verify multiple security features like ip policies and SSO authentication
one of
or, and
securePathConfiguration
{object}

enabled
boolean
Enable security policies on a path-level style
skipSecurityPoliciesForInternalTrafficViaPublicDns
boolean
Allow internal traffic from same or shared projects via public DNS to skip all security policies
rules
[array]

{object}

paths
[array] required
Array of path objects which represent the paths and their priority for which the security policies will be enforced

(multiple options: oneOf)
Data about how the path should be handled.

{object}

Route when the path starts with the provided prefix.

path
string required
pattern
^\/([_a-zA-Z0-9-&?=.]*)((\/[_a-zA-Z0-9-&?=.]+)*(\/)?)?$
routingMode
string required
Mode of the path, determining how the URI will be interpreted.
one of
prefix
priority
integer required
min
0
max
100

{object}

Route when the path is an exact match.

path
string required
pattern
^\/([_a-zA-Z0-9-&?=.]*)((\/[_a-zA-Z0-9-&?=.]+)*(\/)?)?$
routingMode
string required
Mode of the path, determining how the URI will be interpreted.
one of
exact
priority
integer required
min
0
max
100

{object}

Route when the path matches the provided regex.

path
string required
routingMode
string required
Mode of the path, determining how the URI will be interpreted.
one of
regex
priority
integer required
min
0
max
100

accessMode
string required
Specify the way the path rule will behave when processing policies. This enables an allow-list/deny-list approach for access control on each path
one of
protected, unprotected
securityPolicies
{object}

orPolicies
{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
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[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

ip
[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

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

sso
{object}
Configure port authentication via SSO

organizationId
string
ID of the SSO organization that the user will have to be a member of
directoryGroupIds
[array]
Array of directory groups that will have access

string

allowAnyOrgUsers
boolean
Allow entire organization to access this service
validateInternalTraffic
boolean
Enforce internal traffic through SSO authentication flow
setCookieOnRootDomain
boolean
Set SSO authentication cookie on root domain
allowInternalTrafficViaPublicDns
boolean
Allow internal traffic from same or shared projects via public DNS to skip SSO authentication flow

headers
[array]
List of header authentication settings, it checks the presence of all headers and compares it against the expected value. Wildcard (*) is supported.

(multiple options: anyOf)

{object}

Matches provided headers as strings.

regexMode
boolean
name
string required
pattern
^[a-zA-Z0-9_\-%$+]+$
value
string required

{object}

Matches provided headers as regex.

regexMode
boolean
name
string required
value
string required

requiredPolicies
{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
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[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

ip
[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

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

sso
{object}
Configure port authentication via SSO

organizationId
string
ID of the SSO organization that the user will have to be a member of
directoryGroupIds
[array]
Array of directory groups that will have access

string

allowAnyOrgUsers
boolean
Allow entire organization to access this service
validateInternalTraffic
boolean
Enforce internal traffic through SSO authentication flow
setCookieOnRootDomain
boolean
Set SSO authentication cookie on root domain
allowInternalTrafficViaPublicDns
boolean
Allow internal traffic from same or shared projects via public DNS to skip SSO authentication flow

headers
[array]
List of header authentication settings, it checks the presence of all headers and compares it against the expected value. Wildcard (*) is supported.

(multiple options: anyOf)

{object}

Matches provided headers as strings.

regexMode
boolean
name
string required
pattern
^[a-zA-Z0-9_\-%$+]+$
value
string required

{object}

Matches provided headers as regex.

regexMode
boolean
name
string required
value
string required

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.
advancedOptions
{object}

enableTlsPassthrough
boolean
Whether this port should use pass through mode for TLS

protocol
(multiple options: oneOf) required
The protocol to use for the port.

string

one of

HTTP, HTTP/2

string

one of

HTTP, HTTP/2, TCP, UDP

source
{object}

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, azure
selfHostedVcsId
string
If projectType is self-hosted, the ID of the self-hosted vcs to use.
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.
vcsLinkId
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 `vcsLinkId` is provided, Northflank will instead use your linked account with that ID.
min length
24
max length
24
projectBranch
string required
The name of the branch to pre-pull for the harness environment.
publicRepo
boolean
Whether the linked repository is public.

repositoryData
{object}

name
string required
Name of the new repository to create.
min length
3
max length
54
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
projectType
string required
The VCS provider to create the repository on.
one of
bitbucket, gitlab, github, self-hosted, azure
vcsLinkId
string required
Linked account ID under which to create the repository.
min length
24
max length
24
accountLogin
string
Linked account login to create the repository under.
selfHostedVcsId
string
If projectType is self-hosted, the ID of the self-hosted vcs to use.
privateRepo
boolean
Whether the new repository should be private.
context
string
Namespace/owner the repository is created under (gitlab/bitbucket).
folder
string
Project/folder the repository is created under (bitbucket).
description
string
Description for the new repository.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$

runtimeEnvironment
{object}
An object containing the runtime environment to set for the harness

runtimeFiles
{object}
Secret files as JSON object, encrypted at rest. File path must be absolute

deployment
{object} required

gpu
{object}

enabled
boolean
Whether GPUs are enabled for this workload.
configuration
{object}

gpuType
string required
The type of GPU to use.
gpuCount
integer
The number of GPUs to allocate.
timesliced
boolean
Whether GPU timeslicing is enabled.

volumes
[array]
Per-replica persistent volumes for a statefulSet service. Each replica receives its own instance of every volume. Only valid when `deployment.type` is `statefulSet`.

{object}

id
string required
Slug identifying this volume within the service.
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
mounts
[array] required
Array of mounts, containerMountPaths must be unique

{object}

volumeMountPath
string
Optionally specify the path inside this volume that should be mounted
pattern
^((?!\.\.).)*$
containerMountPath
string required
Specify the path into which the volume should be mounted
pattern
^((?!:).)*$

spec
{object} required
Per-replica volume storage schema

storage
{object}
Runtime storage settings. Ephemeral storage defaults to 10240 MiB.

ephemeralStorage
{object}

storageSize
integer
Ephemeral storage per container in MB
min
1024

workspaceSize
integer
Size of the persistent workspace volume in MiB. Can only be grown after creation; shrinking is rejected because Kubernetes does not support shrinking persistent volume claims.
min
5120
max
102400

harness
{object} required

type
string required
The harness environment type to run.
one of
claude, codex
authMode
string
How the harness authenticates: `apiKey` (a provider key is stored) or `account` (interactive/account login, no key).
one of
apiKey, account
apiKey
string
Masked API key used by the harness environment. Absent for `account` harnesses.
cloneDirectory
string
Absolute path the repo is cloned into in the harness container.

id
string required
Identifier for the harness
appId
string required
Full identifier used for harness deployment
cluster
{object} required
Cluster information

id
string required
The id of the cluster associated with this project.
name
string required
The name of the cluster associated with this project.
namespace
string
Namespace this resource is located within on the cluster.
loadBalancers
[array]
Load balancer DNS for the cluster.

string

createdAt
string
time of creation
updatedAt
string
time of update
harnessPaused
boolean
Is the harness paused?
status
{object} required
Details about the current harness status.

deployment
{object} required
Details about the current deployment status.

status
string required
The current status of the deployment.
one of
PENDING, IN_PROGRESS, COMPLETED, FAILED
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.

API

CLI

JS Client

GET /v1/projects/{projectId}/harnesses/{harnessId}

GET /v1/teams/{teamId}/projects/{projectId}/harnesses/{harnessId}

Example response

200 OK

Details about the harness.

JSON

{
  "data": {
    "name": "Example Harness",
    "description": "A harness description",
    "billing": {
      "deploymentPlan": "nf-compute-20"
    },
    "ports": [
      {
        "name": "p01",
        "internalPort": 8080,
        "public": true,
        "security": {
          "credentials": [
            {
              "username": "admin",
              "password": "password123",
              "type": "basic-auth"
            }
          ],
          "ip": [
            {
              "addresses": [
                "127.0.0.1"
              ],
              "action": "DENY"
            }
          ],
          "policies": [
            {
              "addresses": [
                "127.0.0.1"
              ],
              "action": "DENY"
            }
          ],
          "headers": [
            {
              "regexMode": false,
              "name": "headerName",
              "value": "headerValue"
            }
          ],
          "securePathConfiguration": {
            "rules": [
              {
                "paths": [
                  {
                    "routingMode": "prefix",
                    "priority": 80
                  }
                ],
                "accessMode": "protected",
                "securityPolicies": {
                  "orPolicies": {
                    "credentials": [
                      {
                        "username": "admin",
                        "password": "password123",
                        "type": "basic-auth"
                      }
                    ],
                    "ip": [
                      {
                        "addresses": [
                          "127.0.0.1"
                        ],
                        "action": "DENY"
                      }
                    ],
                    "policies": [
                      {
                        "addresses": [
                          "127.0.0.1"
                        ],
                        "action": "DENY"
                      }
                    ],
                    "headers": [
                      {
                        "regexMode": false,
                        "name": "headerName",
                        "value": "headerValue"
                      }
                    ]
                  },
                  "requiredPolicies": {
                    "credentials": [
                      {
                        "username": "admin",
                        "password": "password123",
                        "type": "basic-auth"
                      }
                    ],
                    "ip": [
                      {
                        "addresses": [
                          "127.0.0.1"
                        ],
                        "action": "DENY"
                      }
                    ],
                    "policies": [
                      {
                        "addresses": [
                          "127.0.0.1"
                        ],
                        "action": "DENY"
                      }
                    ],
                    "headers": [
                      {
                        "regexMode": false,
                        "name": "headerName",
                        "value": "headerValue"
                      }
                    ]
                  }
                }
              }
            ]
          }
        },
        "domains": [
          "app.example.com"
        ]
      }
    ],
    "source": {
      "projectUrl": "https://github.com/northflank/gatsby-with-northflank",
      "projectType": "github",
      "accountLogin": "github-user",
      "projectBranch": "master"
    },
    "repositoryData": {
      "name": "my-harness-repo"
    },
    "runtimeEnvironment": {
      "VARIABLE_1": "abcdef",
      "VARIABLE_2": "12345"
    },
    "runtimeFiles": {
      "/dir/fileName": {
        "data": "VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=",
        "encoding": "utf-8"
      }
    },
    "deployment": {
      "volumes": [
        {
          "id": "data",
          "mounts": [
            {
              "volumeMountPath": "",
              "containerMountPath": "/container"
            }
          ],
          "spec": {
            "storageClassName": "ssd",
            "storageSize": 6144
          }
        }
      ],
      "storage": {
        "ephemeralStorage": {
          "storageSize": 1024
        }
      },
      "workspaceSize": 10240
    },
    "harness": {
      "type": "claude",
      "authMode": "apiKey",
      "apiKey": "sk-...abcd"
    },
    "id": "example-harness",
    "appId": "/example-user/default-project/example-harness",
    "cluster": {
      "id": "nf-europe-west",
      "name": "nf-europe-west",
      "namespace": "ns-8zy2mcjh9zn2",
      "loadBalancers": [
        "lb.659200800000000000000000.northflank.com"
      ]
    },
    "status": {
      "deployment": {
        "status": "COMPLETED",
        "reason": "DEPLOYING",
        "lastTransitionTime": "2021-11-29T11:47:16.624Z"
      }
    }
  }
}