Add mkdocs role for publishing user and operator guides on Azimuth subdomain

roles/admin_dashboard_ingress/defaults/main.yml

@@ -266,6 +266,79 @@ admin_dashboard_ingress_kubernetes_dashboard:
   port: "{{ admin_dashboard_ingress_kubernetes_dashboard_port }}"
   tls_secret_name: "{{ admin_dashboard_ingress_kubernetes_dashboard_tls_secret_name }}"
 
+#####
+# NOTE(scott): We're slightly hijacking the admin dashboards functionality here
+# since the static docs pages are not strictly admin-only dashboards but it's much
+# easier to reuse the existing functionality rather than duplicating the role.
+#####
+
+# Settings for the operator docs ingress
+#   The namespace for the ingress
+admin_dashboard_ingress_operator_docs_namespace: mkdocs
+#   The name for the ingress
+admin_dashboard_ingress_operator_docs_name: operator-docs
+#   The host for the ingress
+admin_dashboard_ingress_operator_docs_host: >-
+  {{-
+    "{}.{}".format(ingress_operator_docs_subdomain, ingress_base_domain)
+    if ingress_operator_docs_subdomain is defined and ingress_base_domain is defined
+    else undef(hint = 'admin_dashboard_ingress_operator_docs_host is required')
+  }}
+#   The name of the service for the ingress
+admin_dashboard_ingress_operator_docs_service: operator-docs-mkdocs-helm
+#   The name of the service port for the ingress
+admin_dashboard_ingress_operator_docs_port: http
+#   The name of the secret containing the certificate for the ingress
+admin_dashboard_ingress_operator_docs_tls_secret_name: >-
+  {{-
+    admin_dashboard_ingress_tls_wildcard_secret_name
+    if admin_dashboard_ingress_tls_wildcard_certificate
+    else admin_dashboard_ingress_operator_docs_name ~ '-tls'
+  }}
+#   The ingress definition
+admin_dashboard_ingress_operator_docs:
+  name: "{{ admin_dashboard_ingress_operator_docs_name }}"
+  namespace: "{{ admin_dashboard_ingress_operator_docs_namespace }}"
+  host: "{{ admin_dashboard_ingress_operator_docs_host }}"
+  service: "{{ admin_dashboard_ingress_operator_docs_service }}"
+  port: "{{ admin_dashboard_ingress_operator_docs_port }}"
+  tls_secret_name: "{{ admin_dashboard_ingress_operator_docs_tls_secret_name }}"
+
+# Settings for the user docs ingress
+#   The namespace for the ingress
+admin_dashboard_ingress_user_docs_namespace: mkdocs
+#   The name for the ingress
+admin_dashboard_ingress_user_docs_name: user-docs
+#   The host for the ingress
+admin_dashboard_ingress_user_docs_host: >-
+  {{-
+    "{}.{}".format(ingress_user_docs_subdomain, ingress_base_domain)
+    if ingress_user_docs_subdomain is defined and ingress_base_domain is defined
+    else undef(hint = 'admin_dashboard_ingress_user_docs_host is required')
+  }}
+#   The name of the service for the ingress
+admin_dashboard_ingress_user_docs_service: user-docs-mkdocs-helm
+#   The name of the service port for the ingress
+admin_dashboard_ingress_user_docs_port: http
+#   The name of the secret containing the certificate for the ingress
+admin_dashboard_ingress_user_docs_tls_secret_name: >-
+  {{-
+    admin_dashboard_ingress_tls_wildcard_secret_name
+    if admin_dashboard_ingress_tls_wildcard_certificate
+    else admin_dashboard_ingress_user_docs_name ~ '-tls'
+  }}
+#   The ingress definition
+admin_dashboard_ingress_user_docs:
+  name: "{{ admin_dashboard_ingress_user_docs_name }}"
+  namespace: "{{ admin_dashboard_ingress_user_docs_namespace }}"
+  host: "{{ admin_dashboard_ingress_user_docs_host }}"
+  service: "{{ admin_dashboard_ingress_user_docs_service }}"
+  port: "{{ admin_dashboard_ingress_user_docs_port }}"
+  tls_secret_name: "{{ admin_dashboard_ingress_user_docs_tls_secret_name }}"
+  # We want TLS but not auth annotations for user docs
+  annotations: "{{ admin_dashboard_ingress_tls_annotations if admin_dashboard_ingress_tls_enabled else {} }}"
+  # annotations: "{{ admin_dashboard_ingress_annotations if false else {} }}" # Don't want auth for user docs
+
 # The list of ingresses to create
 admin_dashboard_ingresses: >-
   {{-
@@ -276,6 +349,8 @@ admin_dashboard_ingresses: >-
       admin_dashboard_ingress_ara,
       admin_dashboard_ingress_helm_dashboard,
       admin_dashboard_ingress_kubernetes_dashboard,
+      admin_dashboard_ingress_operator_docs,
+      admin_dashboard_ingress_user_docs,
     ] |
       select() |
       list

roles/admin_dashboard_ingress/tasks/main.yml

@@ -66,7 +66,7 @@
         name: "{{ item.name }}"
         namespace: "{{ item.namespace }}"
         labels: "{{ admin_dashboard_ingress_labels }}"
-        annotations: "{{ admin_dashboard_ingress_annotations }}"
+        annotations: "{{ item.annotations | default(admin_dashboard_ingress_annotations) }}"
       spec: >-
         {{-
           {

roles/mkdocs/defaults/main.yml

@@ -0,0 +1,54 @@
+---
+
+# Whether to enable self-hosted documentation sites
+mkdocs_enabled: true
+mkdocs_operator_docs_enabled: "{{ mkdocs_enabled }}"
+mkdocs_user_docs_enabled: "{{ mkdocs_enabled }}"
+
+# The Helm chart to use
+mkdocs_chart_repo: https://azimuth-cloud.github.io/mkdocs-helm
+mkdocs_chart_name: mkdocs-helm
+mkdocs_chart_version: 0.1.0
+
+# Helm Release information
+# TODO: Are we happy with this namespace? Maybe 'azimuth' namespace instead?
+mkdocs_release_namespace: mkdocs
+
+# The timeout to wait for chart deployment to become ready
+mkdocs_wait_timeout: 5m
+
+# Optional SSH private key to use for accessing private repos
+mkdocs_deploy_ssh_private_key:
+
+# The values for the operator docs release
+mkdocs_operator_docs_repo: https://github.com/azimuth-cloud/azimuth-config
+mkdocs_operator_docs_branch: stable # TODO: Can we make this match deployed release tag?
+mkdocs_operator_docs_release_defaults:
+  repo: "{{ mkdocs_operator_docs_repo }}"
+  branch: "{{ mkdocs_operator_docs_branch }}"
+  requirementsPath: requirements-docs.txt
+  sshPrivateKey: "{{ mkdocs_deploy_ssh_private_key }}"
+
+mkdocs_operator_docs_release_overrides: {}
+mkdocs_operator_docs_release_values: >-
+  {{-
+    mkdocs_operator_docs_release_defaults |
+      combine(mkdocs_operator_docs_release_overrides, recursive = True)
+  }}
+
+# The values for the user docs release
+# TODO: Move these docs to azimuth-config repo
+mkdocs_user_docs_repo: https://github.com/azimuth-cloud/azimuth-user-docs
+mkdocs_user_docs_branch: # TODO: Can we make this match deployed release tag?
+mkdocs_user_docs_release_defaults:
+  repo: "{{ mkdocs_user_docs_repo }}"
+  branch: "{{ mkdocs_user_docs_branch }}"
+  requirementsPath: requirements.txt
+  sshPrivateKey: "{{ mkdocs_deploy_ssh_private_key }}"
+
+mkdocs_user_docs_release_overrides: {}
+mkdocs_user_docs_release_values: >-
+  {{-
+    mkdocs_user_docs_release_defaults |
+      combine(mkdocs_user_docs_release_overrides, recursive = True)
+  }}

roles/mkdocs/tasks/main.yml

@@ -0,0 +1,35 @@
+---
+
+# TODO: Add sshPrivateKeySecretRef field to mkdocs-helm and create secret separately here?
+
+- name: Install operator docs site on target Kubernetes cluster
+  kubernetes.core.helm:
+    chart_ref: "{{ mkdocs_chart_name }}"
+    chart_repo_url: "{{ mkdocs_chart_repo }}"
+    chart_version: "{{ mkdocs_chart_version }}"
+    release_state: "{{ 'present' if mkdocs_operator_docs_enabled else 'absent' }}"
+    release_namespace: "{{ mkdocs_release_namespace }}"
+    release_name: operator-docs
+    release_values: "{{ mkdocs_operator_docs_release_values }}"
+    atomic: yes
+    create_namespace: yes
+    wait: yes
+    wait_timeout: "{{ mkdocs_wait_timeout }}"
+
+
+- name: Install user docs site on target Kubernetes cluster
+  kubernetes.core.helm:
+    chart_ref: "{{ mkdocs_chart_name }}"
+    chart_repo_url: "{{ mkdocs_chart_repo }}"
+    chart_version: "{{ mkdocs_chart_version }}"
+    release_state: "{{ 'present' if mkdocs_user_docs_enabled else 'absent' }}"
+    release_namespace: "{{ mkdocs_release_namespace }}"
+    release_name: user-docs
+    release_values: "{{ mkdocs_user_docs_release_values }}"
+    atomic: yes
+    create_namespace: yes
+    wait: yes
+    wait_timeout: "{{ mkdocs_wait_timeout }}"
+
+# TODO: How to we trigger a docs rebuild if Helm values haven't changed (but remote docs have)?
+# Restart nginx pod? Add k8s cronjob?