@intentius/chant-lexicon-k8s 0.0.13 → 0.0.15

package/src/composites/config-connector-context.ts

@@ -0,0 +1,62 @@
+/**
+ * ConfigConnectorContext composite — bootstrap Config Connector per-namespace context.
+ *
+ * @gke Creates a ConfigConnectorContext resource that configures
+ * Config Connector to manage GCP resources in a specific namespace.
+ */
+
+export interface ConfigConnectorContextProps {
+  /** Context name (default: "configconnectorcontext.core.cnrm.cloud.google.com"). */
+  name?: string;
+  /** Google service account email for Config Connector to use. */
+  googleServiceAccountEmail: string;
+  /** Namespace for the context (default: "default"). */
+  namespace?: string;
+  /** Whether to sync status into spec (default: "absent"). */
+  stateIntoSpec?: "absent" | "merge";
+}
+
+export interface ConfigConnectorContextResult {
+  context: Record<string, unknown>;
+}
+
+/**
+ * Create a ConfigConnectorContext composite — returns prop objects for
+ * a ConfigConnectorContext resource.
+ *
+ * @gke
+ * @example
+ * ```ts
+ * import { ConfigConnectorContext } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { context } = ConfigConnectorContext({
+ *   googleServiceAccountEmail: "cnrm@my-project.iam.gserviceaccount.com",
+ *   namespace: "config-connector",
+ * });
+ * ```
+ */
+export function ConfigConnectorContext(
+  props: ConfigConnectorContextProps,
+): ConfigConnectorContextResult {
+  const {
+    name = "configconnectorcontext.core.cnrm.cloud.google.com",
+    googleServiceAccountEmail,
+    namespace = "default",
+    stateIntoSpec = "absent",
+  } = props;
+
+  const contextProps: Record<string, unknown> = {
+    apiVersion: "core.cnrm.cloud.google.com/v1beta1",
+    kind: "ConfigConnectorContext",
+    metadata: {
+      name,
+      namespace,
+    },
+    spec: {
+      googleServiceAccount: googleServiceAccountEmail,
+      stateIntoSpec,
+    },
+  };
+
+  return { context: contextProps };
+}

package/src/composites/configured-app.ts

@@ -0,0 +1,224 @@
+/**
+ * ConfiguredApp composite — Deployment + Service + optional ConfigMap.
+ *
+ * Wires ConfigMap→Volume→VolumeMount and Secret→Volume→VolumeMount
+ * triangles, plus envFrom injection. Covers cdk8s-plus Volume.fromConfigMap(),
+ * Volume.fromSecret(), and container.mount() patterns.
+ */
+
+import type { ContainerSecurityContext } from "./security-context";
+
+export interface ConfiguredAppProps {
+  /** Application name — used in metadata and labels. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Container port (default: 80). */
+  port?: number;
+  /** Number of replicas (default: 2). */
+  replicas?: number;
+  /** Config data — creates a ConfigMap. */
+  configData?: Record<string, string>;
+  /** Mount path for the ConfigMap volume. */
+  configMountPath?: string;
+  /** Existing Secret name to mount as a volume. */
+  secretName?: string;
+  /** Mount path for the Secret volume. */
+  secretMountPath?: string;
+  /** Inject config/secrets as environment variables. */
+  envFrom?: {
+    configMapRef?: string;
+    secretRef?: string;
+  };
+  /** Init containers (e.g., migrations, cert setup). */
+  initContainers?: Array<{
+    name: string;
+    image: string;
+    command?: string[];
+    args?: string[];
+  }>;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "256Mi"). */
+  memoryLimit?: string;
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "128Mi"). */
+  memoryRequest?: string;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+}
+
+export interface ConfiguredAppResult {
+  deployment: Record<string, unknown>;
+  service: Record<string, unknown>;
+  configMap?: Record<string, unknown>;
+}
+
+/**
+ * Create a ConfiguredApp composite — returns prop objects for
+ * a Deployment, Service, and optional ConfigMap.
+ *
+ * @example
+ * ```ts
+ * import { ConfiguredApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service, configMap } = ConfiguredApp({
+ *   name: "api",
+ *   image: "api:1.0",
+ *   port: 8080,
+ *   configData: { "app.conf": "key=value" },
+ *   configMountPath: "/etc/api",
+ *   secretName: "api-creds",
+ *   secretMountPath: "/secrets",
+ *   envFrom: { secretRef: "api-env-secret" },
+ * });
+ * ```
+ */
+export function ConfiguredApp(props: ConfiguredAppProps): ConfiguredAppResult {
+  const {
+    name,
+    image,
+    port = 80,
+    replicas = 2,
+    configData,
+    configMountPath,
+    secretName,
+    secretMountPath,
+    envFrom,
+    initContainers,
+    labels: extraLabels = {},
+    cpuLimit = "500m",
+    memoryLimit = "256Mi",
+    cpuRequest = "100m",
+    memoryRequest = "128Mi",
+    namespace,
+    env,
+    securityContext,
+  } = props;
+
+  const configMapName = `${name}-config`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build volumes and volumeMounts
+  const volumes: Array<Record<string, unknown>> = [];
+  const volumeMounts: Array<Record<string, unknown>> = [];
+
+  if (configData && configMountPath) {
+    volumes.push({
+      name: "config",
+      configMap: { name: configMapName },
+    });
+    volumeMounts.push({
+      name: "config",
+      mountPath: configMountPath,
+      readOnly: true,
+    });
+  }
+
+  if (secretName && secretMountPath) {
+    volumes.push({
+      name: "secret",
+      secret: { secretName },
+    });
+    volumeMounts.push({
+      name: "secret",
+      mountPath: secretMountPath,
+      readOnly: true,
+    });
+  }
+
+  // Build envFrom array
+  const envFromList: Array<Record<string, unknown>> = [];
+  if (envFrom?.configMapRef) {
+    envFromList.push({ configMapRef: { name: envFrom.configMapRef } });
+  }
+  if (envFrom?.secretRef) {
+    envFromList.push({ secretRef: { name: envFrom.secretRef } });
+  }
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ports: [{ containerPort: port, name: "http" }],
+    resources: {
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+    },
+    ...(env && { env }),
+    ...(envFromList.length > 0 && { envFrom: envFromList }),
+    ...(volumeMounts.length > 0 && { volumeMounts }),
+    ...(securityContext && { securityContext }),
+  };
+
+  const podSpec: Record<string, unknown> = {
+    containers: [container],
+    ...(volumes.length > 0 && { volumes }),
+    ...(initContainers && {
+      initContainers: initContainers.map((ic) => ({
+        name: ic.name,
+        image: ic.image,
+        ...(ic.command && { command: ic.command }),
+        ...(ic.args && { args: ic.args }),
+      })),
+    }),
+  };
+
+  const deploymentProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      replicas,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: podSpec,
+      },
+    },
+  };
+
+  const serviceProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: [{ port: 80, targetPort: port, protocol: "TCP", name: "http" }],
+      type: "ClusterIP",
+    },
+  };
+
+  const result: ConfiguredAppResult = {
+    deployment: deploymentProps,
+    service: serviceProps,
+  };
+
+  if (configData) {
+    result.configMap = {
+      metadata: {
+        name: configMapName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+      },
+      data: configData,
+    };
+  }
+
+  return result;
+}

package/src/composites/cron-workload.ts

@@ -5,6 +5,8 @@
  * proper RBAC permissions.
  */
 
+import type { ContainerSecurityContext } from "./security-context";
+
 export interface CronWorkloadProps {
   /** Workload name — used in metadata and labels. */
   name: string;
@@ -33,6 +35,8 @@ export interface CronWorkloadProps {
   namespace?: string;
   /** Environment variables. */
   env?: Array<{ name: string; value: string }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
 }
 
 export interface CronWorkloadResult {
@@ -75,6 +79,7 @@ export function CronWorkload(props: CronWorkloadProps): CronWorkloadResult {
     labels: extraLabels = {},
     namespace,
     env,
+    securityContext,
   } = props;
 
   const saName = `${name}-sa`;
@@ -110,6 +115,7 @@ export function CronWorkload(props: CronWorkloadProps): CronWorkloadResult {
                   ...(command && { command }),
                   ...(args && { args }),
                   ...(env && { env }),
+                  ...(securityContext && { securityContext }),
                 },
               ],
             },

package/src/composites/ebs-storage-class.ts

@@ -0,0 +1,96 @@
+/**
+ * EbsStorageClass composite — StorageClass for AWS EBS CSI driver.
+ *
+ * @eks Creates a StorageClass with the `ebs.csi.aws.com` provisioner.
+ */
+
+export interface EbsStorageClassProps {
+  /** StorageClass name. */
+  name: string;
+  /** EBS volume type (default: "gp3"). */
+  type?: string;
+  /** IOPS for io1/io2/gp3 volumes. */
+  iops?: string | number;
+  /** Throughput for gp3 volumes (MiB/s). */
+  throughput?: string | number;
+  /** Enable encryption (default: true). */
+  encrypted?: boolean;
+  /** KMS key ID for encryption. */
+  kmsKeyId?: string;
+  /** Filesystem type (default: "ext4"). */
+  fsType?: string;
+  /** Reclaim policy (default: "Delete"). */
+  reclaimPolicy?: string;
+  /** Volume binding mode (default: "WaitForFirstConsumer"). */
+  volumeBindingMode?: string;
+  /** Allow volume expansion (default: true). */
+  allowVolumeExpansion?: boolean;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+}
+
+export interface EbsStorageClassResult {
+  storageClass: Record<string, unknown>;
+}
+
+/**
+ * Create an EbsStorageClass composite — returns prop objects for
+ * a StorageClass with the EBS CSI provisioner.
+ *
+ * @eks
+ * @example
+ * ```ts
+ * import { EbsStorageClass } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { storageClass } = EbsStorageClass({
+ *   name: "gp3-encrypted",
+ *   type: "gp3",
+ *   encrypted: true,
+ * });
+ * ```
+ */
+export function EbsStorageClass(props: EbsStorageClassProps): EbsStorageClassResult {
+  const {
+    name,
+    type = "gp3",
+    iops,
+    throughput,
+    encrypted = true,
+    kmsKeyId,
+    fsType = "ext4",
+    reclaimPolicy = "Delete",
+    volumeBindingMode = "WaitForFirstConsumer",
+    allowVolumeExpansion = true,
+    labels: extraLabels = {},
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const parameters: Record<string, string> = {
+    type,
+    fsType,
+    encrypted: String(encrypted),
+  };
+
+  if (iops !== undefined) parameters.iops = String(iops);
+  if (throughput !== undefined) parameters.throughput = String(throughput);
+  if (kmsKeyId) parameters.kmsKeyId = kmsKeyId;
+
+  const storageClassProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "storage" },
+    },
+    provisioner: "ebs.csi.aws.com",
+    parameters,
+    reclaimPolicy,
+    volumeBindingMode,
+    allowVolumeExpansion,
+  };
+
+  return { storageClass: storageClassProps };
+}

package/src/composites/efs-storage-class.ts

@@ -0,0 +1,77 @@
+/**
+ * EfsStorageClass composite — StorageClass for AWS EFS CSI driver.
+ *
+ * @eks Creates a StorageClass with the `efs.csi.aws.com` provisioner.
+ * EFS provides ReadWriteMany access mode (shared across pods/nodes).
+ */
+
+export interface EfsStorageClassProps {
+  /** StorageClass name. */
+  name: string;
+  /** EFS filesystem ID (required). */
+  fileSystemId: string;
+  /** Directory permissions (default: "700"). */
+  directoryPerms?: string;
+  /** Base path for dynamic provisioning (default: "/dynamic_provisioning"). */
+  basePath?: string;
+  /** Reclaim policy (default: "Delete"). */
+  reclaimPolicy?: string;
+  /** Provisioning mode (default: "efs-ap"). */
+  provisioningMode?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+}
+
+export interface EfsStorageClassResult {
+  storageClass: Record<string, unknown>;
+}
+
+/**
+ * Create an EfsStorageClass composite — returns prop objects for
+ * a StorageClass with the EFS CSI provisioner.
+ *
+ * @eks
+ * @example
+ * ```ts
+ * import { EfsStorageClass } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { storageClass } = EfsStorageClass({
+ *   name: "efs-shared",
+ *   fileSystemId: "fs-12345678",
+ * });
+ * ```
+ */
+export function EfsStorageClass(props: EfsStorageClassProps): EfsStorageClassResult {
+  const {
+    name,
+    fileSystemId,
+    directoryPerms = "700",
+    basePath = "/dynamic_provisioning",
+    reclaimPolicy = "Delete",
+    provisioningMode = "efs-ap",
+    labels: extraLabels = {},
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const storageClassProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "storage" },
+    },
+    provisioner: "efs.csi.aws.com",
+    parameters: {
+      provisioningMode,
+      fileSystemId,
+      directoryPerms,
+      basePath,
+    },
+    reclaimPolicy,
+  };
+
+  return { storageClass: storageClassProps };
+}

package/src/composites/external-dns-agent.ts

@@ -0,0 +1,174 @@
+/**
+ * ExternalDnsAgent composite — Deployment + IRSA ServiceAccount + ClusterRole + ClusterRoleBinding.
+ *
+ * @eks ExternalDNS for Route53 DNS management. Common in production EKS setups
+ * where Ingress/Service hostnames should automatically create DNS records.
+ */
+
+export interface ExternalDnsAgentProps {
+  /** IAM Role ARN for IRSA (needs Route53 permissions). */
+  iamRoleArn: string;
+  /** Domain filters — only manage DNS records for these domains. */
+  domainFilters: string[];
+  /** DNS provider (default: "aws"). */
+  provider?: string;
+  /** Source of DNS records (default: "ingress"). */
+  source?: string;
+  /** TXT record owner ID for identifying managed records. */
+  txtOwnerId?: string;
+  /** Agent name (default: "external-dns"). */
+  name?: string;
+  /** Container image (default: "registry.k8s.io/external-dns/external-dns:v0.14.0"). */
+  image?: string;
+  /** Namespace (default: "kube-system"). */
+  namespace?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+}
+
+export interface ExternalDnsAgentResult {
+  deployment: Record<string, unknown>;
+  serviceAccount: Record<string, unknown>;
+  clusterRole: Record<string, unknown>;
+  clusterRoleBinding: Record<string, unknown>;
+}
+
+/**
+ * Create an ExternalDnsAgent composite — returns prop objects for
+ * a Deployment, ServiceAccount (with IRSA), ClusterRole, and ClusterRoleBinding.
+ *
+ * @eks
+ * @example
+ * ```ts
+ * import { ExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, serviceAccount, clusterRole, clusterRoleBinding } = ExternalDnsAgent({
+ *   iamRoleArn: "arn:aws:iam::123456789012:role/external-dns-role",
+ *   domainFilters: ["example.com"],
+ *   txtOwnerId: "my-cluster",
+ * });
+ * ```
+ */
+export function ExternalDnsAgent(props: ExternalDnsAgentProps): ExternalDnsAgentResult {
+  const {
+    iamRoleArn,
+    domainFilters,
+    provider = "aws",
+    source = "ingress",
+    txtOwnerId,
+    name = "external-dns",
+    image = "registry.k8s.io/external-dns/external-dns:v0.14.0",
+    namespace = "kube-system",
+    labels: extraLabels = {},
+  } = props;
+
+  const saName = `${name}-sa`;
+  const clusterRoleName = `${name}-role`;
+  const bindingName = `${name}-binding`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build args for external-dns
+  const args: string[] = [
+    `--source=${source}`,
+    `--provider=${provider}`,
+    "--policy=upsert-only",
+    "--registry=txt",
+  ];
+
+  for (const domain of domainFilters) {
+    args.push(`--domain-filter=${domain}`);
+  }
+
+  if (txtOwnerId) {
+    args.push(`--txt-owner-id=${txtOwnerId}`);
+  }
+
+  const deploymentProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "dns" },
+    },
+    spec: {
+      replicas: 1,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          containers: [
+            {
+              name,
+              image,
+              args,
+              resources: {
+                requests: { cpu: "50m", memory: "64Mi" },
+                limits: { cpu: "100m", memory: "128Mi" },
+              },
+              securityContext: {
+                runAsNonRoot: true,
+                runAsUser: 65534,
+                readOnlyRootFilesystem: true,
+                allowPrivilegeEscalation: false,
+              },
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  const serviceAccountProps: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "dns" },
+      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: ["services", "endpoints", "pods"], verbs: ["get", "watch", "list"] },
+      { apiGroups: ["extensions", "networking.k8s.io"], resources: ["ingresses"], verbs: ["get", "watch", "list"] },
+      { apiGroups: [""], resources: ["nodes"], verbs: ["list", "watch"] },
+    ],
+  };
+
+  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,
+      },
+    ],
+  };
+
+  return {
+    deployment: deploymentProps,
+    serviceAccount: serviceAccountProps,
+    clusterRole: clusterRoleProps,
+    clusterRoleBinding: clusterRoleBindingProps,
+  };
+}