Kubernetes Ingress TLS Certificate Expiry Guard

id: kubernetes-ingress-tls-certificate-expiry-guard
namespace: company.team
description: |
  Automated Kubernetes Ingress TLS certificate expiration sentinel. Probes active hostnames defined across
  Ingress resources, measures remaining SSL certificate validity, and alerts SRE teams on Slack before expiration.

concurrency:
  limit: 1

inputs:
  - id: days_before_expiry_warning
    type: INT
    displayName: Expiry Warning Threshold
    defaults: 21
    description: "Number of days before SSL/TLS certificate expiration to trigger an
      operational alert."

  - id: ingress_hosts_list
    type: STRING
    displayName: Ingress Domain Hosts
    defaults: "api.company.com,app.company.com"
    description: "Comma-separated list of public Ingress domain hostnames to verify
      over TLS."

  - id: slack_channel
    type: STRING
    displayName: Slack Channel
    defaults: "#sre-alerts"
    description: "Slack channel destination for SSL/TLS certificate renewal alerts."

triggers:
  - id: daily_cert_audit
    type: io.kestra.plugin.core.trigger.Schedule
    description: "Audits Ingress TLS certificates daily at 08:00 UTC."
    cron: "0 8 * * *"

tasks:
  - id: probe_tls_certificates
    type: io.kestra.plugin.scripts.python.Script
    description: "Establishes TLS handshakes with specified Ingress domain endpoints
      to parse x509 expiration dates."
    containerImage: python:3.11-slim
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    outputFiles:
      - cert_audit_report.json
    script: |
      import ssl
      import socket
      import json
      from datetime import datetime, timezone
      from kestra import Kestra

      hosts_raw = "{{ inputs.ingress_hosts_list }}"
      hosts = [h.strip() for h in hosts_raw.split(",") if h.strip()]
      threshold_days = int("{{ inputs.days_before_expiry_warning }}")
      now = datetime.now(timezone.utc)

      results = []
      expiring_certs = []

      for host in hosts:
          try:
              ctx = ssl.create_default_context()
              with socket.create_connection((host, 443), timeout=5) as sock:
                  with ctx.wrap_socket(sock, server_hostname=host) as ssock:
                      cert = ssock.getpeercert()

              # Parse notAfter date format: 'May 15 12:00:00 2025 GMT'
              expire_str = cert.get("notAfter", "")
              expire_dt = datetime.strptime(expire_str, "%b %d %H:%M:%S %Y %Z").replace(tzinfo=timezone.utc)
              days_remaining = (expire_dt - now).days

              record = {
                  "host": host,
                  "expiration_date": expire_str,
                  "days_remaining": days_remaining,
                  "is_expiring": days_remaining <= threshold_days,
                  "status": "EXPIRING" if days_remaining <= threshold_days else "VALID"
              }
              results.append(record)

              if days_remaining <= threshold_days:
                  expiring_certs.append(record)

          except Exception as err:
              results.append({
                  "host": host,
                  "error": str(err),
                  "days_remaining": -1,
                  "is_expiring": True,
                  "status": "PROBE_FAILED"
              })
              expiring_certs.append({
                  "host": host,
                  "days_remaining": -1,
                  "error": str(err)
              })

      has_expiring = len(expiring_certs) > 0

      report = {
          "total_hosts_probed": len(hosts),
          "warning_threshold_days": threshold_days,
          "expiring_count": len(expiring_certs),
          "results": results,
          "has_expiring": has_expiring
      }

      with open("cert_audit_report.json", "w", encoding="utf-8") as f:
          json.dump(report, f, indent=2)

      top_offender = expiring_certs[0] if expiring_certs else {}
      Kestra.outputs({
          "has_expiring": has_expiring,
          "expiring_count": len(expiring_certs),
          "top_host": top_offender.get("host", "None"),
          "top_days_remaining": top_offender.get("days_remaining", 999)
      })

  - id: evaluate_cert_expiry
    type: io.kestra.plugin.core.flow.If
    description: "Branches execution based on whether any Ingress certificates are
      nearing expiration."
    condition: "{{ outputs.probe_tls_certificates.vars.has_expiring }}"
    then:
      - id: notify_slack_sre_team
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: "Dispatches high-priority certificate renewal warning to SRE Slack
          channel."
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "channel": "{{ inputs.slack_channel }}",
            "text": "*CRITICAL: Kubernetes Ingress TLS Certificate Expiration Warning*\n• *Affected Domains Count*: {{ outputs.probe_tls_certificates.vars.expiring_count }}\n• *Most Urgent Domain*: `{{ outputs.probe_tls_certificates.vars.top_host }}`\n• *Days Remaining*: {{ outputs.probe_tls_certificates.vars.top_days_remaining }} days (Threshold: {{ inputs.days_before_expiry_warning }} days)\n• *Operational Impact*: Expired TLS certificates trigger immediate browser security warnings, breaking external client connections and customer traffic.\n• *Recommended Remediation*: Verify cert-manager ClusterIssuer status or manually rotate the Kubernetes TLS Secret associated with `{{ outputs.probe_tls_certificates.vars.top_host }}`."
          }

    else:
      - id: log_valid_certs_status
        type: io.kestra.plugin.core.log.Log
        description: "Logs confirmation that all probed Ingress endpoints possess valid
          certificates."
        message: "Kubernetes Ingress TLS certificate audit compliant. All endpoints have
          more than {{ inputs.days_before_expiry_warning }} days validity
          remaining."

  - id: export_cert_manifest
    type: io.kestra.plugin.core.debug.Return
    description: "Outputs structured JSON certificate verification manifest for
      security audits."
    format: |
      {
        "pipeline": "kubernetes-ingress-tls-certificate-expiry-guard",
        "audited_at": "{{ execution.startDate }}",
        "expiring_count": {{ outputs.probe_tls_certificates.vars.expiring_count }},
        "status": "{{ outputs.probe_tls_certificates.vars.has_expiring ? 'ACTION_REQUIRED' : 'COMPLIANT' }}"
      }