diff --git a/docs/en/solutions/ArtifactPromotionRun_Approval_Notification_with_CorpWeChat.md b/docs/en/solutions/ArtifactPromotionRun_Approval_Notification_with_CorpWeChat.md new file mode 100644 index 0000000..7ad982c --- /dev/null +++ b/docs/en/solutions/ArtifactPromotionRun_Approval_Notification_with_CorpWeChat.md @@ -0,0 +1,493 @@ +--- +id: KB2505xxxx +products: + - Alauda DevOps +kind: + - Solution +--- + +# ArtifactPromotionRun Approval Event Notification with CorpWeChat + +## Overview + +This guide demonstrates how to use **Kube Event Enricher** to enable personalized subscriptions to artifact promotion approval events and deliver notifications via CorpWeChat. + +### Architecture Flow + +```text +K8s Events (ArtifactPromotionRun) + ↓ +APIServerSource (Watches Event resources) + ↓ +Kube Event Enricher Sink (Enriches event data) + ↓ +Knative Broker (Event distribution) + ↓ +ClusterSubscription (Personal subscription + CloudEvent filtering) + ↓ +CorpWeChat Notification Service (Katanomi Plugin) +``` + +### Supported Event Types + +| Event Type | CloudEvent Type | Trigger Scenario | Notification Recipients | +|---------|----------------|----------|---------| +| Approval Pending | `dev.katanomi.cloudevents.kubeevent.artifactpromotionrun.approvalpending.v1alpha1` | Artifact promotion request pending approval | Approvers | +| Approval Denied | `dev.katanomi.cloudevents.kubeevent.artifactpromotionrun.approvaldenied.v1alpha1` | Promotion request has been rejected | Requester | +| Approval Approved | `dev.katanomi.cloudevents.kubeevent.artifactpromotionrun.running.v1alpha1` | Promotion request approved and now executing | Requester | +| Promotion Failed | `dev.katanomi.cloudevents.kubeevent.artifactpromotionrun.failed.v1alpha1` | Promotion operation has failed | Requester | + +--- + +## Prerequisites + +ACP Version Requirement: >= 4.0 + +### Required Components + +Before proceeding, ensure the following components are installed and configured: + +- **Alauda DevOps v3**: Provides ArtifactPromotion and subscription/notification capabilities +- **Knative Eventing**: Supplies Broker and Trigger mechanisms for event routing, deployed in ACP Global +- **Kube Event Enricher Sink**: Event enrichment service (installed in this guide), deployed in ACP Global + +### Permission Requirements + +- **System Administrator**: Responsible for infrastructure setup and notification template configuration +- **Project Administrator/Developer**: Configures personal subscriptions for team members and individual users + +--- + +## Offline Package Preparation + +This section describes the required materials for deploying artifact promotion notifications in offline environments. + +### Required Materials + +The following components are required: + +- Kube Event Enricher Sink deployment manifests and container images +- Artifact promotion notification template YAML files + +### Downloading and Preparing the Installation Package + +For downloading the offline installation package and uploading container images to your cluster registry, refer to the **[Offline Package Preparation](ArtifactPromotionRun_Approval_Notification_with_CorpWeChat_Install_kubeevent-enricher.md#offline-package-preparation)** section in the Installation Guide. + +**Note**: All subsequent commands in this guide assume you are working from the `kubeevent-enricher` directory. + +## Setup Overview + +This solution consists of two phases: **System Configuration** (one-time) and **User Configuration** (on-demand). + +--- + +## System Configuration + +### 1.1 Deploy Kube Event Enricher Sink + +Refer to the [Kube Event Enricher Sink Installation Guide](ArtifactPromotionRun_Approval_Notification_with_CorpWeChat_Install_kubeevent-enricher.md) for deployment instructions. + +### 1.2 Create APIServerSource to Watch Kubernetes Events + +Create a dedicated namespace and deploy an APIServerSource to watch all Kubernetes Events: + +```bash +# Create watcher namespace +kubectl create namespace kubeevent-watcher + +# Create APIServerSource and RBAC configuration +cat < + corpSecret: + agentId: +kind: Secret +metadata: + labels: + cpaas.io/notification.server.category: Corp + cpaas.io/notification.server.type: CorpWeChat + name: platform-corpwechat-server + namespace: cpaas-system +type: NotificationServer +EOF +``` + +### 1.4 Create Notification Templates + +Create notification templates for artifact promotion events: + +```bash +export PLATFORM_URL=xx # Set to ACP platform URL +cat dist/kubeevent.artifactpromotionrun.template.yaml | envsubst | kubectl apply -f - +``` + +This manifest contains four NotificationTemplate resources: +- `kubeevent.artifactpromotionrun.approvalpending` - Approval Pending +- `kubeevent.artifactpromotionrun.approvaldenied` - Approval Denied +- `kubeevent.artifactpromotionrun.running` - Approval Approved/Executing +- `kubeevent.artifactpromotionrun.failed` - Promotion Failed + +### 1.5 Update Katanomi Platform Configuration + +Update the Katanomi configuration to enable the CorpWeChat notification channel and associate notification templates in the ACP Global Cluster: + +```bash +cat < -o yaml + ``` + Ensure `sink.pluginclasses` annotation contains `corpwechat` and the status shows `Ready`. + +4. **Review kubeevent-enricher-sink logs**: + ```bash + kubectl -n kubeevent-enricher logs -l app=kubeevent-enricher-sink --tail=100 + ``` + +5. **Review katanomi-plugin logs**: + ```bash + kubectl -n cpaas-system logs -l control-plane=katanomi-plugin --tail=100 + ``` + + +--- + +## Advanced Configuration and References + +### Subscribing to Multiple Namespaces + +To subscribe a single user to promotion events across multiple namespaces, add multiple subscription entries: + +```bash +kubectl apply -f - <//` | `http://broker-ingress.knative-operators.svc.cluster.local` | No | +| `--log-level` | Log level for the application. Valid values: `debug`, `info`, `warn`, `error` | `info` | No | +| `--event-type-prefix` | Prefix to add to the CloudEvent type attribute. The final type will be `...v1alpha1` | `dev.katanomi.cloudevents.kubeevent` | No | + +## Uninstallation + +To remove the Kube Event Enricher Sink from your cluster: + +```bash +kubectl delete -f dist/install.yaml +``` + +## Troubleshooting + +### Check Service Status + +```bash +# View deployment details +kubectl -n kubeevent-enricher describe deploy kubeevent-enricher-sink + +# View pod logs +kubectl -n kubeevent-enricher logs -l app=kubeevent-enricher-sink --tail=100 +``` + +### Common Issues + +**Issue**: Pods fail to start with "ImagePullBackOff" +- **Solution**: Ensure your cluster has access to the container registry. Check image pull secrets if using a private registry. + +**Issue**: Events are not being enriched +- **Solution**: + - Verify the APIServerSource is correctly configured to send to the enricher service + - Check that the enricher has proper RBAC permissions to read the involved resources + - Review enricher logs for error messages + +**Issue**: Events not reaching the broker +- **Solution**: + - Verify the `--broker-ingress` flag points to the correct broker ingress service + - Check network policies allow traffic from the enricher namespace to the broker + - Ensure the broker exists in the target namespace + +## Next Steps + +After installation, refer to the following documentation: + +- [Artifact Promotion Notifications](ArtifactPromotionRun_Approval_Notification_with_CorpWeChat.md) - Implement artifact promotion scenario notifications using Kube Event Enricher