Addons /

Create addon

Creates a new addon

Required permission

Project > Addons > General > Create

Path parameters

projectId
string required
ID of the project

Request body

(multiple options: anyOf)
The provisioner type of the addon

{object}

Native Northflank addons

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

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

type
string required
The identifier for the type of addon. Addon types can be found at the Get Addon Types endpoint.
version
string required
The version of the addon type to use. If set to `latest`, the addon will be created with the most recent addon version. If set to a major version appended with `-latest`, e.g. `14-latest`, the addon will be created with the most recent minor version belonging to that major version.
billing
{object} required

deploymentPlan
string required
The ID of the deployment plan to use.
pattern
^[A-Za-z0-9-]+$
storageClass
string
The type of storage. Only configurable if the relevant feature flag is enabled for you account
one of
ssd, hdd
storage
integer required
The size of the addon storage, in megabytes.
min
4096
replicas
integer required
The number of addon replicas to run.
min
1
zonalRedundancy
{object}

type
string
Defines scheduling behaviour across different zones within the same region.
one of
required, disabled
minZones
integer
Defines how many zones are required and will prevent containers from additional scheduling into existing zones. (Only relevant if type is set to "required")
min
1

source
{object}
Optional object containing data about an existing addon to fork. If provided, the addon will be created from that existing addon backup.

addonId
string required
ID of the addon to fork.
pattern
^[A-Za-z0-9-]+$
backupId
string required
ID of a backup belonging to that addon to use for the fork.
pattern
^[A-Za-z0-9-]+$

tlsEnabled
boolean
Enables access to the addon via TLS (if supported by the addon type).
externalAccessEnabled
boolean
Enables external access to the addon via TLS (if supported by the addon type).
ipPolicies
[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

pitrEnabled
boolean
Enables point-in-time recovery (PITR) for the addon (if supported by the addon type).
typeSpecificSettings
{object}

redisMaxMemoryPolicy
string
Redis only: Key eviction policy at memory pressure.
one of
noeviction, allkeys-lru, allkeys-lfu, volatile-lru, volatile-lfu, allkeys-random, volatile-random, volatile-ttl
redisSentinelEnabled
boolean
Redis only: Deploy Redis with Sentinel high availability. Default: false
postgresqlWalLevel
string
PostgreSQL only: Configure wal_level setting.
one of
replica, logical
postgresqlConnectionPoolerEnabled
boolean
PostgreSQL only: Run connection pooler in front of postgres instance.
postgresqlConnectionPoolerReplicas
integer
PostgreSQL only: Number of connection pooler instances in case connection pooler is enabled.
min
1
max
3
postgresqlReadConnectionPoolerEnabled
boolean
PostgreSQL only: Run connection pooler in front of read-only postgres instance.
postgresqlReadConnectionPoolerReplicas
integer
PostgreSQL only: Number of read-only connection pooler instances in case read-only connection pooler is enabled.
min
1
max
3

customCredentials
{object}

dbName
string
Custom database name. Not supported for all addon types.

backupSchedules
[array]

{object}

scheduling
{object} required
Schedule for the backup.

interval
string required
The interval between backups. Each addon can only have one backup schedule of each interval for each backup type.
one of
hourly, daily, weekly
minute
[array] required
An array of minutes when the backup should be performed.

integer
A minute when the backup should be performed.
min
0
max
59

hour
[array]
An array of hours in 24 hour format when the backup should be performed. At these hours, a backup will be performed at each of the minutes provided in the `minute` field. Required for `daily` and `weekly` intervals and unavailable for `hourly` intervals.

integer
An hour when the backup should be performed, in 24 hour format.
min
0
max
23

day
[array]
An array of days of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday. On these days, a backup will be performed at each of the minutes provided in the `minute` field whenever it is an hour from the `hour` field. Required for `weekly` intervals and unavailable for `hourly` and `daily` intervals.

integer
A day of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday.
min
0
max
6

backupType
string required
The type of the backup to be performed.
one of
dump, snapshot
additionalDestinations
[array]
List of destinations for which a backup should be created of this backup. Only applicable for snapshot backups.

{object}

destinationId
string required
min length
3
max length
100
pattern
^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$
retentionTime
integer
The time the backup is retained for, in days. `hourly` backups have a maximum retention of 7 days, `daily` backups have a maximum retention of 60 days and `weekly` backups have a maximum retention of 120 days.
min
1
max
120
type
string required
one of
custom

compressionType
string
The compression algorithm of the backup. Only applicable for dump backups. Defaults to `gz`.
one of
gz, zstd
retentionTime
integer required
The time the backup is retained for, in days. `hourly` backups have a maximum retention of 7 days, `daily` backups have a maximum retention of 60 days and `weekly` backups have a maximum retention of 120 days.
min
1
max
120

metadata
{object}
Allow setting custom labels and annotations for workloads.

labels
{object}
Specify custom labels for the workload.

annotations
{object}
Specify custom annotations for the workload as string or object.

{object}

Northflank bring your own addon with templating engine

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

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

type
string required
The identifier for the type of addon. Addon types can be found at the Get Addon Types endpoint.
templateValues
{object}
The template values to be passed to the templating engine.

Response body

{object}
Response object.

data
(multiple options: oneOf) required
Result data.

{object}

Native Northflank addons

name
string required
The name of the addon.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
A description of the addon.
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
1
max length
100
pattern
^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$

type
string required
The identifier for the type of addon. Addon types can be found at the Get Addon Types endpoint.
version
string required
The version of the addon type to use. If set to `latest`, the addon will be created with the most recent addon version. If set to a major version appended with `-latest`, e.g. `14-latest`, the addon will be created with the most recent minor version belonging to that major version.
billing
{object} required

deploymentPlan
string required
The ID of the deployment plan to use.
pattern
^[A-Za-z0-9-]+$
storageClass
string
The type of storage. Only configurable if the relevant feature flag is enabled for you account
one of
ssd, hdd
storage
integer required
The size of the addon storage, in megabytes.
min
4096
replicas
integer required
The number of addon replicas to run.
min
1
zonalRedundancy
{object}

type
string
Defines scheduling behaviour across different zones within the same region.
one of
required, disabled
minZones
integer
Defines how many zones are required and will prevent containers from additional scheduling into existing zones. (Only relevant if type is set to "required")
min
1

source
{object}
Optional object containing data about an existing addon to fork. If provided, the addon will be created from that existing addon backup.

addonId
string required
ID of the addon to fork.
pattern
^[A-Za-z0-9-]+$
backupId
string required
ID of a backup belonging to that addon to use for the fork.
pattern
^[A-Za-z0-9-]+$

tlsEnabled
boolean
Enables access to the addon via TLS (if supported by the addon type).
externalAccessEnabled
boolean
Enables external access to the addon via TLS (if supported by the addon type).
ipPolicies
[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

pitrEnabled
boolean
Enables point-in-time recovery (PITR) for the addon (if supported by the addon type).
typeSpecificSettings
{object}

redisMaxMemoryPolicy
string
Redis only: Key eviction policy at memory pressure.
one of
noeviction, allkeys-lru, allkeys-lfu, volatile-lru, volatile-lfu, allkeys-random, volatile-random, volatile-ttl
redisSentinelEnabled
boolean
Redis only: Deploy Redis with Sentinel high availability. Default: false
postgresqlWalLevel
string
PostgreSQL only: Configure wal_level setting.
one of
replica, logical
postgresqlConnectionPoolerEnabled
boolean
PostgreSQL only: Run connection pooler in front of postgres instance.
postgresqlConnectionPoolerReplicas
integer
PostgreSQL only: Number of connection pooler instances in case connection pooler is enabled.
min
1
max
3
postgresqlReadConnectionPoolerEnabled
boolean
PostgreSQL only: Run connection pooler in front of read-only postgres instance.
postgresqlReadConnectionPoolerReplicas
integer
PostgreSQL only: Number of read-only connection pooler instances in case read-only connection pooler is enabled.
min
1
max
3

customCredentials
{object}

dbName
string
Custom database name. Not supported for all addon types.

backupSchedules
[array]

{object}

scheduling
{object} required
Schedule for the backup.

interval
string required
The interval between backups. Each addon can only have one backup schedule of each interval for each backup type.
one of
hourly, daily, weekly
minute
[array] required
An array of minutes when the backup should be performed.

integer
A minute when the backup should be performed.
min
0
max
59

hour
[array]
An array of hours in 24 hour format when the backup should be performed. At these hours, a backup will be performed at each of the minutes provided in the `minute` field. Required for `daily` and `weekly` intervals and unavailable for `hourly` intervals.

integer
An hour when the backup should be performed, in 24 hour format.
min
0
max
23

day
[array]
An array of days of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday. On these days, a backup will be performed at each of the minutes provided in the `minute` field whenever it is an hour from the `hour` field. Required for `weekly` intervals and unavailable for `hourly` and `daily` intervals.

integer
A day of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday.
min
0
max
6

backupType
string required
The type of the backup to be performed.
one of
dump, snapshot
additionalDestinations
[array]
List of destinations for which a backup should be created of this backup. Only applicable for snapshot backups.

{object}

destinationId
string required
retentionTime
integer
The time the backup is retained for, in days. `hourly` backups have a maximum retention of 7 days, `daily` backups have a maximum retention of 60 days and `weekly` backups have a maximum retention of 120 days.
min
1
max
120
type
string required
one of
custom

compressionType
string
The compression algorithm of the backup. Only applicable for dump backups. Defaults to `gz`.
one of
gz, zstd
retentionTime
integer required
The time the backup is retained for, in days. `hourly` backups have a maximum retention of 7 days, `daily` backups have a maximum retention of 60 days and `weekly` backups have a maximum retention of 120 days.
min
1
max
120

metadata
{object}
Allow setting custom labels and annotations for workloads.

labels
{object}
Specify custom labels for the workload.

annotations
{object}
Specify custom annotations for the workload as string or object.

id
string required
Identifier for the addon.
appId
string required
Full identifier used for deployment
status
string required
The current state of the addon.
one of
preDeployment, triggerAllocation, allocating, postDeployment, running, paused, scaling, upgrading, resetting, backup, restore, failed, error, errorAllocating, deleting, deleted
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

{object}

Northflank bring your own addon with templating engine

name
string required
The name of the addon.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
A description of the addon.
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
1
max length
100
pattern
^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$

type
string required
The identifier for the type of addon. Addon types can be found at the Get Addon Types endpoint.
templateValues
{object}
The template values to be passed to the templating engine.

id
string required
Identifier for the addon.
appId
string required
Full identifier used for deployment
status
string required
The current state of the addon.
one of
preDeployment, triggerAllocation, allocating, postDeployment, running, paused, scaling, upgrading, resetting, backup, restore, failed, error, errorAllocating, deleting, deleted
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

API

CLI

JS Client

POST /v1/projects/{projectId}/addons

Example request

Request body

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Addon","description":"An addon description","projectId":"example-project","tags":["my-tag"],"type":"postgresql","version":"latest","billing":{"deploymentPlan":"nf-compute-20","storageClass":"ssd","storage":4096,"replicas":1},"source":{"addonId":"existing-addon","backupId":"existing-backup"},"ipPolicies":[{"addresses":["127.0.0.1"],"action":"DENY"}],"backupSchedules":[{"scheduling":{"interval":"weekly","minute":[30],"hour":[18],"day":[4]},"backupType":"snapshot","additionalDestinations":[{"retentionTime":7}],"compressionType":"gz","retentionTime":7}]}' \
  https://api.northflank.com/v1/projects/{projectId}/addons

Example response

200 OK

Details about the newly created addon.

JSON

{
  "data": {
    "name": "Example Addon",
    "description": "An addon description",
    "tags": [
      "my-tag"
    ],
    "type": "postgresql",
    "version": "latest",
    "billing": {
      "deploymentPlan": "nf-compute-20",
      "storageClass": "ssd",
      "storage": 4096,
      "replicas": 1
    },
    "source": {
      "addonId": "existing-addon",
      "backupId": "existing-backup"
    },
    "ipPolicies": [
      {
        "addresses": [
          "127.0.0.1"
        ],
        "action": "DENY"
      }
    ],
    "backupSchedules": [
      {
        "scheduling": {
          "interval": "weekly",
          "minute": [
            30
          ],
          "hour": [
            18
          ],
          "day": [
            4
          ]
        },
        "backupType": "snapshot",
        "additionalDestinations": [
          {
            "retentionTime": 7
          }
        ],
        "compressionType": "gz",
        "retentionTime": 7
      }
    ],
    "id": "example-addon",
    "appId": "/example-user/default-project/example-addon",
    "status": "running",
    "cluster": {
      "id": "nf-europe-west",
      "name": "nf-europe-west",
      "namespace": "ns-8zy2mcjh9zn2",
      "loadBalancers": [
        "lb.659200800000000000000000.northflank.com"
      ]
    }
  }
}

JSON

{
  "data": {
    "name": "Example Addon",
    "description": "An addon description",
    "tags": [
      "my-tag"
    ],
    "type": "postgresql",
    "templateValues": "{\"replicas\": 2}",
    "id": "example-addon",
    "appId": "/example-user/default-project/example-addon",
    "status": "running",
    "cluster": {
      "id": "nf-europe-west",
      "name": "nf-europe-west",
      "namespace": "ns-8zy2mcjh9zn2",
      "loadBalancers": [
        "lb.659200800000000000000000.northflank.com"
      ]
    }
  }
}