kestra-io / kestra-io/plugin-oci
[Plugin] OCI — Notifications (ONS)
- 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