GKE Cluster Health and Observability Compliance Gate

id: gke-cluster-health-compliance-gate
namespace: company.team

description: |
  Read a GKE cluster's real metadata, classify it HEALTHY, WARNING, CRITICAL or PROBE_FAILED
  from its actual node pool statuses and whether logging or monitoring export is disabled,
  alert Slack with the exact node pool names and service values, and log a final audit
  summary either way.

inputs:
  - id: cluster_project_id
    type: STRING
    displayName: Cluster project ID
    description: GCP project that owns the cluster. Maps to the ClusterMetadata
      task's clusterProjectId field.
    defaults: "my-gcp-project"

  - id: cluster_zone
    type: STRING
    displayName: Cluster zone or region
    description: Zone or region where the cluster resides, for example
      us-central1-a. Maps to the ClusterMetadata task's clusterZone field.
    defaults: "us-central1-a"

  - id: cluster_id
    type: STRING
    displayName: Cluster ID
    description: Name of the GKE cluster to audit. Maps to the ClusterMetadata
      task's clusterId field.
    defaults: "production-cluster"

  - id: unhealthy_node_pool_threshold
    type: INT
    displayName: Unhealthy node pool threshold
    description: Number of node pools reporting ERROR, RUNNING_WITH_ERROR or
      STATUS_UNSPECIFIED at or above which the cluster is classified CRITICAL.
    defaults: 1

  - id: require_observability
    type: BOOL
    displayName: Require observability export
    description: When true, a logging or monitoring service set to none, GKE's own
      value for disabled, is treated as a CRITICAL compliance violation.
    defaults: true

  - id: observability_scope
    type: SELECT
    displayName: Observability scope checked
    description: Which service require_observability checks. logging checks
      loggingService only, monitoring checks monitoringService only, both checks
      either.
    values:
      - "logging"
      - "monitoring"
      - "both"
    defaults: "both"

tasks:
  - id: probe_cluster
    type: io.kestra.plugin.gcp.gke.ClusterMetadata
    description: Read-only. Fetches the cluster's networking, node pool statuses,
      and logging and monitoring service configuration.
    allowFailure: true
    serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT') }}"
    clusterProjectId: "{{ inputs.cluster_project_id }}"
    clusterZone: "{{ inputs.cluster_zone }}"
    clusterId: "{{ inputs.cluster_id }}"

  - id: audit_node_pools
    type: io.kestra.plugin.core.output.OutputValues
    description: Splits node pools into those in a failed state and those merely
      mid-transition. Empty lists when the probe itself did not return.
    values:
      bad_pools: >-
        {{ (outputs.probe_cluster is not defined) ? '[]' :
        (outputs.probe_cluster.nodePools | jq('[.[] | select(.status == "ERROR"
        or .status == "RUNNING_WITH_ERROR" or .status == "STATUS_UNSPECIFIED") |
        .name]') | first | toJson) }}
      transitional_pools: >-
        {{ (outputs.probe_cluster is not defined) ? '[]' :
        (outputs.probe_cluster.nodePools | jq('[.[] | select(.status ==
        "PROVISIONING" or .status == "RECONCILING" or .status == "STOPPING") |
        .name]') | first | toJson) }}

  - id: classify_cluster_health
    type: io.kestra.plugin.core.debug.Return
    description: PROBE_FAILED when the probe produced no output at all, CRITICAL
      when enough node pools are failed or observability export is disabled,
      WARNING when a node pool is mid-transition, HEALTHY otherwise.
    format: "{{ outputs.probe_cluster is not defined ? 'PROBE_FAILED' :
      (((fromJson(outputs.audit_node_pools.values.bad_pools) | length) >=
      inputs.unhealthy_node_pool_threshold or (inputs.require_observability and
      ((inputs.observability_scope != 'monitoring' and
      outputs.probe_cluster.loggingService == 'none') or
      (inputs.observability_scope != 'logging' and
      outputs.probe_cluster.monitoringService == 'none')))) ? 'CRITICAL' :
      ((fromJson(outputs.audit_node_pools.values.transitional_pools) | length) >
      0 ? 'WARNING' : 'HEALTHY')) }}"

  - id: route_by_cluster_health
    type: io.kestra.plugin.core.flow.Switch
    description: Branch A logs a healthy cluster. Branch B alerts Slack when a node
      pool failed, is mid-transition, observability export is disabled, or the
      probe itself failed.
    value: "{{ outputs.classify_cluster_health.value }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "GKE cluster {{ inputs.cluster_id }} healthy. {{
            outputs.probe_cluster.nodePoolsCount }} node pool(s), logging={{
            outputs.probe_cluster.loggingService }}, monitoring={{
            outputs.probe_cluster.monitoringService }}."
      "WARNING":
        - id: alert_warning
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {"text": "GKE cluster " ~ inputs.cluster_id ~ " WARNING. Node pool(s) mid-transition: " ~ (fromJson(outputs.audit_node_pools.values.transitional_pools) | join(", ")) ~ ". No action needed if this is an expected upgrade or scale event, alert again if it persists."} | toJson }}
      "CRITICAL":
        - id: alert_critical
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {"text": "GKE cluster " ~ inputs.cluster_id ~ " CRITICAL. Failed node pool(s): " ~ (fromJson(outputs.audit_node_pools.values.bad_pools) | join(", ")) ~ ". loggingService=" ~ outputs.probe_cluster.loggingService ~ " monitoringService=" ~ outputs.probe_cluster.monitoringService ~ "."} | toJson }}
      "PROBE_FAILED":
        - id: alert_probe_failed
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {"text": "GKE cluster metadata probe for " ~ inputs.cluster_id ~ " in " ~ inputs.cluster_project_id ~ "/" ~ inputs.cluster_zone ~ " did not return a result. Check GCP_SERVICE_ACCOUNT and that the cluster exists at that project and zone."} | toJson }}

  - id: log_audit_summary
    type: io.kestra.plugin.core.log.Log
    description: Final audit log confirming the gate ran, regardless of the branch
      taken above.
    message: "GKE cluster health compliance gate completed. cluster={{
      inputs.cluster_id }} status={{ outputs.classify_cluster_health.value }}
      require_observability={{ inputs.require_observability }}"

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {{ {"text": "GKE cluster health compliance gate flow failed (execution " ~ execution.id ~ "). Check the execution logs."} | toJson }}

triggers:
  - id: hourly
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled.
    cron: "0 * * * *"
    disabled: true
    inputs:
      cluster_project_id: "my-gcp-project"
      cluster_zone: "us-central1-a"
      cluster_id: "production-cluster"
      unhealthy_node_pool_threshold: 1
      require_observability: true
      observability_scope: "both"