@intentius/chant-lexicon-k8s 0.0.13 → 0.0.15

package/src/composites/adot-collector.ts

@@ -0,0 +1,245 @@
+/**
+ * AdotCollector composite — DaemonSet + RBAC + ConfigMap for AWS Distro for OpenTelemetry.
+ *
+ * @eks ADOT collector for CloudWatch and X-Ray. NodeAgent specialization
+ * with pre-configured pipelines for AWS observability.
+ */
+
+export interface AdotCollectorProps {
+  /** AWS region. */
+  region: string;
+  /** EKS cluster name. */
+  clusterName: string;
+  /** Exporters to enable (default: ["cloudwatch", "xray"]). */
+  exporters?: ("cloudwatch" | "xray" | "prometheus")[];
+  /** Agent name (default: "adot-collector"). */
+  name?: string;
+  /** ADOT image (default: "public.ecr.aws/aws-observability/aws-otel-collector:latest"). */
+  image?: string;
+  /** Namespace (default: "amazon-metrics"). */
+  namespace?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "256Mi"). */
+  memoryRequest?: string;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "512Mi"). */
+  memoryLimit?: string;
+  /** IAM Role ARN for IRSA (adds eks.amazonaws.com/role-arn annotation to ServiceAccount). */
+  iamRoleArn?: string;
+}
+
+export interface AdotCollectorResult {
+  daemonSet: Record<string, unknown>;
+  serviceAccount: Record<string, unknown>;
+  clusterRole: Record<string, unknown>;
+  clusterRoleBinding: Record<string, unknown>;
+  configMap: Record<string, unknown>;
+}
+
+/**
+ * Create an AdotCollector composite — returns prop objects for
+ * a DaemonSet, ServiceAccount, ClusterRole, ClusterRoleBinding, and ConfigMap.
+ *
+ * @eks
+ * @example
+ * ```ts
+ * import { AdotCollector } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap } = AdotCollector({
+ *   region: "us-east-1",
+ *   clusterName: "my-cluster",
+ *   exporters: ["cloudwatch", "xray"],
+ * });
+ * ```
+ */
+export function AdotCollector(props: AdotCollectorProps): AdotCollectorResult {
+  const {
+    region,
+    clusterName,
+    exporters = ["cloudwatch", "xray"],
+    name = "adot-collector",
+    image = "public.ecr.aws/aws-observability/aws-otel-collector:latest",
+    namespace = "amazon-metrics",
+    labels: extraLabels = {},
+    cpuRequest = "100m",
+    memoryRequest = "256Mi",
+    cpuLimit = "500m",
+    memoryLimit = "512Mi",
+    iamRoleArn,
+  } = props;
+
+  const saName = `${name}-sa`;
+  const clusterRoleName = `${name}-role`;
+  const bindingName = `${name}-binding`;
+  const configMapName = `${name}-config`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build ADOT config YAML
+  const exporterConfigs: string[] = [];
+  const exporterNames: string[] = [];
+
+  if (exporters.includes("cloudwatch")) {
+    exporterConfigs.push(`  awsemf:
+    region: ${region}
+    namespace: ContainerInsights
+    log_group_name: '/aws/containerinsights/${clusterName}/performance'
+    dimension_rollup_option: NoDimensionRollup`);
+    exporterNames.push("awsemf");
+  }
+
+  if (exporters.includes("xray")) {
+    exporterConfigs.push(`  awsxray:
+    region: ${region}`);
+    exporterNames.push("awsxray");
+  }
+
+  if (exporters.includes("prometheus")) {
+    exporterConfigs.push(`  prometheusremotewrite:
+    endpoint: http://prometheus:9090/api/v1/write`);
+    exporterNames.push("prometheusremotewrite");
+  }
+
+  const adotConfig = `receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+    timeout: 30s
+    send_batch_size: 8192
+
+exporters:
+${exporterConfigs.join("\n")}
+
+service:
+  pipelines:
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [${exporterNames.filter((e) => e !== "awsxray").join(", ") || "awsemf"}]
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [${exporterNames.filter((e) => e !== "awsemf").join(", ") || "awsxray"}]
+`;
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    args: ["--config=/etc/adot/config.yaml"],
+    ports: [
+      { containerPort: 4317, name: "otlp-grpc" },
+      { containerPort: 4318, name: "otlp-http" },
+    ],
+    resources: {
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+    },
+    volumeMounts: [
+      { name: "config", mountPath: "/etc/adot", readOnly: true },
+    ],
+    securityContext: {
+      runAsNonRoot: true,
+      runAsUser: 10001,
+      readOnlyRootFilesystem: true,
+      allowPrivilegeEscalation: false,
+    },
+  };
+
+  const daemonSetProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+    },
+    spec: {
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          containers: [container],
+          volumes: [
+            { name: "config", configMap: { name: configMapName } },
+          ],
+          tolerations: [{ operator: "Exists" }],
+        },
+      },
+    },
+  };
+
+  const serviceAccountProps: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+      ...(iamRoleArn ? { annotations: { "eks.amazonaws.com/role-arn": iamRoleArn } } : {}),
+    },
+  };
+
+  const clusterRoleProps: Record<string, unknown> = {
+    metadata: {
+      name: clusterRoleName,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: [
+      { apiGroups: [""], resources: ["pods", "nodes", "endpoints"], verbs: ["get", "list", "watch"] },
+      { apiGroups: ["apps"], resources: ["replicasets"], verbs: ["get", "list", "watch"] },
+      { apiGroups: ["batch"], resources: ["jobs"], verbs: ["get", "list", "watch"] },
+      { apiGroups: [""], resources: ["nodes/proxy"], verbs: ["get"] },
+      { apiGroups: [""], resources: ["nodes/stats", "configmaps", "events"], verbs: ["create", "get"] },
+      { apiGroups: [""], resources: ["configmaps"], verbs: ["get", "update", "create"], resourceNames: ["otel-container-insight-clusterleader"] },
+    ],
+  };
+
+  const clusterRoleBindingProps: Record<string, unknown> = {
+    metadata: {
+      name: bindingName,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "ClusterRole",
+      name: clusterRoleName,
+    },
+    subjects: [
+      {
+        kind: "ServiceAccount",
+        name: saName,
+        namespace,
+      },
+    ],
+  };
+
+  const configMapProps: Record<string, unknown> = {
+    metadata: {
+      name: configMapName,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+    },
+    data: {
+      "config.yaml": adotConfig,
+    },
+  };
+
+  return {
+    daemonSet: daemonSetProps,
+    serviceAccount: serviceAccountProps,
+    clusterRole: clusterRoleProps,
+    clusterRoleBinding: clusterRoleBindingProps,
+    configMap: configMapProps,
+  };
+}

package/src/composites/agic-ingress.ts

@@ -0,0 +1,149 @@
+/**
+ * AgicIngress composite — Ingress with Azure Application Gateway Ingress Controller annotations.
+ *
+ * @aks Full `appgw.ingress.kubernetes.io/*` annotation set including SSL redirect,
+ * WAF policy, backend path prefix, and cookie-based affinity.
+ */
+
+export interface AgicIngressHost {
+  /** Hostname (e.g., "api.example.com"). */
+  hostname: string;
+  /** Path rules for this host. */
+  paths: Array<{
+    path: string;
+    pathType?: string;
+    serviceName: string;
+    servicePort: number;
+  }>;
+}
+
+export interface AgicIngressProps {
+  /** Ingress name — used in metadata and labels. */
+  name: string;
+  /** Host definitions with paths. */
+  hosts: AgicIngressHost[];
+  /** Azure Key Vault certificate URI or secret name for TLS. */
+  certificateArn?: string;
+  /** WAF policy resource ID. */
+  wafPolicyId?: string;
+  /** Health check path for backend. */
+  healthCheckPath?: string;
+  /** Enable HTTP->HTTPS redirect (default: true when certificateArn set). */
+  sslRedirect?: boolean;
+  /** Backend path prefix override. */
+  backendPathPrefix?: string;
+  /** Enable cookie-based affinity (default: false). */
+  cookieAffinity?: boolean;
+  /** Additional annotations on the Ingress. */
+  annotations?: Record<string, string>;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export interface AgicIngressResult {
+  ingress: Record<string, unknown>;
+}
+
+/**
+ * Create an AgicIngress composite — returns prop objects for
+ * an Ingress with Azure Application Gateway Ingress Controller annotations.
+ *
+ * @aks
+ * @example
+ * ```ts
+ * import { AgicIngress } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { ingress } = AgicIngress({
+ *   name: "api-ingress",
+ *   hosts: [
+ *     {
+ *       hostname: "api.example.com",
+ *       paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+ *     },
+ *   ],
+ *   certificateArn: "keyvault-secret-name",
+ *   wafPolicyId: "/subscriptions/.../Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies/my-waf",
+ * });
+ * ```
+ */
+export function AgicIngress(props: AgicIngressProps): AgicIngressResult {
+  const {
+    name,
+    hosts,
+    certificateArn,
+    wafPolicyId,
+    healthCheckPath,
+    sslRedirect,
+    backendPathPrefix,
+    cookieAffinity = false,
+    annotations: extraAnnotations = {},
+    labels: extraLabels = {},
+    namespace,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build AGIC annotations
+  const annotations: Record<string, string> = {
+    "kubernetes.io/ingress.class": "azure/application-gateway",
+    ...extraAnnotations,
+  };
+
+  if (sslRedirect ?? (certificateArn !== undefined)) {
+    annotations["appgw.ingress.kubernetes.io/ssl-redirect"] = "true";
+  }
+
+  if (certificateArn) {
+    annotations["appgw.ingress.kubernetes.io/appgw-ssl-certificate"] = certificateArn;
+  }
+
+  if (wafPolicyId) {
+    annotations["appgw.ingress.kubernetes.io/waf-policy-for-path"] = wafPolicyId;
+  }
+
+  if (healthCheckPath) {
+    annotations["appgw.ingress.kubernetes.io/health-probe-path"] = healthCheckPath;
+  }
+
+  if (backendPathPrefix) {
+    annotations["appgw.ingress.kubernetes.io/backend-path-prefix"] = backendPathPrefix;
+  }
+
+  if (cookieAffinity) {
+    annotations["appgw.ingress.kubernetes.io/cookie-based-affinity"] = "true";
+  }
+
+  const ingressRules = hosts.map((host) => ({
+    host: host.hostname,
+    http: {
+      paths: host.paths.map((p) => ({
+        path: p.path,
+        pathType: p.pathType ?? "Prefix",
+        backend: {
+          service: { name: p.serviceName, port: { number: p.servicePort } },
+        },
+      })),
+    },
+  }));
+
+  const ingressProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "ingress" },
+      annotations,
+    },
+    spec: {
+      ingressClassName: "azure/application-gateway",
+      rules: ingressRules,
+    },
+  };
+
+  return { ingress: ingressProps };
+}

package/src/composites/alb-ingress.ts

@@ -0,0 +1,152 @@
+/**
+ * AlbIngress composite — Ingress with AWS Load Balancer Controller annotations.
+ *
+ * @eks Full `alb.ingress.kubernetes.io/*` annotation set including group name
+ * (shared ALB), SSL redirect, subnets, security groups.
+ */
+
+export interface AlbIngressHost {
+  /** Hostname (e.g., "api.example.com"). */
+  hostname: string;
+  /** Path rules for this host. */
+  paths: Array<{
+    path: string;
+    pathType?: string;
+    serviceName: string;
+    /** Port on the Kubernetes Service (not the container port). */
+    servicePort: number;
+  }>;
+}
+
+export interface AlbIngressProps {
+  /** Ingress name — used in metadata and labels. */
+  name: string;
+  /** Host definitions with paths. */
+  hosts: AlbIngressHost[];
+  /** ALB scheme (default: "internet-facing"). */
+  scheme?: "internet-facing" | "internal";
+  /** Target type (default: "ip"). */
+  targetType?: "ip" | "instance";
+  /** ACM certificate ARN for TLS. */
+  certificateArn?: string;
+  /** WAF Web ACL ARN. */
+  wafAclArn?: string;
+  /** Health check path for target group. */
+  healthCheckPath?: string;
+  /** Ingress group name for shared ALB. */
+  groupName?: string;
+  /** Enable HTTP→HTTPS redirect (default: true when certificateArn set). */
+  sslRedirect?: boolean;
+  /** Additional annotations on the Ingress. */
+  annotations?: Record<string, string>;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export interface AlbIngressResult {
+  ingress: Record<string, unknown>;
+}
+
+/**
+ * Create an AlbIngress composite — returns prop objects for
+ * an Ingress with AWS ALB Controller annotations.
+ *
+ * @eks
+ * @example
+ * ```ts
+ * import { AlbIngress } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { ingress } = AlbIngress({
+ *   name: "api-ingress",
+ *   hosts: [
+ *     {
+ *       hostname: "api.example.com",
+ *       paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+ *     },
+ *   ],
+ *   scheme: "internet-facing",
+ *   certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-123",
+ *   groupName: "shared-alb",
+ * });
+ * ```
+ */
+export function AlbIngress(props: AlbIngressProps): AlbIngressResult {
+  const {
+    name,
+    hosts,
+    scheme = "internet-facing",
+    targetType = "ip",
+    certificateArn,
+    wafAclArn,
+    healthCheckPath,
+    groupName,
+    sslRedirect,
+    annotations: extraAnnotations = {},
+    labels: extraLabels = {},
+    namespace,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build ALB annotations
+  const annotations: Record<string, string> = {
+    "alb.ingress.kubernetes.io/scheme": scheme,
+    "alb.ingress.kubernetes.io/target-type": targetType,
+    ...extraAnnotations,
+  };
+
+  if (certificateArn) {
+    annotations["alb.ingress.kubernetes.io/certificate-arn"] = certificateArn;
+    annotations["alb.ingress.kubernetes.io/listen-ports"] = '[{"HTTPS":443}]';
+  }
+
+  if (sslRedirect ?? !!certificateArn) {
+    annotations["alb.ingress.kubernetes.io/ssl-redirect"] = "443";
+  }
+
+  if (wafAclArn) {
+    annotations["alb.ingress.kubernetes.io/wafv2-acl-arn"] = wafAclArn;
+  }
+
+  if (healthCheckPath) {
+    annotations["alb.ingress.kubernetes.io/healthcheck-path"] = healthCheckPath;
+  }
+
+  if (groupName) {
+    annotations["alb.ingress.kubernetes.io/group.name"] = groupName;
+  }
+
+  const ingressRules = hosts.map((host) => ({
+    host: host.hostname,
+    http: {
+      paths: host.paths.map((p) => ({
+        path: p.path,
+        pathType: p.pathType ?? "Prefix",
+        backend: {
+          service: { name: p.serviceName, port: { number: p.servicePort } },
+        },
+      })),
+    },
+  }));
+
+  const ingressProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "ingress" },
+      annotations,
+    },
+    spec: {
+      ingressClassName: "alb",
+      rules: ingressRules,
+    },
+  };
+
+  return { ingress: ingressProps };
+}

package/src/composites/autoscaled-service.ts

@@ -6,6 +6,8 @@
  * PDB selectors match pod labels, and resource requests are set.
  */
 
+import type { ContainerSecurityContext } from "./security-context";
+
 export interface AutoscaledServiceProps {
   /** Application name — used in metadata and labels. */
   name: string;
@@ -40,12 +42,33 @@ export interface AutoscaledServiceProps {
   livenessPath?: string;
   /** Readiness probe path (default: "/readyz"). */
   readinessPath?: string;
+  /** Init containers (e.g., migrations, cert setup). */
+  initContainers?: Array<{
+    name: string;
+    image: string;
+    command?: string[];
+    args?: string[];
+  }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+  /** Termination grace period in seconds. */
+  terminationGracePeriodSeconds?: number;
+  /** Priority class name for pod scheduling. */
+  priorityClassName?: string;
   /** Additional labels to apply to all resources. */
   labels?: Record<string, string>;
   /** Namespace for all resources. */
   namespace?: string;
   /** Environment variables for the container. */
   env?: Array<{ name: string; value: string }>;
+  /** Service account name for the pod. */
+  serviceAccountName?: string;
+  /** Volumes to attach to the pod. */
+  volumes?: Array<Record<string, unknown>>;
+  /** Volume mounts for the primary container. */
+  volumeMounts?: Array<Record<string, unknown>>;
+  /** Convenience: auto-generate emptyDir volumes + mounts for writable temp dirs (e.g. ["/tmp", "/var/cache/nginx"]). */
+  tmpDirs?: string[];
 }
 
 export interface AutoscaledServiceResult {
@@ -89,9 +112,17 @@ export function AutoscaledService(props: AutoscaledServiceProps): AutoscaledServ
     topologySpread = false,
     livenessPath = "/healthz",
     readinessPath = "/readyz",
+    initContainers,
+    securityContext,
+    terminationGracePeriodSeconds,
+    priorityClassName,
     labels: extraLabels = {},
     namespace,
     env,
+    serviceAccountName,
+    volumes: explicitVolumes = [],
+    volumeMounts: explicitMounts = [],
+    tmpDirs = [],
   } = props;
 
   const commonLabels: Record<string, string> = {
@@ -115,6 +146,12 @@ export function AutoscaledService(props: AutoscaledServiceProps): AutoscaledServ
     }];
   })();
 
+  // Generate emptyDir volumes/mounts from tmpDirs, then merge with explicit
+  const tmpVolumes = tmpDirs.map((_, i) => ({ name: `tmp-${i}`, emptyDir: {} }));
+  const tmpMounts = tmpDirs.map((dir, i) => ({ name: `tmp-${i}`, mountPath: dir }));
+  const allVolumes = [...explicitVolumes, ...tmpVolumes];
+  const allMounts = [...explicitMounts, ...tmpMounts];
+
   const resources: Record<string, unknown> = {
     requests: { cpu: cpuRequest, memory: memoryRequest },
     ...(cpuLimit || memoryLimit
@@ -156,9 +193,23 @@ export function AutoscaledService(props: AutoscaledServiceProps): AutoscaledServ
                 periodSeconds: 5,
               },
               ...(env && { env }),
+              ...(securityContext && { securityContext }),
+              ...(allMounts.length > 0 && { volumeMounts: allMounts }),
             },
           ],
+          ...(initContainers && {
+            initContainers: initContainers.map((ic) => ({
+              name: ic.name,
+              image: ic.image,
+              ...(ic.command && { command: ic.command }),
+              ...(ic.args && { args: ic.args }),
+            })),
+          }),
           ...(topologyConstraints && { topologySpreadConstraints: topologyConstraints }),
+          ...(terminationGracePeriodSeconds !== undefined && { terminationGracePeriodSeconds }),
+          ...(priorityClassName && { priorityClassName }),
+          ...(serviceAccountName && { serviceAccountName }),
+          ...(allVolumes.length > 0 && { volumes: allVolumes }),
         },
       },
     },