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

## Available types

Managed external addon types currently include:

- Amazon S3 Bucket

- Amazon RDS

## Create an external addon

### 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](https://search.opentofu.org/provider/opentofu/aws/latest)).

### Create the addon

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

## Using external addons

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.

## Create from templates

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:

```json
{
  "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:**

```json
{
  "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.

## Next steps

- [Bring your own cloud to Northflank: Use all the features of the Northflank platform on other cloud hosting providers, with control over your own infrastructure.](/v1/application/bring-your-own-cloud/use-other-cloud-providers-with-northflank)
- [Use Tailscale: Allow secure access to Tailscale devices to resources within your project.](/v1/application/network/use-tailscale)
- [Use path-based routing: Route incoming traffic to different services and ports for paths on a subdomain.](/v1/application/domains/use-path-based-routing)
- [Audit logs: Monitor and review events affecting your organisation, teams, projects, and resources.](/v1/application/observe/audit-logs)