From 08a056dbac0d5167c2508d33c6037b9ea315b8a0 Mon Sep 17 00:00:00 2001 From: RITHIKA KATHIRVEL Date: Thu, 13 Aug 2026 17:39:53 +0530 Subject: [PATCH] oci landing zone terraform module skills for IAM --- oci/SKILL.md | 62 ++-- .../README.txt | 94 +++++ .../terraform-oci-modules-iam-skill/SKILL.md | 77 ++++ .../agents/openai.yaml | 4 + .../references/input-collection.md | 329 ++++++++++++++++++ .../references/lifecycle-safety.md | 43 +++ .../references/main-tf-map.md | 108 ++++++ .../references/module-support.md | 27 ++ .../references/terraform-sources.md | 138 ++++++++ .../references/validation.md | 82 +++++ 10 files changed, 938 insertions(+), 26 deletions(-) create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/README.txt create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/SKILL.md create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/agents/openai.yaml create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/input-collection.md create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/lifecycle-safety.md create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/main-tf-map.md create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/module-support.md create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/terraform-sources.md create mode 100644 oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/validation.md diff --git a/oci/SKILL.md b/oci/SKILL.md index ca21127..80f9e39 100644 --- a/oci/SKILL.md +++ b/oci/SKILL.md @@ -1,11 +1,11 @@ --- name: oci -description: Oracle Cloud Infrastructure guidance for designing, operating, and troubleshooting OCI services, including OCI Kubernetes Engine (OKE), OCI Internet of Things Platform, OCI Functions deployment and troubleshooting, and Enterprise AI workflows for OCI Generative AI models, Responses API agents, RAG, cost estimation, governance, private endpoints, hosted agentic applications, and Oracle platform integrations. Use when the user asks about OKE cluster design, Terraform or Resource Manager planning, OKE incident troubleshooting, Generic VNIC Attachment, Multus, pod networking, node pools, add-ons, ingress, load balancers, OCIR image pulls, Workload Identity, Kubernetes workloads on OCI, OCI IoT domains or digital twins, device publish flows, OCI Functions setup, deployment, invocation, or troubleshooting, OCI Generative AI, Enterprise AI Models, Enterprise AI Agents, governed GenAI applications, agentic workflows, RAG on Oracle Cloud, or OCI Generative AI pricing. +description: Oracle Cloud Infrastructure guidance for designing, operating, and troubleshooting OCI services, including OCI Kubernetes Engine (OKE), OCI Internet of Things Platform, OCI Functions deployment and troubleshooting, OCI IAM Terraform configuration, and Enterprise AI workflows for OCI Generative AI models, Responses API agents, RAG, cost estimation, governance, private endpoints, hosted agentic applications, and Oracle platform integrations. Use when the user asks about OKE cluster design, Terraform or Resource Manager planning, OCI compartment hierarchy, classic IAM groups or group membership assignment, dynamic groups, IAM policies, OCI Identity Domains resources, OKE incident troubleshooting, Generic VNIC Attachment, Multus, pod networking, node pools, add-ons, ingress, load balancers, OCIR image pulls, Workload Identity, Kubernetes workloads on OCI, OCI IoT domains or digital twins, device publish flows, OCI Functions setup, deployment, invocation, or troubleshooting, OCI Generative AI, Enterprise AI Models, Enterprise AI Agents, governed GenAI applications, agentic workflows, RAG on Oracle Cloud, or OCI Generative AI pricing. --- # Oracle Cloud Infrastructure Skills -Use this domain for practical Oracle Cloud Infrastructure guidance. Current content covers OCI Kubernetes Engine (OKE): cluster design, operational troubleshooting, Generic VNIC Attachment (GVA), and Multus multi-interface pod validation. It covers OCI Internet of Things Platform resource discovery, digital twin lifecycle workflows, device publish flows, and optional MCP-assisted operation. It covers OCI Functions local deployment and diagnosis-first troubleshooting. It also covers Enterprise AI because that work is built around OCI Generative AI, OCI networking, IAM, cost estimation, hosted applications, and OCI platform integrations. +Use this domain for practical Oracle Cloud Infrastructure guidance. Current content covers OCI Kubernetes Engine (OKE): cluster design, operational troubleshooting, Generic VNIC Attachment (GVA), and Multus multi-interface pod validation. It covers OCI Internet of Things Platform resource discovery, digital twin lifecycle workflows, device publish flows, and optional MCP-assisted operation. It covers OCI Functions local deployment and diagnosis-first troubleshooting. It includes a constrained Terraform Configuration generator for OCI IAM compartments, groups, dynamic groups, policies, and Identity Domains resources. It also covers Enterprise AI because that work is built around OCI Generative AI, OCI networking, IAM, cost estimation, hosted applications, and OCI platform integrations. ## How to Use This Domain @@ -46,6 +46,11 @@ oci/ │ ├── scripts/ │ ├── templates/ │ └── tests/ +├── oci-landing-zone-terraform-module/ +│ └── terraform-oci-modules-iam-skill/ +│ ├── SKILL.md +│ ├── agents/ +│ └── references/ └── oke/ ├── cluster-design.md ├── troubleshooting.md @@ -61,19 +66,20 @@ oci/ ## Category Routing -| Topic | Start With | -|-------|------------| -| Design or scaffold an OKE cluster, Terraform stack, or OCI Resource Manager stack | Start with `oci/oke/cluster-design.md`, then load `oci/oke/skills/oke-cluster-generator/SKILL.md` | -| Troubleshoot OKE workloads, pods, services, DNS, add-ons, ingress, load balancers, image pulls, storage, Workload Identity, or cluster access | Start with `oci/oke/troubleshooting.md`, then load `oci/oke/skills/oke-troubleshooter/SKILL.md` | -| Configure OKE managed node pools with Generic VNIC Attachment secondary VNIC profiles and Application Resources | Start with `oci/oke/gva-node-pools.md`, then load `oci/oke/skills/oke-gva-deployer/SKILL.md` | -| Deploy or validate Multus NetworkAttachmentDefinitions and multi-interface pods on OKE | Start with `oci/oke/multus-multihome.md`, then load `oci/oke/skills/oke-multihome-deployer/SKILL.md` | -| Deploy an OCI Function from a local macOS or Linux workstation | `oci/functions/oci-functions-deploy/SKILL.md` | -| Troubleshoot OCI Functions setup, deployment, invocation, or observability | `oci/functions/oci-functions-troubleshoot/SKILL.md` | +| Topic | Start With | +|------------------------------------------------------------------------------------------------------------------------------------------------|------------| +| Design or scaffold an OKE cluster, Terraform stack, or OCI Resource Manager stack | Start with `oci/oke/cluster-design.md`, then load `oci/oke/skills/oke-cluster-generator/SKILL.md` | +| Troubleshoot OKE workloads, pods, services, DNS, add-ons, ingress, load balancers, image pulls, storage, Workload Identity, or cluster access | Start with `oci/oke/troubleshooting.md`, then load `oci/oke/skills/oke-troubleshooter/SKILL.md` | +| Configure OKE managed node pools with Generic VNIC Attachment secondary VNIC profiles and Application Resources | Start with `oci/oke/gva-node-pools.md`, then load `oci/oke/skills/oke-gva-deployer/SKILL.md` | +| Deploy or validate Multus NetworkAttachmentDefinitions and multi-interface pods on OKE | Start with `oci/oke/multus-multihome.md`, then load `oci/oke/skills/oke-multihome-deployer/SKILL.md` | +| Deploy an OCI Function from a local macOS or Linux workstation | `oci/functions/oci-functions-deploy/SKILL.md` | +| Troubleshoot OCI Functions setup, deployment, invocation, or observability | `oci/functions/oci-functions-troubleshoot/SKILL.md` | +| Generate or update Terraform Configuration for OCI IAM compartments, groups, dynamic groups, policies, or Identity Domains | `oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/SKILL.md` | | OCI IoT domains, domain groups, digital twin models, adapters, instances, relationships, raw commands, Data API access, or HTTPS publish flows | `oci/iot-platform/SKILL.md` | -| OCI Generative AI models, custom/imported models, endpoints, or private endpoints | `oci/enterprise-ai/SKILL.md` | -| OCI Responses API agents, tools, memory, File Search, Code Interpreter, MCP, or SQL Search | `oci/enterprise-ai/SKILL.md` | -| OCI Generative AI and OCI Generative AI Agents cost estimation | `oci/enterprise-ai/cost/cost-estimation.md` | -| OCI Enterprise AI governance, IAM, API keys, OAuth, guardrails, or ZPR | `oci/enterprise-ai/governance/private-endpoints-and-governance.md` | +| OCI Generative AI models, custom/imported models, endpoints, or private endpoints | `oci/enterprise-ai/SKILL.md` | +| OCI Responses API agents, tools, memory, File Search, Code Interpreter, MCP, or SQL Search | `oci/enterprise-ai/SKILL.md` | +| OCI Generative AI and OCI Generative AI Agents cost estimation | `oci/enterprise-ai/cost/cost-estimation.md` | +| OCI Enterprise AI governance, IAM, API keys, OAuth, guardrails, or ZPR | `oci/enterprise-ai/governance/private-endpoints-and-governance.md` | ## Key Starting Points @@ -85,6 +91,7 @@ oci/ - `oci/functions/oci-functions-troubleshoot/SKILL.md` - `oci/functions/oci-functions-deploy/references/oci-functions-quickstart.md` - `oci/functions/oci-functions-troubleshoot/references/error-patterns.md` +- `oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/SKILL.md` - `oci/iot-platform/SKILL.md` - `oci/iot-platform/references/cli-workflows.md` - `oci/iot-platform/references/mcp-optional-use.md` @@ -106,23 +113,25 @@ The OKE operational skills include deterministic helper tools under `oci/oke/scr ## Common Multi-Step Flows -| Task | Recommended Sequence | -|------|----------------------| -| Plan a production OKE cluster | `oke/cluster-design.md` | -| Diagnose an OKE service with no load balancer IP | `oke/troubleshooting.md` | +| Task | Recommended Sequence | +|------------------------------------------------------------------|----------------------| +| Plan a production OKE cluster | `oke/cluster-design.md` | +| Diagnose an OKE service with no load balancer IP | `oke/troubleshooting.md` | | Build a node pool with workload-specific secondary VNIC profiles | `oke/gva-node-pools.md` -> `oke/multus-multihome.md` if pods need multiple interfaces | -| Validate Multus pod networking on GVA-enabled nodes | `oke/multus-multihome.md` -> `oke/troubleshooting.md` if symptoms remain | -| Investigate OKE workload access to OCI APIs | `oke/troubleshooting.md` | -| Deploy a local function | `functions/oci-functions-deploy/SKILL.md` -> preflight -> Fn context validation -> OCIR auth check -> app selection -> scaffold -> deploy | -| Troubleshoot a failed function deploy | `functions/oci-functions-troubleshoot/SKILL.md` -> `functions/oci-functions-troubleshoot/references/error-patterns.md` -> `functions/oci-functions-troubleshoot/references/deploy.md` | -| Troubleshoot function invocation failures | `functions/oci-functions-troubleshoot/SKILL.md` -> `functions/oci-functions-troubleshoot/references/invoke.md` -> logs, traces, metrics, and limits | -| Explore or update OCI IoT digital twin resources | `iot-platform/SKILL.md` -> `iot-platform/references/cli-workflows.md` -> `iot-platform/references/resilience-guidance.md` | -| Publish test telemetry to an OCI IoT twin | `iot-platform/SKILL.md` -> `iot-platform/references/cli-workflows.md` -> `iot-platform/templates/publish-curl.template.sh` | -| Build a governed enterprise assistant | `enterprise-ai/SKILL.md` -> `enterprise-ai/agent-workflows/agent-tools.md` -> `enterprise-ai/data/rag-and-search.md` -> `enterprise-ai/governance/private-endpoints-and-governance.md` | +| Validate Multus pod networking on GVA-enabled nodes | `oke/multus-multihome.md` -> `oke/troubleshooting.md` if symptoms remain | +| Investigate OKE workload access to OCI APIs | `oke/troubleshooting.md` | +| Deploy a local function | `functions/oci-functions-deploy/SKILL.md` -> preflight -> Fn context validation -> OCIR auth check -> app selection -> scaffold -> deploy | +| Troubleshoot a failed function deploy | `functions/oci-functions-troubleshoot/SKILL.md` -> `functions/oci-functions-troubleshoot/references/error-patterns.md` -> `functions/oci-functions-troubleshoot/references/deploy.md` | +| Troubleshoot function invocation failures | `functions/oci-functions-troubleshoot/SKILL.md` -> `functions/oci-functions-troubleshoot/references/invoke.md` -> logs, traces, metrics, and limits | +| Generate OCI IAM Terraform Configuration | `oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/SKILL.md` -> determine supported module -> collect and validate inputs -> generate `main.tf`, `variables.tf`, and `terraform.tfvars` without running Terraform | +| Explore or update OCI IoT digital twin resources | `iot-platform/SKILL.md` -> `iot-platform/references/cli-workflows.md` -> `iot-platform/references/resilience-guidance.md` | +| Publish test telemetry to an OCI IoT twin | `iot-platform/SKILL.md` -> `iot-platform/references/cli-workflows.md` -> `iot-platform/templates/publish-curl.template.sh` | +| Build a governed enterprise assistant | `enterprise-ai/SKILL.md` -> `enterprise-ai/agent-workflows/agent-tools.md` -> `enterprise-ai/data/rag-and-search.md` -> `enterprise-ai/governance/private-endpoints-and-governance.md` | ## Scope Boundaries - Keep OCI service, networking, IAM, agent hosting, and cost-estimation guidance in this domain. +- Route OCI IAM Terraform configuration to `oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/`; it supports only the upstream compartments, groups, dynamic groups, policies, and Identity Domains modules, and does not create standalone classic users or memberships. - Route OCI IoT domain, digital twin, adapter, device publish, raw command, and Data API workflows to `oci/iot-platform/`. - Route Oracle Database-owned implementation details to `db/features/`. - Route APEX artifact generation to `apex/apexlang/`. @@ -134,6 +143,7 @@ The OKE operational skills include deterministic helper tools under `oci/oke/scr - https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengAttaching_Multiple_VNICs.htm - https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm - https://github.com/oracle-terraform-modules/terraform-oci-oke +- https://github.com/oci-landing-zones/terraform-oci-modules-iam - https://docs.oracle.com/en-us/iaas/Content/internet-of-things/home.htm - https://github.com/oracle-samples/oci-iot-samples - https://docs.oracle.com/en-us/iaas/Content/generative-ai/overview.htm diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/README.txt b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/README.txt new file mode 100644 index 0000000..9b5a9a5 --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/README.txt @@ -0,0 +1,94 @@ +Build OCI IAM Terraform Skill +=============================== + +This skill safely generates or updates Terraform root configuration for OCI IAM +by using only the supported modules from: +https://github.com/oci-landing-zones/terraform-oci-modules-iam + +It supports compartment hierarchies, classic IAM groups (including assigning +existing users), dynamic groups, IAM policies, and Identity Domains resources. +It does not create classic IAM users, manage standalone memberships, or manage +Cloud Guard security zones/recipes. For unsupported requests, it reports that +the Terraform module is not supported instead of inventing an alternative. + +How this skill works +--------------------- + +1. Inspects the target Terraform project before making changes. +2. Checks module-support.md to confirm the requested capability has an upstream + submodule. +3. Collects required inputs from the matching input-collection.md section. +4. Ask whether the user wants documented optional parameters, then validate the + completed inputs with validation.md. +5. Uses terraform-sources.md and main-tf-map.md to generate the smallest safe + configuration change. +6. This skill not run or install Terraform. It Hands off terraform init, validate, plan, + and apply for the user to run; Terraform 1.3.0 or later is required and the + plan must be reviewed before applying. + + +How to use +---------- + +Unzip this folder and put the /references and SKILL.md in a folder named `build-oci-iam-main-tf` + +Load this skill into an agent whenever the use case is to create or update OCI IAM +Terraform using the `oci-landing-zones/terraform-oci-modules-iam` repository. +Typical requests include compartments, IAM groups, dynamic groups, IAM policies, +and Identity Domains resources. + +After loading, the agent reads `SKILL.md` first and follows its reference-routing +workflow: confirm support, collect inputs, ask about optional parameters, +validate the values, then generate the smallest safe Terraform change. The agent +must not run or install Terraform, and it must hand off `terraform init`, +`terraform validate`, `terraform plan`, and `terraform apply` for the user to +run. Terraform 1.3.0 or later is required, and the user must review the plan +before applying it. + +The skill is additive by default. It preserves existing project layout and does +not modify Terraform state. Updates, moves, removals, recovery, and deletion +requests require the extra lifecycle checks in lifecycle-safety.md. + + +Reference files +--------------- + +module-support.md + The upstream support allowlist: exact module directories for compartments, + groups, dynamic-groups, policies, and identity-domains. It also identifies + unsupported capabilities and provides the required rejection wording. + +input-collection.md + Module-specific input checklist and structural checks. Its sections cover + compartments, groups, dynamic groups, policies, and Identity Domains. It + distinguishes required data from optional parameters, handles secrets safely, + and requires an optional-input question before validation. + +terraform-sources.md + The canonical Git module source format, approved module paths, version-pin + guidance, and integration rules for existing repositories or a new minimal + Terraform workspace. + +validation.md + The validation contract: tenancy OCID checks through the OCI MCP interface, + lifecycle state requirements, compartment hierarchy checks, and safe behavior + when validation is missing or fails. + +main-tf-map.md + Rules for mapping validated data into main.tf, variables.tf, and + terraform.tfvars. It explains when to extend an existing module versus add a + supported module block, while preserving repository conventions. + +lifecycle-safety.md + Additional guardrails for updates, moves, recovery, remove-from-configuration, + and deletes. It covers state ownership, dependencies, compartment deletion + staging, and the required user-facing plan review warning. + +Quick reference flow +-------------------- + +request -> module-support.md -> relevant input-collection.md section + +terraform-sources.md -> validation.md -> main-tf-map.md -> generate safely + +For lifecycle changes, read lifecycle-safety.md before collecting inputs and +apply the state checks in validation.md before proposing a configuration change. diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/SKILL.md b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/SKILL.md new file mode 100644 index 0000000..b9d9672 --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/SKILL.md @@ -0,0 +1,77 @@ +--- +name: build-oci-iam-main-tf +description: "Generate or update safe Terraform root configurations for OCI IAM with the upstream `oci-landing-zones/terraform-oci-modules-iam` repository. Use for OCI compartments and hierarchy, classic IAM groups (including member assignment), dynamic groups, IAM policies, and OCI Identity Domains resources when the request must be mapped to a supported upstream module, inputs collected and validated, and `main.tf`, `variables.tf`, and `terraform.tfvars` produced. Also use to determine support: clearly report 'the Terraform module for the requested capability is not supported' for requests outside the repository's documented modules, including standalone classic users or memberships and Cloud Guard security zones." +--- + +# Build OCI IAM Terraform + +Generate only configurations that the upstream repository supports. Default to additive-only changes. Never invent a module path, input name, or resource model, never mutate, replace, rename, move, or re-parent an existing resource unless the user explicitly and unambiguously asks for that exact resource change, and never install or execute Terraform. + +## Required workflow + +1. Inspect the target before writing. + - Inspect the project root, its Terraform files, repository documentation, provider/backend setup, and established file layout. A `.tf` file is only one signal; do not assume its presence or absence alone defines the project. + - For an update, move, recovery, removal, or deletion, inspect any accessible local Terraform state file read-only to establish the exact state address. Never modify a state file or run a Terraform state command. + - Treat it as an existing project when the user has placed a project in scope or an established configuration is present. Otherwise, create a minimal configuration in a user-selected target directory; ask for the target if none is available. Do not hardcode or assume a local path, and do not overwrite unrelated files. + - If the request would change an existing resource, proceed only when the user explicitly names that existing resource and the intended mutation; otherwise stop and ask for confirmation or a narrower request. + - Read [references/module-support.md](references/module-support.md) first. Resolve every requested capability to an exact supported subdirectory. + - If any requested capability has no supported module, do not produce an alternative implementation. Tell the user: **"The Terraform module for `` is not supported by `oci-landing-zones/terraform-oci-modules-iam`."** Name the supported alternatives only when relevant. + - For any update, move, recovery, removal, or deletion request, read [references/lifecycle-safety.md](references/lifecycle-safety.md) before collecting inputs or proposing a change. + +2. Collect inputs by module. + - Read only the relevant section in [input collection](references/input-collection.md): compartments, groups, dynamic groups, policies, or Identity Domains. + - Ask concise follow-up questions for required values that are not present. Preserve literal OCIDs and parent-child relationships; do not fabricate them. + - After required inputs are complete and before reading `validation.md`, you must ask whether the user wants to provide any documented optional parameters for the selected module. Do not read `validation.md` until the user has either provided those optional values or explicitly declined them. If they decline, use documented defaults only; never invent optional values. + - Read [references/terraform-sources.md](references/terraform-sources.md) before creating any module block. It defines the canonical Git source format. + +3. Validate before generating usable configuration. + - Read [references/validation.md](references/validation.md) after all requested inputs are collected. + - Apply every non-placeholder rule. If an input is missing or known invalid, pause and ask for its corrected value; never proceed with known invalid inputs. If OCI MCP is unavailable, tell the user that MCP validation was skipped and continue only with non-MCP validation rules. + - For update, move, recovery, removal, or destroy requests, require Terraform-state existence before proposing the mutation. If a dedicated validation section is not yet defined for the selected resource family, apply the common rules and its collection-reference structural checks only; do not invent additional rules. + +4. Generate after validation succeeds. + - Read [references/main-tf-map.md](references/main-tf-map.md) and the relevant source snippets. + - In an existing project, always preserve the repository's established style and layout when adding or mutating a resource: file placement, formatting, naming, variable-data convention, provider/backend configuration, module organization, and Terraform version constraints. Only mutate an existing resource when the user explicitly asks for that exact resource change. Prefer the smallest additive change possible. Update or add `main.tf`, `variables.tf`, and `terraform.tfvars` only when compatible with that setup. + - In a new project, create exactly `main.tf`, `variables.tf`, and `terraform.tfvars`. Include an OCI provider block and required-provider constraint. Keep authentication values as variables and do not put private keys, API keys, tokens, or passwords in `terraform.tfvars`. + - Put module source, module wiring, and provider configuration in `main.tf`; declarations and types in `variables.tf`; validated non-secret example values in `terraform.tfvars`. + +5. Hand off without running commands. + - Tell the user Terraform 1.3.0 or later is required by the upstream modules and must be installed before use. + - Provide, but never run: `terraform init`, `terraform validate`, `terraform plan`, and `terraform apply`. + - State that `terraform plan` must be reviewed before `terraform apply`. + +## Boundaries + +- Use only the source repository and subdirectories listed in `module-support.md`. +- Do not silently substitute direct `oci_*` resources for an unavailable submodule. +- A classic IAM **group** can assign existing user names as members. There is no separate `users` or `memberships` top-level module; reject requests that require creating users or managing memberships independently. +- Do not claim Cloud Guard support. It belongs to other OCI landing-zone module collections, not this repository. +- Do not run `terraform`, `tofu`, package-manager, provider-login, or install commands. +- Do not create, modify, replace, move, or delete a state file. Do not create a lock file or `.terraform` directory. + +## Reference routing + +Read references only along this path; do not load every file for every request. + +```text +request + -> module-support.md + -> unsupported: report "Terraform module is not supported" and stop + -> supported: relevant input reference + terraform-sources.md + -> validation.md + -> main-tf-map.md + -> generate or update the project files +``` + +| Need at this stage | Read | +| --- | --- | +| Confirm an exact submodule or reject a request | [module-support.md](references/module-support.md) | +| Update, move, recover, remove, or delete a resource | [lifecycle-safety.md](references/lifecycle-safety.md) | +| Build exact Git sources and provider baseline | [terraform-sources.md](references/terraform-sources.md) | +| Collect OCI IAM groups | [input-collection.md — Groups](references/input-collection.md#groups) | +| Collect OCI IAM dynamic groups | [input-collection.md — Dynamic groups](references/input-collection.md#dynamic-groups) | +| Collect OCI IAM policies | [input-collection.md — Policies](references/input-collection.md#policies) | +| Collect compartment hierarchy data | [input-collection.md — Compartments](references/input-collection.md#compartments) | +| Collect Identity Domains data | [input-collection.md — Identity Domains](references/input-collection.md#identity-domains) | +| Map validated values to files | [main-tf-map.md](references/main-tf-map.md) | +| Apply the future validation contract | [validation.md](references/validation.md) | diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/agents/openai.yaml b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/agents/openai.yaml new file mode 100644 index 0000000..6997672 --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Build OCI IAM main.tf" + short_description: "Generate supported OCI IAM Terraform" + default_prompt: "Use $build-oci-iam-main-tf to create validated Terraform root files for supported OCI IAM modules." diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/input-collection.md b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/input-collection.md new file mode 100644 index 0000000..0678190 --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/input-collection.md @@ -0,0 +1,329 @@ +# OCI IAM input collection reference + +## Compartments + +# Compartments input collection + +Use this reference after `module-support.md` confirms `compartments` is supported. Map data exactly to the upstream `compartments_configuration` object; it supports a hierarchy of up to six levels. + +Source of truth: [upstream compartments SPEC.md](https://github.com/oci-landing-zones/terraform-oci-modules-iam/blob/main/compartments/SPEC.md). Re-check it before generating when a requested attribute is not covered here. + +## Required inputs + +- `tenancy_ocid`; +- `compartments_configuration.compartments`: a map keyed by stable logical keys; +- for every compartment at every hierarchy level: `name` and `description`. + +For root (first-level) compartments, collect `default_parent_id` or an explicit `parent_id` when the parent is not the tenancy. Do not infer OCIDs or parent relationships from display names. + +## Optional inputs in `compartments_configuration` + +- `default_parent_id` — default parent for all first-level compartments; +- `default_defined_tags` and `default_freeform_tags` — defaults for all compartments; +- `enable_delete` — physically delete compartments on destroy; default is `false`; +- per-compartment `parent_id`, `defined_tags`, and `freeform_tags`; +- per-compartment `tag_defaults`, each with `tag_id`, `default_value`, and optional `is_user_required`; +- nested `children` maps, to a maximum of six hierarchy levels. + +## Optional module inputs + +- `compartments_dependency` — external compartment map, where every entry has an `id` OCID; +- `derive_keys_from_hierarchy` — whether to derive identifying keys from the hierarchy; default is `false`; +- `module_name` — default `iam-compartments`; +- `tags_dependency` — external tag map, where every entry has an `id` OCID. + +## Mandatory optional-input question + +After collecting all required inputs and before reading `validation.md`, ask: + +> Do you want to provide any optional compartment parameters—parent override, tags, tag defaults, nested children, delete behavior, external dependencies, derived keys, or module name? + +If the user declines, use only documented defaults; do not invent optional values. If they provide options, collect their exact values and then continue to validation. + +## Structural checks before validation + +- Keep stable, unique map keys at every hierarchy level. +- Keep every parent reference resolvable through the tenancy, the hierarchy, or a documented external dependency. +- Reject cycles, orphaned parent references, and a parent that is also its own child. +- Supply `tag_id` and `default_value` for each tag default. +- Do not create a seventh hierarchy level. + +## Output discipline + +Put user data in `terraform.tfvars` and pass `var.compartments_configuration` (plus any selected optional module inputs) to the module. Keep the module block free of hard-coded topology data. + +## Dynamic groups + +# OCI IAM dynamic groups input collection + +Use this reference after `module-support.md` confirms `dynamic-groups` is supported. Map only to the upstream `dynamic_groups_configuration` object. + +Source of truth: [upstream dynamic-groups SPEC.md](https://github.com/oci-landing-zones/terraform-oci-modules-iam/blob/main/dynamic-groups/SPEC.md). Re-check it before generating when a requested attribute is not covered here. + +## Required module input + +- `tenancy_ocid`. + +## Required dynamic-group configuration + +`dynamic_groups_configuration` is optional at the module boundary. For every requested `dynamic_groups` map entry, collect: + +- a stable logical key; +- `name`; +- `description`; +- `matching_rule`. + +The matching rule defines the resource principals in the group. Collect it exactly as approved; do not infer, normalize, broaden, or combine matching rules. + +## Optional dynamic-group configuration + +- top-level `default_defined_tags` and `default_freeform_tags`; +- per-group `defined_tags` and `freeform_tags`; +- `module_name`, default `iam-dynamic-groups`. + +## Mandatory optional-input question + +After collecting required dynamic-group data and before reading `validation.md`, ask: + +> Do you want to provide optional dynamic-group parameters—default tags, per-group tags, or module name? + +If the user declines, use documented defaults only; never invent optional tags or a matching rule. + +## Structural checks before validation + +- Keep logical keys and dynamic-group names unique. +- Require a non-empty matching rule for every group. +- Preserve the user's exact matching-rule text and record its intended OCI resource scope. + +## Output discipline + +Put validated, non-secret dynamic-group data in the repository's established variable-data location and pass only `tenancy_ocid`, `dynamic_groups_configuration`, and any selected documented module option. + +## Groups + +# OCI IAM groups input collection + +Use this reference after `module-support.md` confirms `groups` is supported. Map only to the upstream `groups_configuration` object. + +Source of truth: [upstream groups SPEC.md](https://github.com/oci-landing-zones/terraform-oci-modules-iam/blob/main/groups/SPEC.md). Re-check it before generating when a requested attribute is not covered here. + +## Required module input + +- `tenancy_ocid`. + +## Required group configuration + +`groups_configuration` is optional at the module boundary. For every requested `groups` map entry, collect: + +- a stable logical key; +- `name`; +- `description`. + +## Optional group configuration + +- top-level `enable_debug`, default `false`; +- top-level `default_defined_tags` and `default_freeform_tags`; +- per-group `members`: existing OCI user names to assign to the group; +- per-group `defined_tags` and `freeform_tags`; +- `module_name`, default `iam-groups`. + +The module looks up existing OCI users and creates group memberships. It does not create users. If the request needs a user to be created, report that the Terraform module for classic IAM users is not supported. + +## Mandatory optional-input question + +After collecting required group data and before reading `validation.md`, ask: + +> Do you want to provide optional group parameters—existing members, tags, debug output, or module name? + +If the user declines, use documented defaults only; never invent members, tags, or optional values. + +## Structural checks before validation + +- Keep group logical keys and names unique. +- Confirm every requested member is an existing OCI user name; do not treat a display name or email as a user name without confirmation. +- Do not add memberships for users the request does not name. + +## Output discipline + +Put validated, non-secret group data in the repository's established variable-data location and pass only `tenancy_ocid`, `groups_configuration`, and any selected documented module option. + +## Identity Domains + +# Identity Domains input collection + +Use this reference after `module-support.md` confirms `identity-domains` is supported. Map only to the upstream module's documented input objects. It supports identity domains, domain groups, dynamic groups, identity providers, and applications; do not infer classic IAM input shapes. + +Source of truth: [upstream identity-domains SPEC.md](https://github.com/oci-landing-zones/terraform-oci-modules-iam/blob/main/identity-domains/SPEC.md). Re-check it before generating when a requested attribute is not covered here. + +## Required module input + +- `tenancy_ocid`. + +All configuration objects below are optional at the module boundary. Collect one only when the user requests that resource family. Use stable logical keys for every map entry. + +## Identity domains: `identity_domains_configuration` + +For every `identity_domains` map entry, collect: + +- `display_name`; +- `description`; +- `license_type`; +- `allow_signing_cert_public_access`. + +Documented optional configuration: + +- defaults: `default_compartment_id`, `default_defined_tags`, `default_freeform_tags`; +- per-domain `compartment_id`, `home_region`, `admin_email`, `admin_first_name`, `admin_last_name`, `admin_user_name`; +- `is_hidden_on_login`, `is_notification_bypassed`, `is_primary_email_required`; +- per-domain `defined_tags`, `freeform_tags`, and `replica_region`. + +## Domain groups: `identity_domain_groups_configuration` + +For every `groups` map entry, collect: + +- `name`; +- the identity domain to use, either the configuration's `default_identity_domain_id` or the entry's `identity_domain_id`. + +Documented optional configuration: + +- top-level `ignore_external_membership_updates` (default `true`), `default_defined_tags`, and `default_freeform_tags`; +- per-group `description`, `requestable`, `members`, `defined_tags`, and `freeform_tags`. + +Group members must be the identifiers expected by the current upstream module; do not assume classic IAM user names work here. + +## Domain dynamic groups: `identity_domain_dynamic_groups_configuration` + +For every `dynamic_groups` map entry, collect: + +- `name`; +- `matching_rule`; +- the identity domain to use, through `default_identity_domain_id` or `identity_domain_id`. + +Documented optional configuration: top-level default defined/freeform tags, plus per-group `description`, `defined_tags`, and `freeform_tags`. Do not invent or broaden matching rules. + +## Identity providers: `identity_domain_identity_providers_configuration` + +For every `identity_providers` map entry, collect: + +- `name`; +- `enabled`; +- `add_to_default_idp_policy`; +- the identity domain to use, through `default_identity_domain_id` or `identity_domain_id`. + +Documented optional configuration: + +- `description`, `icon_file`, `name_id_format`, `user_mapping_method`, `user_mapping_store_attribute`, and `assertion_attribute`; +- `idp_metadata_file`; or manually supplied IdP metadata: `identity_domain_idp_id`, issuer URI, SSO URL/binding, signing/encryption certificates, and global-logout settings; +- `signature_hash_algorithm` and `send_signing_certificate`. + +Use either metadata-file input or manual metadata fields only as supported by the chosen provider type. Do not put private signing keys or secrets in Terraform files. + +## Applications: `identity_domain_applications_configuration` + +For every `applications` map entry, collect: + +- `name`; +- `display_name`; +- `type`: one of the documented application types (`SAML`, `Mobile (public)`, `Confidential`, `SCIM`, `FusionApps`, or `GenericSCIM`); +- the identity domain to use, through `default_identity_domain_id` or `identity_domain_id`. + +Documented optional configuration is extensive. Ask only for options applicable to the selected application type: + +- common: description, active state, application group IDs, URLs, display/access settings, authorization enforcement, tags; +- OAuth client: grant types, HTTPS policy, redirect/logout URLs, client type, certificate, introspection/on-behalf-of settings, encryption, consent, client IPs, resources, roles; +- OAuth resource server: token/refresh settings, audiences, and scoped permissions; +- SAML: service-provider ID, entity/assertion-consumer URLs, name-ID settings, signing/encryption, single logout, attribute mappings, app links; +- Fusion, web-tier, SCIM, and catalogue-app provisioning: service URLs, policy JSON, connectivity, synchronization, SCIM HTTP settings, and Fusion administrator/settings fields. + +Treat application `client_secret`, `fa_admin_password`, custom authorization headers, certificates, and comparable values as secrets. Do not put them in `terraform.tfvars`, source control, chat output, or examples; use the project's approved secret-input mechanism. + +## Optional module inputs and dependencies + +- `compartments_dependency`: external compartment map; every entry must contain an `id` OCID; +- `identity_domains_dependency`: external identity-domain map; every entry must contain an `id`; +- `module_name`, defaulting to `iam-identity-domains`. + +## Mandatory optional-input question + +After collecting required inputs for each requested resource family and before reading `validation.md`, ask: + +> Do you want to provide any documented optional Identity Domains parameters—for defaults, tags, membership handling, application protocol settings, identity-provider metadata, replication, dependencies, or module name? + +Then ask only the type-specific follow-up questions relevant to the requested domain, group, dynamic-group, identity-provider, or application configuration. If the user declines, use documented defaults only; never invent optional values. + +## Structural checks before validation + +- Keep logical keys unique across each configuration map. +- Ensure every referenced identity-domain ID is supplied directly, inherited from a documented default, or resolved through an approved dependency. +- Require the documented mandatory fields for every requested entry, including dynamic-group matching rules and identity-provider booleans. +- Keep application type and its optional protocol/provisioning settings consistent; do not apply SAML, OAuth, SCIM, or Fusion fields to an unrelated app type. +- Keep Identity Domains resources separate from classic OCI IAM resources unless the user explicitly requests both module families. + +## Output discipline + +Put validated non-secret configuration data in the repository's established variable-data location. Pass only selected configuration objects and documented dependencies to the module; do not add unrequested resource families or undocumented arguments. + +## Policies + +# OCI IAM policies input collection + +Use this reference after `module-support.md` confirms `policies` is supported. Map only to the upstream `policies_configuration` object. Choose direct supplied policies, template policies, or both only when the user explicitly requests them. + +Source of truth: [upstream policies SPEC.md](https://github.com/oci-landing-zones/terraform-oci-modules-iam/blob/main/policies/SPEC.md). Re-check it before generating when a requested attribute is not covered here. + +## Required module input + +- `tenancy_ocid`. + +## Direct policies: `supplied_policies` + +For every directly supplied policy map entry, collect: + +- a stable logical key; +- `name`; +- `description`; +- `compartment_id` (a literal OCID or documented dependency reference); +- `statements` as one or more complete OCI policy statements. + +Optional per-policy fields: `defined_tags` and `freeform_tags`. + +Do not rewrite policy statements, expand their permissions, or choose a compartment scope on the user's behalf. + +## Template policies: `template_policies` + +Use template policies only when the user requests the upstream policy templates. Documented optional settings include: + +- tenancy-level `groups_with_tenancy_level_roles`, with a group `name` and `roles` value; +- tenancy-level OCI-service toggles for all policies, scanning, Cloud Guard, OS Management, block storage, file storage, OKE, streaming, and object storage; +- tenancy-level `policy_name_prefix`; +- compartment-level `supplied_compartments`, each with `name`, `id`, and required `cislz_metadata` map. + +Do not invent template roles, service toggles, compartment metadata, or template policy targets. Consult the upstream module README for the required `cislz_metadata` shape before generating template policies. + +## Other optional module and configuration inputs + +- `enable_cis_benchmark_checks` in `policies_configuration`, default `true`; +- `policy_name_prefix`, `policy_name_suffix`, `defined_tags`, and `freeform_tags` in `policies_configuration`; +- `compartments_dependency`, where every external compartment map entry has an `id` OCID; +- `enable_debug`, default `false`; +- `enable_output`, default `true`; +- `module_name`, default `iam-policies`. + +## Mandatory optional-input question + +After collecting the required direct-policy or template-policy data and before reading `validation.md`, ask: + +> Do you want to provide optional policy parameters—CIS checks, tags, name prefix/suffix, template settings, compartment dependencies, debug/output controls, or module name? + +If the user declines, use documented defaults only; do not invent policies, roles, scopes, template settings, or optional values. + +## Structural checks before validation + +- Keep policy keys and policy names unique within their target scope. +- Require at least one complete statement for every supplied policy. +- Ensure every compartment ID is supplied directly or resolves through a documented dependency. +- Do not mix template and supplied policy data unintentionally; retain each mode's map/object structure. + +## Output discipline + +Put validated, non-secret policy data in the repository's established variable-data location. Pass only documented module inputs and preserve the project's existing policy-data style. diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/lifecycle-safety.md b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/lifecycle-safety.md new file mode 100644 index 0000000..f708bdb --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/lifecycle-safety.md @@ -0,0 +1,43 @@ +# OCI IAM and compartment lifecycle safety + +Read this reference whenever the request updates, moves, recovers, removes, or destroys an IAM or compartment resource. Treat lifecycle changes as high-impact: preserve repository style, state only verified effects, and never run Terraform commands. + +## Update + +- Distinguish an in-place metadata/configuration change from a replacement before proposing a change. Surface a planned replacement or destroy/create action clearly to the user. +- Use the tenancy home-region OCI provider context for IAM operations. Do not introduce or change provider aliases unless the existing repository and the user request it. +- Warn that IAM changes can take time to propagate after they succeed in the home region. +- Preserve existing resource names, map keys, provider settings, and module layout unless the user explicitly requests a change. + +## Move + +- For a compartment move, collect the intended parent OCID and preserve the hierarchy. Explain that moving a compartment is an OCI asynchronous operation and must be reviewed in the plan. +- Do not describe global IAM users, groups, or policies as ordinary compartment-scoped resources. For changes in relationship or membership, use only the documented upstream module configuration; do not create direct OCI resources as a substitute. +- If the requested move is not supported by the upstream module, report that the Terraform module is not supported. + +## Recover + +- Terraform cannot recover a soft-deleted OCI compartment by itself. +- A compartment recovery must be performed outside Terraform using an OCI-supported recovery path. After recovery, the resource must be brought back under Terraform state using the user's approved state-management process. +- Do not run recovery, import, CLI, Console, or Terraform commands. Explain the limitation and direct the user to their approved operational procedure. + +## Delete and remove-from-configuration + +- Treat removing an object from a module configuration as a requested Terraform destroy operation, not merely a source-code cleanup. +- For compartments, keep `enable_delete = false` by default. OCI requires the compartment to be empty before it can be deleted. +- Before proposing a compartment deletion, ask the user to confirm the exact logical key/OCID, confirm that it is empty, and approve deletion. +- Use a staged approach for a compartment whose configuration currently has deletion disabled: + 1. Temporarily set the existing module's documented `enable_delete` option to `true` while retaining the compartment configuration. + 2. Have the user review and apply that isolated lifecycle-setting change. + 3. Remove only the confirmed compartment entry, then have the user review a plan showing only the intended destroy. + 4. After successful deletion, restore `enable_delete = false` unless the user explicitly wants it left enabled. +- Do not remove a group, dynamic group, policy, or Identity Domains object without warning that dependent policy assignments, memberships, applications, or other references may be affected. Ask the user to confirm the intended object and review the plan. + +## Required user-facing handoff + +For every lifecycle mutation, state: + +- the exact object(s) expected to change; +- whether the expected action is update, move, replacement, or delete; +- dependencies and operational prerequisites; +- that the user must review `terraform plan` before `terraform apply`. diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/main-tf-map.md b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/main-tf-map.md new file mode 100644 index 0000000..2992f1e --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/main-tf-map.md @@ -0,0 +1,108 @@ +# Terraform file map + +Use this map only after support has been confirmed and validation has passed. First distinguish a module block that is absent from the **current repository** from a capability that is absent from the **upstream module repository**: + +- Existing module block absent, but upstream supports the capability: add the documented upstream module block. +- Existing module block present: extend its configuration data; do not add a duplicate module block. +- Upstream does not support the capability: tell the user the Terraform module is not supported; do not write a replacement module or direct `oci_*` resources. + +## Existing repository: choose the change + +Inspect the repository's current module blocks and trace the variable or local value supplied to each module input. + +| User request | Existing repository state | Required change | +| --- | --- | --- | +| Add an object or an optional input for a supported capability | A module block for that same upstream capability already exists | Add the validated data to the module's existing documented configuration object or optional module input. Preserve its map keys, object relationships, tags, and existing variable-data convention. Do not add a duplicate module block. | +| Add a different supported capability | No module block for that upstream capability exists | Add one module block using the canonical upstream source, plus its typed variable declaration and validated data, integrated with the existing provider and project conventions. | +| Request an unsupported capability | No upstream module exists | Stop for that capability and say: “The Terraform module for `` is not supported by `oci-landing-zones/terraform-oci-modules-iam`.” | + +Never use the absence of a module block in the current repository as a reason to say the capability is unsupported. Support is determined solely by `module-support.md` and the upstream repository. + +Examples of the first row: add a compartment to `compartments_configuration`; add a group to `groups_configuration`; add a dynamic group to `dynamic_groups_configuration`; add a policy to the policies module's documented configuration; or add an Identity Domains object to its documented configuration. In each case, extend the existing module's data instead of creating another module block. + +## Existing repository: file placement + +Always preserve the repository's established style and layout rather than forcing a new one. Match nearby Terraform formatting, indentation, block ordering, naming, comments, variable-data format, and file placement; make the smallest scoped change that adds or mutates the requested resource. + +- Locate the existing configuration value for the selected module. It may be in `terraform.tfvars`, a `*.tfvars` environment file, a `.tf` local, or another established configuration source. Update that source only. +- Reuse existing OCI provider configuration, aliases, `required_providers`, backend, version constraints, naming convention, and variable types. +- Add the module block to the repository's appropriate root/module `.tf` file. If the repository uses `main.tf`, add it there; otherwise preserve its chosen layout. +- Add or extend typed variable declarations in the existing variable-definition file. Do not weaken a documented object type to `any`. +- Add validated non-secret values to the existing variable-data file. Do not overwrite unrelated environment values. +- Avoid duplicate providers, duplicate module names, conflicting variables, backend changes, or state changes. + +### Example: extend an existing compartments configuration + +When this module already exists, the change is configuration data—not a second module: + +```hcl +compartments_configuration = { + # Preserve existing values. + compartments = { + # Preserve existing compartment entries. + app = { + name = "app" + description = "Application compartment" + } + } +} +``` + +Use the exact current configuration shape from the repository and `compartments/SPEC.md`; this is only a placement example. Do not replace the existing object with this sample. + +### New supported-module pattern + +When, for example, dynamic groups are requested and no dynamic-groups module block exists, add one documented module block: + +```hcl +module "dynamic_groups" { + source = "git::https://github.com/oci-landing-zones/terraform-oci-modules-iam.git//dynamic-groups?ref=" + + tenancy_id = var.tenancy_ocid + dynamic_groups_configuration = var.dynamic_groups_configuration +} +``` + +Confirm the current `dynamic-groups/SPEC.md` before emitting the final argument names and type. Do not add this block when dynamic groups are unsupported; do not create a custom alternative. + +## No repository or directory in scope: minimal project + +Ask the user for a target directory. Then create only: + +```text +main.tf +variables.tf +terraform.tfvars +``` + +### `main.tf` + +Include, in order: + +1. a `terraform` block with `required_version = ">= 1.3.0"` and OCI `required_providers`; +2. an OCI provider block consuming variables; +3. one module block for each requested, upstream-supported capability. + +### `variables.tf` + +- Declare the OCI authentication and region variables for the selected authentication method. +- Declare one typed configuration variable for each selected module, based on its current `SPEC.md`. +- Do not declare variables or modules for unsupported capabilities. + +### `terraform.tfvars` + +- Put only validated, non-secret provider and module data here. +- Use placeholders for unsupplied OCIDs and credentials; never include private-key contents, tokens, or passwords. + +## Final handoff + +Do not run Terraform. Tell the user to install Terraform 1.3.0 or later if required, then provide: + +```bash +terraform init +terraform validate +terraform plan +terraform apply +``` + +Tell the user to review the plan before applying it. diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/module-support.md b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/module-support.md new file mode 100644 index 0000000..f591357 --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/module-support.md @@ -0,0 +1,27 @@ +# Upstream module support matrix + +Source repository: `https://github.com/oci-landing-zones/terraform-oci-modules-iam` + +Verify the current repository tree and the selected module's documentation before generation. This matrix is the initial allowlist, not permission to guess undocumented inputs. + +| Requested capability | Status | Exact upstream submodule | Notes | +| --- | --- | --- | --- | +| Compartments | Supported | `compartments` | Supports compartment definitions and nesting through its documented configuration. | +| Compartment hierarchy | Supported | `compartments` | Keep parents and children in the supplied order. | +| IAM groups | Supported | `groups` | Local groups; member assignment refers to existing user names. | +| Assign existing users to a group | Supported within `groups` | `groups` | Not a standalone membership module. | +| IAM dynamic groups | Supported | `dynamic-groups` | Requires a matching rule. | +| IAM policies | Supported | `policies` | Requires explicit policy statements and scope. | +| Identity Domains | Supported | `identity-domains` | Confirm the requested resource type and input shape in the module's current `SPEC.md`. | +| Create classic IAM users | Not supported | — | The Terraform module for classic IAM users is not supported. | +| Standalone classic IAM memberships | Not supported | — | The Terraform module for standalone memberships is not supported. Use `groups` only to attach existing user names. | +| Cloud Guard security zones or recipes | Not supported | — | The Terraform module for Cloud Guard is not supported. | +| Any other OCI IAM/governance feature | Unknown/not supported | — | Treat as unavailable unless the current upstream tree documents a matching top-level module. | + +## Rejection response + +Use this response pattern and stop generation for the unsupported part: + +> The Terraform module for `` is not supported by `oci-landing-zones/terraform-oci-modules-iam`, so I cannot generate a module block for it. + +If a request combines supported and unsupported capabilities, ask whether to continue with only the supported portion. Do not include the unavailable feature in Terraform. diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/terraform-sources.md b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/terraform-sources.md new file mode 100644 index 0000000..1aec695 --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/terraform-sources.md @@ -0,0 +1,138 @@ +# Terraform sources, repository integration, and minimal-workspace baseline + +Read this reference after module support has been confirmed and before creating a module block. It applies both when updating an existing repository and when creating a minimal Terraform workspace. + +## Canonical upstream source + +Use this exact source form for every supported module: + +```hcl +source = "git::https://github.com/oci-landing-zones/terraform-oci-modules-iam.git//?ref=" +``` + +Replace `` only with `compartments`, `groups`, `dynamic-groups`, `policies`, or `identity-domains`. Replace `` with a user-approved release tag or immutable commit SHA. + +- Ask the user for a pin if one is not supplied for production use. +- Use `ref=main` only for a clearly marked evaluation draft with the user's approval. +- Confirm each module's current `README.md` and `SPEC.md` before emitting its input arguments. +- If the requested capability has no listed submodule, report that the Terraform module is not supported. Do not substitute a direct provider resource or a custom module. + +## Existing repository mode + +Before editing, inspect the repository's root/module layout, Terraform version constraints, required providers, provider aliases, backend, variable naming, locals, existing module names, environment conventions, and `.gitignore` policy. + +### Integrate without disrupting existing setup + +- Match the repository's existing Terraform style and layout when adding or changing a resource, including file placement, formatting, indentation, naming, comments, and variable-data convention. +- Reuse an existing compatible OCI provider and `required_providers` block; do not add a duplicate provider or overwrite an existing version constraint. +- Preserve provider aliases. Pass an alias to a module only if the module's documentation supports it and the current project needs that tenancy/region/account context. +- Reuse established variable files and configuration-object conventions. Add `main.tf`, `variables.tf`, or `terraform.tfvars` only when they fit the repository's structure; otherwise add the smallest compatible change to its existing layout. +- Select non-conflicting module, variable, local, and map-key names. Do not rename existing objects solely for consistency. +- Preserve the existing backend and state model. Never add, remove, or reconfigure a backend unless the user explicitly requests it. +- Put user-supplied topology and policy data in the project's existing variable-data convention. If `terraform.tfvars` is used, keep it non-secret and avoid overwriting existing values. +- Do not write environment credentials, private-key contents, tokens, or passwords into repository files. + +### Existing-repository module pattern + +Adapt this pattern to the project's names and provider configuration: + +```hcl +module "groups" { + source = "git::https://github.com/oci-landing-zones/terraform-oci-modules-iam.git//groups?ref=" + + tenancy_id = var.tenancy_ocid + groups_configuration = var.groups_configuration +} +``` + +The argument names are module-specific. Do not copy `tenancy_id` or `groups_configuration` into another module without confirming its current specification. + +## Minimal workspace mode + +Use this mode only when no project is in scope. Ask the user for the target directory; do not assume or hardcode one. Create only these files unless the user asks for more: + +```text +main.tf +variables.tf +terraform.tfvars +``` + +### `main.tf` baseline + +```hcl +terraform { + required_version = ">= 1.3.0" + + required_providers { + oci = { + source = "oracle/oci" + } + } +} + +provider "oci" { + tenancy_ocid = var.tenancy_ocid + user_ocid = var.user_ocid + fingerprint = var.fingerprint + private_key_path = var.private_key_path + region = var.region +} + +# Add only supported, validated module blocks below this line. +``` + +### `variables.tf` baseline + +```hcl +variable "tenancy_ocid" { + description = "OCI tenancy OCID." + type = string +} + +variable "user_ocid" { + description = "OCI user OCID for API-key authentication." + type = string +} + +variable "fingerprint" { + description = "OCI API-key fingerprint." + type = string +} + +variable "private_key_path" { + description = "Local path to the OCI API private key; do not store private-key contents in Terraform files." + type = string +} + +variable "region" { + description = "OCI region identifier." + type = string +} +``` + +Add the selected module's typed configuration variable after consulting that module's `SPEC.md`. Do not use `any` merely to avoid modeling the documented object. + +### `terraform.tfvars` baseline + +```hcl +tenancy_ocid = "" +user_ocid = "" +fingerprint = "" +private_key_path = "" +region = "" +``` + +Replace placeholders only with validated, non-secret values. Do not place private-key contents, tokens, passwords, or other secrets in this file. Suggest a `.gitignore` entry when appropriate, but do not change unrelated files unless asked. + +## Execution handoff + +Do not install Terraform and do not execute commands. After generating the configuration, tell the user to install Terraform 1.3.0 or later if it is unavailable, then provide: + +```bash +terraform init +terraform validate +terraform plan +terraform apply +``` + +Ask the user to review the plan before applying it. diff --git a/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/validation.md b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/validation.md new file mode 100644 index 0000000..3ca5b79 --- /dev/null +++ b/oci/oci-landing-zone-terraform-module/terraform-oci-modules-iam-skill/references/validation.md @@ -0,0 +1,82 @@ +# Validation contract + +Read this file after support is confirmed and all required and optional inputs are collected. Never proceed with a known invalid input. When validation fails, pause and ask the user for the corrected value before generating or mutating configuration. + +## Validation outcomes + +- **Pass:** continue to generation. +- **Known invalid or missing input:** stop and ask for the valid OCID, corrected value, or missing information. Do not proceed with a known invalid input. +- **OCI MCP tool unavailable:** tell the user that OCI MCP is unavailable, tenancy validation was skipped, and continue with the remaining non-MCP validation rules. Do not claim the tenancy OCID was validated. + +## Common lifecycle-state gate — all resources + +For every update, move, recover, remove-from-configuration, or destroy request involving an IAM or compartment resource: + +1. Inspect any accessible local Terraform state file read-only and identify the exact Terraform resource address. Do not run `terraform state` or any other Terraform command, and never create, modify, replace, move, or delete a state file. +2. Require the exact resource to exist in the current Terraform state before proposing the mutation. Configuration presence alone is not evidence of state ownership. +3. If no local state file is accessible, ask the user to confirm the state address from their approved state-inspection process. Do not assume a remote-state resource exists. +4. If the resource is absent from the current state, stop and do not assume it is managed. Give the user these options: manually import or adopt the existing OCI resource into state using their approved process; or reconcile or remove the stale configuration manually. Do not import, adopt, create a replacement, or alter state without explicit user direction and an approved state-management process. + +This applies equally to compartments, groups, dynamic groups, policies, and Identity Domains resources. + +## Tenancy OCID validation — all module requests + +`tenancy_ocid` must be supplied and must resolve to the active usable tenancy through the OCI API MCP server. + +### OCI MCP availability check + +Before stating that OCI MCP is unavailable, inspect the currently available tool inventory for both `get_oci_command_help` and `run_oci_command` from the OCI MCP server. If both are present, call `get_oci_command_help` with `iam compartment get` before making a live read. + +Treat OCI MCP as unavailable only when the OCI tools are absent from the tool inventory or the tool catalog/loading mechanism reports that they cannot be invoked. A returned authentication, authorization, connectivity, or OCI API error means the server is available but the tenancy validation failed; report that distinction and ask for corrected access or a valid tenancy OCID. Do not report an available tool as unavailable merely because it was not listed in an earlier tool snapshot or because the live read failed. + +### MCP validation interface + +Use the OCI MCP server for this read-only validation; never fall back to a shell command. + +| MCP tool | Purpose | Request format | +| --- | --- | --- | +| `get_oci_command_help` | Confirm current CLI syntax before the live read | `{ "command": "iam compartment get" }` | +| `run_oci_command` | Verify the supplied tenancy OCID resolves as the root compartment | `{ "command": "iam compartment get --compartment-id " }` | + +Rules for the tool request: + +- Pass only the OCI command text after `oci`; never include `oci`, `--profile`, `--auth`, or `--help`. +- Do not set a per-call profile; MCP server authentication and tenancy selection are server-level. +- Treat a successful response for the exact supplied OCID as valid. Treat not found, forbidden, authentication failure, or any different returned tenancy identifier as a validation failure. +- If the OCI MCP tool is unavailable, tell the user that tenancy validation was skipped because MCP is unavailable, then continue with the remaining validation rules. Do not guess, use the local OCI CLI, or claim the OCID is valid. +- If MCP returns not found, forbidden, authentication failure, or a different tenancy identifier, treat the supplied `tenancy_ocid` as unvalidated/invalid for this workflow. Pause and ask the user for a valid tenancy OCID or corrected OCI access before proceeding. + +## Compartment validation + +Apply these rules whenever the request creates, updates, moves, removes, or destroys a compartment hierarchy through the `compartments` module. + +> **Note:** An OCI tenancy is the root compartment. Validate tenancy OCIDs and all other compartment OCIDs with OCI IAM compartment commands (for example, `iam compartment get --compartment-id `), rather than using a separate tenancy command. + +### Name uniqueness within the parent + +Every compartment `name` must be unique among all compartments with the same effective parent. Determine the effective parent from, in order: + +1. the first-level compartment's explicit `parent_id`; +2. `default_parent_id`; +3. the tenancy root when neither is supplied; +4. the declared hierarchy parent for nested `children`. + +Inspect the full requested `compartments_configuration`, including nested children, and reject duplicate names in the same effective parent. The same name may appear under different parents only when OCI permits that scope. Do not confuse a Terraform map key with a compartment name. + +### Required description + +Every requested compartment at every level must include a `description` that is not `null`. Report the exact logical key/path for any missing or null description. + +### Nested hierarchy inputs + +For each requested nested compartment: + +- require a valid `name` and non-null `description`; +- ensure its parent exists as an ancestor declared in the same hierarchy or as a documented external parent dependency; +- resolve an external parent OCID with OCI MCP before treating it as valid; +- reject an unresolved parent reference, a self-parent, a cycle, or more than six hierarchy levels; +- preserve literal OCIDs and declared key references; do not infer a parent from a display name. + +## Validation scope still to be added + +Dedicated validation rules for Identity Domains, classic IAM groups, dynamic groups, and policies will be added later. Until then, apply the common lifecycle-state gate, tenancy-OCID validation, the module-specific structural checks in their collection references, and all existing repository-preservation rules. Do not invent additional rules.