@intentius/chant-lexicon-aws 0.0.13 → 0.0.15

package/dist/rules/waw030.ts

@@ -10,6 +10,8 @@
  * - API Gateway V2 Deployment with no DependsOn on any Route
  * - DynamoDB ScalableTarget with no DependsOn on the Table
  * - ECS ScalableTarget with no DependsOn on the ECS Service
+ * - EKS Addon with hardcoded ClusterName but no DependsOn on the Cluster or Nodegroup
+ * - EKS Nodegroup with hardcoded ClusterName but no DependsOn on the Cluster
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
@@ -34,6 +36,9 @@ export function checkMissingDependsOn(ctx: PostSynthContext): PostSynthDiagnosti
     const dynamoTableIds: string[] = [];
     const ecsServiceIds: string[] = [];
     const scalableTargetEntries: { logicalId: string; namespace: string }[] = [];
+    const eksClusterIds: string[] = [];
+    const eksNodegroupIds: string[] = [];
+    const eksAddonIds: string[] = [];
 
     for (const [logicalId, resource] of Object.entries(resources)) {
       if (resource.Type === "AWS::ElasticLoadBalancingV2::Listener") {
@@ -60,6 +65,15 @@ export function checkMissingDependsOn(ctx: PostSynthContext): PostSynthDiagnosti
       if (resource.Type === "AWS::ECS::Service") {
         ecsServiceIds.push(logicalId);
       }
+      if (resource.Type === "AWS::EKS::Cluster") {
+        eksClusterIds.push(logicalId);
+      }
+      if (resource.Type === "AWS::EKS::Nodegroup") {
+        eksNodegroupIds.push(logicalId);
+      }
+      if (resource.Type === "AWS::EKS::Addon") {
+        eksAddonIds.push(logicalId);
+      }
       if (resource.Type === "AWS::ApplicationAutoScaling::ScalableTarget") {
         const props = resource.Properties ?? {};
         const ns = inferScalingNamespace(props);
@@ -144,6 +158,47 @@ export function checkMissingDependsOn(ctx: PostSynthContext): PostSynthDiagnosti
       }
     }
 
+    // Pattern 7: EKS Addon with hardcoded ClusterName but no dependency on Cluster or Nodegroup
+    for (const addonId of eksAddonIds) {
+      const resource = resources[addonId];
+      const deps = getDependsOnSet(resource);
+      const propRefs = collectPropertyRefs(resource);
+      const allClusterAndNodeDeps = [...eksClusterIds, ...eksNodegroupIds];
+
+      const hasClusterDep = allClusterAndNodeDeps.some((id) => deps.has(id));
+      const hasClusterRef = allClusterAndNodeDeps.some((id) => propRefs.has(id));
+
+      if (!hasClusterDep && !hasClusterRef && eksClusterIds.length > 0) {
+        diagnostics.push({
+          checkId: "WAW030",
+          severity: "warning",
+          message: `EKS Addon "${addonId}" has no dependency on the Cluster or Nodegroup — the addon may fail if the cluster or nodes aren't ready yet. Add DependsOn.`,
+          entity: addonId,
+          lexicon: "aws",
+        });
+      }
+    }
+
+    // Pattern 8: EKS Nodegroup with hardcoded ClusterName but no dependency on Cluster
+    for (const ngId of eksNodegroupIds) {
+      const resource = resources[ngId];
+      const deps = getDependsOnSet(resource);
+      const propRefs = collectPropertyRefs(resource);
+
+      const hasClusterDep = eksClusterIds.some((id) => deps.has(id));
+      const hasClusterRef = eksClusterIds.some((id) => propRefs.has(id));
+
+      if (!hasClusterDep && !hasClusterRef && eksClusterIds.length > 0) {
+        diagnostics.push({
+          checkId: "WAW030",
+          severity: "warning",
+          message: `EKS Nodegroup "${ngId}" has no dependency on the Cluster — the node group may fail if the cluster isn't ready yet. Add DependsOn.`,
+          entity: ngId,
+          lexicon: "aws",
+        });
+      }
+    }
+
     // Pattern 5 & 6: ScalableTarget with no DependsOn on the target resource
     for (const entry of scalableTargetEntries) {
       const resource = resources[entry.logicalId];

package/dist/rules/waw031.ts

@@ -0,0 +1,66 @@
+/**
+ * WAW031: EKS Addon Missing ServiceAccountRoleArn
+ *
+ * Certain EKS addons require a ServiceAccountRoleArn (IRSA role) to function.
+ * Without one, the addon pods can't authenticate to AWS APIs and the addon
+ * hangs in CREATING status indefinitely.
+ *
+ * Known addons that require IRSA:
+ * - aws-ebs-csi-driver (needs EBS API access)
+ * - aws-efs-csi-driver (needs EFS API access)
+ * - adot (needs CloudWatch/X-Ray access)
+ * - amazon-cloudwatch-observability (needs CloudWatch access)
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+
+/** Addons that are known to require a ServiceAccountRoleArn to function. */
+const ADDONS_REQUIRING_IRSA: Record<string, string> = {
+  "aws-ebs-csi-driver": "EBS API access to manage volumes",
+  "aws-efs-csi-driver": "EFS API access to manage file systems",
+  "adot": "CloudWatch/X-Ray access for metrics and traces",
+  "amazon-cloudwatch-observability": "CloudWatch access for logs and metrics",
+};
+
+export function checkAddonMissingRole(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::EKS::Addon") continue;
+
+      const props = resource.Properties ?? {};
+      const addonName = typeof props.AddonName === "string" ? props.AddonName : null;
+      if (!addonName) continue;
+
+      const reason = ADDONS_REQUIRING_IRSA[addonName];
+      if (!reason) continue;
+
+      // Check if ServiceAccountRoleArn is set (could be a string, Ref, or GetAtt)
+      if (!props.ServiceAccountRoleArn) {
+        diagnostics.push({
+          checkId: "WAW031",
+          severity: "warning",
+          message: `EKS Addon "${logicalId}" (${addonName}) has no ServiceAccountRoleArn — it needs an IRSA role for ${reason}. Without it, the addon will hang in CREATING status.`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw031: PostSynthCheck = {
+  id: "WAW031",
+  description: "EKS Addon missing ServiceAccountRoleArn for addons that require IRSA",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkAddonMissingRole(ctx);
+  },
+};

package/dist/skills/chant-eks.md

@@ -0,0 +1,175 @@
+---
+skill: chant-eks
+description: End-to-end EKS workflow bridging AWS infrastructure and Kubernetes workloads
+user-invocable: true
+---
+
+# EKS End-to-End Workflow
+
+## Overview
+
+This skill bridges two lexicons:
+- **`@intentius/chant-lexicon-aws`** — EKS cluster, node groups, IAM roles, OIDC provider (CloudFormation)
+- **`@intentius/chant-lexicon-k8s`** — Kubernetes workloads, IRSA, ALB Ingress, storage, observability (K8s YAML)
+
+## Architecture
+
+```
+AWS Lexicon (CloudFormation)          K8s Lexicon (kubectl apply)
+┌────────────────────────┐           ┌────────────────────────────┐
+│ VPC + Subnets          │           │ NamespaceEnv (quotas)      │
+│ EKS Cluster            │           │ AutoscaledService (app)    │
+│ Managed Node Group     │──ARNs──→  │ IrsaServiceAccount (IRSA)  │
+│ OIDC Provider          │           │ AlbIngress (ALB)           │
+│ IAM Roles (IRSA)       │           │ EbsStorageClass (gp3)      │
+│ EKS Add-ons            │           │ FluentBitAgent (logs)      │
+└────────────────────────┘           │ ExternalDnsAgent (DNS)     │
+                                     └────────────────────────────┘
+```
+
+## Step 1: Provision AWS Infrastructure
+
+```bash
+# Build CloudFormation template
+chant build src/infra/ --output infra.json
+
+# Deploy
+aws cloudformation deploy \
+  --template-file infra.json \
+  --stack-name my-eks-cluster \
+  --capabilities CAPABILITY_NAMED_IAM
+```
+
+Key AWS resources:
+- **EKS Cluster** — control plane
+- **Managed Node Group** — EC2 worker nodes
+- **OIDC Provider** — enables IRSA (IAM Roles for Service Accounts)
+- **IAM Roles** — node role, app IRSA roles, ALB controller role
+
+## Step 2: Configure kubectl
+
+```bash
+aws eks update-kubeconfig --name my-cluster --region us-east-1
+kubectl get nodes  # verify connectivity
+```
+
+## Step 3: Deploy K8s Workloads
+
+```bash
+# Build K8s manifests
+chant build src/k8s/ --output manifests.yaml
+
+# Apply
+kubectl apply -f manifests.yaml
+```
+
+### Key K8s composites for EKS
+
+```typescript
+import {
+  NamespaceEnv,
+  AutoscaledService,
+  IrsaServiceAccount,
+  AlbIngress,
+  EbsStorageClass,
+  FluentBitAgent,
+  ExternalDnsAgent,
+} from "@intentius/chant-lexicon-k8s";
+
+// 1. Namespace with quotas and network isolation
+const ns = NamespaceEnv({
+  name: "prod",
+  cpuQuota: "16",
+  memoryQuota: "32Gi",
+  defaultCpuRequest: "100m",
+  defaultMemoryRequest: "128Mi",
+  defaultDenyIngress: true,
+});
+
+// 2. IRSA ServiceAccount (use IAM Role ARN from CloudFormation outputs)
+const irsa = IrsaServiceAccount({
+  name: "app-sa",
+  iamRoleArn: "arn:aws:iam::123456789012:role/app-role",  // from CF output
+  namespace: "prod",
+});
+
+// 3. Application with autoscaling
+const app = AutoscaledService({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  maxReplicas: 10,
+  cpuRequest: "200m",
+  memoryRequest: "256Mi",
+  namespace: "prod",
+});
+
+// 4. ALB Ingress (use ACM cert ARN from CloudFormation outputs)
+const ingress = AlbIngress({
+  name: "api-ingress",
+  hosts: [{ hostname: "api.example.com", paths: [{ path: "/", serviceName: "api", servicePort: 80 }] }],
+  certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc",  // from CF output
+  namespace: "prod",
+});
+
+// 5. Storage
+const storage = EbsStorageClass({ name: "gp3-encrypted", type: "gp3", encrypted: true });
+
+// 6. Observability
+const logging = FluentBitAgent({
+  logGroup: "/aws/eks/my-cluster/containers",
+  region: "us-east-1",
+  clusterName: "my-cluster",
+});
+
+// 7. DNS
+const dns = ExternalDnsAgent({
+  iamRoleArn: "arn:aws:iam::123456789012:role/external-dns-role",
+  domainFilters: ["example.com"],
+});
+```
+
+## Step 4: Verify
+
+```bash
+kubectl get pods -n prod
+kubectl get ingress -n prod
+kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=fluent-bit
+```
+
+## Cleanup
+
+```bash
+# Delete K8s workloads first
+kubectl delete -f manifests.yaml
+
+# Then delete AWS infrastructure
+aws cloudformation delete-stack --stack-name my-eks-cluster
+aws cloudformation wait stack-delete-complete --stack-name my-eks-cluster
+```
+
+## Cross-Lexicon Value Flow
+
+CloudFormation outputs flow into K8s composite props:
+
+| CloudFormation Output | K8s Composite Prop |
+|----------------------|-------------------|
+| App IAM Role ARN | `IrsaServiceAccount.iamRoleArn` |
+| ALB Controller Role ARN | `IrsaServiceAccount.iamRoleArn` (for ALB controller SA) |
+| ACM Certificate ARN | `AlbIngress.certificateArn` |
+| ExternalDNS Role ARN | `ExternalDnsAgent.iamRoleArn` |
+| EKS Cluster Name | `FluentBitAgent.clusterName`, `AdotCollector.clusterName` |
+| EFS Filesystem ID | `EfsStorageClass.fileSystemId` |
+
+## EKS Init Template
+
+Scaffold a dual-lexicon EKS project:
+
+```bash
+chant init --lexicon aws --template eks
+```
+
+This creates:
+- `src/infra/` — EKS cluster, node group, IAM (AWS lexicon)
+- `src/k8s/` — namespace, app, ingress, storage (K8s lexicon)
+- `package.json` with both `@intentius/chant-lexicon-aws` and `@intentius/chant-lexicon-k8s`