nx-terraform 0.2.0

package/README.md

@@ -0,0 +1,11 @@
+# nx-terraform
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build nx-terraform` to build the library.
+
+## Running unit tests
+
+Run `nx test nx-terraform` to execute the unit tests via [Jest](https://jestjs.io).

package/generators.json

@@ -0,0 +1,15 @@
+{
+  "generators": {
+    "preset": {
+      "factory": "./src/generators/preset/generator",
+      "schema": "./src/generators/preset/schema.json",
+      "description": "preset generator",
+      "x-use-standalone-layout": true
+    },
+    "terraform-backend": {
+      "factory": "./src/generators/terraform-backend/terraform-backend",
+      "schema": "./src/generators/terraform-backend/schema.json",
+      "description": "terraform-backend generator"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "nx-terraform",
+  "version": "0.2.0",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "url": "https://github.com/alexpialetski/nx-terraform"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nx/devkit": "22.0.2",
+    "tslib": "^2.3.0"
+  },
+  "generators": "./generators.json"
+}

package/src/generators/preset/generator.d.ts

@@ -0,0 +1,4 @@
+import { Tree } from '@nx/devkit';
+import { PresetGeneratorSchema } from './schema';
+export declare function presetGenerator(tree: Tree, options: PresetGeneratorSchema): Promise<import("@nx/devkit").GeneratorCallback>;
+export default presetGenerator;

package/src/generators/preset/generator.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presetGenerator = presetGenerator;
+const tslib_1 = require("tslib");
+const devkit_1 = require("@nx/devkit");
+const terraform_backend_1 = require("../terraform-backend/terraform-backend");
+function presetGenerator(tree, options) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const tasks = [];
+        // Scaffold terraform backend project
+        yield (0, terraform_backend_1.terraformBackendGenerator)(tree, {
+            name: 'terraform-setup',
+            backendType: options.backendType,
+        });
+        yield (0, devkit_1.formatFiles)(tree);
+        return (0, devkit_1.runTasksInSerial)(...tasks);
+    });
+}
+exports.default = presetGenerator;
+//# sourceMappingURL=generator.js.map

package/src/generators/preset/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../../../packages/nx-terraform/src/generators/preset/generator.ts"],"names":[],"mappings":";;AAKA,0CAeC;;AApBD,uCAAiE;AAGjE,8EAAmF;AAEnF,SAAsB,eAAe,CACnC,IAAU,EACV,OAA8B;;QAE9B,MAAM,KAAK,GAAG,EAAE,CAAC;QAEjB,qCAAqC;QACrC,MAAM,IAAA,6CAAyB,EAAC,IAAI,EAAE;YACpC,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;QAEH,MAAM,IAAA,oBAAW,EAAC,IAAI,CAAC,CAAC;QAExB,OAAO,IAAA,yBAAgB,EAAC,GAAG,KAAK,CAAC,CAAC;IACpC,CAAC;CAAA;AAED,kBAAe,eAAe,CAAC"}

package/src/generators/preset/schema.d.ts

@@ -0,0 +1,4 @@
+export interface PresetGeneratorSchema {
+  projectName: string;
+  backendType: 'aws-s3' | 'local';
+}

package/src/generators/preset/schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "NxTerraformPreset",
+  "title": "Nx Terraform preset",
+  "description": "Initializes a workspace with a Terraform backend project configured via nx-terraform preset.",
+  "type": "object",
+  "properties": {
+    "projectName": {
+      "type": "string",
+      "description": "Name of the initial Terraform backend project.",
+      "aliases": ["name"],
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What project name would you like to use?"
+    },
+    "backendType": {
+      "type": "string",
+      "description": "Terraform backend type to scaffold (aws-s3 or local).",
+      "enum": ["aws-s3", "local"],
+      "x-prompt": {
+        "message": "Select Terraform backend type",
+        "type": "list",
+        "items": [
+          { "value": "aws-s3", "label": "AWS S3 remote backend" },
+          { "value": "local", "label": "Local backend" }
+        ]
+      }
+    }
+  },
+  "required": ["projectName", "backendType"]
+}

package/src/generators/terraform-backend/files/aws-s3-backend/README.md

@@ -0,0 +1,70 @@
+# Terraform Backend: AWS S3
+
+This package (`<%= name %>`) provisions the AWS infrastructure required for a remote Terraform state backend using S3 and optional locking features.
+
+## 📋 Overview
+
+This backend includes:
+
+- **S3 Bucket** for Terraform state storage with versioning and object lock
+- **Backend Configuration** file generation for cluster package initialization
+- **Bucket Existence Validation** to handle temporary AWS account scenarios
+
+## 🏗️ Resources Created
+
+### S3 Bucket (`aws_s3_bucket.tf_state`)
+
+- **Purpose**: Stores Terraform state for the cluster infrastructure
+- **Features**:
+  - Versioning enabled for state history
+  - Object lock enabled for state protection
+  - Force destroy enabled for temporary accounts
+- **Naming**: `<%= bucketNamePrefix %>-${data.aws_caller_identity.current.account_id}-${data.aws_region.current.region}` (prefix + AWS account id + region)
+
+### Backend Configuration (`local_file.backend_config`)
+
+- **Purpose**: Generates `backend.config` file for cluster initialization
+- **Content**: S3 bucket name, key, and region configuration
+- **Usage**: Referenced by cluster package Terraform initialization
+
+### Bucket Existence Check (`data.external.check_bucket`)
+
+- **Purpose**: Prevents resource conflicts in temporary AWS accounts
+- **Script**: `scripts/check_bucket.sh`
+- **Logic**: Only creates bucket if it doesn't already exist
+
+## 🔐 Security Considerations
+
+### S3 Bucket Security
+
+- **Versioning**: Enabled to track state changes
+- **Object Lock**: Prevents accidental state deletion
+- **Access Control**: Controlled through IAM policies
+
+### Additional Security
+
+For production environments, additionally consider:
+
+- KMS encryption for S3 bucket
+- Bucket policies for access control
+- VPC endpoints for S3 access
+- **Lifecycle Policies**: Can be configured for state retention
+- **Monitoring**: CloudTrail logging for audit and compliance
+
+## 🔄 Dependencies
+
+- **Upstream**: AWS Provider configuration
+- **Downstream**: Packages that depend on initialized backend
+
+## 📊 Outputs
+
+Generated by the Nx Terraform backend generator (type: <%= backendType %>).
+
+- **backend.config**: Backend configuration for cluster package Terraform initialization
+- **S3 bucket**: Terraform state storage with versioning and object lock enabled
+
+After creation, other Terraform modules can reference the generated `backend.config` file for initialization.
+
+## 🧪 Validation
+
+The included script `scripts/check_bucket.sh` prevents duplicate bucket creation when working in ephemeral AWS accounts.

package/src/generators/terraform-backend/files/aws-s3-backend/__ignoreFile__

@@ -0,0 +1,3 @@
+backend.config
+.terraform
+tfplan

package/src/generators/terraform-backend/files/aws-s3-backend/backend.tf

@@ -0,0 +1,3 @@
+terraform {
+  backend "local" {}
+}

package/src/generators/terraform-backend/files/aws-s3-backend/locals.tf

@@ -0,0 +1,3 @@
+locals {
+  bucket_name = "<%= bucketNamePrefix %>-${data.aws_caller_identity.current.account_id}-${data.aws_region.current.region}"
+}

package/src/generators/terraform-backend/files/aws-s3-backend/main.tf

@@ -0,0 +1,12 @@
+data "aws_region" "current" {}
+
+data "aws_caller_identity" "current" {}
+
+resource "local_file" "backend_config" {
+  content  = <<EOF
+bucket = "${local.bucket_name}"
+key    = "tf_state"
+region = "${data.aws_region.current.region}"
+EOF
+  filename = "backend.config"
+}

package/src/generators/terraform-backend/files/aws-s3-backend/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "<%= name %>",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "clean": "rimraf terraform.tfstate.d tfplan"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "rimraf": "^5.0.10"
+  }
+}

package/src/generators/terraform-backend/files/aws-s3-backend/provider.tf

@@ -0,0 +1,32 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "6.2.0"
+    }
+    local = {
+      source  = "hashicorp/local"
+      version = "2.5.3"
+    }
+    external = {
+      source  = "hashicorp/external"
+      version = "2.3.5"
+    }
+  }
+
+  # needed for NX cache reset when new module is added
+  # required_modules {
+  #   github-oidc = {
+  #     source  = "terraform-module/github-oidc-provider/aws"
+  #     version = "~> 1"
+  #   }
+  # }
+}
+
+provider "aws" {
+  region = var.region
+}
+
+provider "local" {}
+
+provider "external" {}

package/src/generators/terraform-backend/files/aws-s3-backend/s3.tf

@@ -0,0 +1,37 @@
+// check if bucket already exists
+data "external" "check_bucket" {
+  program = ["bash", "./scripts/check_bucket.sh"]
+
+
+  query = {
+    bucket_name = local.bucket_name
+  }
+}
+
+resource "aws_s3_bucket" "tf_state" {
+  count = data.external.check_bucket.result.exists == "false" ? 1 : 0
+
+  bucket              = local.bucket_name
+  object_lock_enabled = true
+  force_destroy       = true
+
+  lifecycle {
+    prevent_destroy = false
+  }
+}
+
+resource "aws_s3_bucket_versioning" "tf_state" {
+  count = data.external.check_bucket.result.exists == "false" ? 1 : 0
+
+  bucket = local.bucket_name
+
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_object_lock_configuration" "tf_state" {
+  count = data.external.check_bucket.result.exists == "false" ? 1 : 0
+
+  bucket = local.bucket_name
+}

package/src/generators/terraform-backend/files/aws-s3-backend/scripts/check_bucket.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Exit if any of the intermediate steps fail
+set -e
+eval "$(jq -r '@sh "BUCKET_NAME=\(.bucket_name)"')"
+
+if aws s3api head-bucket --bucket "$BUCKET_NAME" >/dev/null 2>&1; then
+  echo '{"exists": "true"}'
+else
+  echo '{"exists": "false"}'
+fi

package/src/generators/terraform-backend/files/aws-s3-backend/variables.tf

@@ -0,0 +1,9 @@
+variable "region" {
+  description = "AWS region to deploy resources"
+  type        = string
+}
+
+variable "account_id" {
+  description = "AWS account ID"
+  type        = string
+}

package/src/generators/terraform-backend/files/local-backend/README.md

@@ -0,0 +1,19 @@
+# Terraform Backend: Local
+
+This package (`<%= name %>`) sets up a local Terraform backend storing state on the filesystem. Suitable for quick prototyping or development where remote state durability and collaboration are not required.
+
+State will be stored in the working directory under terraform.tfstate.
+
+## ⚠️ When To Use
+
+Use the local backend only for:
+
+- Personal development
+- Small throwaway experiments
+- CI jobs that don't need shared state
+
+Avoid for:
+
+- Team collaboration
+- Production infrastructure
+- Environments needing state locking/versioning

package/src/generators/terraform-backend/files/local-backend/__ignoreFile__

@@ -0,0 +1,3 @@
+backend.config
+.terraform
+tfplan

package/src/generators/terraform-backend/files/local-backend/backend.tf

@@ -0,0 +1,5 @@
+terraform {
+  backend "local" {
+    path = local.state_file_path
+  }
+}

package/src/generators/terraform-backend/files/local-backend/locals.tf

@@ -0,0 +1,3 @@
+locals {
+  state_file_path = "${path.module}/terraform.tfstate"
+}

package/src/generators/terraform-backend/files/local-backend/main.tf

@@ -0,0 +1,8 @@
+
+# TODO: update backend configuration with needed for local backend
+resource "local_file" "backend_config" {
+  content  = <<EOF
+path = "${local.state_file_path}"
+EOF
+  filename = "backend.config"
+}

package/src/generators/terraform-backend/files/local-backend/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "<%= name %>",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "clean": "rimraf terraform.tfstate.d tfplan"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "rimraf": "^5.0.10"
+  }
+}

package/src/generators/terraform-backend/schema.d.ts

@@ -0,0 +1,11 @@
+export interface TerraformBackendGeneratorSchema {
+  name: string;
+  backendType: 'aws-s3' | 'local';
+  bucketNamePrefix?: string;
+}
+
+export interface TerraformBackendGeneratorNormalizedSchema
+  extends TerraformBackendGeneratorSchema {
+  bucketNamePrefix: string;
+  ignoreFile: string;
+}

package/src/generators/terraform-backend/schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "TerraformBackend",
+  "title": "",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use?"
+    },
+    "backendType": {
+      "type": "string",
+      "description": "Type of Terraform backend to generate (aws-s3 or local).",
+      "enum": ["aws-s3", "local"],
+      "x-prompt": {
+        "message": "Which Terraform backend type?",
+        "type": "list",
+        "items": [
+          { "value": "aws-s3", "label": "AWS S3 remote backend" },
+          { "value": "local", "label": "Local backend (local state files)" }
+        ]
+      }
+    },
+    "bucketNamePrefix": {
+      "type": "string",
+      "description": "Optional prefix for derived bucket name (aws-s3). Default: tf-rs-school-",
+      "minLength": 3,
+      "pattern": "^[a-z0-9][a-z0-9.-]{1,30}$",
+      "x-prompt": "(Optional) Prefix for bucket name? Leave blank for tf-rs-school-"
+    }
+  },
+  "required": ["name", "backendType"]
+}

package/src/generators/terraform-backend/terraform-backend.d.ts

@@ -0,0 +1,4 @@
+import { Tree } from '@nx/devkit';
+import { TerraformBackendGeneratorSchema } from './schema';
+export declare function terraformBackendGenerator(tree: Tree, options: TerraformBackendGeneratorSchema): Promise<void>;
+export default terraformBackendGenerator;

package/src/generators/terraform-backend/terraform-backend.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.terraformBackendGenerator = terraformBackendGenerator;
+const tslib_1 = require("tslib");
+const devkit_1 = require("@nx/devkit");
+const path = require("path");
+function terraformBackendGenerator(tree, options) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const projectRoot = `packages/${options.name}`;
+        const normalizedOptions = normalizeOptions(options);
+        // Minimal project.json configuration
+        (0, devkit_1.addProjectConfiguration)(tree, normalizedOptions.name, {
+            root: projectRoot,
+            projectType: 'application',
+            sourceRoot: `${projectRoot}`,
+            targets: {},
+        });
+        // Select template directory based on backendType
+        const templateDir = path.join(__dirname, 'files', normalizedOptions.backendType === 'aws-s3'
+            ? 'aws-s3-backend'
+            : 'local-backend');
+        (0, devkit_1.generateFiles)(tree, templateDir, projectRoot, normalizedOptions);
+        // No post-processing needed; EJS handled bucket name logic.
+        yield (0, devkit_1.formatFiles)(tree);
+    });
+}
+const normalizeOptions = (options) => (Object.assign(Object.assign({}, options), { bucketNamePrefix: options.bucketNamePrefix || 'terraform-state', ignoreFile: '.gitignore' }));
+exports.default = terraformBackendGenerator;
+//# sourceMappingURL=terraform-backend.js.map

package/src/generators/terraform-backend/terraform-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terraform-backend.js","sourceRoot":"","sources":["../../../../../../packages/nx-terraform/src/generators/terraform-backend/terraform-backend.ts"],"names":[],"mappings":";;AAYA,8DA4BC;;AAxCD,uCAKoB;AACpB,6BAA6B;AAM7B,SAAsB,yBAAyB,CAC7C,IAAU,EACV,OAAwC;;QAExC,MAAM,WAAW,GAAG,YAAY,OAAO,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAEpD,qCAAqC;QACrC,IAAA,gCAAuB,EAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,EAAE;YACpD,IAAI,EAAE,WAAW;YACjB,WAAW,EAAE,aAAa;YAC1B,UAAU,EAAE,GAAG,WAAW,EAAE;YAC5B,OAAO,EAAE,EAAE;SACZ,CAAC,CAAC;QAEH,iDAAiD;QACjD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAC3B,SAAS,EACT,OAAO,EACP,iBAAiB,CAAC,WAAW,KAAK,QAAQ;YACxC,CAAC,CAAC,gBAAgB;YAClB,CAAC,CAAC,eAAe,CACpB,CAAC;QAEF,IAAA,sBAAa,EAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;QAEjE,4DAA4D;QAC5D,MAAM,IAAA,oBAAW,EAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CAAA;AAED,MAAM,gBAAgB,GAAG,CACvB,OAAwC,EACG,EAAE,CAAC,iCAC3C,OAAO,KACV,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,iBAAiB,EAC/D,UAAU,EAAE,YAAY,IACxB,CAAC;AAEH,kBAAe,yBAAyB,CAAC"}

package/src/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/nx-terraform/src/index.ts"],"names":[],"mappings":""}