oke-multi-home-pods

name	oke-multi-home-pods
description	Use this skill when the user wants to configure or generate artifacts for Oracle Kubernetes Engine multi-homed pods with OCI VCN-Native CNI, Multus CNI, ipvlan, and Generic VNIC Attachment (GVA), including discovery-backed customer input collection, node pool JSON, NADs, cloud-init, test pod manifests, and verification steps.

OKE Multi-Home Pods

Use this skill for end-to-end OKE multi-home pod workflows that combine:

• OCI VCN-Native CNI
• Multus CNI
• ipvlan for the secondary interface
• GVA-backed secondary VNICs on worker nodes

This skill supports two modes:

• use an existing GVA-enabled node pool
• create a new GVA-enabled node pool

Do not use this skill for generic GVA Application Resource scheduling workflows. For that case, prefer the existing oke-gva-deployer skill.

What To Read

Read only what you need:

• references/guide.md for the technical workflow and example manifests
• assets/customer-input-template.yaml for required fields, prompting metadata, and defaults

Use these scripts instead of reconstructing the workflow from scratch:

• scripts/check_multus.sh
• scripts/discover_customer_inputs.py
• scripts/render_artifacts.py
• scripts/scaffold_workspace.sh

Workflow

1. Confirm the target cluster explicitly. Do not run discovery against an implicit or default cluster.

2. If the user wants discovery or does not know cluster metadata, run:

bash scripts/scaffold_workspace.sh
python3 scripts/discover_customer_inputs.py --cluster <cluster-name-or-ocid>

This creates customer-input-template.yaml in the current working directory if it is missing, then writes customer-input.discovered.yaml with discovered cluster metadata and cached subnet/NSG choices.

3. Check whether Multus is already deployed on the target cluster context:

bash scripts/check_multus.sh --context <kubectl-context>

If multus_installed is false, stop and ask the user whether they want to install Multus before continuing.

• Do not assume Multus is present because the guide requires it.
• Do not proceed to final multi-home pod manifests until the user either confirms Multus is installed or asks you to install it.

4. Use the x_codex_prompting block in the customer input YAML to ask for missing values.

• Ask in small batches.
• Use encoded options where they exist.
• Use cached subnet and NSG discovery data to present numbered choices.
• Do not guess interface names; inspect them on a real worker node and then ask the user to confirm.
• Respect deployment.mode. If it is existing-gva-node-pool, do not require create-only node pool fields and do not render nodepool.json. If it is create-gva-node-pool, require the node pool creation inputs and render nodepool.json.

5. When required values are complete, render the artifacts:

python3 scripts/render_artifacts.py --input customer-input.discovered.yaml

If discovery was not used:

python3 scripts/render_artifacts.py --input customer-input-template.yaml

6. Before handoff, run strict validation:

python3 scripts/render_artifacts.py --input <input-yaml> --strict

Expected Outputs

The renderer writes rendered/ in the current working directory:

• nodepool.json
• cloud-init.sh
• oci-vcn-native-network-nad.yaml
• ipvlan-network.yaml
• sleep-forever-pod.yaml
• verification.md

Operating Rules

• Never invent OCIDs, subnet IDs, NSG IDs, interface names, or image IDs.
• Never auto-select a cluster without explicit user input in the current turn.
• Use discovery to reduce prompting, not to bypass customer confirmation.
• Always check Multus on the explicit target cluster context before assuming the cluster is ready for multi-home pods.
• If Multus is missing, ask the user whether they want to install it before continuing.
• Keep eth0 pinned to the intended default interface.
• Keep net1 pinned to the intended secondary interface.
• Do not silently choose subnets or NSGs from discovery results.
• If the cluster CNI type is not OCI_VCN_IP_NATIVE, stop and explain the mismatch.
• If GVA is not enabled or planned on the node pool, stop and explain that multi-homed pods require the needed secondary VNICs.

Interface Inspection

When interface names are still unknown, prefer kubectl debug node/... against a worker in the target node pool.

Primary command:

kubectl --context <kubectl-context> debug node/<node-name> -it --image=nicolaka/netshoot --profile=sysadmin -- chroot /host ip -br addr

Fallback command:

kubectl --context <kubectl-context> debug node/<node-name> -it --image=nicolaka/netshoot --profile=sysadmin -- chroot /host ifconfig -a

Useful follow-up:

kubectl --context <kubectl-context> debug node/<node-name> -it --image=nicolaka/netshoot --profile=sysadmin -- chroot /host ip route

Use these results to identify:

• the interface carrying the default pod network subnet
• the interface carrying the secondary net1 subnet
• the exact interface names to place into interfaces.default_network.interface_name and interfaces.secondary_network.interface_name

When To Use Which Script

• Use scripts/scaffold_workspace.sh when the working directory does not yet have the template files.
• Use scripts/check_multus.sh immediately after the cluster is identified and before generating final multi-home pod artifacts.
• Use scripts/discover_customer_inputs.py when the user has provided an explicit cluster name, context, or OCID and wants you to auto-populate cluster metadata.
• Use scripts/render_artifacts.py once the customer input YAML is complete enough to render outputs.

Response Shape

Keep operational responses short and ordered like this:

1. Status
2. Missing Inputs or Generated Files
3. Commands to Run
4. Validation
5. Risks