fused-infra

name	fused-infra
description	Reference for the infrastructure managed by fused — what resources exist, why each one is needed, and when they are created, updated, or deleted. Covers the AWS backend (IAM, Lambda, ECR, S3) and the local backend (data directories + venvs, see "Local backend infra"). Use when helping users understand, provision, or troubleshoot the resources that back an fused environment.

fused AWS infrastructure

Part of the Fused skill set. This covers the AWS resources only. For install and provisioning see fused-setup; see fused-guide for the full set.

fused manages a small, fixed set of AWS resources per environment. All resources are scoped to the environment's function_prefix (default openfused-). Nothing outside that scope is touched.

---

Resources managed

IAM role

Name: <prefix> with trailing - stripped (e.g. openfused- → fused), or overridden with --role-name / role_name in the env config.

Why: Every Lambda function must assume an IAM role to run. fused creates and owns this role so users don't have to wire one up manually.

What's in the inline policy (openfused-default):

Statement	Permissions	Scope
S3Access	GetObject, PutObject, DeleteObject, ListBucket	All S3 (arn:aws:s3:::*)
LambdaSelfInvoke	lambda:InvokeFunction	arn:aws:lambda:<region>:<account>:function:<prefix>*
SecretsRead	secretsmanager:GetSecretValue	arn:aws:secretsmanager:<region>:<account>:secret:<prefix>*
CloudWatchLogs	CreateLogGroup, CreateLogStream, PutLogEvents	All (arn:aws:logs:*:*:*)
ECRPull (only when docker_image is set)	ecr:GetAuthorizationToken, ecr:BatchGetImage, ecr:GetDownloadUrlForLayer	All (*)

The policy is re-applied on every infra apply, so it self-heals if manually changed.

When managed: created on first infra apply (or env create without --no-provision). Updated any time the policy diverges from the desired state (e.g. adding docker_image to an env adds the ECR statement).

---

Lambda function

Naming: one function per environment, <prefix>container. Example: openfused-container.

Why: Lambda execution is container-based — the env's docker_image (an ECR image URI, built with fused infra build-image) is the function's code. Packages are baked into the image (env update -p <pkg> + infra build-image); fused never pip-installs packages at invocation time.

Runtime: the env's docker_image ECR URI (PackageType: Image).

Configuration applied on infra apply:

• Code: the image URI from docker_image
• Timeout: value from lambda_timeout in the env config (default 300 s)
• MemorySize: value from lambda_memory_mb (default 1024 MB)
• EphemeralStorage: value from lambda_tmp_storage_mb (when not the 512 MB default)
• Architectures: value from lambda_architecture — changing it is a REPLACE (delete + recreate), since architecture cannot be updated on an Image-type function
• TenancyConfig: {"TenantIsolationMode": "PER_TENANT"} — every compute function fused invokes is created with AWS Lambda tenant isolation mode, so each invocation runs in an execution environment dedicated to its tenant id (the caller identity, or a shared placeholder).

infra plan compares the live function's image URI, memory size, ephemeral storage, architecture, and tags against the desired state and reports drift (a leftover zip-packaged function from an old install is reported as REPLACE). infra apply reconciles them. Tenant isolation is not drift-checked: AWS only allows it to be set at function creation.

What's NOT managed: Lambda functions outside <prefix>* are never touched. The deployed serve Lambda (behind API Gateway) is intentionally not tenant-isolated — API Gateway can't attach a tenant id on invoke; isolation happens on its call into the compute function instead.

---

ECR repository

Name: extracted from the docker_image URI (registry host stripped, tag stripped) — e.g. 123.dkr.ecr.us-east-1.amazonaws.com/myapp:latest → myapp — or, before a first image exists, image_build.repo (default: the prefix minus the trailing dash).

Why: the Lambda function's container image must live in ECR in the same account. fused ensures the repo exists before docker push.

When managed: infra apply creates the repository if missing. infra build-image also creates it during the build workflow.

Teardown: deleted (with force=True, removing all images) when infra teardown is run and a docker_image is configured.

Serve repo: infra serve creates a separate ECR repository, <prefix.rstrip('-')>-serve, holding the dispatcher image (content-tagged). It is created on first infra serve and removed by infra teardown.

---

S3 cache bucket (optional — only when cache_bucket is set)

Name: auto-derived as <prefix without trailing dash>-cache (e.g. openfused-cache), or set explicitly with --cache-bucket / --no-cache-bucket.

Why: execute_code supports an input_files parameter that uploads local files into the Lambda execution context. Those files are staged in this bucket as a temporary zip, then downloaded and extracted inside Lambda before user code runs.

When managed: infra apply creates the bucket if it does not exist. S3 bucket creation is region-aware (us-east-1 does not accept a LocationConstraint).

Lifecycle rules: infra apply also reconciles three openfused-managed expiry rules on the bucket (and infra plan reports them as drift when absent):

Rule ID	Prefix	Expiration	Purpose
openfused-expire-spill	spill/	1 day	One-shot large-result spills (caching off) — read once, then garbage
openfused-expire-context	context/	1 day	Staged input_files zips
openfused-gc-results	results/	30 days	Storage GC backstop for cache entries — not the freshness mechanism (that's cache_max_age at read time), so keep TTLs under 30d

Rules are merged idempotently: any customer-defined rule (one whose ID does not start with openfused-) is preserved. Requires s3:GetLifecycleConfiguration and s3:PutLifecycleConfiguration.

Teardown: all objects are deleted first, then the bucket itself is deleted when infra teardown runs.

What's NOT managed: user data buckets (the ones you pass to files list, files get, etc.) are never created or deleted by fused infra.

---

Lifecycle

When invoked as MCP tools (infra_plan, infra_apply, env_create, infra_build_image, infra_lambda_reset, infra_teardown), these long-running operations stream live progress notifications to the client as each resource change, build step, or deletion happens. Progress reporting is best-effort: a disconnected client never aborts the operation.

On env create (AWS, default)

1. Config is written to ~/.openfused/envs.json.
2. infra apply runs automatically — provisions the IAM role, the S3 bucket (if cache_bucket set), and — when docker_image or image_build is configured — the ECR repo, the container image (built and pushed during apply if missing from ECR), and the <prefix>container Lambda function.

Pass --no-provision to skip step 2 (useful when the role already exists or you want to review the plan first).

On first execute_code call

If infra apply has not already created it, the <prefix>container function is created lazily on the first call from the env's docker_image and waited on until Active (~15–30 s). With no image configured, the call fails with guidance to run fused infra build-image first. Subsequent calls reuse the function.

infra plan

Dry run. Compares current AWS state against desired state and prints a diff. Exits 0 if nothing to change, 1 if there is drift. Useful in CI.

infra apply

Reconciles all managed resources to the desired state. Safe to run repeatedly — idempotent.

infra teardown

Deletes Lambda functions (all matching <prefix>*), the IAM role and its inline policy, the CodeBuild project and its service role (if the env uses the codebuild builder), the ECR repository (if docker_image set), and the cache bucket (if set). Prompts for confirmation unless --yes is passed.

Does NOT delete: user S3 buckets, Secrets Manager secrets.

infra build-image

Builds a Docker image and pushes it to ECR, then writes the resulting digest URI back into the resolved env's docker_image field. The next infra apply will update the <prefix>container Lambda function to use it.

By default the build runs remotely in AWS CodeBuild — no Docker daemon needed on the host. Pass --builder local (or set the env's builder to local) to fall back to a host docker build instead. CodeBuild builds in your own account, requires a cache bucket (the build source is uploaded there under codebuild-source/), and pushes via a service role whose ECR push is scoped to just this env's repo (the broad Lambda-execution ECR-pull grant stays *). The CodeBuild project (<prefix>build) + role are provisioned on demand and also appear in infra plan/infra apply and are removed by infra teardown. It accepts a user Dockerfile via --context-dir/--dockerfile. With no cache bucket (a deliberate --no-cache-bucket), the CodeBuild build fails fast with guidance to set one or pass --builder local. Limitation: concurrent same-tag builds aren't supported (digest resolved by mutable tag). The managed Fused-hosted build server (per-tenant ECR + immutable tags) is designed but not yet implemented.

---

When to run infra apply

Situation	Action needed
New environment	env create does it automatically
Changed lambda_timeout in env config	infra apply
Changed docker_image (e.g. after build-image)	infra apply
fused handler code updated (new release)	infra build-image (the handler files are baked into the image), then infra apply
IAM policy manually modified in AWS console	infra apply — self-heals
docker_image added to an existing env	infra apply — adds ECR pull permission to IAM role

---

Permissions required to run infra commands

The AWS credentials used to run infra apply / teardown must have:

• iam:CreateRole, iam:GetRole, iam:PutRolePolicy, iam:DeleteRole, iam:DeleteRolePolicy, iam:GetRolePolicy
• lambda:CreateFunction, lambda:GetFunction, lambda:ListFunctions, lambda:UpdateFunctionCode, lambda:UpdateFunctionConfiguration, lambda:DeleteFunction, lambda:TagResource
• ecr:DescribeRepositories, ecr:CreateRepository, ecr:DeleteRepository
• s3:HeadBucket, s3:CreateBucket, s3:DeleteBucket, s3:ListBucket, s3:DeleteObject, s3:GetLifecycleConfiguration, s3:PutLifecycleConfiguration (if cache_bucket set)
• tag:GetResources (Resource Groups Tagging API — discovers deployed resources by their fused:* tags)
• sts:GetCallerIdentity

---

Local backend infra

For a local environment (backend: "local"), "infra" is the data/secrets/venvs directories and the cached venv holding the env's packages, managed by LocalPythonInfraManager. No cloud resources; the only prerequisites are a Python interpreter and (optionally) uv. The same infra_* MCP tools and fused infra CLI commands dispatch to it.

What's managed	Detail
Data directory	local_path (default ~/.openfused/data) — created on apply.
Secrets directory	the parent dir of secrets_file — created on apply.
Venvs directory	venvs_path (default ~/.openfused/venvs) — created on apply.

• infra plan — reports missing dirs; exits 1 on drift.
• infra apply — creates the dirs and the packages venv. Idempotent.
• infra build-image — errors for local envs (no image; run infra apply).
• infra teardown — removes the venvs dir (always — venvs are a reproducible cache) and (destructive) local_path. Background code serve endpoints survive; they are detached host processes — stop them by killing the process (Ctrl-C, or kill <pid>).
• infra lambda-reset — clears the in-process venv ready-cache; nothing is deleted from disk.