kestra-io / kestra-io/plugin-oci

[Plugin] OCI — Notifications (ONS)

Open
#11 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 Notifications sub-plugin for `plugin-oci` enables Kestra flows to publish messages to OCI Notification Service (ONS) topics — sending alerts, status updates, or event payloads to email, Slack, PagerDuty, or custom HTTP endpoints configured as ONS subscriptions. This makes OCI Notifications a lightweight, native alerting and fan-out mechanism available directly from any Kestra task.

## Motivation

Ops and platform teams on OCI already have ONS topics wired to their alerting endpoints (email, PagerDuty, custom webhooks). When a Kestra pipeline fails or completes a critical step, they want to publish to an existing ONS topic rather than configure a separate notification system. A native `PublishMessage` task lets flows reuse the notification infrastructure already configured in OCI, eliminating the need for custom HTTP tasks with manual OCI request signing.

## Context

Part of the OCI Plugin Suite EPIC: https://github.com/kestra-io/plugin-oci/issues/2
Reference: `plugin-aws` SNS `Publish` task.

## API Reference

- **Official docs**: https://docs.oracle.com/en-us/iaas/api/#/en/notification/latest/
- **Authentication**: Config-file (`~/.oci/config`), instance principal, or `SimpleAuthenticationDetailsProvider`
- **Base URL pattern**: `https://notification.{region}.oraclecloud.com/20181201/`
- **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")
// Notifications (ONS)
implementation "com.oracle.oci.sdk:oci-java-sdk-ons"
implementation "com.oracle.oci.sdk:oci-java-sdk-common"
```

## Plugin Structure

- **Repository**: `plugin-oci`
- **Namespace**: `io.kestra.plugin.oci.ons`
- **Sub-plugins**: `ons` (topics, subscriptions, publish)

## Suggested Tasks

1. `PublishMessage` — publish a message (title + body) to an ONS topic
2. `CreateTopic` — create a new ONS topic in a compartment
3. `DeleteTopic` — delete a topic
4. `ListTopics` — list topics in a compartment
5. `CreateSubscription` — add a subscription (email, HTTPS, PagerDuty, Slack) to a topic
6. `DeleteSubscription` — remove a subscription from a topic
7. Add `NewMessageTrigger` — receive and process ONS messages via a confirmation URL (advanced)
8. Write unit + integration tests

## YAML Examples

### Example 1 — Notify an ops team when a pipeline completes

```yaml
id: pipeline_with_notification
namespace: company.ops

tasks:
- id: run_pipeline
type: io.kestra.plugin.core.log.Log
message: Running batch pipeline...

- id: notify_success
type: io.kestra.plugin.oci.ons.PublishMessage
region: eu-frankfurt-1
tenancyOcid: "{{ secret('OCI_TENANCY_OCID') }}"
userId: "{{ secret('OCI_USER_OCID') }}"
fingerprint: "{{ secret('OCI_FINGERPRINT') }}"
privateKey: "{{ secret('OCI_PRIVATE_KEY') }}"
topicId: "{{ secret('OCI_ONS_TOPIC_OCID') }}"
title: "Pipeline {{ flow.id }} completed"
body: "Execution {{ execution.id }} finished at {{ execution.startDate }}"
```

### Example 2 — Alert on failure using Kestra error handling

```yaml
id: pipeline_with_alerting
namespace: company.ops

tasks:
- id: risky_task
type: io.kestra.plugin.core.log.Log
message: Processing...

errors:
- id: alert_on_failure
type: io.kestra.plugin.oci.ons.PublishMessage
region: eu-frankfurt-1
tenancyOcid: "{{ secret('OCI_TENANCY_OCID') }}"
userId: "{{ secret('OCI_USER_OCID') }}"
fingerprint: "{{ secret('OCI_FINGERPRINT') }}"
privateKey: "{{ secret('OCI_PRIVATE_KEY') }}"
topicId: "{{ secret('OCI_ALERTS_TOPIC_OCID') }}"
title: "ALERT: {{ flow.id }} failed"
body: "Execution {{ execution.id }} failed — check Kestra UI for details"
```

### Example 3 — List all ONS topics and log their ARN equivalents

```yaml
id: audit_ons_topics
namespace: company.ops

tasks:
- id: list_topics
type: io.kestra.plugin.oci.ons.ListTopics
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_count
type: io.kestra.plugin.core.log.Log
message: "Found {{ outputs.list_topics.count }} ONS topics"
```

## Acceptance Criteria

- [ ] `PublishMessage`, `CreateTopic`, `DeleteTopic`, `ListTopics`, `CreateSubscription`, `DeleteSubscription` tasks implemented
- [ ] `PublishMessage` accepts title and body as expression-rendered strings
- [ ] 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 reading the plugin-aws SNS Publish task as the stated reference, then inspect build.gradle and the existing plugin-oci structure. Implement the six requested ONS tasks, expression-rendered PublishMessage fields, package-info.java metadata, and unit/integration coverage; run ./gradlew test and ./gradlew build to verify completion.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.