ArgoCD Deployment

This document explains how we manage deployments using ArgoCD and provides guidance for creating new deployments.

Overview

ArgoCD is used for GitOps-based continuous deployment. Application definitions are stored in a Git repository and ArgoCD reconciles the desired state with the cluster.

ArgoCD Application Structure

OCI Helm Chart Deployment

For applications with Helm charts published to Docker Hub:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: registration-portal-dev
  namespace: argocd
spec:
  project: default
  destination:
    name: idl-xnl-jhb1-rc01  # Cluster name
    namespace: event-dev
  source:
    repoURL: registry-1.docker.io
    chart: christhonie/registration-portal
    targetRevision: 1.2.4-SNAPSHOT-RELEASE  # Chart version
    helm:
      releaseName: dev-registration-portal
      valuesObject:
        # Helm values go here
        config:
          profiles: "dev,kubernetes,api-docs"
        image:
          tag: "1.2.4-SNAPSHOT"  # Docker image tag
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
      allowEmpty: false
    syncOptions:
      - CreateNamespace=true
  revisionHistoryLimit: 3

Git Source Deployment

For raw Kubernetes manifests (like GreenMail):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: greenmail-dev
  namespace: argocd
spec:
  project: default
  destination:
    name: idl-xnl-jhb1-rc01
    namespace: event-dev
  source:
    repoURL: [email protected]:christhonie/idl-xnl-jhb-rc01.git
    targetRevision: HEAD
    path: event-membership/greenmail-dev
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Version Conventions

Component Format Example

Helm Chart Version

<MAVEN_VERSION>-RELEASE

1.2.4-SNAPSHOT-RELEASE

Docker Image Tag

<MAVEN_VERSION>

1.2.4-SNAPSHOT

Database Name

<app>_<env> (underscores)

registration_ui_dev

Common Values Configuration

Application Profiles

config:
  profiles: "dev,kubernetes,api-docs"

Common profiles:

  • dev - Development settings, verbose logging

  • kubernetes - Enables Spring Cloud Kubernetes

  • api-docs - Enables Swagger/OpenAPI documentation

  • otlp - Enables OpenTelemetry instrumentation

Database Configuration

config:
  db:
    # URL format WITHOUT driver prefix (jdbc: or r2dbc:)
    url: mysql://idealogic-prod.mysql.svc.cluster.local:6446/registration_ui_dev?useUnicode=true&characterEncoding=utf8
    username: dev
  existingsecret: event-admin-service  # Password from shared secret

Email Configuration (GreenMail)

config:
  mail:
    host: greenmail.event-dev.svc.cluster.local
    port: 25
    from: [email protected]
    username: ""
    password: ""
    protocol: smtp
    tls: false
    properties.mail.smtp:
      auth: false
      starttls.enable: false

OpenTelemetry Configuration

config:
  otel:
    enabled: true
    url: "http://opentelemetry-collector.observability.svc.cluster.local:4317"

Logging Configuration

config:
  logging:
    level:
      ROOT: DEBUG
      za.co.idealogic.registration.ui: DEBUG
      org.springframework.security: DEBUG

Liquibase Contexts

config:
  liquibase:
    contexts: "dev,faker"  # Include faker for test data

Image Configuration

image:
  pullPolicy: Always  # Use Always for SNAPSHOT versions
  tag: "1.2.4-SNAPSHOT"

imagePullSecrets:
  - name: christhonie-docker  # Docker Hub credentials

Ingress Configuration

ingress:
  enabled: true
  className: "nginx"
  annotations:
    "cert-manager.io/cluster-issuer": "letsencrypt-prod"
    "external-dns.alpha.kubernetes.io/cloudflare-proxied": "false"
  hostname: registration-portal-dev.idealogic.co.za
  pathType: Prefix
  tls: true

Scaling Configuration

replicaCount: 1  # Set to 0 to disable deployment

Setting replicaCount: 0 is useful when:

  • Debugging deployment issues

  • Waiting for dependencies to be ready

  • Temporarily disabling an environment

Creating a New Deployment

Step 1: Create ArgoCD Application File

Create a new YAML file in argocd/ directory:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: <app-name>-<env>
  namespace: argocd
spec:
  project: default
  destination:
    name: idl-xnl-jhb1-rc01
    namespace: event-<env>
  source:
    repoURL: registry-1.docker.io
    chart: christhonie/<chart-name>
    targetRevision: <version>-RELEASE
    helm:
      releaseName: <env>-<app-name>
      valuesObject:
        # ... values configuration
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
      allowEmpty: false
    syncOptions:
      - CreateNamespace=true
  revisionHistoryLimit: 3

Step 2: Configure Values

Add the appropriate values for your environment. Reference existing deployments for patterns.

Step 3: Commit and Push

git add argocd/<app-name>-<env>.yml
git commit -m "Add ArgoCD Application for <app-name>-<env>"
git push

Step 4: Verify Deployment

Check ArgoCD UI or CLI:

argocd app get <app-name>-<env>
argocd app sync <app-name>-<env>  # If not auto-syncing

Updating Deployments

Updating Chart Version

Edit the ArgoCD Application:

source:
  targetRevision: 1.2.5-SNAPSHOT-RELEASE  # New version
  helm:
    valuesObject:
      image:
        tag: "1.2.5-SNAPSHOT"  # Must match

Updating Configuration

Simply edit the valuesObject section and commit. ArgoCD will automatically sync the changes.

Common Issues and Solutions

Application OutOfSync but Won’t Sync

Cause: Resource has been manually modified or has invalid fields.

Solution:

argocd app sync <app-name> --force

Pod CrashLoopBackOff

Check the pod logs:

kubectl logs -n event-<env> -l app.kubernetes.io/name=<app-name> --previous

Common causes:

  • Missing secrets: Verify existingsecret points to valid secret

  • Database connection failed: Check database URL and credentials

  • Missing K8s dependencies: Ensure spring-cloud-starter-kubernetes-fabric8-config is included

CreateContainerError: no command specified

Cause: Docker image built without proper entrypoint.

Solution: Rebuild the Docker image with proper ENTRYPOINT or CMD in Dockerfile.

Chart Not Found

Cause: Chart version doesn’t exist in registry.

Solution:

  1. Verify chart exists: helm show chart oci://registry-1.docker.io/christhonie/<chart> --version <version>

  2. Run Helm release workflow if chart needs to be published

Wrong Database Name

Cause: Database name format mismatch.

Solution: Use underscores in database names (e.g., registration_ui_dev, not registration-ui-dev).

Environment Conventions

Environment Namespace Hostname Pattern

Development

event-dev

<app>-dev.idealogic.co.za

Staging

event-staging

<app>-staging.idealogic.co.za

Production

event-prod

<app>.myriadevents.co.za

Related Documentation