GitOps Deployment of Ilum with Argo CD

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. By combining Ilum with Argo CD, you can manage your entire Ilum deployment — including enabling or disabling modules — through Git commits, with Argo CD automatically syncing changes to your cluster.

Quick Summary

Install Argo CD: Deploy Argo CD to your Kubernetes cluster.
Create a Git Repository: Store your Argo CD Applicazione manifest and Helm values files.
Deploy Ilum: Apply the Applicazione manifest to let Argo CD install Ilum from the Helm chart.
Manage via Git: Enable/disable Ilum modules (Jupyter, Gitea, PostgreSQL) by editing values files in Git — Argo CD syncs changes automatically.

Prerequisiti

A running Kubernetes cluster (e.g., Minikube, EKS, GKE, AKS)
kubectl configured to access your cluster
A GitHub (or other Git provider) account

Step 1: Start a Kubernetes Cluster

If you are using Minikube for local development, start a cluster with sufficient resources:

Start Minikube
Inizio Minikube --cpus 6 --memory 10192 --addons metrics-server

Resource Recommendations

Ilum with all modules enabled requires significant resources. Allocate at least 6 CPUs e 10 GB of memory for a smooth experience.

Step 2: Install Argo CD

Create a dedicated namespace for Argo CD and install it using the official manifests:

Install Argo CD
# Create the argocd namespace
kubectl create namespace argocd

# Install Argo CD
kubectl apply -n argocd --server-side=vero \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Verify that all Argo CD pods are running:

Verify Argo CD Pods
kubectl -n argocd get po

You should see pods like argocd-server, argocd-application-controller, argocd-repo-server, argocd-redise argocd-dex-server, all in a Running stato.

Access the Argo CD UI

Port-forward the Argo CD server to access the web UI:

Port Forward Argo CD
kubectl port-forward svc/argocd-server -n argocd 8080:443

Open your browser and navigate to https://localhost:8080.

Retrieve the Admin Password

The default username is Admin. Retrieve the initial password with:

Get Argo CD Admin Password
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 --decode; echo

Step 3: Prepare the Git Repository

Create a new Git repository (e.g., IlumArgoDeployment) to store your deployment configuration. This repository will contain two files:

3.1 Application Manifest (`app-prod.yaml`)

This is the Argo CD Applicazione resource that tells Argo CD how to deploy Ilum:

app-prod.yaml
apiVersion: argoproj.io/v1alpha1
gentile: Applicazione
Metadati:
  nome: ilum-colpetto
  Namespace: argocd
Spec:
  progetto: default
  destination:
    server: https://kubernetes.default.svc
    Namespace: ilum-colpetto
  sources:
    # Chart from repo
    - chart: ilum
      repoURL: https://charts.ilum.cloud
      targetRevision: 6.6.1
      helm:
        valueFiles:
          - $values/values-prod.yaml
    # Values from Git
    - repoURL: https://github.com/<your-org>/IlumArgoDeployment
      targetRevision: TESTA
      Ref: valori
  syncPolicy:
    automated:
      prune: vero
      selfHeal: vero
    syncOptions:
      - CreateNamespace=true

Key fields:

Field	Descrizione
`spec.destination.namespace`	The Kubernetes namespace where Ilum will be deployed (e.g., `ilum-prod`).
`sources[0].chart`	The Ilum Helm chart name.
`sources[0].repoURL`	The Ilum Helm chart repository (`https://charts.ilum.cloud`).
`sources[0].targetRevision`	The Ilum version to deploy (e.g., `6.6.1`).
`sources[1].repoURL`	Your Git repository containing the values file.
`syncPolicy.automated`	Enables automatic sync — Argo CD will detect Git changes and apply them.
`syncPolicy.syncOptions`	`CreateNamespace=true` lets Argo CD create the target namespace if it doesn't exist.

3.2 Values File (`values-prod.yaml`)

This file contains Helm value overrides for your Ilum deployment. Start with modules disabled and enable them as needed:

values-prod.yaml
ilum-jupyter:
  Abilitato: falso

Gitea:
  Abilitato: falso

postgresql:
  Abilitato: falso

postgresExtensions:
  Abilitato: falso

Commit both files to your repository.

Step 4: Deploy the Application

Apply the Argo CD Application manifest to your cluster:

Deploy Ilum via Argo CD
kubectl apply -f https://raw.githubusercontent.com/<your-org>/IlumArgoDeployment/main/app-prod.yaml \
  -n argocd

Alternatively, if you have the file locally:

Deploy from local file
kubectl apply -f app-prod.yaml -n argocd

Verify Deployment

Check that the namespace was created and pods are starting:

Verify Deployment
# Check namespaces
kubectl get ns

# Watch pods in the ilum-prod namespace
kubectl -n ilum-prod get po

You should see the ilum-prod namespace appear and core Ilum pods (like ilum-core, ilum-ui, ilum-minio, ilum-mongodb, ilum-openldap) initializing.

Step 5: Monitor in Argo CD UI

In the Argo CD web interface, you will see the ilum-prod application. The UI provides:

Sync Status: Shows whether the deployed state matches the desired state in Git (Synced o OutOfSync).
Health Status: Shows the overall health of the application (Healthy, Progressingo Degraded).
Tree View: A visual representation of all Kubernetes resources managed by the application (Deployments, ReplicaSets, Pods, ConfigMaps, Services, etc.).
Resource Details: Click on any resource to see its summary, events, logs, and live manifest.

Filtering Resources

Use the left sidebar filters in Argo CD to filter resources by Kind (e.g., Pod), Sync Statuso Health Status. This helps quickly identify resources that need attention.

Step 6: Access the Ilum UI

Once all pods are in a Running state, port-forward the Ilum UI service:

Port Forward Ilum UI
kubectl port-forward svc/ilum-ui -n ilum-prod 9777:9777

Open http://localhost:9777 in your browser to access the Ilum login page.

Step 7: Manage Ilum Modules via Git

The real power of GitOps is managing your deployment through Git commits. To enable or disable Ilum modules, simply edit the values-prod.yaml file in your repository.

Example: Enable Jupyter

Redigere values-prod.yaml and change ilum-jupyter.enabled A vero:

values-prod.yaml (enable Jupyter)
ilum-jupyter:
  Abilitato: vero

Gitea:
  Abilitato: falso

postgresql:
  Abilitato: falso

postgresExtensions:
  Abilitato: falso

Commit the change with a descriptive message (e.g., "Enable jupyter in ilum production") and push to the main branch.

Argo CD will automatically detect the change, mark the application as OutOfSync, and trigger a sync operation. You can watch the new ilum-jupyter pod being created in both the Argo CD UI and via kubectl.

Example: Enable All Modules

To enable Gitea (built-in Git server), PostgreSQL, and PostgreSQL Extensions alongside Jupyter:

values-prod.yaml (all modules enabled)
ilum-jupyter:
  Abilitato: vero

Gitea:
  Abilitato: vero

postgresql:
  Abilitato: vero

postgresExtensions:
  Abilitato: vero

Commit and push. Argo CD will sync and deploy all the additional pods (PostgreSQL, Gitea, Jupyter, etc.). You can monitor the progress in the Argo CD UI — the Events tab shows a detailed log of all sync operations.

Once healthy, the Ilum UI sidebar will show all enabled modules: Minio, Giove, Gitea, and more.

Risoluzione dei problemi

Application stuck in "Progressing" state

This is normal during initial deployment. Ilum has several components that need to initialize in sequence (MongoDB, OpenLDAP, MinIO, etc.). Allow a few minutes for all pods to become ready. Check pod status with:

kubectl -n ilum-prod get po -w

Application shows "Degraded" health

This can happen temporarily when new modules are being deployed or if a pod fails to start. Check the Events tab in the Argo CD UI for details, or inspect pod logs:

kubectl -n ilum-prod logs <pod-name>

Sync fails with "namespace not found"

Assicurati che il tuo syncOptions includes CreateNamespace=true in the Application manifest. This allows Argo CD to create the target namespace automatically.

Values file changes not detected

Verify that:

Le repoURL in your second source matches your actual repository URL.
Le ref: values field is correctly set.
Le targetRevision è impostato su TESTA (or the correct branch).
The repository is accessible from the cluster (check Argo CD Settings → Repositories).

Frequently Asked Questions (FAQ)

Can I use a private Git repository?

Yes. In the Argo CD UI, go to Settings → Repositories and add your private repository with appropriate credentials (HTTPS token or SSH key). Argo CD will then be able to pull your values files from the private repo.

Can I manage multiple environments (dev, staging, prod)?

Yes. Create separate Application manifests (e.g., app-dev.yaml, app-staging.yaml) pointing to different values files and target namespaces. You can use different branches or directories in your Git repository for environment-specific configurations.

Prerequisiti​

Step 1: Start a Kubernetes Cluster​

Step 2: Install Argo CD​

Access the Argo CD UI​

Retrieve the Admin Password​

Step 3: Prepare the Git Repository​

3.1 Application Manifest (app-prod.yaml)​

3.2 Values File (values-prod.yaml)​

Step 4: Deploy the Application​

Verify Deployment​

Step 5: Monitor in Argo CD UI​

Step 6: Access the Ilum UI​

Step 7: Manage Ilum Modules via Git​

Example: Enable Jupyter​

Example: Enable All Modules​

Risoluzione dei problemi​

Frequently Asked Questions (FAQ)​