Create a managed external addon

Managed external addons are preconfigured OpenTofu resources that simplify setup of common cloud resources like S3 buckets or RDS instances. They expose a subset of configuration fields for easier management while providing the same infrastructure-as-code benefits.

Unlike regular addons which run on Northflank infrastructure, external addons are hosted in your cloud account.

Managed external addons:

• Are created using OpenTofu (infrastructure as code)
• Run in your cloud provider account (currently AWS only)
• Can be linked to services via secret groups
• Support common resources like S3 buckets and RDS databases

Anything you can create with a managed external addon can also be created using custom OpenTofu resources for more control.

Managed external addon types currently include:

• Amazon S3 Bucket
• Amazon RDS

From the Addons page

1. Navigate to your project
2. Click Addons → External addons tab
3. Click Create new addon
4. Select External addon from the sidebar

Basic information

1. External addon type: Select the resource type (e.g., Amazon S3 Bucket, Amazon RDS)
2. External addon name: Provide a name for the resource
3. Description: (Optional) Describe the purpose of this resource
4. Tags: (Optional) Add tags for organization

Integration

1. Integration: Select your cloud provider integration (currently AWS only)
2. Region: Choose the cloud region where the resource will be created

This determines where the external addon will be provisioned in your cloud account.

Create the addon

Click Create external addon to provision the resource in your cloud account using OpenTofu.

Once created, external addons work like regular addons. You can:

• Link outputs to secret groups
• Reference them in services for connection details
• Manage them through the Northflank interface

For example, an S3 bucket external addon can expose bucket name and region to a secret group, which your service can then consume.

External addons can be created using the External Addon template node. This allows you to define external resources alongside other infrastructure.

Example: S3 bucket with secret group

This example creates an S3 bucket and links its outputs to a secret group:

{
  "kind": "ExternalAddon",
  "ref": "my-s3-bucket",
  "condition": "success",
  "spec": {
    "name": "my-app-bucket",
    "description": "S3 bucket for application storage",
    "tags": [],
    "spec": {
      "config": {
        "aws_s3_bucket": {
          "nf": {
            "bucket": "my-app-bucket-name"
          }
        },
        "aws_s3_bucket_acl": {
          "nf": {
            "depends_on": [
              "aws_s3_bucket.nf",
              "aws_s3_bucket_ownership_controls.nf"
            ],
            "bucket": "${'\\${aws_s3_bucket.nf.id}'}",
            "acl": "private"
          }
        },
        "aws_s3_bucket_versioning": {
          "nf": {
            "depends_on": ["aws_s3_bucket.nf"],
            "bucket": "${'\\${aws_s3_bucket.nf.id}'}",
            "versioning_configuration": {
              "status": "Disabled"
            }
          }
        },
        "aws_s3_bucket_ownership_controls": {
          "nf": {
            "depends_on": ["aws_s3_bucket.nf"],
            "bucket": "${'\\${aws_s3_bucket.nf.id}'}",
            "rule": {
              "object_ownership": "ObjectWriter"
            }
          }
        },
        "envs": {
          "data": {
            "bucket_name": {},
            "bucket_arn": {},
            "bucket_domain_name": {},
            "bucket_regional_domain_name": {},
            "region": {}
          }
        },
        "secrets": {
          "data": {}
        }
      },
      "provider": {
        "aws": {
          "integrationId": "your-integration-id",
          "region": "us-east-1"
        }
      },
      "resourceType": "s3"
    }
  }
}

Link outputs to a secret group:

{
  "kind": "SecretGroup",
  "ref": "s3-config",
  "spec": {
    "name": "s3-bucket-config",
    "type": "secret",
    "secretType": "environment-arguments",
    "priority": 10,
    "secrets": {
      "variables": {},
      "files": {},
      "dockerSecretMounts": {}
    },
    "addonDependencies": [],
    "externalAddonDependencies": [
      {
        "addonId": "${refs.my-s3-bucket.id}",
        "keys": [
          {"keyName": "bucket_name"},
          {"keyName": "bucket_arn"},
          {"keyName": "bucket_domain_name"},
          {"keyName": "bucket_regional_domain_name"},
          {"keyName": "region"}
        ]
      }
    ]
  }
}

The secret group automatically receives the S3 bucket details as environment variables, which can then be referenced by your services.