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

3. Workload identity (optional): Select a workload identity to automatically inject cloud credentials into services and jobs using this addon

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

When you select a workload identity, it is automatically injected into services and jobs that use this addon via a secret group, allowing them to access cloud resources without separate configuration. The workload identity must use the same cloud provider as the addon.

Configuration mode

Choose between Managed and Advanced configuration:

• Managed: Configure only recommended settings
• Advanced: Access all configuration options from the OpenTofu provider

For Advanced mode:

Enter the JSON configuration for your resource. Configuration fields match the OpenTofu provider for your cloud platform (e.g., AWS provider).

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.