kestra-io / kestra-io/plugin-oci

[Plugin] OCI — Resource Manager (Terraform Stacks)

Open
#12 0 comments 0 reactions 0 assignees View on GitHub
area/plugin
Dominant language
Java
Stars
0
Forks
0
Avg merge
18h 3m
Merged PRs (30d)
1

Description

## Summary

The OCI Resource Manager sub-plugin for `plugin-oci` enables Kestra flows to create, plan, and apply Terraform stacks via OCI Resource Manager — Oracle's managed Terraform service. This brings infrastructure-as-code provisioning into the orchestration layer, letting teams provision OCI infrastructure as a step in a larger pipeline (before running jobs, after releasing software, or as part of environment tear-down).

## Motivation

Platform and DevOps teams using OCI Resource Manager to manage infrastructure need to trigger stack operations from pipeline events: provision an environment before a load test, tear it down after, or apply changes as part of a CI/CD flow. Currently this requires OCI CLI invocations in shell scripts outside Kestra's control. A native plugin task submits the Terraform plan/apply job, waits for completion, and emits the job state and output variables as typed task outputs.

## Context

Part of the OCI Plugin Suite EPIC: https://github.com/kestra-io/plugin-oci/issues/2
Reference: `plugin-terraform` for pattern inspiration; OCI Resource Manager is functionally equivalent to Terraform Cloud workspaces.

## API Reference

- **Official docs**: https://docs.oracle.com/en-us/iaas/api/#/en/resourcemanager/latest/
- **Authentication**: Config-file (`~/.oci/config`), instance principal, or `SimpleAuthenticationDetailsProvider`
- **Base URL pattern**: `https://resourcemanager.{region}.oraclecloud.com/20180917/`
- **SDK**: OCI Java SDK v3.87.0 via BOM

## Gradle Dependencies

Add to `build.gradle`:

```groovy
// OCI Java SDK BOM
implementation platform("com.oracle.oci.sdk:oci-java-sdk-bom:3.87.0")
// Resource Manager
implementation "com.oracle.oci.sdk:oci-java-sdk-resourcemanager"
implementation "com.oracle.oci.sdk:oci-java-sdk-common"
```

## Plugin Structure

- **Repository**: `plugin-oci`
- **Namespace**: `io.kestra.plugin.oci.resourcemanager`
- **Sub-plugins**: `resourcemanager` (stacks, jobs)

## Suggested Tasks

1. `PlanStack` — create and run a plan job on a stack, wait for completion, emit plan output
2. `ApplyStack` — create and run an apply job on a stack, wait for completion, emit outputs
3. `DestroyStack` — create and run a destroy job on a stack
4. `GetJob` — fetch job details and emit lifecycle state and output variables
5. `ListJobs` — list jobs for a stack with optional state filter
6. `CreateStack` — create a new Resource Manager stack (from a zip or Object Storage path)
7. `DeleteStack` — delete a stack
8. `ListStacks` — list stacks in a compartment
9. Add `JobCompletedTrigger` — poll until a job reaches SUCCEEDED or FAILED
10. Write unit + integration tests

## YAML Examples

### Example 1 — Plan and apply a Terraform stack for a new environment

```yaml
id: provision_oci_environment
namespace: company.platform

inputs:
- id: stack_ocid
type: STRING

tasks:
- id: plan
type: io.kestra.plugin.oci.resourcemanager.PlanStack
region: eu-frankfurt-1
tenancyOcid: "{{ secret('OCI_TENANCY_OCID') }}"
userId: "{{ secret('OCI_USER_OCID') }}"
fingerprint: "{{ secret('OCI_FINGERPRINT') }}"
privateKey: "{{ secret('OCI_PRIVATE_KEY') }}"
stackId: "{{ inputs.stack_ocid }}"
waitForCompletion: true

- id: apply
type: io.kestra.plugin.oci.resourcemanager.ApplyStack
region: eu-frankfurt-1
tenancyOcid: "{{ secret('OCI_TENANCY_OCID') }}"
userId: "{{ secret('OCI_USER_OCID') }}"
fingerprint: "{{ secret('OCI_FINGERPRINT') }}"
privateKey: "{{ secret('OCI_PRIVATE_KEY') }}"
stackId: "{{ inputs.stack_ocid }}"
waitForCompletion: true

- id: log_outputs
type: io.kestra.plugin.core.log.Log
message: "Stack applied — job state: {{ outputs.apply.lifecycleState }}"
```

### Example 2 — List all stacks and log their names

```yaml
id: audit_rm_stacks
namespace: company.platform

tasks:
- id: list_stacks
type: io.kestra.plugin.oci.resourcemanager.ListStacks
region: eu-frankfurt-1
tenancyOcid: "{{ secret('OCI_TENANCY_OCID') }}"
userId: "{{ secret('OCI_USER_OCID') }}"
fingerprint: "{{ secret('OCI_FINGERPRINT') }}"
privateKey: "{{ secret('OCI_PRIVATE_KEY') }}"
compartmentId: "{{ secret('OCI_COMPARTMENT_OCID') }}"

- id: log
type: io.kestra.plugin.core.log.Log
message: "Found {{ outputs.list_stacks.count }} Resource Manager stacks"
```

### Example 3 — React when a Terraform job completes

```yaml
id: on_rm_job_complete
namespace: company.platform

triggers:
- id: job_watcher
type: io.kestra.plugin.oci.resourcemanager.JobCompletedTrigger
region: eu-frankfurt-1
tenancyOcid: "{{ secret('OCI_TENANCY_OCID') }}"
userId: "{{ secret('OCI_USER_OCID') }}"
fingerprint: "{{ secret('OCI_FINGERPRINT') }}"
privateKey: "{{ secret('OCI_PRIVATE_KEY') }}"
jobId: "{{ secret('OCI_RM_JOB_OCID') }}"
interval: PT2M

tasks:
- id: handle
type: io.kestra.plugin.core.log.Log
message: "Resource Manager job {{ trigger.jobId }} — state: {{ trigger.lifecycleState }}"
```

## Acceptance Criteria

- [ ] `PlanStack`, `ApplyStack`, `DestroyStack`, `GetJob`, `ListJobs`, `CreateStack`, `DeleteStack`, `ListStacks` tasks implemented
- [ ] `PlanStack`, `ApplyStack`, `DestroyStack` support `waitForCompletion: true`
- [ ] `JobCompletedTrigger` polling trigger implemented
- [ ] `ApplyStack` output includes Terraform output variables as a map
- [ ] All `Property` fields support Kestra expression language
- [ ] Unit + integration tests pass (`./gradlew test`)
- [ ] `package-info.java` with `@PluginSubGroup(category = PluginSubGroup.PluginCategory.CLOUD)`
- [ ] Build passes with `./gradlew build`

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the existing plugin-terraform pattern and the OCI SDK dependencies proposed for build.gradle. Map the Resource Manager tasks and JobCompletedTrigger under io.kestra.plugin.oci.resourcemanager, then add package-info.java and unit/integration tests. Done means all listed tasks, polling and expression support are implemented and ./gradlew test and ./gradlew build pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
cloud, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.