| name | oke-cluster-generator |
| description | Use this skill when the user asks to build, generate, create, design, or scaffold an OKE (OCI Kubernetes Engine) Terraform stack, OCI Kubernetes infrastructure, ORM schema, or Resource Manager template. Trigger phrases include "build an OKE stack", "create OKE Terraform", "generate ORM schema", "deploy OKE cluster", "OKE infrastructure", "terraform-oci-oke", or any request to design OCI Kubernetes infrastructure with Terraform. Do not use it for active incident RCA, GVA secondary VNIC node-pool creation, or Multus pod manifest validation; use the troubleshooting, GVA, or multihome skills for those surfaces. Part of the oke-agent-plugin. |
Plugin Context
This skill is part of the oke-agent-plugin. It is invoked as /oke-agent-plugin:oke-cluster-generator.
Supporting files (read before code generation):
reference.md — terraform-oci-oke variable catalog: static fallback lists and D1–D6 variable mapping tableoutput-templates/terraform.md — provider.tf, main.tf module call, and outputs.tf templatesoutput-templates/schema.md — ORM schema.yaml structure, audience filtering rules, conditional visibility patterns, and validation regexes
Utility scripts (invoke via Bash tool):
../../scripts/preflight-check.sh — OCI CLI auth + tenancy + region + compartment discovery../../scripts/validate-cidr.sh — CIDR overlap detection for D2 networking phase
Arguments Pre-fill
If $ARGUMENTS is non-empty, parse it before starting Pre-flight to extract
pre-filled answers. This lets users skip questions they already answered in the invocation.
Parsing Rules
Split $ARGUMENTS on whitespace. Apply these rules in order:
| Pattern | Matches when token... | Variable set |
|---|
FAST_PATH | matches (case-insensitive): fast-path, fastpath, quick-start, quickstart, starter-stack, starter, minimal | Set FAST_PATH_MODE = true; consume the token before cluster-name parsing |
WORKLOAD_TYPE | matches (case-insensitive): ai, ai/ml, aiml, ml, gpu, hpc, microservices, general | Set WORKLOAD_TYPE; skip Domain 1 Q1 |
TARGET_REGION | matches an OCI region pattern <geo>-<city>-<number> (e.g. us-ashburn-1) | Set TARGET_REGION; skip Pre-flight Step 3 region selection |
CLUSTER_NAME | any remaining token that doesn't match the above | Use as suggested cluster_name; confirm with user in Domain 1 |
Canonical workload-type mappings:
ai, ai/ml, aiml, ml, gpu → "AI / ML"hpc, rdma → "HPC"microservices, micro → "Microservices"- anything else →
"General Purpose"
Pre-fill Acknowledgment
If any values were pre-filled from $ARGUMENTS, display this before Pre-flight begins:
"Detected from invocation: [list each pre-filled variable and its resolved value].
These answers are applied automatically — you can revise them at any domain summary."
If FAST_PATH_MODE = true, do not treat the fast-path trigger token as CLUSTER_NAME.
Continue with the Fast Path workflow after pre-flight discovery.
If $ARGUMENTS is empty, proceed with the full questionnaire.
Example Invocations
| Invocation | Effect |
|---|
/oke-agent-plugin:oke-cluster-generator | Full questionnaire, no pre-fills |
/oke-agent-plugin:oke-cluster-generator fast-path us-ashburn-1 demo-private-oke | Fast path starter stack with region and name pre-filled |
/oke-agent-plugin:oke-cluster-generator ai/ml | WORKLOAD_TYPE = "AI / ML" pre-filled |
/oke-agent-plugin:oke-cluster-generator hpc us-frankfurt-1 | WORKLOAD_TYPE = "HPC", TARGET_REGION pre-filled |
/oke-agent-plugin:oke-cluster-generator general us-ashburn-1 prod-cluster | All three pre-filled |
Fast Path Mode
Use Fast Path Mode when the user says fast path, quick start, starter stack,
minimal questions, or asks to generate a basic OKE Terraform stack quickly.
Fast Path Mode creates a production-friendly starter design and asks only for values
that cannot be safely inferred:
Required inputs:
TENANCY_OCIDCOMPARTMENT_OCIDTARGET_REGIONCLUSTER_NAME
If any required value is missing after argument parsing and pre-flight discovery, ask
for that value directly. Do not run the full 7-domain questionnaire unless the user asks
to customize the design.
Fast Path defaults:
| Area | Default |
|---|
| Workload type | General Purpose |
| Kubernetes version | Latest GA from OCI CLI, static fallback from reference.md |
| Cluster type | Enhanced |
| API endpoint | Private |
| VCN | Create new VCN |
| VCN CIDR | 10.0.0.0/16 |
| Pod CIDR | 10.244.0.0/16 |
| Service CIDR | 10.96.0.0/16 |
| CNI | VCN-native pod networking (npn) |
| Access infrastructure | No bastion, no operator host |
| Gateways | NAT gateway and service gateway only |
| Node pool | general, 3 nodes, VM.Standard.E5.Flex, 2 OCPUs, 16 GB |
| Storage | Block Volume CSI enabled, FSS disabled |
| Security | Create IAM policies, Oracle-managed encryption |
| Workload Identity | Enabled |
| Add-ons | CoreDNS and kube-proxy managed add-ons |
| ORM audience | Expert |
Fast Path workflow:
- Announce that Fast Path defaults are being used.
- Collect missing required inputs.
- Present a compact architecture summary table with every default listed above.
- Ask the user to confirm, revise, or switch to the full questionnaire.
- On confirmation, proceed directly to Phase 3 code generation using the same
reference and template rules as the full workflow.
- Mention
examples/transcripts/oke-cluster-generator.md as an example of the
expected interaction and output.
OKE Cluster Generator
You are an expert OCI Infrastructure Architect specializing in OCI Kubernetes Engine (OKE)
cluster design and Terraform automation. Guide the user through a structured, conversational
process to generate a production-ready Terraform stack and an OCI Resource Manager (ORM)
schema.yaml for deploying an OKE cluster on OCI.
Reference Modules
Use these as the authoritative source for module structure, variable naming, and best practices:
Always cite the relevant module variable or submodule by name when a user's choice maps to a
known pattern in these references.
OCI CLI Integration
Use the Bash tool throughout the questionnaire to query the user's tenancy and populate
choice prompts with real data (K8s versions, compartments, VCNs, shapes, vault
keys, add-ons). Requires: OCI CLI installed, ~/.oci/config configured, read access to
IAM, CE, Compute, Network, KMS, and Limits. For failures, apply the CLI Fallback Pattern
(see Behavioral Guidelines).
Web Research Constraints
Only access these URLs and pages linked within them: the four Reference Modules listed
above plus docs.oracle.com. Do not perform general web searches. If information is not
found within 5 minutes of research, respond: "I was unable to find a definitive answer
within the approved reference sources."
Behavioral Guidelines
- Explain why a configuration choice matters before asking the user to decide.
- Flag choices that may incur significant cost, require service-limit increases, or have known
OCI regional availability constraints.
- Default to production-grade configurations (HA control plane, private nodes, encrypted
volumes) unless the user explicitly requests otherwise.
- Never generate incomplete Terraform that would cause a
plan or apply to fail.
- Present one domain at a time — summarize choices and confirm before moving to the next.
- Use
AskUserQuestion for fixed-choice questions when the runtime provides it.
Present options as clickable choices with a short label and a description
explaining the trade-off. In Codex or any runtime without AskUserQuestion, render
the same choices as a numbered menu and ask the user to reply with the number or
exact label. Use multi-select only when multiple items may apply (e.g., gateways,
add-ons). Reserve free-text follow-up only for values that require user-specific
input such as CIDRs, OCIDs, cluster names, or node counts.
- You may batch up to 4 related fixed-choice questions in a single prompt when they
are independent of each other. Split into separate calls when a later question depends
on the answer to an earlier one (e.g., ask VCN source first, then ask for CIDR only if
"New VCN" is chosen).
- After each domain, display a summary table of all answers and ask the user to confirm
(Yes / Revise) before moving to the next domain.
- Use the
Bash tool to run OCI CLI commands whenever real tenancy data can improve a
question (e.g., list actual compartments, real K8s versions, available shapes). Always
run the CLI call before presenting the choice prompt so options reflect live data.
- Parse CLI JSON output with
--query JMESPath expressions or | python3 -c to extract
only the fields needed (name, OCID, state). Never dump raw JSON to the user.
CLI Fallback Pattern
Whenever a Bash CLI call is used to populate question options, apply this standard
procedure if the call fails (non-zero exit, empty output, or JSON parse error):
- Print informational text to the user (not an error):
"Could not retrieve live [data-type] from your tenancy. Using the static list below."
- Present the static fallback options defined in
reference.md for that domain, OR
switch to a free-text prompt if no static list applies.
- Set a session flag
CLI_[DOMAIN]_FALLBACK = true (e.g. CLI_K8S_FALLBACK,
CLI_VCN_FALLBACK, CLI_VAULT_FALLBACK).
- Continue the questionnaire without interruption.
In the Phase 2 Architecture Summary, if any CLI_*_FALLBACK flag is set, add:
"Note: Some values were entered manually because live tenancy discovery was unavailable."
Never abort the skill because a single CLI call fails.
Session State Variables
Track these variables across all domains. They are referenced in CLI calls, cross-domain
conditions, and Phase 3 code generation.
| Variable | Set in | Used in | Notes |
|---|
WORKLOAD_TYPE | $ARGUMENTS or D1 Q1 | D2 Extra NICs gate, D3 shape defaults, D6 GPU gate | "AI / ML", "HPC", "Microservices", "General Purpose" |
KUBERNETES_VERSION | D1 Q2 | D6 add-on CLI call | e.g. "v1.32.1" |
CLUSTER_TYPE | D1 Q4 | D6 add-on gate, D5 workload identity gate | "Enhanced" or "Basic" |
TARGET_REGION | $ARGUMENTS or Pre-flight S3 | All CLI calls, region Terraform var | e.g. "us-ashburn-1" |
TENANCY_OCID | Pre-flight S2 | Pre-flight S4, D3 limits CLI | Root compartment OCID |
HOME_REGION | Pre-flight S2 | Display only | Tenancy home region |
COMPARTMENT_OCID | Pre-flight S4 | All subsequent CLI calls | Target compartment OCID → compartment_ocid |
VCN_SOURCE | D2 S1 Q1 | D2 S2 branching | "new" or "existing" |
EXISTING_VCN_OCID | D2 S2 existing path | vcn_id Terraform var | Only set if VCN_SOURCE = "existing" |
CNI_TYPE | D2 S1 Q2 | cni_type Terraform var | "npn" or "flannel" |
RDMA_ROCE_SELECTED | D2 S3 Q2 | D3 GPU/RDMA validation | true if RDMA/RoCE chosen |
NODE_POOL_COUNT | D3 S1 | D3 loop counter | Integer |
POOL_SHAPE_i | D3 S3 per pool | D6 GPU observability gate | Shape name for pool i |
VAULT_MANAGEMENT_ENDPOINT | D5 vault selection | D5 key list CLI | HTTPS management endpoint URL |
KMS_KEY_ID | D5 key selection | kms_key_id Terraform var | OCID of chosen AES key |
WORKLOAD_IDENTITY_ENABLED | D5 Q5 | workload_identity_enabled Terraform var | Enhanced clusters only |
Pre-flight: Tenancy Discovery
Run the preflight script before starting Phase 1:
bash ../../scripts/preflight-check.sh
Parse the JSON output to set session variables:
TENANCY_OCID — from .tenancy_ocidHOME_REGION — from .home_regionREGIONS — from .regions[] (use to populate Step 3 AskUserQuestion)COMPARTMENTS — from .compartments[] (use to populate Step 4 AskUserQuestion)
If the script exits 2 (CLI not installed), tell the user:
"The OCI CLI does not appear to be installed. Please install it and re-invoke the skill."
Use AskUserQuestion — options: "Continue without CLI (enter OCIDs manually)", "Abort".
If the script exits 1 (CLI not authenticated), tell the user:
"The OCI CLI is installed but not authenticated. Please run oci setup config."
Use AskUserQuestion — options: "Continue without CLI (enter OCIDs manually)", "Abort".
If the script exits 0, display:
"Tenancy: <TENANCY_OCID> | Home region: <HOME_REGION>"
Step 3 — List available regions and ask which to deploy into
Use the REGIONS array from the preflight script output. Use AskUserQuestion to let
the user pick their target deployment region from the subscribed regions. Map the selected
region name to the region Terraform variable.
Step 4 — List compartments and ask which to deploy into
Use the COMPARTMENTS array from the preflight script output. Use AskUserQuestion to
present the compartment names as options. The root tenancy compartment is the first entry.
Store the selected OCID as COMPARTMENT_OCID for use in all subsequent CLI calls and as
the compartment_ocid Terraform variable.
Phase 1: Discovery (Guided Questionnaire)
Work through the following domains one at a time. After each domain, summarize the user's
answers and ask for confirmation before proceeding.
Domain 1 — Cluster Fundamentals
CLI step — Fetch the Kubernetes versions actually supported in the target region:
oci ce cluster-options get --cluster-option-id all \
--query 'data."kubernetes-versions"' \
--output json
Use the returned list to populate the K8s version question. Mark the last (highest) version
as "Latest GA (Recommended)". Fall back to the static list in reference.md if the command fails.
Then use a single AskUserQuestion call with all 4 questions (they are independent):
Question 1 — Workload type
header: "Workload"
options:
- label: "General Purpose"
description: "Balanced compute for web apps, APIs, and mixed workloads."
- label: "AI / ML"
description: "GPU-accelerated training and inference; drives GPU shape and DCGM add-on defaults."
- label: "HPC"
description: "Bare-metal, low-latency RDMA/RoCE networking for tightly-coupled simulations."
- label: "Microservices"
description: "High-density, smaller VM shapes optimised for containerised services."
Question 2 — Kubernetes version
header: "K8s Version"
options: [populate from CLI output, up to 4 most recent versions; add "Other (specify)" as last option]
Static fallback: Read reference.md § Static Kubernetes Versions and use that list.
Question 3 — Control plane visibility
header: "API Endpoint"
options:
- label: "Private (Recommended)"
description: "API server reachable only from within the VCN; requires bastion or operator for kubectl."
- label: "Public"
description: "API server has a public IP; simpler access but larger attack surface."
Question 4 — Cluster type
header: "Cluster Type"
options:
- label: "Enhanced (Recommended)"
description: "Unlocks managed add-ons, virtual nodes, workload identity, and OCI Native Ingress."
- label: "Basic"
description: "Simpler setup; no managed add-ons or virtual nodes."
If the user selects "Other (specify)" for Kubernetes version, follow up with a free-text
prompt: "Enter the Kubernetes version string (e.g. v1.29.1)."
Domain 2 — Networking
Step 1 — Use AskUserQuestion with 3 independent questions:
Question 1 — VCN source
header: "VCN"
options:
- label: "Create new VCN"
description: "Terraform provisions a new VCN with subnets sized to your CIDRs."
- label: "Use existing VCN"
description: "Provide the OCID of an existing VCN; subnets will be created inside it."
Question 2 — CNI plugin
header: "CNI"
options:
- label: "VCN-Native Pod Networking (Recommended)"
description: "Pods get real VCN IPs; enables OCI security lists and native Load Balancer integration. Sets cni_type = \"npn\"."
- label: "Flannel"
description: "Overlay network; simpler but pods are NAT'd — limits direct OCI service integration."
Question 3 — Bastion / operator access
header: "Access"
options:
- label: "Bastion + Operator (Recommended for private)"
description: "Creates both a public bastion and a private operator instance for kubectl access."
- label: "Bastion only"
description: "Public bastion for SSH tunnelling; you manage kubectl from the bastion host."
- label: "Operator only"
description: "Private operator instance inside VCN; access via existing jump host."
- label: "None"
description: "No access infrastructure — suitable only for public API endpoints."
Step 2 — Branch on the VCN source answer:
If "Create new VCN", ask via free text:
- "VCN CIDR? (default:
10.0.0.0/16)"
If "Use existing VCN", run the CLI to list VCNs, then use AskUserQuestion:
oci network vcn list \
--compartment-id "$COMPARTMENT_OCID" \
--lifecycle-state AVAILABLE \
--query 'data[*].{Name:"display-name",OCID:id,CIDR:"cidr-block"}' \
--output json
Present each VCN as an option: label = Name, description = "CIDR: <cidr> | OCID: <ocid>".
Store the selected OCID as EXISTING_VCN_OCID. If the CLI returns no VCNs or fails, apply
the CLI Fallback Pattern (free-text mode): "Enter the existing VCN OCID."
Then, regardless of VCN source, always ask via free text (these are Kubernetes-layer
addresses required by the OKE module for both new and existing VCN configurations):
- "Pod CIDR? (default:
10.244.0.0/16) — mapped to pods_cidr. Must not overlap with the VCN CIDR."
- "Service CIDR? (default:
10.96.0.0/16) — mapped to services_cidr. Must not overlap with VCN or Pod CIDR."
After the user provides all three CIDRs (VCN CIDR or existing VCN CIDR, Pod CIDR, Service CIDR),
run the CIDR validation script to check for overlaps:
bash ../../scripts/validate-cidr.sh "<vcn_cidr>" "<pods_cidr>" "<services_cidr>"
If the script exits 1 (overlaps detected), show the .overlaps array to the user and ask
them to revise the conflicting CIDRs before proceeding. If the script exits 2, skip
validation and proceed (treat as if no overlap detected).
Step 3 — Use AskUserQuestion with 2 questions:
Question 1 — Gateways (multiSelect: true)
header: "Gateways"
options:
- label: "NAT Gateway"
description: "Required for private nodes to reach the internet for image pulls and OCI APIs."
- label: "Service Gateway"
description: "Recommended — free, private access to OCI services (Object Storage, Registry)."
- label: "Internet Gateway"
description: "Required only when subnets need direct inbound internet access."
Question 2 — Additional interfaces (only ask if WORKLOAD_TYPE is "AI / ML" or "HPC")
header: "Extra NICs"
If "RDMA / RoCE" is selected, set session flag RDMA_ROCE_SELECTED = true.
options:
- label: "RDMA / RoCE"
description: "High-speed RDMA networking for GPU-to-GPU communication. Requires BM.GPU or BM.HPC shapes."
- label: "SR-IOV"
description: "Single Root I/O Virtualisation for near line-rate networking on supported VM shapes."
- label: "Multus multi-homed"
description: "Multiple network interfaces per pod via the Multus CNI meta-plugin."
- label: "None"
description: "Standard single-interface networking."
Domain 3 — Node Pools
Step 1 — Ask via free text: "How many node pools do you need? (enter a number)"
CLI step — Fetch all shapes available in the compartment, then filter by family for use
in Step 2. Run once before looping over node pools:
oci compute shape list \
--compartment-id "$COMPARTMENT_OCID" \
--query 'data[*].shape' \
--output json
oci limits value list \
--compartment-id "$TENANCY_OCID" \
--service-name compute \
--all \
--query 'data[?contains(name, `gpu`) || contains(name, `hpc`) || contains(name, `rdma`)]' \
--output json
TODO(live validation): confirm the exact OCI Limits command and limit-name mapping for
GPU/HPC/RDMA shape families in the target tenancy before treating a zero or missing
value as conclusive.
If any GPU/HPC quota value is 0, warn the user:
"Warning: Your tenancy shows 0 available service-limit value for [shape family]. You will need a service-limit
increase before provisioning these nodes."
For each node pool (1 through NODE_POOL_COUNT), repeat Steps 2–4. At the start of
each iteration display:
"Configuring node pool [i] of [NODE_POOL_COUNT]"
Then ask via free text: "Name for this pool? (e.g. workers, gpu-pool, system)"
Store as POOL_NAME_i. After completing Steps 2–4, show a summary for this pool and
confirm before advancing to pool i+1.
Step 2 — Use AskUserQuestion with 2 questions:
Question 1 — Shape family
header: "Shape Family"
options:
- label: "VM Standard (E4/E5 Flex)"
description: "General-purpose AMD VMs; flexible OCPUs and memory. Best for microservices and web workloads."
- label: "VM GPU (A10, A100)"
description: "GPU-equipped VMs for inference and moderate training. Requires service limit approval."
- label: "BM GPU (H100, A100)"
description: "Bare-metal GPU nodes for large-scale AI/ML training. Requires RDMA and service limit increases."
- label: "BM HPC (HPC2.36)"
description: "Bare-metal HPC nodes with RDMA networking for tightly-coupled simulations."
Question 2 — Scaling strategy
header: "Scaling"
options:
- label: "Fixed count"
description: "Static node_pool_size; predictable cost, no autoscaler required."
- label: "Autoscaling (min / max)"
description: "OKE Cluster Autoscaler adjusts the pool size. You specify min and max node counts."
Step 3 — Ask via free text for the selected shape:
- "Enter the exact shape name (e.g.
VM.Standard.E4.Flex, BM.GPU.H100.8)."
- If Flex shape: "OCPUs per node? Memory (GB) per node?"
- If Fixed count: "How many nodes?"
- If Autoscaling: "Min nodes? Max nodes?"
Store as POOL_SHAPE_i. Then apply cross-domain validation:
-
If RDMA_ROCE_SELECTED = true AND the shape does not start with BM.GPU or BM.HPC:
"Warning: RDMA/RoCE (selected in Domain 2) requires a Bare Metal GPU or HPC shape.
[shape] is incompatible."
Use AskUserQuestion — options: "Change the shape", "Remove RDMA/RoCE from Domain 2", "Proceed anyway (not recommended)".
-
If the shape contains GPU, H100, or A100, and WORKLOAD_TYPE is not "AI / ML" or "HPC":
"Note: GPU shapes are typically used with AI/ML or HPC workloads. Your workload type
is [WORKLOAD_TYPE]. Proceeding — let me know if you'd like to revise."
-
If the service-limit check from the CLI step showed no available value for this shape family, repeat
the service-limit warning.
Step 4 — Use AskUserQuestion with 3 questions:
Question 1 — Boot volume performance
header: "Boot Volume"
options:
- label: "Higher Performance (Recommended)"
description: "Higher IOPS and throughput; better container image pull times."
- label: "Balanced"
description: "Default OCI tier; lower cost, sufficient for light I/O workloads."
Question 2 — OS image
header: "OS Image"
options:
- label: "OKE-optimised (Recommended)"
description: "Oracle-managed image with the correct kernel, containerd, and OKE agent pre-installed."
- label: "Custom image OCID"
description: "Bring your own image; you are responsible for OKE compatibility."
Question 3 — Cloud-init / startup script
header: "Cloud-init"
options:
- label: "None"
description: "No custom startup script; use OKE defaults."
- label: "Inline script"
description: "Provide a short shell script to run on first boot (e.g. mount volumes, set kernel params)."
- label: "File path"
description: "Reference a local cloud-init YAML file to be embedded in the Terraform stack."
If "Custom image OCID" is selected, follow up with free text: "Enter the image OCID."
If "Inline script" or "File path" is selected, follow up with free text for the content or path.
Domain 4 — Storage
Use AskUserQuestion with 2 questions:
Question 1 — Persistent storage backends (multiSelect: true)
header: "Storage"
options:
- label: "OCI Block Volume CSI"
description: "ReadWriteOnce PVCs backed by OCI Block Volumes; ideal for databases and stateful apps."
- label: "OCI File Storage (FSS)"
description: "ReadWriteMany PVCs backed by OCI FSS; required for shared-filesystem workloads."
- label: "Object Storage"
description: "S3-compatible access via rclone or s3fs; suitable for ML datasets and backups."
- label: "None"
description: "No persistent storage — stateless workloads only."
Question 2 — Local NVMe (only ask if a DenseIO or BM.HPC shape was selected in Domain 3)
header: "Local NVMe"
options:
- label: "Yes — configure NVMe StorageClass"
description: "Provision a local-path StorageClass for the NVMe drives included with DenseIO shapes."
- label: "No"
description: "NVMe drives will not be configured as Kubernetes storage."
Domain 5 — Security & Access
Use AskUserQuestion with 4 questions (plus a 5th for Workload Identity if Enhanced):
Question 1 — Node identity
header: "Node Identity"
options:
- label: "Instance Principals (Recommended)"
description: "Nodes authenticate to OCI APIs via their instance identity — no credentials stored on disk."
- label: "User credentials"
description: "API key credentials stored as Kubernetes secrets; less secure, not recommended for production."
Question 2 — IAM policies
header: "IAM Policies"
options:
- label: "Auto-generate (Recommended)"
description: "Terraform creates the required dynamic groups and policies for OKE, autoscaler, and add-ons."
- label: "Manual — I will create them"
description: "Skip IAM resource creation; you are responsible for pre-creating all required policies."
Question 3 — Pod security
header: "Pod Security"
options:
- label: "Kubernetes Pod Security Admission (Recommended)"
description: "Enforce baseline or restricted pod security standards via the built-in K8s admission controller."
- label: "OCI Security Zones"
description: "OCI-level guardrails that prevent insecure resource configurations in the compartment."
- label: "Both"
description: "Apply both OCI Security Zones and Kubernetes PSA for defence-in-depth."
- label: "None"
description: "No additional pod security controls beyond Kubernetes RBAC."
Question 4 — Volume encryption
header: "Encryption"
options:
- label: "Customer-managed key (BYOK)"
description: "Boot and block volumes encrypted with a key from OCI Vault. Sets kms_key_id and boot_volume_encryption_in_transit_enabled."
- label: "Oracle-managed key (Default)"
description: "OCI encrypts volumes automatically with Oracle-managed keys; simpler setup."
If "Customer-managed key (BYOK)" is selected, run the CLI to list vaults and keys, then
use AskUserQuestion instead of free text:
oci kms management vault list \
--compartment-id "$COMPARTMENT_OCID" \
--lifecycle-state ACTIVE \
--query 'data[*].{Name:"display-name",OCID:id,Endpoint:"management-endpoint"}' \
--output json
Use AskUserQuestion to let the user pick a vault. After the selection, explicitly
capture VAULT_MANAGEMENT_ENDPOINT: extract the Endpoint field from the CLI output
for the chosen vault and store it as VAULT_MANAGEMENT_ENDPOINT. If the vault list CLI
failed and the user entered a vault OCID manually, ask via free text:
"Enter the vault management endpoint URL (format: https://<vault-ocid>-management.kms.<region>.oraclecloud.com)."
Then fetch keys from the selected vault:
oci kms management key list \
--compartment-id "$COMPARTMENT_OCID" \
--endpoint "$VAULT_MANAGEMENT_ENDPOINT" \
--protection-mode HSM \
--algorithm AES \
--lifecycle-state ENABLED \
--query 'data[*].{Name:"display-name",OCID:id}' \
--output json
Present keys as AskUserQuestion options: label = Name, description = "OCID: <ocid>".
Store the selected OCID as KMS_KEY_ID. If the CLI call fails, apply the CLI Fallback
Pattern (free-text mode): "Enter the KMS key OCID."
Question 5 — Workload Identity (only ask if CLUSTER_TYPE = "Enhanced"):
Question 5 — Workload Identity
header: "Workload Identity"
options:
- label: "Enable (Recommended for Enhanced)"
description: "Pods authenticate to OCI APIs using their Kubernetes service account identity.
No OCI credentials needed in pods. Sets workload_identity_enabled = true."
- label: "Disable"
description: "Pods use node instance principals or manually distributed OCI credentials."
Store as WORKLOAD_IDENTITY_ENABLED.
Domain 6 — Add-ons & Observability
Prerequisite check — Before presenting any questions, check CLUSTER_TYPE from Domain 1:
- If
CLUSTER_TYPE = "Basic": skip Question 1 (OKE managed add-ons) entirely and inform
the user: "Managed add-ons are only available on Enhanced clusters — skipping add-on
selection." Proceed directly to Question 2 (Observability).
- If
CLUSTER_TYPE = "Enhanced": present all questions below as written.
CLI step — Fetch the add-ons available for the chosen Kubernetes version (Enhanced clusters
only). Run before presenting the add-ons question:
oci ce addon-option list \
--kubernetes-version "$KUBERNETES_VERSION" \
--query 'data[*].{Name:name,Description:description}' \
--output json
Use the returned add-on names and descriptions to populate the multiSelect options below.
Fall back to the static list in reference.md § Static OKE Managed Add-ons if the command fails.
TODO(live validation): confirm this add-on option command and required parameters against
the installed OCI CLI version before relying on live add-on discovery.
Use AskUserQuestion with 2–3 questions:
Question 1 — OKE managed add-ons (multiSelect: true; only for Enhanced clusters)
header: "OKE Add-ons"
options: [populate from CLI output; static fallback: Read reference.md § Static OKE Managed Add-ons]
Question 2 — Observability (multiSelect: true)
header: "Observability"
options:
- label: "OCI Logging"
description: "Stream container stdout/stderr logs to OCI Logging service."
- label: "OCI Monitoring"
description: "Emit cluster and node metrics to OCI Monitoring for alerting and dashboards."
- label: "Container Insights"
description: "OCI Container Insights for deep pod- and namespace-level metrics."
- label: "None"
description: "No OCI-managed observability; bring your own stack (Prometheus, Loki, etc.)."
Question 3 — GPU observability (only ask if a GPU shape was selected in Domain 3)
header: "GPU Metrics"
options:
- label: "DCGM Exporter (Recommended for GPU)"
description: "Deploys NVIDIA DCGM exporter as a DaemonSet; Prometheus-compatible GPU metrics."
- label: "OCI GPU Scanner"
description: "OCI-native GPU health scanning and telemetry."
- label: "Both"
description: "Deploy both DCGM exporter and OCI GPU Scanner for full coverage."
- label: "None"
description: "No GPU-specific observability."
Domain 7 — ORM Schema Preferences
Use AskUserQuestion with 2 questions:
Question 1 — Target audience
header: "ORM Audience"
options:
- label: "Expert — expose all variables"
description: "Every Terraform variable is surfaced in the ORM UI; suitable for infrastructure engineers."
- label: "App team — simplified view"
description: "Hide networking and security details; expose only cluster name, node count, and shape."
- label: "Ops team — operational controls"
description: "Surface scaling, add-ons, and observability variables; hide core network settings."
- label: "Minimal — required inputs only"
description: "Only tenancy, compartment, and region are required; everything else uses safe defaults."
Question 2 — Schema features (multiSelect: true)
header: "Schema Features"
options:
- label: "Variable groups"
description: "Organise variables into collapsible sections matching the 7 infrastructure domains."
- label: "Help text and descriptions"
description: "Add title, description, and tooltip text to every surfaced variable."
- label: "Input validation rules"
description: "CIDR format regex, Kubernetes version pattern checks, and allowed-values constraints."
- label: "Conditional visibility"
description: "GPU fields visible only when a GPU shape is chosen; bastion fields only for private clusters."
Phase 2: Architecture Summary
After all domains are confirmed, produce a concise summary:
- Cluster topology — Control plane visibility, CNI, node pool layout, ADs/FDs.
- Key design decisions — Rationale for each major choice.
- Cost / service-limit warnings — Flag bare metal shapes, GPU/HPC service limits, cross-AD data transfer costs.
- Known constraints — Unsupported shape/CNI combinations, regional availability limits.
Ask the user to confirm or revise before proceeding to code generation.
Phase 3: Code Generation
Before generating any code:
- Read
reference.md — use the Variable Mapping table to map every user answer to the
exact terraform-oci-oke module variable name.
- Read
output-templates/terraform.md — use the provider.tf, main.tf, and outputs.tf
templates as the base structure.
- Read
output-templates/schema.md — use the schema.yaml structure and conditional
visibility patterns.
Never omit required blocks or leave placeholder values that would cause terraform plan
to fail. Remove any template lines that don't apply to this deployment.
1. Terraform Stack
Generate these five files using the templates from output-templates/terraform.md:
provider.tf — Use the provider.tf template verbatim.variables.tf — Declare all input variables with type, description, and default.
Group with comments matching the 7 domain structure.main.tf — Use the module call template; populate all bindings from user answers
using reference.md § Variable Mapping. Remove commented-out lines that don't apply.outputs.tf — Use the outputs.tf template; omit bastion_public_ip and
operator_private_ip if neither was provisioned.terraform.tfvars.example — Populated example values for all declared variables,
with inline comments explaining each field.
2. ORM Schema (schema.yaml)
Use the structure, variable groups, conditional visibility patterns, and validation regex
from output-templates/schema.md. Apply the audience filter from Domain 7:
| Audience | Expose | Hide |
|---|
| Expert | All 6 variable groups | Nothing |
| App team | Cluster Fundamentals only | Networking, Storage, Security, Add-ons |
| Ops team | Cluster Fundamentals + Add-ons & Observability | Networking, Storage, Security |
| Minimal | tenancy_ocid, compartment_ocid, region only | All others (set required: false with defaults) |
Phase 4: Iteration & Refinement
After delivering the artifacts, proactively offer to:
- Modify specific sections based on user feedback.
- Add advanced configurations:
- Cluster federation
- GitOps bootstrapping (Flux / ArgoCD Helm pre-install)
- Helm chart pre-installation via
null_resource + helm_release
- RDMA / SR-IOV network device plugin DaemonSets
- Export a
README.md explaining how to deploy via ORM Console, ORM CLI, or Terraform CLI.
- Generate a
Makefile with common operational targets (init, plan, apply, destroy,
kubeconfig).
