Merge pull request #17 from hotosm/infra/193-eoapi

build: install eoAPI chart

Author: spwoodcock

.github/pull_request_template.md

@@ -0,0 +1,41 @@
+## What type of PR is this? (check all applicable)
+
+- [ ] 🍕 Feature
+- [ ] 🐛 Bug Fix
+- [ ] 📝 Documentation
+- [ ] 🧑‍💻 Refactor
+- [ ] ✅ Test
+- [ ] 🤖 Build or CI
+- [ ] ❓ Other (please specify)
+
+## Related Issue
+
+Example: Fixes #123
+
+## Describe this PR
+
+A brief description of how this solves the issue.
+
+## Screenshots
+
+Please provide screenshots of the change.
+
+## Alternative Approaches Considered
+
+Did you attempt any other approaches that are not documented in code?
+
+## Review Guide
+
+Notes for the reviewer. How to test this change?
+
+## Checklist before requesting a review
+
+- 📖 Read the HOT Contributing Guide: <https://docs.hotosm.org/become-a-contributor/>
+- 📖 Read the HOT Code of Conduct: <https://docs.hotosm.org/code-of-conduct>
+- 👷‍♀️ Create small PRs. In most cases, this will be possible.
+- ✅ Provide tests for your changes.
+- 📝 Use descriptive commit messages.
+- 📗 Update any related documentation and include any relevant screenshots.
+- 🔠 Does this PR introduce or change any environment variables? If so, make sure to specify this change in the description.
+
+## [optional] What gif best describes this PR or how it makes you feel?

.github/workflows/ci.yaml

@@ -1,4 +1,4 @@
-name: Deploy Terraform
+name: Deploy Changes
 on:
   push:
     branches:
@@ -35,12 +35,30 @@ jobs:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE }}
       - name: Provision TF
         uses: op5dev/tf-via-pr@v13
+        env:
+          TF_VAR_cluster_ci_access_role_arn: ${{ secrets.AWS_OIDC_ROLE }}
+          TF_VAR_cluster_admin_access_role_arns: ${{ secrets.CLUSTER_ADMIN_ACCESS_ROLE_ARNS }}
         with:
+          # command: 'apply'
           command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
           tool: tofu
           working-directory: terraform
           validate: true
           format: true
           arg-var-file: ${{ env.VAR_FILE }}
-          arg-var: cluster_ci_access_role_arn=${{ secrets.AWS_OIDC_ROLE }}
-          label-pr: false
+      - name: Get TF Outputs
+        run: |
+          echo "S3_BACKUP_ROLE=$(tofu -chdir=terraform output -var-file=vars/production.tfvars s3_backup_role)" >> $GITHUB_ENV
+          echo "CLUSTER_NAME=$(tofu -chdir=terraform output -var-file=vars/production.tfvars cluster_name)" >> $GITHUB_ENV
+      - name: Pull kubeconfig
+        run: |
+          aws eks update-kubeconfig --name ${{ env.CLUSTER_NAME }}
+      - name: Apply manifests
+        run: |
+          kubectl apply -f kubernetes/manifests/ ${{ github.event_name == 'pull_request' && '--dry-run' || '' }}
+      - name: Deploy eoAPI Chart
+        uses: helmfile/helmfile-action@v2.0.4
+        with:
+          helmfile-args: 'apply'
+          # helmfile-args: ${{ github.event_name == 'push' && 'apply' || 'diff' }}
+          helmfile-workdirectory: kubernetes/helm

Makefile

@@ -1,6 +1,6 @@
 AWS_PROFILE ?= default
-CLUSTER_NAME = $(shell tofu -chdir=terraform output cluster_name)
-S3_BACKUP_ROLE = $(shell tofu -chdir=terraform output s3_backup_role)
+CLUSTER_NAME = $(shell tofu -chdir=terraform output -var-file=vars/local.tfvars cluster_name)
+S3_BACKUP_ROLE = $(shell tofu -chdir=terraform output -var-file=vars/local.tfvars s3_backup_role)
 
 PGO_CHART_VERSION = 5.7.4
 EOAPI_CHART_VERSION = 0.7.1
@@ -34,4 +34,4 @@ init-eoapi:
 ## deploy-eoapi: Upgrade or install eoAPI release
 deploy-eoapi:
 	helm repo list | grep "eoapi" >/dev/null 2>&1 || { echo "Not initialized, run 'make init-eoapi' before retrying"; exit 1; }
-	helm upgrade --install --namespace eoapi --create-namespace eoapi eoapi/eoapi --version $(EOAPI_CHART_VERSION) -f kubernetes/helm/eoapi.yaml --set previousVersion=$(EOAPI_CHART_VERSION) --set postgrescluster.metadata.annotations.eks.amazonaws.com/role-arn=$(S3_BACKUP_ROLE)
+	helm upgrade --install --namespace eoapi --create-namespace eoapi eoapi/eoapi --version $(EOAPI_CHART_VERSION) -f kubernetes/helm/eoapi-values.yaml --set previousVersion=$(EOAPI_CHART_VERSION) --set postgrescluster.metadata.annotations."eks\.amazonaws\.com/role-arn"=$(S3_BACKUP_ROLE)

README.md

@@ -11,9 +11,30 @@ See the [inital proposal](docs/proposal.md) for more background.
 
 #### Required Tools
 
-[AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
-[OpenTofu](https://opentofu.org/docs/intro/install/)
-[kubectl](https://kubernetes.io/docs/tasks/tools/)
-[Helm](https://helm.sh/docs/intro/install/)
+- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+- [OpenTofu](https://opentofu.org/docs/intro/install/)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/)
+- [Helm](https://helm.sh/docs/intro/install/)
 
-// TODO 🚧
+
+### Areas for Further (Initial) Development
+
+#### Variable Management
+
+- Duplication exists between TF inputs, CI workflows, and local scripts.
+- A tool like https://github.com/helmfile/helmfile may help with sourcing variables by environment.
+    - A basic version has been added to deploy revision deltas, further templating would be required.
+- As more HOT applications + services are moved to cluster, this will only grow.
+
+#### Deployment
+
+- Provisioning is currently done in the same workflow (TF, K8s, Helm), mostly as byproduct of initial development phase. Can be further refined.
+- GitOps tools like ArgoCD are [under consideration](https://github.com/hotosm/k8s-infra/issues/14)
+- Flux [Tofu controller](https://github.com/flux-iac/tofu-controller) may be an analog for base infrastructure (further investigation required).
+
+#### Bridging TF and Kubernetes
+
+- TF-managed information often needs to be referenced on the cluster
+    - ex: PostgresCluster CRD requires the role ARN authorized for backups. Role and bucket are created in TF.
+- Global cluster resources are provisioned through TF, but argument can be made for their management by K8s. 
+- Ideal solution enables cluster resources to reference, mount, inject, etc. TF-managed information with minimal developer intervention.

kubernetes/README.md

@@ -0,0 +1,151 @@
+# Cluster Applications
+
+See [initial migration outline](../proposal.md) for main HOT OSM applications.
+
+Relevant Docs:
+- [kubectl]
+- [Helm]
+
+## Global
+
+### ClusterIssuer
+
+Issue TLS certificates for the cluster via [cert-manager]. See also [eoAPI TLS section](#transport-layer-security-tls).
+
+Install:
+```sh
+# ** See helm/eoapi-values.yaml for initial setup **
+$ kubectl apply -f kubernetes/manifests/cluster-issuer.yaml
+```
+
+## eoAPI
+
+Open source Earth Observation (EO) backend supporting Open Aerial Map (OAM).
+
+Site: https://eoapi.dev/
+Chart: https://github.com/developmentseed/eoapi-k8s
+
+Install:
+```sh
+$ helm upgrade --install --set disable_check_for_upgrades=true pgo oci://registry.developers.crunchydata.com/crunchydata/pgo --version $PGO_VERSION
+$ helm repo add eoapi https://devseed.com/eoapi-k8s/
+$ helm upgrade --install --namespace eoapi --create-namespace eoapi eoapi/eoapi \
+    --version $EOAPI_CHART_VERSION \
+    -f kubernetes/helm/eoapi-values.yaml \
+    --set previousVersion=$EOAPI_CHART_VERSION \
+    --set postgrescluster.metadata.annotations."eks\.amazonaws\.com/role-arn"=$S3_BACKUP_ROLE
+```
+
+#### helmfile
+
+A basic [helmfile] has been added for GitHub Actions, but its recommended to use outside of CI workflows to maintain consistency.
+
+```sh
+$ helmfile apply
+```
+
+Provided the values match, a similar workflow can be achieved with the Makefile commands if the additional install isn't desired.
+
+### Configuration
+
+See [eoAPI chart docs]. The following sections provide a basic outline of overlays, customizations, and considerations specific to HOT's initial implementation.
+
+#### Transport Layer Security (TLS)
+
+See [cert-manager docs] and [eoAPI guidance on cert-manager setup]. 
+
+- Requires a domain controlled by HOT
+- Issuer manifests and chart settings have been made available to provision certificates using [ingress annotations] and Let's Encrypt/[ACME]
+- Recommend going through staging issuer first to avoid hitting rate limits
+
+#### Backups
+
+Enabled with default settings, see the [PostgresOperator docs] for further customization. 
+
+Uses an [OIDC auth setup] to access S3, which requires propagating TF-managed information to K8s.
+
+> [!NOTE]
+> Further development to bridge and/or reorganize TF and K8s-provisioned resources may remove the need to set a `role-arn` annotation on each release.
+
+#### Monitoring / Observability / Autoscaling
+
+The eoAPI support chart adds Prometheus and Grafana tooling to enable systems analysis, visualization, and custom metrics for autoscaling. 
+
+- [eoAPI support chart setup]: in-depth walkthrough
+- [eoAPI chart configuration]: set HPA behavior for services
+- [eoAPI support chart dependencies]: explore further customization, provider documentation
+
+_Currently set to install once TLS is enabled in eoAPI._
+
+## Tips + Commands
+
+### Setup
+
+#### Local Context
+
+```sh
+$ aws eks update-kubeconfig --name <cluster_name>
+```
+
+### Debugging
+
+CLI manual will be most helpful:
+```sh
+$ kubectl --help
+```
+
+#### Examples
+
+Basic cluster overview:
+```sh
+$ kubectl get pod,svc,deploy -A
+```
+
+Shell into default container on pod:
+```sh
+$ kubectl -n <ns> exec -it <pod> -- bash
+# $
+```
+
+Inspect ingress details:
+```sh
+$ kubectl -n <ns> describe ingress/<ingress>
+```
+
+Redirect pod log output to file:
+```sh
+$ kubectl -n <ns> logs <pod> --all-containers=true >> file.log
+```
+
+[kubectl]:
+  https://kubernetes.io/docs/reference/kubectl/
+[Helm]:
+  https://helm.sh/docs/
+[Let's Encrypt]:
+  https://letsencrypt.org/
+[cert-manager]:
+  https://cert-manager.io/
+[cert-manager docs]:
+  https://cert-manager.io/docs/configuration/
+[helmfile]:
+  https://github.com/helmfile/helmfile
+[eoAPI chart docs]:
+  https://github.com/developmentseed/eoapi-k8s/tree/975a26639fa3b8be7d3338220d6ea9c4470d8d15/docs
+[iframing]:
+  https://developmentseed.slack.com/archives/C08B8L61QTT/p1747740182369159?thread_ts=1747314980.658339&cid=C08B8L61QTT
+[eoAPI guidance on cert-manager setup]:
+  https://github.com/developmentseed/eoapi-k8s/blob/main/docs/unified-ingress.md#setting-up-tls-with-cert-manager
+[ingress annotations]:
+  https://cert-manager.io/docs/usage/ingress/
+[ACME]:
+  https://cert-manager.io/docs/configuration/acme/
+[PostgresOperator docs]:
+  https://access.crunchydata.com/documentation/postgres-operator/latest/tutorials/backups-disaster-recovery/backups
+[OIDC auth setup]:
+  https://access.crunchydata.com/documentation/postgres-operator/latest/tutorials/backups-disaster-recovery/backups#using-an-aws-integrated-identity-provider-and-role
+[eoAPI support chart setup]:
+  https://github.com/developmentseed/eoapi-k8s/blob/975a26639fa3b8be7d3338220d6ea9c4470d8d15/docs/autoscaling.md
+[eoAPI chart configuration]:
+  https://github.com/developmentseed/eoapi-k8s/blob/975a26639fa3b8be7d3338220d6ea9c4470d8d15/docs/configuration.md
+[eoAPI support chart dependencies]:
+  https://github.com/developmentseed/eoapi-k8s/blob/975a26639fa3b8be7d3338220d6ea9c4470d8d15/helm-chart/eoapi-support/Chart.yaml

kubernetes/helm/eoapi-support-values.yaml

@@ -0,0 +1,58 @@
+prometheus-adapter:
+  prometheus:
+    url: http://eoapi-support-prometheus-server.eoapi-support.svc.cluster.local
+
+prometheus:
+  server:
+    service:
+      type: ClusterIP
+      annotations: { }
+    ingress:
+      annotations:
+        nginx.ingress.kubernetes.io/auth-type: basic
+        nginx.ingress.kubernetes.io/auth-secret: eoapi-support-prometheus
+        nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required'
+        nginx.ingress.kubernetes.io/enable-cors: "true"
+        nginx.ingress.kubernetes.io/enable-access-log: "true"
+        cert-manager.io/cluster-issuer: "letsencrypt-prod"
+      enabled: true
+      ingressClassName: nginx
+      hosts:
+        - metrics.k8s-prod.hotosm.org
+      tls:
+        - secretName: prometheus-server-tls
+          hosts:
+            - metrics.k8s-prod.hotosm.org
+    persistentVolume:
+      storageClass: gp2
+
+grafana:
+  service:
+    type: ClusterIP
+    annotations: { }
+  ingress:
+    annotations:
+      nginx.ingress.kubernetes.io/enable-cors: "true"
+      nginx.ingress.kubernetes.io/enable-access-log: "true"
+      cert-manager.io/cluster-issuer: "letsencrypt-prod"
+    enabled: true
+    ingressClassName: nginx
+    hosts:
+      - dashboard.k8s-prod.hotosm.org
+    tls:
+      - secretName: grafana-tls
+        hosts:
+          - dashboard.k8s-prod.hotosm.org
+  datasources:
+    datasources.yaml:
+      datasources:
+      - name: prometheus
+        orgId: 1
+        type: prometheus
+        url: http://eoapi-support-prometheus-server.eoapi-support.svc.cluster.local
+        access: proxy
+        jsonData:
+          timeInterval: "5s"
+        isDefault: true
+        editable: true
+        version: 1 # This number should be increased when changes are made to update the datasource